Endpoint Reference

This page summarizes each insurance endpoint. The full field descriptions, rules and examples are behind each endpoint's Details link.

The base address is https://api-gateway.lunixi.com.
Every endpoint requires a request signed with your API key: Flows › Authentication. /pay also requires a Bearer access token.
The common error codes (VALIDATION_ERROR, insurance.validation.invalid, insurance.idempotency.conflict, insurance.dependency.unavailable, insurance.internal.integrity) and the authentication errors apply to every endpoint: Flows › Responses and errors. The tables below give the endpoint-specific codes.
The body of a successful response is under data; the document endpoints return a PDF and the export endpoint returns CSV. On list endpoints, pagination information is in pageInfo: Pagination.

Summary

The Without a Lunixi payment column shows whether the endpoint can be used without taking a payment in Lunixi: Insurance-Only Integration.

Method	Path	`Idempotency-Key`	Without a Lunixi payment
`POST`	`/api/v1/insurance/products`	—	Yes
`GET`	`/api/v1/insurance/products`	—	Yes, without `paymentIntentId`
`GET`	`/api/v1/insurance/reference/{kind}`	—	Yes
`POST`	`/api/v1/insurance/quotes`	Optional	Yes, without `paymentIntentId`
`GET`	`/api/v1/insurance/quotes/{quoteId}`	—	Yes
`GET`	`/api/v1/insurance/quotes/{quoteId}/facilities`	—	Yes
`POST`	`/api/v1/insurance/orders`	Required	Yes
`GET`	`/api/v1/insurance/orders`	—	Yes
`GET`	`/api/v1/insurance/orders/{orderId}`	—	Yes
`POST`	`/api/v1/insurance/orders/{orderId}/bind-payment`	Optional	No
`POST`	`/api/v1/insurance/orders/{orderId}/confirm-payment`	Required	Yes
`POST`	`/api/v1/insurance/orders/{orderId}/issue-policy`	Required	Yes
`POST`	`/api/v1/insurance/orders/{orderId}/pay`	Required	Yes
`POST`	`/api/v1/insurance/orders/{orderId}/cancel`	Required	Yes
`POST`	`/api/v1/insurance/orders/{orderId}/refund-premium`	Required	Yes, with `externalRefund`
`GET`	`/api/v1/insurance/policies/{policyId}/document`	—	Yes
`GET`	`/api/v1/insurance/policies/{policyId}/receipt`	—	Yes
`GET`	`/api/v1/insurance/policies/{policyId}/certificate`	—	Yes
`POST`	`/api/v1/insurance/policies/{policyId}/claims`	Required	Yes
`GET`	`/api/v1/insurance/claims`	—	Yes
`GET`	`/api/v1/insurance/claims/{claimId}`	—	Yes
`GET`	`/api/v1/insurance/claims/{claimId}/document`	—	Yes
`POST`	`/api/v1/insurance/leads`	Required	Yes
`GET`	`/api/v1/insurance/leads`	—	Yes
`GET`	`/api/v1/insurance/leads/{leadId}`	—	Yes
`GET`	`/api/v1/insurance/reconciliation/summary`	—	Yes
`GET`	`/api/v1/insurance/reconciliation/orders`	—	Yes
`GET`	`/api/v1/insurance/reconciliation/export`	—	Yes

Eligibility and reference

`POST /api/v1/insurance/products`


What it does	Returns the insurance types offered for the basket items you will send. Read-only.
Request	`currency`, `context.items` (1-100 items; `insuranceData` is not stored), optional `insuranceType`.
Response	`200`; `data.products[]`: `insuranceType`, `typeObject`, `schemaVersion`, `basketItemIds`, `title`, `description`, `fields`, `prefill`, `providedFields`, `quoteReady`, `insuranceDataIssues`. An empty list means no insurance is offered.
Errors	`400 VALIDATION_ERROR`, `422 insurance.validation.invalid`
Webhook	—
Details	Eligibility › Before the payment

`GET /api/v1/insurance/products`


What it does	With `paymentIntentId`: the types offered for the items of a Lunixi payment. Without `paymentIntentId`: the types sold without a basket item.
Request	Query: `currency`, optional `paymentIntentId` and `insuranceType`.
Response	`200`; the same `data.products[]` as `POST`.
Errors	`400 VALIDATION_ERROR`, `422 insurance.validation.invalid` (`reason: currency_mismatch`)
Webhook	—
Details	Eligibility › After the payment, Without a basket item

`GET /api/v1/insurance/reference/{kind}`


What it does	Lists the Lunixi reference codes used in type fields (country, city, district, brand, model, occupation, address chain and so on). Provider codes are never returned.
Request	Path: `kind`. Query: `parentCode`, `limit` (1-100, default 25), `cursor`; `vehicleTypeCode` and `modelYear` in vehicle lists; `outerDoorNumber` in the building list.
Response	`200`; `data.items[]`: `code`, `label`, `parentCode`; `pageInfo`.
Errors	`400 VALIDATION_ERROR`; `422 insurance.validation.invalid` (`field: kind`, `reason: unknown_reference_kind` or `live_reference_unavailable`; `field: parentCode`, `reason: required`, `not_applicable`, `invalid_reference_code` or `invalid_enum`); `422 insurance.reference.unknown`
Webhook	—
Details	Insurance Types and Schemas › Reference codes

Quotes

`POST /api/v1/insurance/quotes`


What it does	Prices the insurance type for the insured and the insured items; returns one or more options.
Request	`insuranceType`, `currency`, the basket source (`context.items` or `paymentIntentId`; neither for types sold without a basket item), optional `schemaVersion` and `merchantOrderId`, and by type `policyholder`, `insured[]` and the type object. The items' context and pre-fill data complete the body; with `paymentIntentId` the body may be empty (Quote with pre-fill data).
Response	`201`; `data`: `insuranceType`, `schemaVersion`, `options[]`, `excludedOptions[]`.
Errors	`412 insurance.type.not_available`, `412 insurance.provider.not_integrated`, `422 insurance.reference.unknown`, `422 insurance.quote.declined`, `503 insurance.provider.unavailable`
Webhook	—
Details	Quotes › Getting a quote, Option

`GET /api/v1/insurance/quotes/{quoteId}`


What it does	Returns a single option; an expired option is returned with `status: EXPIRED`.
Request	Path: `quoteId` (`insq_…`).
Response	`200`; `data`: the option object.
Errors	`404 insurance.quote.not_found`
Webhook	—
Details	Quotes › Retrieving a quote

`GET /api/v1/insurance/quotes/{quoteId}/facilities`


What it does	Returns the option's contracted health facilities in the given city.
Request	Path: `quoteId`. Query: `cityCode` (`01`-`81`).
Response	`200`; `data.items[]`: `name`, `cityCode`. No pagination.
Errors	`404 insurance.quote.not_found`, `412 insurance.facility.not_supported`, `422 insurance.validation.invalid` (`field: cityCode`)
Webhook	—
Details	Quotes › Contracted facilities

Orders and collection

`POST /api/v1/insurance/orders`


What it does	Creates an order with the option the buyer confirmed. Sends no request to the provider and moves no money.
Request	`quoteId`, `consent.termsVersion`, `consent.termsSha256`, `consent.acceptedAt`, optional `merchantOrderId`.
Response	`201`; `data`: the order object (`paymentMode: NO_PAYMENT`).
Errors	`404 insurance.quote.not_found`, `409 insurance.quote.expired`, `409 insurance.order.state_conflict` (`reason: quote_already_ordered`), `422 insurance.validation.invalid` (`reason: terms_mismatch`)
Webhook	—
Details	Orders › Creating an order, Order object

`GET /api/v1/insurance/orders`


What it does	Lists your orders, newest first; Checkout Form orders are included.
Request	Query: `limit` (1-100, default 25), `cursor`, `paymentIntentId`, `merchantOrderId`.
Response	`200`; `data.items[]`: the order object; `pageInfo`.
Errors	`422 insurance.validation.invalid` (`field: cursor`)
Webhook	—
Details	Orders › Listing

`GET /api/v1/insurance/orders/{orderId}`


What it does	Returns a single order; you track the policy and document status with this endpoint.
Request	Path: `orderId` (`inso_…`).
Response	`200`; `data`: the order object.
Errors	`404 insurance.order.not_found`
Webhook	—
Details	Orders › Retrieving

`POST /api/v1/insurance/orders/{orderId}/bind-payment`


What it does	Binds the order to a Lunixi payment created with insured items. Used only in the flow linked to a Lunixi payment.
Request	`paymentIntentId`.
Response	`200`; `data`: the order object (`paymentMode: LUNIXI_PAYMENT`).
Errors	`404 insurance.order.not_found`, `409 insurance.quote.expired`, `409 insurance.quote.stale`, `409 insurance.order.state_conflict`, `409 insurance.order.premium_item_mismatch`, `412 insurance.order.payment_not_recorded`
Webhook	Policy events after the payment is captured: `insurance.policy.issued`, `insurance.policy.failed`, `insurance.refund.required`, `insurance.policy.document_ready`.
Details	Orders › Binding to a payment, Premium and Payment › With a Lunixi payment

`POST /api/v1/insurance/orders/{orderId}/confirm-payment`


What it does	Reports a premium you collected outside Lunixi; Lunixi forwards the notification to your provider through your connection.
Request	`payment.externalPaymentId`, `payment.paidAmount`, `payment.paidCurrency`, `payment.paidAt`, optional `payment.paymentProvider`.
Response	`200`; `data`: the order object (`paymentMode: EXTERNAL_PAYMENT`, `collectionStatus: COLLECTED`).
Errors	`404 insurance.order.not_found`, `409 insurance.quote.expired`, `409 insurance.order.state_conflict` (`reason: lunixi_payment`, `external_payment`, `collected_by_provider`), `422 insurance.validation.invalid` (`reason: premium_amount_mismatch` or `premium_currency_mismatch`)
Webhook	—
Details	Orders › Reporting a premium collected outside Lunixi

`POST /api/v1/insurance/orders/{orderId}/issue-policy`


What it does	Requests the policy after a premium collected outside Lunixi. No body is sent.
Request	Path: `orderId`.
Response	`200`; `data`: the order object (`policyStatus: PENDING`). The policy is issued in the background.
Errors	`404 insurance.order.not_found`, `409 insurance.order.state_conflict` (`reason: refund_started` or `collected_by_provider`), `412 insurance.premium.not_captured`
Webhook	`insurance.policy.issued`, `insurance.policy.failed`, `insurance.refund.required`, `insurance.policy.document_ready`
Details	Orders › Requesting the policy

`POST /api/v1/insurance/orders/{orderId}/pay`


What it does	Starts the premium charge on an order whose premium the provider collects (`premiumCollectedBy: PROVIDER`). Once the premium is charged, the policy is requested automatically.
Authentication	A Bearer access token and the signature headers together.
Request	`card` for a `CARD` product (PCI-DSS certified merchants only), optional `returnUrl`.
Response	`200`; `data.order` (the order object) and `data.providerPayment` (`insurancePaymentId`, `status`, `paymentInput`, `amount`, `currency`, `failureCode`, `nextAction`).
Errors	`403 insurance.card.pci_required`, `404 insurance.order.not_found`, `409 insurance.order.state_conflict`, `409 insurance.quote.expired`, `412 insurance.payment.merchant_payment_not_captured`, `422 insurance.payment.method_not_supported`, `422 insurance.card.invalid`, `422 insurance.reference.unknown`, `422 insurance.quote.declined`, `503 insurance.provider.unavailable`
Webhook	Policy events once the premium is charged; `insurance.policy.failed` (`errorCode: insurance.payment.declined`) if the charge is declined.
Details	Provider Collection

Cancellation and refund

`POST /api/v1/insurance/orders/{orderId}/cancel`


What it does	Opens a cancellation request at the provider for every issued policy. The result is finalized later. Cancelling does not refund the premium. No body is sent.
Request	Path: `orderId`.
Response	`200`; `data`: the order object (`policyStatus: CANCEL_PENDING`).
Errors	`404 insurance.order.not_found`, `409 insurance.order.state_conflict` (`reason: policy_not_issued`), `412 insurance.provider.not_integrated`
Webhook	`insurance.policy.cancelled`. If the provider rejects the cancellation, no event is sent; `errorCode` becomes `insurance.policy.cancel_failed`.
Details	Cancellation and Premium Refund › Policy cancellation

`POST /api/v1/insurance/orders/{orderId}/refund-premium`


What it does	Refunds the premium in a Lunixi payment, or records a refund you made outside Lunixi. Not used when the provider collected the premium.
Request	No body for a Lunixi payment. For a premium collected outside Lunixi, `externalRefund.externalRefundId` and `externalRefund.refundedAt`.
Response	`200`; `data`: the order object (`refundStatus: PENDING` or `REFUNDED`).
Errors	`404 insurance.order.not_found`, `409 insurance.order.state_conflict` (`reason: policy_active`, `policy_in_progress`, `already_refunded`, `collected_by_provider`), `412 insurance.premium.not_captured`, `422 insurance.validation.invalid`
Webhook	`insurance.refund.completed`
Details	Cancellation and Premium Refund › Premium refund

Policy documents

Documents are not stored by Lunixi; they are fetched from the provider on every request. A successful response is the PDF file itself (Content-Type: application/pdf, Cache-Control: no-store); an error response is the JSON error envelope. A document is available while the policy is ISSUED or CANCEL_PENDING.

`GET /api/v1/insurance/policies/{policyId}/document`


What it does	Returns the policy document as a PDF.
Request	Path: `policyId` (`insp_…`).
Response	`200`; PDF, file name `<policyId>.pdf`.
Errors	`404 insurance.policy.not_found`, `409 insurance.order.state_conflict` (`reason: policy_not_issued` or `policy_cancelled`), `503 insurance.document.unavailable`
Webhook	`insurance.policy.document_ready` when the document is ready.
Details	Policy Document

`GET /api/v1/insurance/policies/{policyId}/receipt`


What it does	Returns the policy's premium receipt as a PDF if the product provides a receipt.
Request	Path: `policyId`.
Response	`200`; PDF, file name `<policyId>-receipt.pdf`.
Errors	Those of the policy document, plus `412 insurance.document.not_supported`
Webhook	—
Details	Policy Document › Receipt

`GET /api/v1/insurance/policies/{policyId}/certificate`


What it does	Returns the policy's certificate as a PDF if the product provides a certificate.
Request	Path: `policyId`.
Response	`200`; PDF, file name `<policyId>-certificate.pdf`.
Errors	Those of the policy document, plus `412 insurance.document.not_supported`
Webhook	—
Details	Policy Document › Certificate

Claims

`POST /api/v1/insurance/policies/{policyId}/claims`


What it does	Reports a claim for an in-force policy to the provider. The documents are sent to the provider in this request and are not stored by Lunixi.
Request	Path: `policyId`. Body: `incidentAt`, `documents[]`.
Response	`201`; `data`: the claim (`status: SUBMITTED` or `UNKNOWN`).
Errors	`404 insurance.policy.not_found`, `409 insurance.claim.state_conflict`, `412 insurance.claim.not_supported`, `422 insurance.claim.rejected`, `503 insurance.provider.unavailable`
Webhook	`insurance.claim.submitted`, `insurance.claim.failed`
Details	Claims › Filing a claim

`GET /api/v1/insurance/claims`


What it does	Lists your claims, newest first.
Request	Query: `limit` (1-100, default 25), `cursor`, `orderId`, `policyId`, `status`.
Response	`200`; `data.items[]`: the claim; `pageInfo`.
Errors	`422 insurance.validation.invalid` (`field: cursor`)
Webhook	—
Details	Claims › Listing

`GET /api/v1/insurance/claims/{claimId}`


What it does	Returns a single claim.
Request	Path: `claimId` (`insclm_…`).
Response	`200`; `data`: the claim.
Errors	`404 insurance.claim.not_found`
Webhook	—
Details	Claims › Retrieving

`GET /api/v1/insurance/claims/{claimId}/document`


What it does	Returns the document the provider issued for the claim as a PDF; the claim must be `SUBMITTED`.
Request	Path: `claimId`.
Response	`200`; PDF, file name `<claimId>.pdf`.
Errors	`404 insurance.claim.not_found`, `409 insurance.claim.state_conflict` (`reason: claim_not_submitted`), `503 insurance.document.unavailable`
Webhook	—
Details	Claims › The provider's claim document

Leads

`POST /api/v1/insurance/leads`


What it does	For insurance types that return no quote, passes the buyer's details to the provider as a lead. There is no quote, premium, policy or document.
Request	`insuranceType`, optional `schemaVersion`, by type `policyholder`, the type object and `company`, optional `note`.
Response	`201`; `data`: the lead (`status: SUBMITTED` or `UNKNOWN`).
Errors	`412 insurance.type.not_available`, `422 insurance.lead.rejected`, `503 insurance.provider.unavailable`
Webhook	`insurance.lead.submitted`
Details	Leads › Submitting a lead

`GET /api/v1/insurance/leads`


What it does	Lists your leads, newest first; personal data is masked.
Request	Query: `limit` (1-100, default 25), `cursor`, `insuranceType`, `status`.
Response	`200`; `data.items[]`: the lead; `pageInfo`.
Errors	`422 insurance.validation.invalid` (`field: cursor`)
Webhook	—
Details	Leads › Listing

`GET /api/v1/insurance/leads/{leadId}`


What it does	Returns a single lead; personal data is masked.
Request	Path: `leadId`.
Response	`200`; `data`: the lead.
Errors	`404 insurance.lead.not_found`
Webhook	—
Details	Leads › Retrieval

Reconciliation

`GET /api/v1/insurance/reconciliation/summary`


What it does	Returns the policy and premium totals of the period per connection, currency and premium collector.
Request	Query: `from`, `to`, optional `connectionId`, `insuranceType`, `currency`.
Response	`200`; `data`: `period`, `filters`, `groups[]`, `generatedAt`.
Errors	`422 insurance.validation.invalid` (`field: filter.from` or `filter.to`)
Webhook	—
Details	Reconciliation Report › Summary

`GET /api/v1/insurance/reconciliation/orders`


What it does	Lists the orders behind the summary together with their policies.
Request	The filter parameters, `limit` (1-100, default 100), `cursor`.
Response	`200`; `data.items[]`: the report row; `pageInfo`.
Errors	`422 insurance.validation.invalid` (`field: filter.*` or `cursor`)
Webhook	—
Details	Reconciliation Report › Rows

`GET /api/v1/insurance/reconciliation/export`


What it does	Returns the report rows as CSV; each policy is one line.
Request	The filter parameters, `cursor` to continue a truncated file.
Response	`200`; `text/csv`, at most 20,000 orders per file.
Errors	`422 insurance.validation.invalid` (`field: filter.*`)
Webhook	—
Details	Reconciliation Report › CSV

Insurance-Only Integration: the end-to-end flow without a Lunixi payment
Flows: authentication, Idempotency-Key and the error envelope
Webhook Events: event payloads and subscription
Error Codes: the meaning of every code

Reconciliation Report Insurance Types and Schemas

Endpoint Reference

Summary

Eligibility and reference

POST /api/v1/insurance/products

GET /api/v1/insurance/products

GET /api/v1/insurance/reference/{kind}

Quotes

POST /api/v1/insurance/quotes

GET /api/v1/insurance/quotes/{quoteId}

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

Orders and collection

POST /api/v1/insurance/orders

GET /api/v1/insurance/orders

GET /api/v1/insurance/orders/{orderId}

POST /api/v1/insurance/orders/{orderId}/bind-payment

POST /api/v1/insurance/orders/{orderId}/confirm-payment

POST /api/v1/insurance/orders/{orderId}/issue-policy

POST /api/v1/insurance/orders/{orderId}/pay

Cancellation and refund

POST /api/v1/insurance/orders/{orderId}/cancel

POST /api/v1/insurance/orders/{orderId}/refund-premium

Policy documents

GET /api/v1/insurance/policies/{policyId}/document

GET /api/v1/insurance/policies/{policyId}/receipt

GET /api/v1/insurance/policies/{policyId}/certificate