Skip to main content

Claims API

There are two sets of claim endpoints. Which one you call depends on who is acting:

  • The organization claims API is read-only and is called with your organization's token. Use it to list and read the claims your organization handles.
  • The traveller claims API is called with a traveller's token. A traveller uses it to create, fill in, submit and withdraw their own claims. The Claims Widget is built on these endpoints.

The examples below use Sitata's staging environment (https://staging.sitata.com). In production, use https://www.sitata.com.

Organization Claims API

These endpoints use your organization's authentication token:

Authorization: TKN YOUR_COMPANY_TOKEN
warning

The organization claims API only returns claims your organization handles, meaning claims on policies that include a product your organization owns. If you only sell policies, the list will be empty and reading a claim will return 401. Follow those claims with webhooks instead. See Who Can See What.

List claims

GET /api/v2/org/:company_id/claims

This returns the claims your organization handles, newest first (by created_at). The response is paginated:

Query parameterDescription
pageThe page to return, starting at 1.
page_sizeHow many claims to return per page. Defaults to 100.

There are no other filters. You can't filter the list by status, date, subscription or traveller.

curl "https://staging.sitata.com/api/v2/org/YOUR_COMPANY_ID/claims?page=1&page_size=50" \
-H "Authorization: TKN YOUR_COMPANY_TOKEN" \
-H "Accept: application/json"

The pagination details come back in the response headers: total, total-pages, page-number, per-page, and a link header with the first, prev, next and last URLs.

The body is an array of claim objects (see The Claim Object). List items are summaries: they include the claim's own fields, but the related records (subscription, subscription_id, user, claim_forms, answers, attachments) are null or empty. To get them, read the claim.

[
{
"id": "8b0d6a4e-2f63-4a51-9a0e-3c9f2d7b1e55",
"human_id": "4F9A2C",
"status": 2,
"source": "reimbursement",
"created_at": "2026-10-20T14:03:11.204512Z",
"updated_at": "2026-10-21T09:12:40.118230Z",
"currency_code": "USD",
"value_requested": 125000,
"value_accepted": null,
"evaluating_at": "2026-10-21T09:12:40.117955Z",
"adjuster_at": null,
"payment_at": null,
"outcome_desc": null,
"payment_ref": null,
"is_automatic": false,
"trigger_event": null,
"category_key": "medical",
"pending_bank_info": false,
"subscription_id": null,
"subscription": null,
"user": null
}
]

Retrieve a claim

GET /api/v2/org/:company_id/claims/:id

:id can be the claim's UUID or its human_id.

curl "https://staging.sitata.com/api/v2/org/YOUR_COMPANY_ID/claims/4F9A2C" \
-H "Authorization: TKN YOUR_COMPANY_TOKEN" \
-H "Accept: application/json"

The response is the full claim, with its related records filled in:

  • subscription: the policy, in the same shape as the subscription endpoints return it, including its products and benefits.
  • subscription_id
  • user: the claimant.
  • claim_forms: the forms the claimant filled in.
  • answers and attachments: the answers and documents from the claim's current submission.

Errors:

StatusWhen
401Your organization doesn't handle this claim.
404No claim has that UUID or human_id.

The Claim Object

These are the fields to use in an integration. The response also has other fields that Sitata's own apps use, such as conversations and SLA timers. Those fields may be null or empty for your organization, so don't build on them.

AttributeTypeDescription
idStringThe claim's UUID.
human_idStringA short, human-friendly reference (for example 4F9A2C). Show it to your customer. Every endpoint that takes a claim id also accepts it.
statusIntegerThe claim's lifecycle status. See The Claim Lifecycle.
sourceStringreimbursement for a claim the traveller filed. direct_settlement for a loss Sitata recorded from a guarantee of payment to a medical provider. Direct-settlement claims never appear in the traveller API.
created_at / updated_atDateTimeTimestamps.
currency_codeStringThe currency of the claim, which is the subscription's currency (ISO 4217).
value_requestedIntegerThe amount the claimant asked for, in the currency's smallest unit.
value_acceptedIntegerThe amount approved, in the currency's smallest unit. It is 0 when a claim is denied and null until a decision is made.
evaluating_atDateTimeWhen the claim moved to evaluating.
adjuster_atDateTimeWhen the claim was accepted or denied.
adjuster_name / adjuster_emailStringThe adjuster who accepted or denied the claim.
outcome_descStringThe adjuster's explanation of the decision. When a claim is denied, this is the reason.
payment_atDateTimeWhen the payment was issued.
payment_refStringThe payment or transfer reference.
pending_bank_infoBooleantrue when status is 4, meaning the claimant needs to provide bank details.
payment_gatewayStringThe payout gateway (wise).
is_automaticBooleantrue for a claim Sitata created automatically (for example Flight Protection).
trigger_eventStringFor automatic claims, what caused the claim: flight_delayed, cancellation, diversion, missed_connection, baggage_delayed or baggage_lost.
air_segment_idStringFor automatic claims, the flight segment the claim is for.
category_keyStringThe claim category (for example medical or baggage). It comes from the claimant's answer when they submit, and an adjuster can change it.
subscription_idStringThe policy the claim is made against. Only included when you read a single claim.
subscriptionObjectThe full policy. Only included when you read a single claim.
userObjectThe claimant.
claim_formsArrayThe forms attached to the claim, with their questions. See Claim Forms And Answers.
answersArrayThe claimant's answers: id, claim_form_element_id, value, claim_id, created_at, updated_at.
attachmentsArrayThe uploaded documents: id, claim_form_element_id, file.original (a signed download URL that expires after 24 hours), deleted_at, created_at, updated_at.
current_submission_idStringThe submission that answers and attachments belong to. It is null until the claim has been submitted once.
catastrophe_eventObjectA catastrophe event the claim is tagged to (id, code, name, peril, kind), or null.

Changing a claim's status

Partners can't change a claim's status with an organization token. Sitata and the product owner's adjusters assess and pay claims in the Sitata dashboard. Each change is delivered to you as a webhook.

Traveller Claims API

These endpoints act as the traveller and use the traveller's own authentication token. See Create Travellers for how to create a traveller and store their authentication_token.

Authorization: TKN TRAVELLER_AUTHENTICATION_TOKEN

If you call these endpoints with an organization token, they return 400 with the message "This endpoint can only be requested by a user. Please use a user authentication token."

tip

You may not need to call these endpoints at all. The Claims Widget gives your customer this whole flow, including bank-detail collection, and you can embed it with the same traveller token (userToken). Only build on these endpoints if you need a fully native experience.

MethodPathPurpose
GET/api/v2/claimsList the traveller's claims (paginated with page and page_size, newest first).
GET/api/v2/claims/:idRead one of the traveller's claims (by UUID or human_id).
POST/api/v2/claimsStart a new draft claim on one of the traveller's subscriptions.
PUT/api/v2/claims/:idSave draft answers and the requested amount.
POST/api/v2/claims/:claim_id/attachmentsUpload a document.
DELETE/api/v2/claims/:claim_id/attachments/:idRemove a document.
PATCH/api/v2/claims/:claim_id/submitSubmit the claim.
PATCH/api/v2/claims/:claim_id/restartSend a new or submitted claim back to draft (new).
PATCH/api/v2/claims/:claim_id/withdrawWithdraw the claim.

A traveller can only file a claim on a subscription they own (the subscription's user). Otherwise the request returns 401.

1. Start a draft claim

curl -X POST "https://staging.sitata.com/api/v2/claims" \
-H "Authorization: TKN TRAVELLER_AUTHENTICATION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"claim": {
"subscription_id": "0c7f1a8e-6d0b-4c1e-9a52-7b7f3f1c2d10"
}
}'

The response is the new claim with status 0 (new). It already has:

  • its human_id;
  • its currency_code, copied from the subscription;
  • its claim_forms, the questions to ask, taken from the subscription's products.

Claim forms and answers

Each entry in claim_forms has a list of elements, sorted by sort_order. Each element has a type:

typeElementHow to answer
0HeaderDisplay only. It takes no answer.
1Numbervalue is the number as a string.
2Short textvalue is the text.
3Long textvalue is the text.
4Single choicevalue is the chosen entry's value from the element's choices.
5Multiple choicevalue is the chosen values joined with a pipe character, for example flight|hotel.
6FileUpload one or more documents for this element (see step 3).

Some elements have children. Show a child element only when its parent's answer matches the child's if_parent_val. For a multiple-choice parent, show it when any chosen value matches.

If a form has a category_element_id, that element sets the claim's category. You must answer it before submitting, or the submit returns 422 with {"errors": "missing_category_answer"}.

An answer looks like this:

{ "claim_form_element_id": "3f0e5b8a-1c2d-4e6f-8a9b-0c1d2e3f4a5b", "value": "medical" }

Sitata doesn't check that the form is complete or that the requested amount is filled in. Your UI is responsible for that.

2. Save progress (optional)

curl -X PUT "https://staging.sitata.com/api/v2/claims/4F9A2C" \
-H "Authorization: TKN TRAVELLER_AUTHENTICATION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"claim": {
"value_requested": 125000,
"answers": [
{ "claim_form_element_id": "3f0e5b8a-1c2d-4e6f-8a9b-0c1d2e3f4a5b", "value": "medical" },
{ "claim_form_element_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "value": "Treated for food poisoning in Lisbon" }
]
}
}'

This saves draft answers so the traveller can come back later. Each call replaces the draft answers with the list you send.

3. Upload documents

Upload each file as multipart/form-data, linked to the form's file element:

curl -X POST "https://staging.sitata.com/api/v2/claims/4F9A2C/attachments" \
-H "Authorization: TKN TRAVELLER_AUTHENTICATION_TOKEN" \
-F "claim_form_attachment[claim_form_element_id]=7d6c5b4a-3e2f-4a1b-9c8d-7e6f5a4b3c2d" \
-F "claim_form_attachment[file]=@/path/to/receipt.pdf"

The response is the attachment. Its file.original is a signed download URL that expires after 24 hours. To remove an attachment before you submit, call DELETE /api/v2/claims/:claim_id/attachments/:id. Removed attachments are kept but marked with deleted_at.

info

Upload documents before you submit. When a claim is submitted, the documents uploaded since the last submission are attached to the new submission. A document uploaded after submission is held for the next submission, and it doesn't appear in the claim's attachments until then.

4. Submit

curl -X PATCH "https://staging.sitata.com/api/v2/claims/4F9A2C/submit" \
-H "Authorization: TKN TRAVELLER_AUTHENTICATION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"claim": {
"value_requested": 125000,
"answers": [
{ "claim_form_element_id": "3f0e5b8a-1c2d-4e6f-8a9b-0c1d2e3f4a5b", "value": "medical" },
{ "claim_form_element_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "value": "Treated for food poisoning in Lisbon" }
]
}
}'
warning

Always send the complete list of answers with the submit request. Submitting discards any saved draft answers and records only the answers in the request body as the submission.

Submitting moves the claim to submitted (1). It saves the answers, documents and form versions as a fixed submission, alerts the handling adjusters, and sends the 600 webhook. Submitting is only possible from new. If the claim is in any other status, the request does nothing and returns the claim unchanged.

5. Edit after submitting (restart)

curl -X PATCH "https://staging.sitata.com/api/v2/claims/4F9A2C/restart" \
-H "Authorization: TKN TRAVELLER_AUTHENTICATION_TOKEN"

This sends a new or submitted claim back to new so the traveller can change it and submit again. Once an adjuster has started evaluating the claim, it can't be restarted. When you resubmit, send the full set of answers again and upload any documents the new submission should include. Each submission is recorded separately, so the adjuster can still see earlier submissions. Restarting a claim doesn't send a webhook. Resubmitting sends 600 again.

6. Withdraw

curl -X PATCH "https://staging.sitata.com/api/v2/claims/4F9A2C/withdraw" \
-H "Authorization: TKN TRAVELLER_AUTHENTICATION_TOKEN"

This moves the claim to withdrawn (-2) and sends the 607 webhook. If the claim's workflow doesn't allow withdrawal from its current status, the request returns 422 with {"errors": "invalid_status"}. A claim that is already final (paid, denied or withdrawn) can never be withdrawn.

Payout details

When a claim reaches pending_bank_info (4), the traveller has to say where the payment should go. Sitata collects these details through Wise. The Claims Widget and Sitata's hosted claim page both handle this step, including the extra checks Wise sometimes asks for, and we recommend using one of them. Sitata never stores raw bank details on the claim. Once Wise confirms the transfer, the claim moves to payment_issued (5).

For the full request and response reference, see the API reference.