Claimity - API Dokumentation

Ü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.

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). Dadurch ist der Access Token an die konkrete Anfrage gebunden.

Authentication Flow

So funktioniert der OAuth2 Client-Credentials Flow.

Ablauf

Key Pair: Organisation erstellt RSA Key Pair in Claimity (Private Key wird sicher gespeichert).
JWT Client Assertion: Client erzeugt ein kurzlebiges JWT (RS256).
Token Request: Client sendet POST /v1/oauth/token (Client-Credentials + Assertion).
Validierung: Auth-Server prüft Signatur der Assertion und die Berechtigungen und liefert Token-Response.
Abfrage-URL: Der Client erstellt die Abfrage-URL (inkl. Query-Parameter).
DPoP Proof: Client erstellt pro Request ein DPoP-JWT (ES256) gebunden an Methode + URL.
API Call: Client ruft Endpunkt auf mit Authorization: DPoP access_token und DPoP: ….
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

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)

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. Dieser wird pro Request erzeugt und signiert (ES256) und bindet die Anfrage an Methode + URL.

Erforderliche Headers

Authorization	DPoP {access_token}
DPoP	{dpop_proof_jwt}
Accept	application/json
Content-Type	application/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:

•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

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.

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.

Experten

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

Fälle

Falldokumente

Reports & Submissions

Submission-Dokumente

Versicherer

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

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.

Kategorie

Payload JSON

Erwartet eine gültige JSON-Struktur.

Antwort

Bereit

Die Antwort der Validierungs-API erscheint hier.

Kategorie wählen
Payload JSON einfügen oder Beispiel übernehmen
Payload validieren