Claims

For an issued policy, you report the claim to your provider through your provider connection. You file the claim with POST /api/v1/insurance/policies/{policyId}/claims and track its outcome from the claim endpoint and by webhook.

• A claim is a notification. Lunixi passes the claim to your provider and shows the outcome of that submission. The assessment of the claim (acceptance, rejection, payment) is done by the insurance company; its result is not part of the claim.
• Lunixi does not store the document. The document you send is processed only in this request and passed to your provider. The document's content is not included in responses, request logs or webhooks.
• A claim belongs to a policy. Insurance is per unit; take the policyId value from the order's policies[] array: Order object.

Authentication and signing: Flows › Authentication.

Policies that accept a claim

What counts is the status of that policy (policies[].policyStatus), not of the order. A policy has at most one open claim at a time: a claim with status PENDING, SUBMITTED or UNKNOWN is open. While a claim that reached the provider (SUBMITTED) exists, no second claim can be filed for the same policy. A FAILED claim does not prevent a new one.

Flow

Filing a claim: POST /api/v1/insurance/policies/{policyId}/claims

Idempotency-Key is required. See Retries and Idempotency-Key.

Documents

• The total size of the documents may be at most 3 MB after base64 decoding. A request over the limit returns 400 VALIDATION_ERROR or 422 insurance.validation.invalid (field: documents, reason: too_large).
• The file must be a PDF; a document whose content is not a PDF returns 422.
• The document may carry your buyer's personal data. Lunixi does not store the document and passes it to the provider; the document's content is not included in request logs.

source lunixi-sign.sh
REQ_PATH="/api/v1/insurance/policies/<policyId>/claims"
CONTENT=$(base64 < cancellation-proof.pdf | tr -d '\n')
BODY=$(printf '{"incidentAt":"2026-10-12T09:30:00+03:00","documents":[{"kind":"CANCELLATION_PROOF","contentType":"application/pdf","contentBase64":"%s"}]}' "$CONTENT")
printf '%s' "$BODY" > claim.json
lunixi_sign POST "$REQ_PATH" "$BODY"
 
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: insurance-claim-1001" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "Digest: $DIGEST" \
  -H "X-Signature: $SIGNATURE" \
  --data-binary @claim.json

The body can be large because of the document; so the example sends the body from a file. Compute Digest from exactly the body you write to the file.

Response

When the request completes, it returns 201 with the claim object in data. If the provider recorded the claim, status is SUBMITTED; if the outcome is not final, it is UNKNOWN.

Outcomes

If the outcome cannot be verified, the claim is reviewed and stays UNKNOWN until its outcome is final.

Retries and Idempotency-Key

• Filing a claim passes the document to the provider in the same request. The request can take up to 45 seconds; set your client's timeout accordingly.
• If you did not get a response after a timeout or a 5xx, repeat the request with the same Idempotency-Key and the same body. If the claim was opened on the first attempt, no new claim is opened; the existing claim is returned with its current status and the document is not sent to the provider again.
• The same key returns the same claim whatever its status. To send a FAILED claim again, generate a new key.
• If you use the same key with a different request (another policy, incident time or document), 409 insurance.idempotency.conflict is returned.

Claim object

The claim does not contain the provider's claim reference or error codes.

Statuses

SUBMITTED and FAILED are final; they do not change.

Listing: GET /api/v1/insurance/claims

Returns your claims from newest to oldest, in cursor-based pages.

In the response, the claims are in the data.items array; pagination information is in pageInfo. A malformed cursor returns 422 insurance.validation.invalid (field: cursor).

source lunixi-sign.sh
REQ_PATH="/api/v1/insurance/claims?limit=25&policyId=<policyId>"
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"

Retrieving: GET /api/v1/insurance/claims/{claimId}

Returns a single claim. In the response, data is the claim object. Use this endpoint to track a claim whose outcome is UNKNOWN or to verify an outcome you did not receive by webhook.

The provider's claim document: GET /api/v1/insurance/claims/{claimId}/document

Returns the document the provider issued for the claim as a PDF. The document is available only when the claim is SUBMITTED.

• Lunixi does not store the document. It is fetched from the provider on every request and passed to you as is.
• A successful response returns 200 and the body is the PDF file itself; there is no JSON envelope. Error responses are the JSON error envelope; tell them apart by the response's Content-Type header.

source lunixi-sign.sh
REQ_PATH="/api/v1/insurance/claims/<claimId>/document"
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" \
  -o claim.pdf

Errors

Common codes: Flows › Responses and errors. Details of the codes: Error Codes › Claims.

State conflict

Field violations

Related

• Orders and Payment Binding: policies[] and the policy status
• Webhook Events: insurance.claim.submitted and insurance.claim.failed
• Error Codes: the claim codes
• Insurance Types and Schemas: TICKET_CANCELLATION