Skip to main content

Claims Integration

Every policy (subscription) sold through Sitata can produce claims. This section explains how claims work and what parts of the lifecycle your platform can see or drive.

A claim always belongs to one subscription: the policy the traveller is claiming against. From that subscription the claim inherits:

  • its currency (currency_code), which is the subscription's currency;
  • its claim forms, which are the questions defined on the subscription's products;
  • its handlers, the organizations responsible for assessing it. These are Sitata and the owner (insurer or underwriter) of each product on the policy.

Each claim also has a short, human-friendly reference, human_id (for example 4F9A2C). Show it to your customer and use it in support conversations. Wherever the API takes a claim id, you can pass either the claim's UUID or its human_id.

Who Can See What

What your organization can access depends on its role in the claim:

Your roleOrganization claims API (/api/v2/org/:company_id/claims)Claim webhooks (600–607)
Product owner / handler: you own a product on the claimed policyYes. You can list and read the claims you handle.Yes
Selling partner: the policy belongs to your organization, but you don't own the productNo. The list returns no claims, and reading a claim returns 401.Yes
Traveller (the claimant), using their own tokenn/a. They use the traveller endpoints instead.n/a
info

If you distribute policies (for example as a travel agency or booking platform), you will usually not be a handler. Use webhooks to follow your customers' claims, and give your customers the Claims Widget or the traveller API to file and track them.

Choosing An Integration

There are four ways to integrate claims, and most integrations combine two or three of them.

OptionBest forWhat it gives you
Claims WidgetMost partnersA complete, branded claims portal you embed in your own site. Your customer can file a claim, answer the claim form, upload documents, track status, chat with support and give bank details for payment. It needs no server-side claims code.
Traveller claims APIPartners building a fully custom, native claims UI (for example inside a mobile app)The endpoints the widget itself uses, called with the traveller's token: create, update, upload documents, submit, withdraw.
Claim webhooksKeeping your systems in syncA signed event each time a claim is submitted, moves to evaluation, is accepted or denied, is reopened or withdrawn, or needs bank details.
Organization claims APIProduct owners and handlers: reporting, back-office reconciliationRead-only, paginated access to every claim your organization handles.

A typical distributor integration looks like this:

  1. Embed the Claims Widget in your customer portal. Pass a userToken so your customer doesn't have to sign in a second time.
  2. Subscribe to the claim webhooks so your CRM or support tooling knows when a claim is filed and when it is decided.
  3. Use each webhook's subscription_id and user_id to match the claim to your own policy and customer records.
tip

If you sell Parametric Flight Protection, claims are created automatically and only need the customer's payout details. See Flight Protection Claims & Payouts for that flow.

The Claim Lifecycle

A claim's status is an integer:

statusNameMeaning
0newA draft. The traveller has created the claim but not submitted it, or it was sent back to draft so they could edit it.
1submittedThe traveller submitted it. The answers and documents are frozen as a submission.
2evaluatingAn adjuster is reviewing the claim.
3acceptedThe claim was approved. value_accepted is the approved amount.
4pending_bank_infoApproved and waiting for the traveller's payout (bank) details.
5payment_issuedPaid. This is a final status.
-1rejectedDenied. outcome_desc holds the reason. This is a final status.
-2withdrawnWithdrawn. This is a final status.

The default path is:

new ──submit──▢ submitted ──▢ evaluating ──▢ accepted ──▢ pending_bank_info ──▢ payment_issued
└─▢ rejected

Some other moves are also possible:

  • Back to draft. The traveller can send a new or submitted claim back to new to edit it, and then resubmit it.
  • Reopen. An adjuster can reopen an evaluating, accepted or pending_bank_info claim, which sends it back to new.
  • Withdraw. A claim can be withdrawn from any status that isn't final.
  • Paid without bank details. An adjuster can mark an accepted claim as paid directly, without asking for bank details.
info

Assessing a claim (moving it to evaluating, then accepting or denying it) and paying it are done by Sitata and the product owner's adjusters in the Sitata dashboard. Partners can't do these through the API. Your integration only observes these changes, through webhooks or by reading the claim.

The exact transitions are controlled by a workflow that can be set up for each product and claim category. The ones above are the default.

Amounts (value_requested, value_accepted) are integers in the currency's smallest unit. For example, 125000 with currency_code "USD" means $1,250.00.

What Isn't Supported

To save you time, here is what the API can't do today:

  • Partners can't create or submit claims with their organization token. You can file a claim through the API only as the traveller, with that traveller's own token. See Traveller Claims API.
  • Partners can't assess claims. There are no partner-facing endpoints for accepting, denying or paying a claim.
  • The organization claims list has no filters. It returns every claim you handle, newest first, one page at a time. You can't filter it by status, date, subscription or traveller.
  • Links to assistance cases aren't exposed. Sitata's team may link a claim to an assistance case, but that link isn't part of the partner API.
  • The widget doesn't send browser events about claim progress. Use the webhooks instead.

Next, the Claims API covers the endpoints and the claim object in detail.