Claimity API

API Documentation

Technical reference and guides for integrating with Claimity.

Overview

The API uses HTTPS methods and RESTful endpoints to create, edit, and manage resources in the system. JSON is used as the exchange format.

First Steps

This API offers comprehensive access to core functions. Whether integrations, automation, or custom applications – the API provides flexibility for connecting Claimity to your systems.

Interface Extension

  • •Check the changelog regularly to stay up to date.
  • •Non-backward-incompatible changes can be introduced without changing the API version.
  • •You will be informed in good time about significant changes.

First Steps

How to start with the API:

1

Create Key Pair

As an organization admin, you can create a key pair in the organization settings of your Claimity account. Subsequently, download the Private Key and keep it safe.

2

Authenticate

Using the created key pair and your Client ID, you can authenticate yourself against the Claimity API and thus obtain an Access Token for your requests.

3

Prepare DPoP Header

To send a request to the API, it is necessary to create a DPoP header. This header is signed with the Private Key and secures the request against potential security risks.

4

First Request

Send an authenticated request to an endpoint with your Access Token and the DPoP header.

Example Request

curl -X GET \
  https://app.claimity.ch/v1/experts/cases \
  -H 'Accept: application/json' \
  -H 'Authorization: DPoP {access-token}' \
  -H 'DPoP: {dpop-header}

Python Notebooks

For a quick start, we provide Python notebooks with which you can execute API queries and view the responses directly.

View Notebooks on GitHub

Report Issue

If you have encountered an error, we will help. Ensure beforehand that the problem is reproducible.

Before Reporting

  • ✓Check reproducibility
  • ✓Perform API tests with Postman/Insomnia
  • ✓Collect details on request and response
  • ✗Do not send access data in the report

Submit Report

Please describe steps to reproduce. Our support will check the case promptly and get back to you as soon as possible.

Report Issue

Note: The API is provided based on this documentation. There is no guided implementation or code support.

Changelog

All changes and updates of the current API version at a glance.

2026-08-02

Reworked the sync filters: updatedSince is now lastChangedSince (both endpoints /v1/insurers/claims and /v1/experts/cases) — the filter now carries the name of the field it filters (LastChangedAt). New: lastReportApprovedSince on /v1/insurers/claims returns only claims whose latest report approval is at/after the given instant (claims without an approved report never match). completedFrom/completedTo are unchanged and filter the moment of the most recent completion.

2026-07-15

Expert API: new endpoint to reopen a completed case (POST /v1/experts/cases/{caseId}:reopen, returns 204). List endpoints gained filters (free-text search q, created/completed date ranges) and an updatedSince cursor for incremental sync. Cases now expose LastChangedAt; claims additionally expose LastReportApprovedAt. Create and upload endpoints now return 201 Created. Every response now returns an X-Correlation-Id header (echoing a valid inbound one) for end-to-end tracing; on errors it is also the ProblemDetails instance.

2026-06-09

Added new "Special Appraisals" category including schema and payload structure.

2025-12-30

Addition of a new endpoint to the insurer API for validating the case structure.

2025-12-28

First API version published.

Authentication

The Claimity Partner API uses OAuth 2.0 Client Credentials with JWT Client Assertion (RS256) and additionally secures every request with DPoP Proof-of-Possession (ES256). The Access Token is bound to your DPoP key (cnf.jkt): use one key for the whole session — the token request and every API call — and sign the token request itself with a DPoP proof.

Authentication Flow

How the OAuth2 Client-Credentials Flow works.

Authentication Flow Sequence Diagram (OAuth2 Client Credentials + DPoP)

Process

  1. Key Pair: Organization creates RSA Key Pair in Claimity (Private Key is stored securely).
  2. JWT Client Assertion: Client generates a short-lived JWT (RS256).
  3. Token Request: Client sends POST /v1/oauth/token (Client-Credentials + Assertion) with a DPoP proof, which binds the issued token to the DPoP key.
  4. Validation: Auth server checks signature of the assertion and permissions and returns Token Response.
  5. Query URL: The client creates the query URL (incl. query parameters).
  6. DPoP Proof: Client creates a DPoP JWT (ES256) per request bound to method + URL, signed with the same key used for the token request.
  7. API Call: Client calls endpoint with Authorization: DPoP access_token and DPoP: ….
  8. Response: API checks Token/DPoP and processes the request / returns the response.

Read Access Token

For partner integrations, your organization authenticates via a signed JWT Client Assertion.

Prerequisites

  • •Client ID (e.g. org-expo-00001) readable from Claimity organization settings
  • •Private RSA Key from Claimity organization settings (keep safe and never share)

Token Endpoint

URLPOST https://app.claimity.ch/v1/oauth/token
Content-Typeapplication/x-www-form-urlencoded
Form Fields
grant_type = client_credentials
client_id = <Your client id>
client_assertion_type = urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion = <JWT (RS256)>
scope (optional)

URL

POST https://app.claimity.ch/v1/oauth/token

Content-Type

application/x-www-form-urlencoded

Form Fields

grant_type = client_credentials
client_id = <Your client id>
client_assertion_type = urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion = <JWT (RS256)>
scope (optional)
JWT Client Assertion (RS256)

The assertion is a short-lived JWT (10 minutes) and is signed with your RSA Private Key.

  • •iss/sub = client_id
  • •aud = https://app.claimity.ch/realms/claimity/protocol/openid-connect/token
  • •jti = UUID (unique)
  • •iat/exp = “now” / “now+90s”
  • •kid (optional)
Example: Token Request (cURL, placeholder)
curl -X POST \
  'https://app.claimity.ch/v1/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=org-expo-00001' \
  -d 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
  -d 'client_assertion=<RS256-JWT-CLIENT-ASSERTION>' \
  -d 'scope=roles'

Token Response

The response contains an access_token. Important: For API calls, this token is used as a DPoP Token.

Send API Requests

Every request additionally requires a DPoP Proof JWT. A fresh proof is generated per request and signed (ES256) to bind the request to method + URL, but always with the same key the Access Token is bound to (cnf.jkt). A proof signed with a different key is rejected with 401 "Access token is not bound to the DPoP proof key".

Required Headers

AuthorizationDPoP {access_token}
DPoP{dpop_proof_jwt}
Acceptapplication/json
Content-Typeapplication/json

Authorization

DPoP {access_token}

DPoP

{dpop_proof_jwt}

Accept

application/json

Content-Type

application/json
DPoP Proof Content
  • •htu must be the exact URL incl. query string
  • •htm must correspond exactly to the HTTP method (GET/POST/PUT/DELETE)
  • •jti must be new per request (no replays)
  • •iat must be within the allowed time window (avoid clock skew)
  • •ath = base64url(SHA-256(access_token))
Example: Authenticated API Call (cURL)
curl -X GET \
  'https://app.claimity.ch/v1/experts/cases?page=1&size=50' \
  -H 'Accept: application/json' \
  -H 'Authorization: DPoP {access_token}' \
  -H 'DPoP: {dpop_proof_jwt}'
Troubleshooting: 401 invalid_dpop

Common causes:

  • •not bound: request signed with a different key than the token — reuse the single session key and send a DPoP proof on the token request
  • •htu mismatch: URL must be exact incl. query
  • •htm mismatch: Method must match
  • •iat outside window: Correct system time
  • •replay: jti must be new per request
  • •ath mismatch: SHA-256(access_token) base64url

Correlation ID

Every response returns an X-Correlation-Id header. Claimity uses the same id in its server logs and, on errors, as the instance field of the application/problem+json body — log it and include it in support requests.

You can also supply your own id to trace a request end-to-end: send an X-Correlation-Id request header with a short, printable token (≤ 80 characters). A valid value is echoed back unchanged; an invalid or oversized one is ignored and Claimity generates its own. The correlation id is independent of DPoP (the proof binds only method + URL), so adding this header does not affect signing.

API Basics

Core concepts and conventions used throughout the API.

Request Format

Every request consists of Method, URL, optional Query Parameters, Headers and (for POST/PUT) a JSON Body.

URL Structure

Base URL: https://app.claimity.ch
Path: /v1/<resource>
Query: e.g. ?page=1&size=50
Example URL
https://app.claimity.ch/v1/…?page=1&size=50

HTTP Methods

GETRetrieve resources
POSTCreate resources
PUTReplace/update resources
DELETEDelete resources

Typical Headers

  • •Accept: application/json
  • •Content-Type: application/json (for JSON Body)
  • •Authorization: DPoP <access_token>
  • •DPoP: <dpop_proof_jwt>

Response Format

Responses are generally JSON (Content-Type: application/json) and use HTTP status codes to signal success/error.

Success Responses

  • •2xx (e.g. 200, 201, 204)
  • •Body usually contains an object or a list
Example (Object)
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "…",
  "…": "…"
}

Error Responses (ProblemDetails)

  • •4xx/5xx (e.g. 400, 401, 403, 404, 429, 500)
  • •Body follows a ProblemDetails-like structure
Example (Problem JSON)
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "…"
}

Rate Limiting

The Partner API is protected by rate limiting to ensure fair usage and stability. Limits are applied per client partition.

Anonymous validation

POST /v1/insurers/claims:validate is usable without a token and therefore limited more strictly.

  • •FixedWindow: 10 requests/minute per client/IP

Standard for Partner API

For standard endpoints, the number of requests is slightly limited.

  • •TokenBucket: approx. 60 Requests/Minute, Burst up to 20, Queue 0

Document Routes

For endpoints with .../documents..., stricter limits apply (e.g. for upload/download).

  • •TokenBucket: approx. 20 Requests/Minute, Burst up to 10, Queue 0

Token Endpoint

The token endpoint is strictly limited to prevent possible attacks.

  • •Fixed Window: 10 Requests/Minute per Client
When a limit is reached (HTTP 429)
  • •Response: 429 Too Many Requests (Rejection Code 429)
  • •Optional Header: Retry-After
  • •Diagnostic/Policy Hint: X-RateLimit-Policy
  • •Body: Problem JSON

Recommendations for Clients

  • •Retry 429 requests with backoff and respect Retry-After.
  • •Throttle document uploads/downloads.
  • •Bursts are limited (no queuing) – high parallelism leads to 429 faster.

Idempotency (Idempotency-Key)

POST requests may carry an Idempotency-Key header (any unique value, e.g. a UUID). If the same request is repeated — say after a timeout — the API returns the stored response again without executing the operation a second time.

  • •The key is bound to method, path, client and payload hash — the same key with a different payload counts as a new request.
  • •Stored responses are kept for replay for 24 hours.
  • •Request bodies over 16 MB bypass idempotency; responses over 16 MB are not stored for replay (a retry re-executes the operation).
  • •Recommendation: always set it on POST /v1/insurers/claims — retries after network errors are then guaranteed to be duplicate-free.

Error catalog

Errors follow the ProblemDetails structure (title, status, detail). Payload validation errors arrive as ValidationProblemDetails with an errors map; every message names the field path and the concrete expectation.

titleMeaning
invalid_org_contextThe token is not associated with a (single) organization of the expected type.
forbiddenAccess to the resource is not allowed with this token.
org_without_membersThe organization has no members — creation/retrieval is not possible.
invalid_categoryUnknown claim category (allowed: vehicle, appraiser, fraud, special).
invalid_payloadPayloadJson is missing or not valid JSON.
invalid_stateThe action is not allowed in the current claim status (e.g. reopening a case that is not completed).
invalid_document / missing_documentsDocument invalid, or required documents are missing.
unsupported_content_type / size_limit_exceededFile type not allowed, or the upload limit was exceeded.
upstream_timeout / upstream_errorA downstream service did not respond (in time) — retry with backoff.
Example: 400 from payload validation (POST /v1/insurers/claims:validate)
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "PayloadJson": [
      "PayloadJson does not match the required schema for the selected category.",
      "counterparty.email: is required.",
      "workshop.country: must be one of: CH, DE, AT, FR, IT, LI.",
      "incidentDate: the incident date cannot be in the future — got 2099-01-15, today is 2026-08-02 (Europe/Zurich)."
    ]
  }
}

Experts

Endpoints for experts to work with cases, documents, and report submissions.

Timestamps & incremental synchronisation

Timestamps and sync filters (inclusive >=), named after the field they filter:

  • CreatedAt — When the claim was created. Filters: createdFrom / createdTo.
  • completedFrom / completedTo filter on the moment of the most recent completion (Finalized event; for reopened cases the newest completion counts). Meant for reporting windows (“all cases completed in Q2”) — not for synchronisation.
  • LastChangedAt — Last partner-relevant change (status, documents, reports, comments). Filter: lastChangedSince.

Cases

Case Documents

Reports & Submissions

Submission Documents

Insurers

Endpoints for insurers to create/validate/retrieve claims, documents, and report overviews.

Timestamps & incremental synchronisation

Four timestamps drive list filtering and synchronisation. The sync filters are named after the field they filter and compare inclusively (>=).

  • CreatedAt — When the claim was created. Filters: createdFrom / createdTo.
  • completedFrom / completedTo filter on the moment of the most recent completion (Finalized event; for reopened cases the newest completion counts). Meant for reporting windows (“all cases completed in Q2”) — not for synchronisation.
  • LastChangedAt — Last partner-relevant change (status, documents, reports, comments). Filter: lastChangedSince.
  • LastReportApprovedAt — When the most recent report approval happened (null if none yet). Filter: lastReportApprovedSince — claims without an approved report never match.

Sync recipe (daily poller)

  1. Query with lastChangedSince=<stored cursor> (first run: without the filter).
  2. Process results idempotently — the comparison is inclusive, so the boundary value can appear again.
  3. Store the maximum LastChangedAt you saw as the new cursor.
  4. Only interested in newly approved reports? Same flow with lastReportApprovedSince and LastReportApprovedAt.

Claims

Claim Documents

Reports on Claims

Case Structure & Validation

Each category precisely describes which fields the payloadJson may contain.

Category

Vehicle Appraiser

This structure is intended for payloads for the category Vehicle Appraiser.

Vehicle Appraiser

Test PayloadJson directly

Send a request to the Claimity Validation API and get immediate feedback on your payload.

Expects a valid JSON structure.

Response

Ready

The validation API response appears here.

  1. Select category
  2. Insert Payload JSON or use example
  3. Validate Payload
Claimity Logo

The digital platform for efficient claims management. Automated, transparent, secure.

Help

  • Manual
  • API-Integration
  • Support

Company

  • Website
  • Book a Meeting

Contact

  • info@claimity.ch
  • +41 78 344 77 36
  • Claimity AG
    Wisentalstrasse 7a
    8185 Winkel
    Switzerland

© 2026 Claimity AG. All rights reserved.

Legal NoticePrivacy PolicyTerms of Service