Claimity API

API Dokumentation

Technische Referenz und Leitfäden für die Integration mit Claimity.

Übersicht

Die API nutzt HTTPS-Methoden und RESTful Endpoints, um Ressourcen im System zu erstellen, zu bearbeiten und zu verwalten. Als Austauschformat dient JSON.

Erste Schritte

Diese API bietet umfassenden Zugriff auf zentrale Funktionen. Ob Integrationen, Automatisierung oder eigene Anwendungen – die API liefert Flexibilität für die Anbindung von Claimity an Ihre Systeme.

Erweiterung der Schnittstellen

  • •Prüfen Sie regelmässig das Änderungsprotokoll um auf dem Laufenden zu bleiben.
  • •Nicht abwärtsinkompatible Änderungen können eingeführt werden, ohne die API-Version zu ändern.
  • •Über wesentliche Änderungen werden Sie rechtzeitig informiert.

Erste Schritte

So starten Sie mit der API:

1

Schlüsselpaar erstellen

Als Organisationsadmin können Sie in den Organisationseinstellungen Ihres Claimity Kontos ein Schlüsselpaar erstellen. Laden Sie darauffolgend den Private Key herunter und bewahren Sie diesen sicher auf.

2

Authentifizieren

Mit Hilfe des erstellten Schlüsselpaars und Ihrer Client‑ID können Sie sich gegenüber der Claimity API authentifizieren und so einen Access Token für Ihre Requests erhalten.

3

DPoP-Header vorbereiten

Zum Senden einer Anfrage an die API ist es notwendig, einen DPoP-Header zu erstellen. Dieser Header wird mit dem Private Key signiert und sichert die Anfrage gegen potentiellen Sichereheitsrisiken.

4

Erste Anfrage

Senden Sie mit Ihrem Access Token und dem DPoP-Header eine authentifizierte Anfrage an einen Endpoint.

Beispiel‑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

Für den schnellen Einstieg stellen wir Ihnen Python‑Notebooks zur Verfügung, mit denen Sie API‑Abfragen ausführen und die Responses direkt einsehen können.

Notebooks auf GitHub ansehen

Problem melden

Wenn Sie auf einen Fehler gestossen sind, helfen wir weiter. Stellen Sie vorab sicher, dass das Problem reproduzierbar ist.

Vor dem Melden

  • ✓Reproduzierbarkeit prüfen
  • ✓API‑Tests mit Postman/Insomnia durchführen
  • ✓Details zu Request und Response sammeln
  • ✗Keine Zugangsdaten im Report mitschicken

Report einreichen

Bitte beschreiben Sie Schritte zur Reproduktion. Unser Support prüft den Fall zeitnah und meldet sich schnellstmöglich bei Ihnen.

Problem melden

Hinweis: Die API wird auf Basis dieser Dokumentation bereitgestellt. Es gibt keine geführte Implementierung oder Code‑Support.

Änderungsprotokoll

Alle Änderungen und Updates der aktuellen API‑Version im Überblick.

2026-08-02

Sync-Filter überarbeitet: updatedSince heisst neu lastChangedSince (beide Endpunkte /v1/insurers/claims und /v1/experts/cases) — der Filter trägt damit den Namen des Feldes, das er filtert (LastChangedAt). Neu: lastReportApprovedSince auf /v1/insurers/claims liefert nur Claims, deren letzte Report-Genehmigung am/nach dem angegebenen Zeitpunkt liegt (Claims ohne genehmigten Report matchen nie). completedFrom/completedTo bleiben unverändert und filtern den Zeitpunkt des jüngsten Fallabschlusses.

2026-07-15

Experten-API: neuer Endpunkt zum Wiedereröffnen eines abgeschlossenen Falls (POST /v1/experts/cases/{caseId}:reopen, liefert 204). List-Endpoints um Filter (Freitextsuche q, Datumsbereiche für Erstellung/Abschluss) und einen updatedSince-Cursor für inkrementelle Synchronisierung erweitert. Fälle liefern nun LastChangedAt; Claims zusätzlich LastReportApprovedAt. Create- und Upload-Endpoints liefern nun 201 Created. Jede Antwort liefert nun einen X-Correlation-Id-Header (ein gültiger eingehender Wert wird zurückgegeben) für Ende-zu-Ende-Tracing; bei Fehlern ist er zugleich die ProblemDetails-instance.

2026-06-09

Neue Kategorie „Spezialexpertisen“ inklusive Schema und Payload-Struktur ergänzt.

2025-12-30

Ergänzung eines neuen Endpunkts zur Versicherer-API zum Validieren der Fallstruktur.

2025-12-28

Erste API‑Version veröffentlicht.

Authentifizierung

Die Claimity Partner API nutzt OAuth 2.0 Client Credentials mit JWT Client Assertion (RS256) und sichert jede Anfrage zusätzlich mit DPoP Proof-of-Possession (ES256). Der Access Token ist an Ihren DPoP-Schlüssel gebunden (cnf.jkt): Verwenden Sie einen Schlüsselfür die gesamte Session — den Token-Request und jeden API-Aufruf — und signieren Sie bereits den Token-Request mit einem DPoP-Proof.

Authentication Flow

So funktioniert der OAuth2 Client-Credentials Flow.

Authentication Flow Sequenzdiagramm (OAuth2 Client Credentials + DPoP)

Ablauf

  1. Key Pair: Organisation erstellt RSA Key Pair in Claimity (Private Key wird sicher gespeichert).
  2. JWT Client Assertion: Client erzeugt ein kurzlebiges JWT (RS256).
  3. Token Request: Client sendet POST /v1/oauth/token (Client-Credentials + Assertion) mit einem DPoP-Proof, der den ausgestellten Token an den DPoP-Schlüssel bindet.
  4. Validierung: Auth-Server prüft Signatur der Assertion und die Berechtigungen und liefert Token-Response.
  5. Abfrage-URL: Der Client erstellt die Abfrage-URL (inkl. Query-Parameter).
  6. DPoP Proof: Client erstellt pro Request ein DPoP-JWT (ES256) gebunden an Methode + URL, signiert mit demselben Schlüssel wie beim Token-Request.
  7. API Call: Client ruft Endpunkt auf mit Authorization: DPoP access_token und DPoP: ….
  8. Response: API prüft Token/DPoP und verarbeitet die Anfrage / liefert die Response.

Access Token auslesen

Für Partner-Integrationen authentifiziert sich Ihre Organisation über eine signierte JWT Client Assertion.

Voraussetzungen

  • •Client ID (z. B. org-expo-00001) auslesbar aus den Claimity Organisationseinstellungen
  • •Private RSA Key aus den Claimity Organisationseinstellungen (sicher aufbewaren und niemals teilen)

Token Endpoint

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

Die Assertion ist ein kurzlebiges JWT (10 Minuten) und wird mit deinem RSA Private Key signiert.

  • •iss/sub = client_id
  • •aud = https://app.claimity.ch/realms/claimity/protocol/openid-connect/token
  • •jti = UUID (einzigartig)
  • •iat/exp = “now” / “now+90s”
  • •kid (optional)
Beispiel: Token Request (cURL, Platzhalter)
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

Die Response enthält ein access_token. Wichtig: Für API-Aufrufe wird dieser Token als DPoP Token verwendet.

API Requests senden

Jede Anfrage benötigt zusätzlich einen DPoP Proof JWT. Pro Request wird ein neuer Proof erzeugt und signiert (ES256), um die Anfrage an Methode + URL zu binden — jedoch stets mit demselben Schlüssel, an den der Access Token gebunden ist (cnf.jkt). Ein mit einem anderen Schlüssel signierter Proof wird mit 401 "Access token is not bound to the DPoP proof key" abgelehnt.

Erforderliche 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 Inhalt
  • •htu muss die exakte URL inkl. Query-String sein
  • •htm muss exakt der HTTP-Methode entsprechen (GET/POST/PUT/DELETE)
  • •jti muss pro Request neu sein (keine Replays)
  • •iat muss innerhalb des erlaubten Zeitfensters liegen (Clock-Skew vermeiden)
  • •ath = base64url(SHA-256(access_token))
Beispiel: Authentifizierter 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

Häufige Ursachen:

  • •not bound: Request mit einem anderen Schlüssel als der Token signiert — denselben Session-Schlüssel wiederverwenden und den Token-Request mit einem DPoP-Proof versehen
  • •htu mismatch: URL muss exakt inkl. Query sein
  • •htm mismatch: Methode muss passen
  • •iat ausserhalb des Fensters: Systemzeit korrigieren
  • •replay: jti muss pro Request neu sein
  • •ath mismatch: SHA-256(access_token) base64url

Correlation-ID

Jede Antwort liefert einen X-Correlation-Id-Header zurück. Claimity verwendet dieselbe ID in seinen Server-Logs und bei Fehlern als instance-Feld des application/problem+json-Bodys — protokollieren Sie sie und geben Sie sie bei Support-Anfragen an.

Sie können auch eine eigene ID mitgeben, um eine Anfrage Ende-zu-Ende zu verfolgen: Senden Sie einen X-Correlation-Id-Request-Header mit einem kurzen, druckbaren Token (≤ 80 Zeichen). Ein gültiger Wert wird unverändert zurückgegeben; ein ungültiger oder zu langer wird ignoriert und Claimity erzeugt eine eigene ID. Die Correlation-ID ist unabhängig von DPoP (der Proof bindet nur Methode + URL), das Hinzufügen dieses Headers beeinflusst die Signatur also nicht.

API‑Grundlagen

Zentrale Konzepte und Konventionen, die in der gesamten API genutzt werden.

Request‑Format

Jeder Request besteht aus Methode, URL, optionalen Query‑Parametern, Headers und (bei POST/PUT) einem JSON‑Body.

URL‑Aufbau

Base URL: https://app.claimity.ch
Path: /v1/<resource>
Query: z. B. ?page=1&size=50
Beispiel‑URL
https://app.claimity.ch/v1/…?page=1&size=50

HTTP‑Methoden

GETRessourcen abrufen
POSTRessourcen erstellen
PUTRessourcen ersetzen/aktualisieren
DELETERessourcen löschen

Typische Headers

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

Response‑Format

Responses sind grundsätzlich JSON (Content-Type: application/json) und verwenden HTTP‑Statuscodes, um Erfolg/Fehler zu signalisieren.

Erfolgs‑Responses

  • •2xx (z. B. 200, 201, 204)
  • •Body enthält in der Regel ein Objekt oder eine Liste
Beispiel (Objekt)
HTTP/1.1 200 OK
Content-Type: application/json

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

Fehler‑Responses (ProblemDetails)

  • •4xx/5xx (z. B. 400, 401, 403, 404, 429, 500)
  • •Body folgt einer ProblemDetails‑ähnlichen Struktur
Beispiel (Problem‑JSON)
HTTP/1.1 400 Bad Request
Content-Type: application/json

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

Rate Limiting

Die Partner-API ist durch Rate Limiting geschützt, um faire Nutzung und Stabilität sicherzustellen. Limits werden pro Client-Partition angewendet.

Anonyme Validierung

POST /v1/insurers/claims:validate ist ohne Token nutzbar und daher strenger limitiert.

  • •FixedWindow: 10 Requests/Minute pro Client/IP

Standard für die Partner-API

Für Standard-Endpunkte wird die Anzahl an Abfragen leicht limitiert.

  • •TokenBucket: ca. 60 Requests/Minute, Burst bis 20, Queue 0

Dokument-Routen

Für Endpunkte mit .../documents... gelten strengere Limits (z. B. für Upload/Download).

  • •TokenBucket: ca. 20 Requests/Minute, Burst bis 10, Queue 0

Token-Endpunkt

Der Token-Endpunkt ist streng limitiert um mögliche Attacken zu verhindern.

  • •Fixed Window: 10 Requests/Minute je Client
Wenn ein Limit erreicht wird (HTTP 429)
  • •Response: 429 Too Many Requests (Rejection Code 429)
  • •Optionaler Header: Retry-After
  • •Diagnose/Policy-Hinweis: X-RateLimit-Policy
  • •Body: Problem-JSON

Empfehlungen für Clients

  • •Bei 429 Requests mit Backoff wiederholen und Retry-After beachten.
  • •Dokument-Uploads/Downloads throttlen.
  • •Bursts sind begrenzt (kein Queueing) – bei hoher Parallelität kommt es schneller zu 429.

Idempotenz (Idempotency-Key)

POST-Requests können den Header Idempotency-Key tragen (frei gewählter, eindeutiger Wert, z. B. eine UUID). Wird derselbe Request wiederholt — etwa nach einem Timeout — liefert die API die gespeicherte Antwort erneut, ohne den Vorgang ein zweites Mal auszuführen.

  • •Der Schlüssel ist an Methode, Pfad, Client und Payload-Hash gebunden — derselbe Key mit anderem Payload zählt als neuer Request.
  • •Gespeicherte Antworten werden 24 Stunden für Replay vorgehalten.
  • •Request-Bodies über 16 MB umgehen die Idempotenz; Antworten über 16 MB werden nicht für Replay gespeichert (ein Retry führt den Vorgang erneut aus).
  • •Empfehlung: bei POST /v1/insurers/claims immer setzen — so ist ein Retry nach Netzwerkfehlern garantiert frei von Doppelanlagen.

Fehlerkatalog

Fehler folgen der ProblemDetails-Struktur (title, status, detail). Payload-Validierungsfehler kommen als ValidationProblemDetails mit einer errors-Map; jede Meldung nennt den Feldpfad und die konkrete Erwartung.

titleBedeutung
invalid_org_contextDas Token ist keiner (eindeutigen) Organisation des erwarteten Typs zugeordnet.
forbiddenZugriff auf die Ressource ist mit diesem Token nicht erlaubt.
org_without_membersDie Organisation hat keine Mitglieder — Anlage/Abruf nicht möglich.
invalid_categoryUnbekannte Fallkategorie (erlaubt: vehicle, appraiser, fraud, special).
invalid_payloadPayloadJson fehlt oder ist kein gültiges JSON.
invalid_stateDie Aktion ist im aktuellen Fallstatus nicht erlaubt (z. B. Reopen eines nicht abgeschlossenen Falls).
invalid_document / missing_documentsDokument ungültig bzw. erforderliche Dokumente fehlen.
unsupported_content_type / size_limit_exceededDateityp nicht erlaubt bzw. Upload-Limit überschritten.
upstream_timeout / upstream_errorEin nachgelagerter Dienst hat nicht (rechtzeitig) geantwortet — Retry mit Backoff.
Beispiel: 400 bei der Payload-Validierung (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)."
    ]
  }
}

Experten

Endpoints für Experten zum Arbeiten mit Fällen, Dokumenten und Gutachten-/Report-Submissions.

Zeitstempel & inkrementelle Synchronisierung

Zeitstempel und Sync-Filter (inklusiv >=), benannt nach dem Feld, das sie filtern:

  • CreatedAt — Erstellzeitpunkt des Claims. Filter: createdFrom / createdTo.
  • completedFrom / completedTo filtern auf den Zeitpunkt des jüngsten Fallabschlusses (Finalized-Ereignis; bei wiedereröffneten Fällen zählt der neueste Abschluss). Gedacht für Auswertungszeiträume («alle im Q2 abgeschlossenen Fälle») — nicht für Synchronisierung.
  • LastChangedAt — Letzte partnerrelevante Änderung (Status, Dokumente, Reports, Kommentare). Filter: lastChangedSince.

Fälle

Falldokumente

Reports & Submissions

Submission-Dokumente

Versicherer

Endpoints für Versicherer zum Erstellen/Validieren/Abrufen von Schäden, Dokumenten und Report-Übersichten.

Zeitstempel & inkrementelle Synchronisierung

Vier Zeitstempel steuern Listen-Filter und Synchronisierung. Die Sync-Filter sind nach dem Feld benannt, das sie filtern, und vergleichen inklusiv (>=).

  • CreatedAt — Erstellzeitpunkt des Claims. Filter: createdFrom / createdTo.
  • completedFrom / completedTo filtern auf den Zeitpunkt des jüngsten Fallabschlusses (Finalized-Ereignis; bei wiedereröffneten Fällen zählt der neueste Abschluss). Gedacht für Auswertungszeiträume («alle im Q2 abgeschlossenen Fälle») — nicht für Synchronisierung.
  • LastChangedAt — Letzte partnerrelevante Änderung (Status, Dokumente, Reports, Kommentare). Filter: lastChangedSince.
  • LastReportApprovedAt — Zeitpunkt der letzten Report-Genehmigung (null, falls noch keine). Filter: lastReportApprovedSince — Claims ohne genehmigten Report matchen nie.

Sync-Rezept (täglicher Poller)

  1. Mit lastChangedSince=<gespeicherter Cursor> abfragen (erster Lauf: ohne Filter).
  2. Ergebnisse idempotent verarbeiten — der Vergleich ist inklusiv, der Grenzwert kann erneut erscheinen.
  3. Als neuen Cursor das Maximum der gesehenen LastChangedAt speichern.
  4. Nur an neuen genehmigten Reports interessiert? Gleicher Ablauf mit lastReportApprovedSince und LastReportApprovedAt.

Schäden

Schadendokumente

Reports zu Claims

Fall-Struktur & Validierung

Jede Kategorie beschreibt präzise, welche Felder das payloadJson enthalten darf.

Kategorie

Fahrzeuggutachter

Diese Struktur richtet sich an Payloads für die Kategorie Fahrzeuggutachter.

Fahrzeuggutachter

PayloadJson direkt testen

Senden Sie eine Anfrage an die Claimity Validierungs-API und erhalten Sie sofortiges Feedback zu Ihrem Payload.

Erwartet eine gültige JSON-Struktur.

Antwort

Bereit

Die Antwort der Validierungs-API erscheint hier.

  1. Kategorie wählen
  2. Payload JSON einfügen oder Beispiel übernehmen
  3. Payload validieren
Claimity Logo

Die digitale Plattform für effizientes Schadenmanagement. Automatisiert, transparent, sicher.

Hilfe

  • Bedienungsanleitung
  • API Integration
  • Support

Unternehmen

  • Website
  • Termin buchen

Kontakt

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

© 2026 Claimity AG. Alle Rechte vorbehalten.

ImpressumDatenschutzerklärungNutzungsbedingungen