Your first branded kundli PDF.

1. Before you start

1. Ask your Kundlistar administrator to create your company account and enable the PDF Report module. You will receive a username, password, and existing API base URL.
2. Sign in at the client console using the portal URL supplied by your administrator. Open API Keys and create or copy a company key.
3. Store the API base URL and API key as environment variables on your own server. Use the existing API host supplied by your administrator. SaaS calls use /api/saas/ on that same host; no second public API domain is needed. The console website may use a different frontend domain.
4. Collect the person’s name, date, local birth time, gender, and birth city. Optionally prepare your business name, address, phone number, and consultation notes.
5. Allow up to 240 seconds in your HTTP client/proxy. Report generation runs synchronously, with a 180-second generation timeout.

2. Authenticate from your server

Content-Type: application/json
x-api-key: klive_<your-company-key>

Both POST endpoints require x-api-key. Test keys (ktest_…) also work and use the same company quota. Keep keys and console credentials out of browser bundles, mobile apps, source control, and public logs.

Your console username/password signs you in to the portal. Your API key authenticates integration requests. The token in a PDF URL authorizes that one download link.

MODULE 01 · AVAILABLE

3. PDF Report

Step A — Choose the birth city

POST /api/saas/v1/cities

{"q":"Delhi","country":"IN","limit":10}

q: 2–100 characters. country: uppercase two-letter code, default IN. limit: 1–50, default 10.

{"cities":[{"id":123456,"name":"New Delhi","displayName":"New Delhi, Delhi, India"}],"count":1}

The response also contains coordinates and timezone information. The ID above is illustrative: use an actual returned id. Offer the results to your user so they can choose the correct place.

Step B — Generate the report

POST /api/saas/v1/reports

{
  "chart": {
    "name": "Sample User",
    "dateOfBirth": "1990-01-15",
    "timeOfBirth": {
      "hour": 10,
      "minute": 30,
      "second": 0
    },
    "cityId": "REPLACE_WITH_CITY_ID",
    "gender": "Male",
    "language": "en",
    "chartStyle": "North",
    "ayanamshaMode": "LAHIRI",
    "sections": [
      "vedic",
      "kp",
      "nadi"
    ]
  },
  "branding": {
    "name": "Your Astrology Studio",
    "address": "12 Example Road, New Delhi, India",
    "phone": "+91 98765 43210"
  },
  "notes": {
    "title": "Consultation notes",
    "text": "Prepared for your consultation. Use these insights as guidance."
  },
  "color": {
    "theme": "forest"
  }
}

Step C — Deliver the private link

HTTP 201 Created

{
  "downloadUrl":"https://your-existing-api.example.com/api/saas/v1/reports/REPORT_ID/pdf?token=PRIVATE_TOKEN",
  "expiresAt":"2026-11-04T10:00:00.000Z"
}

Send downloadUrl to the intended recipient or use it as a download button. Opening it returns an application/pdf attachment. No PDF bytes, base64, or calculated chart JSON are returned by the generation POST.

Request fields

Use these exact field names; dob, city, and time are not aliases. Unknown fields and unsupported values return 400. Earlier flat chart payloads remain compatible; use the nested structure for new integrations and customization.

Branding, notes, and report colors

The person’s name stays at the top of the report. Your business name, address, and phone appear in the footer. Branding and notes are private report data and expire with the report after 10 days.

Notes are appended after the generated report content and flow onto additional pages when needed. They are rendered as plain text; HTML, Markdown styling, images, and executable content are not supported.

Choose a predefined theme with {"color":{"theme":"indigo"}}. Custom hex colors are not accepted. Themes style the report header, footer, and section accents; planet/chart colors retain their existing meaning.

Server-side code examples

// Run on your server. Set KUNDLISTAR_API_ORIGIN and KUNDLISTAR_API_KEY.
const base = process.env.KUNDLISTAR_API_ORIGIN;
const headers = {
  'Content-Type': 'application/json',
  'x-api-key': process.env.KUNDLISTAR_API_KEY
};

const cityResponse = await fetch(base + '/api/saas/v1/cities', {
  method: 'POST', headers, body: JSON.stringify({q: 'Delhi', country: 'IN'})
});
const cities = await cityResponse.json();
if (!cityResponse.ok || !cities.cities?.length) throw new Error('Choose a valid city');
// In your product, let the user select the correct city from the results.
const payload = {
  "chart": {
    "name": "Sample User",
    "dateOfBirth": "1990-01-15",
    "timeOfBirth": {
      "hour": 10,
      "minute": 30,
      "second": 0
    },
    "cityId": "REPLACE_WITH_CITY_ID",
    "gender": "Male",
    "language": "en",
    "chartStyle": "North",
    "ayanamshaMode": "LAHIRI",
    "sections": [
      "vedic",
      "kp",
      "nadi"
    ]
  },
  "branding": {
    "name": "Your Astrology Studio",
    "address": "12 Example Road, New Delhi, India",
    "phone": "+91 98765 43210"
  },
  "notes": {
    "title": "Consultation notes",
    "text": "Prepared for your consultation. Use these insights as guidance."
  },
  "color": {
    "theme": "forest"
  }
};
payload.chart.cityId = cities.cities[0].id;

const response = await fetch(base + '/api/saas/v1/reports', {
  method: 'POST', headers, body: JSON.stringify(payload),
  signal: AbortSignal.timeout(240000)
});
const result = await response.json();
if (!response.ok) throw new Error(result.error || 'Report failed');
// Send this private URL to the intended recipient.
// Return these fields only to the intended recipient in your route handler.
// res.json({ downloadUrl: result.downloadUrl, expiresAt: result.expiresAt });

For cURL, save the JSON request above as payload.json and replace its city ID before sending it. The examples use the first city only to illustrate the flow; your interface should let the user choose.

Monthly quota and usage

Each company starts with 500 successful PDF reports per month, shared across all its keys. Administrators can change this quota in either admin panel. A quota of 0 blocks new reports.

• The month resets at 00:00 on the first day in Asia/Kolkata (IST). Requests are charged to the month in which a generation slot is accepted.
• Invalid payloads and failed generations do not consume quota. In-progress generations reserve a slot so simultaneous requests cannot bypass the cap.
• At the cap, the API returns 429 with REPORT_MONTHLY_QUOTA_EXCEEDED, monthlyLimit, and resetsAt. Contact your administrator or wait until reset.
• There is also a 60-POST-requests/minute/company limit. One report/company and two overall can generate at once per backend process; busy requests return 503 with Retry-After.
• Open Dashboard or Usage in the console for lifetime totals, this month’s usage, quota, and remaining reports. Deleting or revoking PDFs does not refund completed generations.

Private links, expiry, and revocation

The token is part of the download URL. Anyone holding the complete URL can download that PDF while it is active, without the company API key or console login. Share it only with the intended recipient.

• Links expire 10 days after report creation. MongoDB automatically removes the record, personal details, branding, notes, and PDF; links reject expiry immediately even before background deletion.
• From PDF Reports in the client console, a company user can revoke an individual report’s link. Revocation is permanent for that link.
• Admins can revoke all existing company PDF links from either admin panel. They can separately revoke console sessions to sign the company out.
• Disabling/rotating an API key stops new requests with that key. It does not revoke already issued PDF links. Use the PDF-link revocation control for that.
• Suspending a company or disabling its PDF permission blocks its links and new report requests. An explicitly revoked link stays revoked after re-enabling.

PDF downloads are marked private, no-store and no-referrer. Omit token query strings and private payloads from your own logs. Maximum PDF size is 12 MiB; select fewer sections if a report exceeds it.

Errors and troubleshooting

Astrology reports provide insights and guidance. They do not replace professional medical, legal, or financial advice.