Recommendation API

Use these APIs to generate health insurance recommendations for a customer and retrieve the results once processing is complete.

Flow

1. Generate a recommendation — Call POST /v1/business/health/recommendation with customer, member, and cover details.
2. Receive a quote_id — The response returns a quote_id that identifies this recommendation job.
3. Poll for results — Call GET /v1/business/health/recommendation/{quote_id} until status is success.
4. Use the recommendations — Once successful, the response includes the recommended plans and variants.

note

Recommendation generation is asynchronous. Do not treat the POST response as final results — always poll the GET endpoint until status is success.

---

Generate Recommendation

Starts a recommendation job and returns a quote_id to poll against.

Endpoint

POST /v1/business/health/recommendation
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Required scope: business.quote.write

Request

Body

{
  "lead_id": "YOUR_LEAD_ID",
  "user_id": "YOUR_USER_ID",
  "customer": {
    "name": "John Doe",
    "gender": "Male",
    "phoneNumber": "9876543210",
    "pinCode": "560001",
    "email": "john.doe@example.com"
  },
  "members": {
    "self": [{ "age": 30 }],
    "spouse": [{ "age": 28 }],
    "son": [{ "age": 5 }]
  },
  "hasPED": false,
  "selectedPEDs": [],
  "plan_type": "base",
  "sum_insured": 1000000,
  "deductible": 0
}

Fields

Field	Type	Required	Description
lead_id	string	Yes	Unique lead identifier on your platform
user_id	string	Yes	Unique identifier of the end user on your platform
customer	object	Yes	Proposer / primary customer details (see Customer Fields)
members	object	Yes	Map of relationships to insured members (see Members)
hasPED	boolean	Yes	Whether any insured member has a pre-existing disease
selectedPEDs	array	No	List of selected pre-existing disease identifiers
plan_type	string	No	Plan type. Use base or super_top_up. Defaults to base if omitted
sum_insured	number	No	Desired sum insured. Defaults to 1000000 if omitted or 0
deductible	number	No	Deductible amount (typically used for super top-up plans)
partner_id	string	No	Partner ID for attribution (requires additional permission if different)
enterprise_id	string	No	Enterprise ID for attribution (requires additional permission if different)
is_porting	boolean	No	Whether this is a porting journey
porting_tenure	number	No	Existing policy tenure in years, when is_porting is true

Customer Fields

Field	Type	Required	Description
name	string	Yes	Customer full name
gender	string	Yes	Customer gender
phoneNumber	string	Yes	Customer phone number
pinCode	string	Yes	Customer PIN / ZIP code
email	string	Yes	Customer email address

Members

members is a map keyed by relationship. Each key maps to an array of objects with an age field.

Key	Multiple members allowed	Description
self	No	Primary insured
spouse	No	Spouse
father	No	Father
mother	No	Mother
daughter	Yes	Daughter(s)
son	Yes	Son(s)

Example member object:

{ "age": 30 }

Response

Success Response (200 OK)

{
  "payload": {
    "quote_id": "18kfaYY6UvClEx35"
  }
}

Response Fields

Field	Type	Description
quote_id	string	Identifier used to poll recommendation status and results

---

Get Recommendation

Retrieves the current status and results for a recommendation job. Poll this endpoint until status is success.

Endpoint

GET /v1/business/health/recommendation/{quote_id}
Authorization: Bearer YOUR_ACCESS_TOKEN

Required scope: business.quote.read

Path Parameters

Field	Type	Required	Description
quote_id	string	Yes	The quote_id returned by Generate Recommendation

Polling Guidance

1. Call this endpoint after receiving a quote_id from Generate Recommendation.
2. Inspect the status field in the response.
3. If status is not success, wait briefly and call again.
4. Stop polling when status is success — recommendations are ready.
5. Use completed_variants / total_variants as an optional progress indicator while processing.

tip

Use a reasonable polling interval (for example, every 2–3 seconds) and set an overall timeout so your client does not poll indefinitely.

Response

Success Response (200 OK) — processing

{
  "payload": {
    "quote_id": "18kfaYY6UvClEx35",
    "status": "pending",
    "total_variants": 23,
    "completed_variants": 8,
    "sum_insured": 1000000,
    "pincode": "560001",
    "plan_type": "BASE",
    "customer_name": "John Doe",
    "customer_phone": "9876543210",
    "customer_gender": "Male",
    "customer_email": "john.doe@example.com",
    "new_recommendations": []
  }
}

Success Response (200 OK) — ready

When status is success, the payload includes recommendation results (for example under new_recommendations). Use those results for the next step in your integration.

{
  "payload": {
    "quote_id": "18kfaYY6UvClEx35",
    "id": "18TzMT7LGohy13QG",
    "status": "success",
    "total_variants": 23,
    "completed_variants": 23,
    "sum_insured": 1000000,
    "pincode": "560001",
    "deductible": 0,
    "copay": 0,
    "plan_type": "BASE",
    "customer_name": "John Doe",
    "customer_phone": "9876543210",
    "customer_gender": "Male",
    "customer_email": "john.doe@example.com",
    "member_details": {
      "self": [{ "age": 30 }],
      "spouse": [{ "age": 28 }],
      "son": [{ "age": 5 }]
    },
    "new_recommendations": [
      {
        "company_id": "18TzMT7LGohy13QG",
        "company_name": "ICICI Lombard",
        "company_logo": "https://cdn.example.com/logo.jpeg",
        "product_id": "prod_123",
        "product_name": "Health Protect",
        "variant_id": "var_456",
        "variant_name": "Gold",
        "recommended": true,
        "online": true,
        "tenure_map": [
          {
            "tenure": 1,
            "premium": 12500.0,
            "deductible": 0
          }
        ]
      }
    ]
  }
}

Response Fields

Field	Type	Description
quote_id	string	Quote identifier for this recommendation
id	string	Recommendation ID
status	string	Current job status. Poll until this is success
total_variants	number	Total variants expected for this recommendation
completed_variants	number	Variants completed so far
sum_insured	number	Sum insured used for the recommendation
pincode	string	Customer pincode
deductible	number	Deductible amount
copay	number	Copay value
plan_type	string	Plan type (BASE or SUPER_TOP_UP)
customer_name	string	Customer name
customer_phone	string	Customer phone
customer_gender	string	Customer gender
customer_email	string	Customer email
member_details	object	Members included in the recommendation
new_recommendations	array	Recommended plans (populated when processing completes successfully)

new_recommendations item fields

Field	Type	Description
company_id	string	Insurer company ID
company_name	string	Insurer name
company_logo	string	Insurer logo URL
company_description	string	Insurer description
company_network_hospital_count	number	Network hospital count
company_claim_settlement_ratio	number	Claim settlement ratio
product_id	string	Product ID
product_name	string	Product name
variant_id	string	Variant ID
variant_name	string	Variant name
variant_description	string	Variant description
recommended	boolean	Whether this variant is recommended
online	boolean	Whether the variant supports online purchase
tenure_map	array	Tenure and premium options
parent_variant_id	string	Parent variant ID, if applicable
filter_tags_ids	array	Filter tag IDs associated with the variant

tenure_map item fields

Field	Type	Description
tenure	number	Policy tenure in years
premium	number	Premium for this tenure
deductible	number	Deductible for this tenure

---

Authentication

Both endpoints require a Bearer token. See the Authentication API.

Endpoint	Required scope
POST	business.quote.write
GET	business.quote.read

note

If you do not have these scopes enabled, contact the OneAssure team.