Quotes

A quote is the price given for a specific basket and insured details. A quote request returns one or more options; each option has its own ID (quoteId), premium and validity. You create an order with the option the buyer confirms.

A quote is not a money movement and does not issue a policy. Your provider connections, not your request, decide which provider gives the quote. A single request can return options from several products and insurance companies in your connections: Multiple options.

Authentication and signing: Flows › Authentication.

Getting a quote: POST /api/v1/insurance/quotes

Idempotency-Key is optional. Each request returns a new, time-limited price.

• Send context.items or paymentIntentId as the basket source; if both are sent, the request is rejected.
• If you send neither, the quote is obtained without a basket item. This applies only to types sold without a basket item: Selling Without a Basket Item.
• The fields of policyholder, insured and the type object, and when they are required, are in the type's schema: Insurance Types and Schemas. A field that is not in the schema is rejected.
• Link each entry of the type object to the insured basket item with basketItemId. In a quote taken with paymentIntentId, basketItemId is required. In a quote taken with context.items, if basketItemId is omitted the type covers all items it is offered for.
• If the items carry insuranceContext or insuranceData, the body is completed from these details and basketItemId can be taken from the item; the rules: Quote with pre-fill data.

A quote request with two tickets for TICKET_CANCELLATION. The values are examples; replace the values in angle brackets with your buyer's details:

{
  "insuranceType": "TICKET_CANCELLATION",
  "currency": "TRY",
  "merchantOrderId": "order-1001",
  "context": {
    "items": [
      {
        "id": "ticket-1",
        "name": "Izmir-Ankara train ticket",
        "price": 50000,
        "category1": "ticket",
        "itemType": "VIRTUAL",
        "insuranceCategory": "TICKET",
        "insuranceTypes": ["TICKET_CANCELLATION"]
      },
      {
        "id": "ticket-2",
        "name": "Izmir-Ankara train ticket",
        "price": 50000,
        "category1": "ticket",
        "itemType": "VIRTUAL",
        "insuranceCategory": "TICKET",
        "insuranceTypes": ["TICKET_CANCELLATION"]
      }
    ]
  },
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<identity number>",
      "birthDate": "<YYYY-MM-DD>",
      "email": "<email>",
      "phone": "<E.164 phone>"
    }
  ],
  "tickets": [
    {
      "basketItemId": "ticket-1",
      "transportMode": "TRAIN",
      "carrier": "Example Carrier",
      "priceAmount": 50000,
      "departureAt": "2025-12-23T12:50:00+03:00",
      "originCity": "Izmir",
      "destinationCity": "Ankara",
      "pnr": "<booking reference>",
      "ticketNumber": "<ticket number>"
    },
    {
      "basketItemId": "ticket-2",
      "transportMode": "TRAIN",
      "carrier": "Example Carrier",
      "priceAmount": 50000,
      "departureAt": "2025-12-23T12:50:00+03:00",
      "originCity": "Izmir",
      "destinationCity": "Ankara",
      "pnr": "<booking reference>",
      "ticketNumber": "<ticket number>"
    }
  ]
}

source lunixi-sign.sh
BODY='<quote request, compact JSON>'
lunixi_sign POST "/api/v1/insurance/quotes" "$BODY"
 
curl -X POST "https://api-gateway.lunixi.com/api/v1/insurance/quotes" \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "Digest: $DIGEST" \
  -H "X-Signature: $SIGNATURE" \
  --data-raw "$BODY"

Response

A successful request returns 201. data carries these fields:

If no option can be obtained from any of your connections, the request returns an error; an empty option list is not returned.

Quote with pre-fill data

If the basket items carry insuranceContext or insuranceData, the quote body is completed from these details. In the request you send only the missing fields or the ones you want to change. The format of the pre-fill data: Basket Items › Insurance pre-fill data.

Whether the items carry everything the quote needs is shown by quoteReady in the Eligibility response. If the items carry everything, you can get the quote with only the type, the currency and the payment ID:

{
  "insuranceType": "TICKET_CANCELLATION",
  "currency": "TRY",
  "paymentIntentId": "<payment ID>"
}

If something is missing, send only the missing fields. In the example the booking code and ticket number needed for the policy are added; the trip, the passenger and the ticket amount come from the item:

{
  "insuranceType": "TICKET_CANCELLATION",
  "currency": "TRY",
  "paymentIntentId": "<payment ID>",
  "tickets": [
    {
      "basketItemId": "ticket-1",
      "pnr": "<booking code>",
      "ticketNumber": "<ticket number>"
    }
  ]
}

Merge rules

• The request wins. The base is the items' context and pre-fill data; the request body is written over the base. For the same field the value you send in the request applies. If the context and the pre-fill data have the same field, the pre-fill data applies.
• If you do not send the type object, it is built from the items that carry context or pre-fill data; basketItemId is the item's id. An item that carries neither is not part of the quote. To cover that item too, send an entry in the type object with that item's basketItemId.
• Type object that is an array (tickets): if you send it, the quote covers only the tickets you send. A ticket whose basketItemId matches an item is completed with that item's details.
• Types with a single object (device, vehicle and so on): the basketItemId in the object selects whose details are used. If you do not send it, the first item carrying context or pre-fill data is used and the quote is tied to that item.
• insured: the items' insured persons are merged into one list in item order; the same identityType and identityNumber is not repeated and the type's maximum is not exceeded. Each entry of the insured list you send in the request is written over the insured person in the same position.
• policyholder: taken from the first item whose pre-fill data gives a policyholder; the fields you send in the request are written over it.

Validation:

• The merged body is fully validated against the type's schema. A field in the pre-fill data or in the request that breaks a rule gets 422 insurance.validation.invalid with its field path.
• A value from the context that does not fit the type is not used; it does not block the quote.
• If the items carry context or pre-fill data, it is first checked whether the type is offered for this basket; if not, 412 insurance.type.not_available is returned.
• If the items carry no context and no pre-fill data, the quote is taken with the request body only, as today.

Multiple options

The quote request is sent at the same time to every product in your connections for which the type is enabled. Each product returns its own option.

• Several options can come from the same insurance company; for example different plans of the same product.
• If the same insurance company's quote comes from two different provider connections of yours, two separate options are returned. Lunixi does not pick one of them for you.
• Options are returned in the order of your connections.
• The response waits for the connections up to a set time. The option of a connection that does not answer within that time is excluded with insurance.provider.unavailable; the other options are returned. Do not set your client timeout below 30 seconds.

Provider and insurance company

In an option, the provider and the insurance company are separate fields:

• provider is the provider connection the quote came from.
• underwriter is the insurance company that issues the policy. The same insurance company can come from different providers; underwriter.code is the same for the same company whichever provider it comes from.
• If the product does not state an insurance company, underwriter is null.
• underwriter.disclosureText is the insurance company's information text to show to the buyer. It is returned in the language of the request (x-lang or Accept-Language: tr, en); if there is no text in that language, the text in the other language is returned.

Excluded options

If a product cannot quote, only that product's option is excluded; the other options are not affected. Excluded options are in the excludedOptions array:

• The most common reason is a field the product needs at the quote stage being missing. If you add the missing fields and get a new quote, that product's option is returned too. Product requirements: Eligibility › Product requirements.
• An excluded option has no quoteId; no order can be created with it.
• excludedOptions is only in the response of getting a quote; it is not in the retrieve response.
• The values you sent and the provider's own error codes are not written to this array.
• If every option is excluded, the request returns an error: 422 insurance.validation.invalid (with every missing field path) if fields the products need are missing, otherwise the providers' decline or availability error.

Option

Showing the options and consent

• For each option, show the buyer the provider's name, the premium, the coverage summary, the insurance company's name (underwriter.name) and, if present, its information text (underwriter.disclosureText), and the terms version.
• Do not preselect insurance. The buyer must explicitly confirm that they accept the terms and consent to their details being shared with the provider for the insurance.
• When creating the order, you send back the terms.version and terms.sha256 values of the option the buyer confirmed exactly as received: Orders › Consent.

Validity

• Each option is valid until expiresAt. The validity depends on the provider's product.
• An order cannot be created with an expired option (409 insurance.quote.expired); get a new quote.
• If the basket or the insured details change, get a new quote. When the order is bound to a payment, the payment's basket is compared with the quoted basket; if they differ, 409 insurance.quote.stale is returned.
• Only one order can be created from an option.

Retrieving a quote: GET /api/v1/insurance/quotes/{quoteId}

Returns a single option. data is the option object above. An expired option is returned with status: EXPIRED.

source lunixi-sign.sh
REQ_PATH="/api/v1/insurance/quotes/<quoteId>"
lunixi_sign GET "$REQ_PATH"
 
curl "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

If the ID is not found or belongs to another account, 404 insurance.quote.not_found is returned.

Contracted facilities: GET /api/v1/insurance/quotes/{quoteId}/facilities

For some insurance types, an option comes with a network of contracted health facilities; for example supplementary health insurance (SUPPLEMENTARY_HEALTH). This endpoint returns an option's contracted facilities in a given province. You can show the facilities to the buyer when they compare plans.

source lunixi-sign.sh
REQ_PATH="/api/v1/insurance/quotes/<quoteId>/facilities?cityCode=06"
lunixi_sign GET "$REQ_PATH"
 
curl "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

The facilities are in the data.items array of the response:

{
  "data": {
    "items": [
      { "name": "<facility name>", "cityCode": "06" }
    ]
  }
}

• The list is read from the option's provider connection on every request and is not stored; it can change over time. Facilities are sorted by name; at most 500 facilities are returned per request. There is no paging.
• The list can be read even if the option's validity period has ended.
• If the option has no contracted facility list, 412 insurance.facility.not_supported is returned without sending a request to the provider.
• If the ID is not found or belongs to another account, 404 insurance.quote.not_found is returned.
• If cityCode is missing or not two digits, 400 VALIDATION_ERROR is returned; if it is outside 01-81, 422 insurance.validation.invalid is returned with the field path cityCode.

Errors

Common codes: Flows › Responses and errors.

Related

• Orders and Payment Binding: creating an order with an option
• Insurance Types and Schemas: type fields and stages
• Selling Without a Basket Item: quotes without a basket source
• Data Formats: amount, time and identity formats