Generate marriage compatibility report

Request: application/json.

Start a compatibility analysis. Pass family_key to use an existing family member, or provide partner details to add them inline. Runs in the background - you are notified when ready.

Body: report_kind (default marriage) - the purchase-screen feature list for each:

compatibility (cheap entry tier): Ashtakoota compatibility score out of 36, full guna breakdown with Manglik dosha check, a shareable Guna Milan match card, Nandini's personalised AI compatibility summary. Does NOT include marriage-timing windows or either partner's full birth charts - upgradable later via POST /marriage/report/{prediction_key}/upgrade/checkout (delta-priced, pay only the difference, previewed by GET /marriage/report/{prediction_key}/upgrade-price).

marriage (full tier): everything in compatibility PLUS auspicious marriage-timing windows, audio narration, both partners' full birth charts (North+South) and detailed kundali summaries.

Plus ONE of two mutually exclusive partner modes:

Existing member: family_key (e.g. Family-12345). Reuses the member's already-generated kundali. All partner_* fields are ignored.

New partner: partner_name + partner_dob (both required) plus optional partner_gender, partner_birth_time, partner_birth_place, partner_latitude, partner_longitude, partner_timezone. The partner is stored ONLY on this report - NOT added to the family list or kundali store - so you can freely compare many prospective partners.

Birth time optional: if partner_birth_time is unknown, pass partner_moon_sign (Vedic Moon sign name) instead - one of the two is required for a new partner. Without an exact time the chart is INDICATIVE (Moon-sign based, no lagna/houses); the report still computes but is flagged confidence: "indicative" instead of "precise". Same contract as POST /users/family (add family member).

Success: 200 - returns prediction_key (Match-XXXXX). Generation runs in the background; poll GET /marriage/report/{prediction_key} and/or wait for the push notification. Also returns 200 with success: false and code: PLAN_LIMIT (not an HTTP error) when header X-Enforce-Paywall: true is sent and no unconsumed purchase credit exists for this partner (get one via POST /subscriptions/checkout with slug compatibility-score or marriage-report first - checkout never generates the report itself, this endpoint is always the separate step-2 call, paid or free-via-coupon; already-generated reports for the same partner stay free forever). If a purchase is still pending (paid moments ago, webhook not yet processed), this call reconciles it against Razorpay live before deciding - if confirmed paid the credit activates and generation proceeds normally; if not, the message is "We're still verifying your payment..." instead of the plain "this report needs to be purchased" text shown when no attempt exists at all

Retry after a failed report is allowed and free (2026-08-20): a failed report does not block a new attempt for the same partner, and the SAME already-paid credit from the first attempt is reused automatically - a paid credit only counts as spent once a report actually reaches done. It is always safe to call POST /subscriptions/checkout (slug compatibility-score or marriage-report) again before retrying - it will report requires_payment: false and hand back the same purchase instead of charging twice.

Errors: 401 invalid/missing token | 404 family_key matches no family member of this user | 409 a report of the same report_kind for this family member is already pending/processing (inline partners are never blocked) | 422 neither family_key nor partner_name+partner_dob supplied, or neither partner_birth_time nor partner_moon_sign supplied for a new partner.

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/json

Successful Response

Bodyapplication/json

Example

{
    "success": true,
    "message": "Success",
    "data": {
        "prediction_key": "Match-12345",
        "message": "Report generation started. You will be notified when ready."
    }
}

🟠401Unauthorized

🟠404Record Not Found

🟠409Record Not Found

🟠422Parameter Error