# Partner sandbox Source: https://documentation.incaseof.law/Partner-Sandbox Build and test your integration against the same API as production — nothing reaches a real person. The sandbox is a separate incaseof.law environment for building and testing your integration. It runs the **same API** as production: the same endpoints, validation, rate limits and webhooks. What it never does is contact a real person or a court. ## Base URL and keys | | Sandbox | Production | | - | - | - | | Base URL | `https://sandbox.incaseof.law` | `https://service.incaseof.law` | | Paths | `/openapi/…` — identical | `/openapi/…` | | Key | a sandbox key, issued by the incaseof.law team on request | your production key | A sandbox key works only against the sandbox, a production key only against production. Keys look the same (`ico_live_…`) — keep them apart in your configuration. The sandbox receives every change before production does, so it is always on the same or a newer version of the API. ## What happens instead of real communication | Channel | In the sandbox | | - | - | | E-mails (portal invitations, notices, login codes) | Sent only to incaseof.law addresses and to test addresses agreed with us. Every other recipient is dropped — the API answers exactly as if the e-mail had been sent. | | SMS | Not sent. | | Letters | Simulated — nothing is printed or posted. | | Court steps | Taken only by the incaseof.law team; in the sandbox they go to the ERV test system, not to a court. | | Webhooks | Delivered to the endpoint configured for your sandbox webhook, exactly as in production. | Claims move through the collection stages as in production. To test your webhook handler for a particular stage, ask the incaseof.law team to move a test claim to it. ## Test data only * Use **invented data only** — no real debtors, customers, addresses or bank details. * The sandbox database is shared with incaseof.law's own testing; do not rely on the data of other test cases. ## Resets * incaseof.law may reset the sandbox at any time. We announce a reset at least **two working days** in advance. * You can ask for your own sandbox data to be deleted at any time — write to [info@incaseof.law](mailto:info@incaseof.law). ## Going live When your integration works in the sandbox, switch the base URL to `https://service.incaseof.law` and use your production key. Nothing else changes. # Partner & Revenue Share Workflow Source: https://documentation.incaseof.law/Partner-Workflow Set up commission-based partnerships and track revenue shares automatically incaseof.law supports a **commission-based partner model** where external partners (e.g. law firms, brokers, referral agencies) can refer customers. When payments are collected on claims linked to a partner's customer, **revenue shares are automatically calculated** based on the partner's commission rate. ## How It Works ```mermaid theme={null} flowchart LR A[Become a Partner] --> B[Create Customer] B --> C[Create Debtor] C --> D[Create Claim with customer_id] D --> E[Payment Received] E --> F[Revenue Share Auto-Created] ``` 1. **Partner**: The referral entity (e.g. a law firm) with a configured commission rate 2. **Customer**: A client brought in by a partner - automatically linked via your API key 3. **Debtor**: The person or company that owes the debt to the customer 4. **Claim**: A debt collection case - linked to a debtor and a customer via `customer_id` 5. **Revenue Share**: Automatically created when incaseof.law earns fees on a claim linked to a customer *** ## Step 1: Create a Partner Partners are created internally by incaseof.law. If you are interested in becoming a partner, contact us at **[info@incaseof.law](mailto:info@incaseof.law)**. Once confirmed, you will receive an **API key** to start integrating. *** ## Step 2: Create a Customer Create a customer. The customer is automatically linked to your partner account via your API key. Send your own ID for the business as `partner_client_reference` and its VAT ID as `uid` **on every case**. If your partner account already has a customer with that reference or UID, the API returns it instead of creating a new one — see [Reusing an existing customer](#reusing-an-existing-customer). > [!NOTE] > > **Nothing reaches a debtor before the customer has accepted our terms.** The customer's contact receives an invitation > and accepts our GTC and DPA when signing in. Until then claims of this customer can be created, but no letter, SMS or > e-mail goes to a debtor and no court filing is made. If your agreement with us requires the provider confirmation > under § 1.5 lit. b, forward it once per customer with > [`POST /openapi/customers/{id}/provider-confirmation`](/api-reference/customers/create-provider-confirmation) — the > same rule applies until it is on file. > [tab] cURL > > ```bash theme={null} > curl -X POST 'https://service.incaseof.law/openapi/customers' \ > -H 'Authorization: Bearer YOUR_API_TOKEN_HERE' \ > -H 'Content-Type: application/json' \ > -d '{ > "name": "Acme Corporation", > "email": "billing@acme.com", > "partner_client_reference": "ACME-001", > "uid": "ATU12345678", > "phone": "+43 1 234 5678", > "address": { > "street": "Ringstrasse 10", > "city": "Wien", > "zip": "1010", > "country": "AT" > } > }' > ``` > [tab] JavaScript > > ```javascript theme={null} > const response = await fetch('https://service.incaseof.law/openapi/customers', { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_TOKEN_HERE', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > name: 'Acme Corporation', > email: 'billing@acme.com', > partner_client_reference: 'ACME-001', > uid: 'ATU12345678', > phone: '+43 1 234 5678', > address: { > street: 'Ringstrasse 10', > city: 'Wien', > zip: '1010', > country: 'AT' > } > }) > }) > > const data = await response.json() > const customerId = data.data.id > console.log(data.reused ? 'Existing customer reused:' : 'Customer created:', customerId) > ``` > [tab] Python > > ```python theme={null} > import requests > > url = 'https://service.incaseof.law/openapi/customers' > headers = { > 'Authorization': 'Bearer YOUR_API_TOKEN_HERE', > 'Content-Type': 'application/json' > } > > payload = { > 'name': 'Acme Corporation', > 'email': 'billing@acme.com', > 'partner_client_reference': 'ACME-001', > 'uid': 'ATU12345678', > 'phone': '+43 1 234 5678', > 'address': { > 'street': 'Ringstrasse 10', > 'city': 'Wien', > 'zip': '1010', > 'country': 'AT' > } > } > > response = requests.post(url, json=payload, headers=headers) > customer = response.json() > customer_id = customer['data']['id'] > print(f"{'Existing customer reused' if customer['reused'] else 'Customer created'}: {customer_id}") > ``` > [!NOTE] > > **Save the customer ID**: You will need the `id` from the response to link claims to this customer. ### Customer Fields | Field | Type | Required | Description | | - | - | - | - | | `name` | string | Yes | Customer name (1-255 chars) | | `email` | string | Yes | Customer email | | `phone` | string | No | Phone number (max 50 chars) | | `address` | object | **Yes** | Postal address of the business: `street`, `zip`, `city` (non-empty) and `country` (ISO code of a European country, e.g. `AT`, `DE`). Becomes the creditor address on letters and on the court-fee invoice. A missing or empty line returns `400 VALIDATION_ERROR` naming it, e.g. `address.zip is required` | | `metadata` | object | No | Arbitrary key-value data | | `partner_client_reference` | string | No | Your own ID for this business (max 255 chars, trimmed, case-sensitive). Unique within your partner account | | `uid` | string | No | EU VAT ID, e.g. `ATU12345678`. Spaces and the separators `-` `.` `/` are removed and letters uppercased; it must then be a 2-letter country code plus 2–12 characters, otherwise 400. Unique within your partner account | | `legal_form` | string | No¹ | The business's legal form: `gmbh`, `ug`, `ag`, `se`, `kg`, `og_ohg`, `gmbh_co_kg`, `gbr`, `partg`, `kgaa`, `eg`, `verein`, `flexco`, `einzelunternehmen`, `eingetragener_kaufmann`, `praktiker`, `pauschalierter_land_forstwirt` | | `legal_representative` | object | No¹ | `{ "function": "Geschäftsführerin", "name": "Dr. Anna Berger" }` (35 characters each) — the legal representative German court filings name | | `owner` | object | No¹ | `{ "first_name", "last_name" }` — for a sole trader (`einzelunternehmen`, `eingetragener_kaufmann`, `praktiker`, `pauschalierter_land_forstwirt`) instead of `legal_representative` | | `billing_email` | string | No¹ | Where invoices from incaseof.law to the business go | | `vat_deductible` | boolean | No¹ | Whether the business may deduct input VAT (Vorsteuerabzug) | | `payout_account` | object | No¹ | `{ "iban", "bic"?, "bank_name"? }` — the account we pay the business's share to. The IBAN's check digits are verified. **On creation only**; `PATCH` refuses it — contact incaseof.law to change it | ¹ Partner keys only. Required when your partner agreement requires it (see [Required fields and prohibited data](#required-fields-and-prohibited-data)). ### Reusing an existing customer Each business you work for should be **one** customer. Before creating, the API looks for a customer of your partner account — first by `partner_client_reference`, then by `uid`, and when neither matches, by the same `email` **and** the same `name` (case and spaces ignored), as long as that customer's stored `partner_client_reference` / `uid` do not differ from the ones you sent: | Result | HTTP | `reused` | What happens | | - | - | - | - | | Match | `200` | `true` | The existing customer is returned (same `id` and `organization_id`). Name, email, address and the business fields (`legal_form` … `payout_account`) are **not** changed — use `PATCH /openapi/customers/{id}` for that. A key the customer does not have yet is added to it. | | No match | `201` | `false` | A new customer is created. | | Reference matches one customer, UID another | `409` | — | Nothing is created. Correct the reference or the UID. | * `null` for either key is treated as not given. Without `partner_client_reference` and `uid`, only name and e-mail identify the customer: the same business sent with a different name or e-mail becomes a new customer. Send `partner_client_reference` (or store the returned `id`) to make the match exact. * Customers created before you sent these keys can be linked with `PATCH /openapi/customers/{id}` (`{"partner_client_reference": "ACME-001", "uid": "ATU12345678"}`); a key already used by another of your customers returns `409`. * The keys are scoped to your partner account: another partner sending the same UID gets its own customer. * The customer's onboarding invitation is sent once, with the first claim filed for that customer — reusing the customer does not send it again. * **E-mail that already has a login.** If the customer's `email` belongs to an existing incaseof.law user — for example one owner with two companies and separate bookkeeping — no invitation is needed: the user is added to the new customer's organisation immediately, receives a short notice e-mail, and finds the company in their account after the next login. The response shows `"existing_user_linked": true`. Each company remains a separate customer with its own `id`. ### Required fields and prohibited data Your partner agreement may require fields the API otherwise treats as optional, and may prohibit health data. incaseof.law sets both for your partner account; they are checked **before anything is stored**, so a refused request leaves nothing behind. * **Required fields** — a request without one answers `400 VALIDATION_ERROR`, one `details` entry per missing field, e.g. `"message": "creditor_confirmation required"`. Checked on creation: * claim: `creditor_confirmation: { "warranties_confirmed": true, "consent_confirmed": true }` * invoice (JSON and PDF upload): `default_date`, `creditor_reminder_dates` (not with `default_basis: "bgb_286_3"`), `contract_date`, `subject` * debtor: `legal_representative` (the debtor's guardian or attorney — send it whenever one exists) * customer: `legal_form`, `legal_representative` (`owner` for a sole trader), `billing_email`, `payout_account`, `vat_deductible` * **Prohibited data** — invoice `subject` / `description`, `invoice_issuer`, `invoice_recipient`, payment `notes`, document `description` and customer `metadata` are checked for health data: a health insurance number (KVNR), an institution code (IK, a nine-digit number on its own), `PZN`, `Pflegegrad`, `Diagnose`, `ICD` or an ICD code (`F32.1`). A match answers `400 PROHIBITED_DATA` naming the field; the value is never echoed. Describe services neutrally, e.g. "Privatärztliche Leistung vom 01.09.2026". *** ## Step 3: Create a Debtor Create the debtor (person or company) that owes the debt to your customer. **You must include the `customer_id`** so the system knows which organization this debtor belongs to. **Salutation** (`person.salutation`): `mr` (Herr), `mrs` (Frau) or `diverse` (Divers). `Herr`, `Herrn`, `Hr.`, `Frau`, `Fr.`, `männlich`, `weiblich`, `male`, `female`, `m`, `w`, `f`, `d` (also followed by academic titles, e.g. `Frau Dr.`) are accepted case-insensitively and stored as the code. `ohne Anrede`, `none`, `unbekannt` or no value means no salutation: the letter then addresses the debtor by name only. Do not send `diverse` as a fallback, for couples or for companies; a couple (`Herr und Frau`) is rejected. An unrecognised `salutation` returns `400 VALIDATION_ERROR` with the accepted values. If your system calls the field `gender`, send it as `person.gender`: the same values are accepted, an unrecognised one is ignored, and it is read only when `salutation` is absent, `null` or empty. Send your own customer number for the debtor as `partner_client_reference` and, for a business, its VAT ID as `company.uid`. A person whose name you hold in one field goes into `person.last_name` with `first_name` empty; such a case is checked by our case managers before the first letter goes out. > [tab] cURL > > ```bash theme={null} > curl -X POST 'https://service.incaseof.law/openapi/debtors' \ > -H 'Authorization: Bearer YOUR_API_TOKEN_HERE' \ > -H 'Content-Type: application/json' \ > -d '{ > "customer_id": "CUSTOMER_ID", > "acting_as": "person", > "debtor_type": "privateperson", > "person": { > "salutation": "mr", > "first_name": "Max", > "last_name": "Mustermann" > }, > "addresses": [{ > "street": "Hauptstrasse 1", > "zip": "1010", > "city": "Wien", > "country": "AT", > "is_primary": true > }], > "communication_channels": [{ > "type": "email", > "value": "max@example.com", > "is_primary": true > }] > }' > ``` > [!NOTE] > > **Save the debtor ID**: You will need the `id` from the response when creating the claim. *** ## Step 4: Create a Claim with Customer ID When creating a claim, pass the `customer_id` to link it to a partner's customer. This enables automatic revenue share tracking. > [tab] cURL > > ```bash theme={null} > curl -X POST 'https://service.incaseof.law/openapi/claims' \ > -H 'Authorization: Bearer YOUR_API_TOKEN_HERE' \ > -H 'Content-Type: application/json' \ > -d '{ > "debtor_id": "DEBTOR_ID", > "customer_id": "CUSTOMER_ID" > }' > ``` > [tab] JavaScript > > ```javascript theme={null} > const response = await fetch('https://service.incaseof.law/openapi/claims', { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_TOKEN_HERE', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > debtor_id: 'DEBTOR_ID', > customer_id: 'CUSTOMER_ID' > }) > }) > > const data = await response.json() > const claimId = data.data.id > console.log('Claim created with customer link:', claimId) > ``` > [tab] Python > > ```python theme={null} > import requests > > url = 'https://service.incaseof.law/openapi/claims' > headers = { > 'Authorization': 'Bearer YOUR_API_TOKEN_HERE', > 'Content-Type': 'application/json' > } > > payload = { > 'debtor_id': 'DEBTOR_ID', > 'customer_id': 'CUSTOMER_ID' > } > > response = requests.post(url, json=payload, headers=headers) > claim = response.json() > claim_id = claim['data']['id'] > print(f'Claim created: {claim_id}') > ``` > [!WARNING] > > The `customer_id` is **required** for partner API tokens. It tells the system which organization this claim belongs to. Without it, the request will fail. You can update the `customer_id` on an existing claim via the update endpoint. *** ## Step 4b: Decide on the court step When out-of-court collection is exhausted, the claim moves to `dunning_action_recommended` (you receive the webhook `claim.collection_stage_changed`). The creditor decides whether to take the claim to court — through your integration: 1. [`GET /openapi/claims/{claim_id}/lawsuit-decision/estimate`](/api-reference/claims/estimate-lawsuit-decision) — the court fee, and whether a lawyer is required (Austria) or not allowed (Germany). `decision_open` is `true` while a decision can still be sent (the claim is at `dunning_action_recommended` or `dunning_action_filed`); once one is recorded (by you or by the creditor in the portal) it turns `false` and `decided` turns `true`. 2. [`POST /openapi/claims/{claim_id}/lawsuit-decision`](/api-reference/claims/create-lawsuit-decision) with `{ "decision": "sue" }` or `{ "decision": "decline" }`. The court fee is invoiced to the **creditor**, at the e-mail address and postal address of the customer you created in Step 2 — keep them current. It is never invoiced to you as the partner. ## Step 5: Automatic Revenue Sharing When incaseof.law earns fees on a claim linked to a customer, the system automatically calculates the partner's commission based on those fees - not the payment amount. No additional API calls are needed - revenue shares are created automatically. ### Revenue Share Statuses | Status | Description | | - | - | | `pending` | Commission calculated, awaiting payout | | `paid` | Commission has been paid to the partner | | `cancelled` | Commission was cancelled (e.g. payment reversed) | *** ## Complete Partner Workflow Example > [tab] JavaScript > > ```javascript theme={null} > const API_BASE = 'https://service.incaseof.law/openapi' > const API_TOKEN = 'YOUR_API_TOKEN_HERE' > > const headers = { > 'Authorization': `Bearer ${API_TOKEN}`, > 'Content-Type': 'application/json' > } > > async function partnerWorkflow() { > // Step 1: Create a customer (automatically linked to your partner via API key) > const customerRes = await fetch(`${API_BASE}/customers`, { > method: 'POST', > headers, > body: JSON.stringify({ > name: 'Acme Corporation', > email: 'billing@acme.com', > address: { street: 'Ringstrasse 10', zip: '1010', city: 'Wien', country: 'AT' } > }) > }) > const customer = await customerRes.json() > const customerId = customer.data.id > console.log('Customer created:', customerId) > > // Step 2: Create a debtor (customer_id required for partner tokens) > const debtorRes = await fetch(`${API_BASE}/debtors`, { > method: 'POST', > headers, > body: JSON.stringify({ > customer_id: customerId, > acting_as: 'person', > debtor_type: 'privateperson', > person: { > salutation: 'mr', > first_name: 'Max', > last_name: 'Mustermann' > }, > addresses: [{ > street: 'Hauptstrasse 1', > zip: '1010', > city: 'Wien', > country: 'AT', > is_primary: true > }], > communication_channels: [{ > type: 'email', > value: 'max@example.com', > is_primary: true > }] > }) > }) > const debtor = await debtorRes.json() > const debtorId = debtor.data.id > console.log('Debtor created:', debtorId) > > // Step 3: Create a claim linked to the customer and debtor > const claimRes = await fetch(`${API_BASE}/claims`, { > method: 'POST', > headers, > body: JSON.stringify({ > debtor_id: debtorId, > customer_id: customerId > }) > }) > const claim = await claimRes.json() > console.log('Claim created:', claim.data.id) > > // Step 4: Upload invoice and record payments as usual > // Revenue shares will be automatically created when payments are recorded > > return { > customerId, > debtorId, > claimId: claim.data.id > } > } > > partnerWorkflow() > ``` > [tab] Python > > ```python theme={null} > import requests > > API_BASE = 'https://service.incaseof.law/openapi' > API_TOKEN = 'YOUR_API_TOKEN_HERE' > > headers = { > 'Authorization': f'Bearer {API_TOKEN}', > 'Content-Type': 'application/json' > } > > def partner_workflow(): > # Step 1: Create a customer (automatically linked to your partner via API key) > customer_res = requests.post(f'{API_BASE}/customers', headers=headers, json={ > 'name': 'Acme Corporation', > 'email': 'billing@acme.com', > 'address': {'street': 'Ringstrasse 10', 'zip': '1010', 'city': 'Wien', 'country': 'AT'} > }) > customer_id = customer_res.json()['data']['id'] > print(f'Customer created: {customer_id}') > > # Step 2: Create a debtor (customer_id required for partner tokens) > debtor_res = requests.post(f'{API_BASE}/debtors', headers=headers, json={ > 'customer_id': customer_id, > 'acting_as': 'person', > 'debtor_type': 'privateperson', > 'person': { > 'salutation': 'mr', > 'first_name': 'Max', > 'last_name': 'Mustermann' > }, > 'addresses': [{ > 'street': 'Hauptstrasse 1', > 'zip': '1010', > 'city': 'Wien', > 'country': 'AT', > 'is_primary': True > }], > 'communication_channels': [{ > 'type': 'email', > 'value': 'max@example.com', > 'is_primary': True > }] > }) > debtor_id = debtor_res.json()['data']['id'] > print(f'Debtor created: {debtor_id}') > > # Step 3: Create a claim linked to the customer and debtor > claim_res = requests.post(f'{API_BASE}/claims', headers=headers, json={ > 'debtor_id': debtor_id, > 'customer_id': customer_id > }) > claim_id = claim_res.json()['data']['id'] > print(f'Claim created: {claim_id}') > > # Step 4: Upload invoices and record payments as usual > # Revenue shares are automatically created when payments are recorded > > return { > 'customer_id': customer_id, > 'debtor_id': debtor_id, > 'claim_id': claim_id > } > > partner_workflow() > ``` *** ## Managing Customers ### List Customers > [tab] cURL > > ```bash theme={null} > curl -X GET 'https://service.incaseof.law/openapi/customers' \ > -H 'Authorization: Bearer YOUR_API_TOKEN_HERE' > ``` ### Update a Customer > [tab] cURL > > ```bash theme={null} > curl -X PATCH 'https://service.incaseof.law/openapi/customers/CUSTOMER_ID' \ > -H 'Authorization: Bearer YOUR_API_TOKEN_HERE' \ > -H 'Content-Type: application/json' \ > -d '{ > "name": "Updated Name", > "email": "new@email.com" > }' > ``` ### Delete a Customer > [tab] cURL > > ```bash theme={null} > curl -X DELETE 'https://service.incaseof.law/openapi/customers/CUSTOMER_ID' \ > -H 'Authorization: Bearer YOUR_API_TOKEN_HERE' > ``` *** ## Next Steps * Use the [Customer API](/api-reference/customers/create-customer) to create customers * Link claims to customers using `customer_id` when [creating claims](/api-reference/claims/create-claim) * Revenue shares are tracked automatically Need help? Contact us at [info@incaseof.law](mailto:info@incaseof.law) # Quick Start Guide Source: https://documentation.incaseof.law/Quick-Start-Guide Get started with the incaseof.law API in minutes. This guide walks you through the most common workflows with practical code examples. ## Prerequisites * **API key**: request one at [app.incaseof.law/openapi](https://app.incaseof.law/openapi). incaseof.law reviews the request and sends the key by e-mail. * **Base URL**: `https://service.incaseof.law` * **Authentication**: All requests require a Bearer token in the Authorization header *** ## Authentication Every API request must include your API token in the Authorization header: ```bash theme={null} Authorization: Bearer YOUR_API_TOKEN_HERE ``` ### Example Request Setup > [tab] cURL > > ```bash theme={null} > curl -X GET 'https://service.incaseof.law/openapi/debtors' \ > -H 'Authorization: Bearer YOUR_API_TOKEN_HERE' > ``` > [tab] JavaScript > > ```javascript theme={null} > const response = await fetch('https://service.incaseof.law/openapi/debtors', { > headers: { > 'Authorization': 'Bearer YOUR_API_TOKEN_HERE', > 'Content-Type': 'application/json' > } > }) > ``` > [tab] Python > > ```python theme={null} > import requests > > headers = { > 'Authorization': 'Bearer YOUR_API_TOKEN_HERE', > 'Content-Type': 'application/json' > } > > response = requests.get( > 'https://service.incaseof.law/openapi/debtors', > headers=headers > ) > ``` *** ## Workflow 1: Create a Debtor Create a debtor (person or company) that you'll later associate with claims. ### Step 1: Create a Person Debtor > [tab] cURL > > ```bash theme={null} > curl -X POST 'https://service.incaseof.law/openapi/debtors' \ > -H 'Authorization: Bearer YOUR_API_TOKEN_HERE' \ > -H 'Content-Type: application/json' \ > -d '{ > "acting_as": "person", > "debtor_type": "privateperson", > "person": { > "salutation": "mr", > "first_name": "Max", > "last_name": "Mustermann" > }, > "addresses": [ > { > "street": "Hauptstrasse 1", > "zip": "1010", > "city": "Wien", > "country": "AT", > "is_primary": true > } > ], > "communication_channels": [ > { > "type": "email", > "value": "max@example.com", > "is_primary": true > }, > { > "type": "phone", > "value": "+43 123 456789" > } > ] > }' > ``` > [tab] JavaScript > > ```javascript theme={null} > const response = await fetch('https://service.incaseof.law/openapi/debtors', { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_TOKEN_HERE', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > acting_as: 'person', > debtor_type: 'privateperson', > person: { > salutation: 'mr', > first_name: 'Max', > last_name: 'Mustermann' > }, > addresses: [ > { > street: 'Hauptstrasse 1', > zip: '1010', > city: 'Wien', > country: 'AT', > is_primary: true > } > ], > communication_channels: [ > { > type: 'email', > value: 'max@example.com', > is_primary: true > }, > { > type: 'phone', > value: '+43 123 456789' > } > ] > }) > }) > > const data = await response.json() > console.log('Debtor created:', data.data.id) > ``` > [tab] Python > > ```python theme={null} > import requests > > url = 'https://service.incaseof.law/openapi/debtors' > headers = { > 'Authorization': 'Bearer YOUR_API_TOKEN_HERE', > 'Content-Type': 'application/json' > } > > payload = { > 'acting_as': 'person', > 'debtor_type': 'privateperson', > 'person': { > 'salutation': 'mr', > 'first_name': 'Max', > 'last_name': 'Mustermann' > }, > 'addresses': [ > { > 'street': 'Hauptstrasse 1', > 'zip': '1010', > 'city': 'Wien', > 'country': 'AT', > 'is_primary': True > } > ], > 'communication_channels': [ > { > 'type': 'email', > 'value': 'max@example.com', > 'is_primary': True > }, > { > 'type': 'phone', > 'value': '+43 123 456789' > } > ] > } > > response = requests.post(url, json=payload, headers=headers) > debtor = response.json() > debtor_id = debtor['data']['id'] > print(f'Debtor created: {debtor_id}') > ``` ### Step 2: Create a Company Debtor > [tab] cURL > > ```bash theme={null} > curl -X POST 'https://service.incaseof.law/openapi/debtors' \ > -H 'Authorization: Bearer YOUR_API_TOKEN_HERE' \ > -H 'Content-Type: application/json' \ > -d '{ > "acting_as": "company", > "debtor_type": "protocolled_company", > "company": { > "company_name": "ACME GmbH", > "firmenbuchnummer": "FN123456a" > }, > "addresses": [ > { > "street": "Industriestrasse 2", > "zip": "80331", > "city": "München", > "country": "DE", > "is_primary": true > } > ], > "communication_channels": [ > { > "type": "email", > "value": "office@acme.de", > "is_primary": true > } > ], > "iban": "DE89370400440532013000", > "bic": "COBADEFFXXX" > }' > ``` > [tab] JavaScript > > ```javascript theme={null} > const response = await fetch('https://service.incaseof.law/openapi/debtors', { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_TOKEN_HERE', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > acting_as: 'company', > debtor_type: 'protocolled_company', > company: { > company_name: 'ACME GmbH', > firmenbuchnummer: 'FN123456a' > }, > addresses: [ > { > street: 'Industriestrasse 2', > zip: '80331', > city: 'München', > country: 'DE', > is_primary: true > } > ], > communication_channels: [ > { > type: 'email', > value: 'office@acme.de', > is_primary: true > } > ], > iban: 'DE89370400440532013000', > bic: 'COBADEFFXXX' > }) > }) > > const data = await response.json() > const debtorId = data.data.id > console.log('Company debtor created:', debtorId) > ``` > [tab] Python > > ```python theme={null} > import requests > > url = 'https://service.incaseof.law/openapi/debtors' > headers = { > 'Authorization': 'Bearer YOUR_API_TOKEN_HERE', > 'Content-Type': 'application/json' > } > > payload = { > 'acting_as': 'company', > 'debtor_type': 'protocolled_company', > 'company': { > 'company_name': 'ACME GmbH', > 'firmenbuchnummer': 'FN123456a' > }, > 'addresses': [ > { > 'street': 'Industriestrasse 2', > 'zip': '80331', > 'city': 'München', > 'country': 'DE', > 'is_primary': True > } > ], > 'communication_channels': [ > { > 'type': 'email', > 'value': 'office@acme.de', > 'is_primary': True > } > ], > 'iban': 'DE89370400440532013000', > 'bic': 'COBADEFFXXX' > } > > response = requests.post(url, json=payload, headers=headers) > debtor = response.json() > debtor_id = debtor['data']['id'] > print(f'Company debtor created: {debtor_id}') > ``` ### Response Example ```json theme={null} { "success": true, "data": { "id": "3c90c3cc-0d44-4b50-8888-8dd257363052", "acting_as": "person", "debtor_type": "privateperson", "person": { "first_name": "Max", "last_name": "Mustermann", "salutation": "mr" }, "addresses": [...], "communication_channels": [...], "created_at": "2025-10-11T10:30:00Z" } } ``` > [!NOTE] > > **Save the debtor ID**: You'll need the `id` from the response for the next step (creating a claim). *** ## Workflow 2: Create a Claim Create a claim (debt collection case) associated with a debtor. > [tab] cURL > > ```bash theme={null} > # Replace DEBTOR_ID with the ID from the previous step > curl -X POST 'https://service.incaseof.law/openapi/claims' \ > -H 'Authorization: Bearer YOUR_API_TOKEN_HERE' \ > -H 'Content-Type: application/json' \ > -d '{ > "debtor_id": "3c90c3cc-0d44-4b50-8888-8dd257363052" > }' > ``` > [tab] JavaScript > > ```javascript theme={null} > // Replace debtorId with the ID from the previous step > const debtorId = '3c90c3cc-0d44-4b50-8888-8dd257363052' > > const response = await fetch('https://service.incaseof.law/openapi/claims', { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_TOKEN_HERE', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > debtor_id: debtorId > }) > }) > > const data = await response.json() > const claimId = data.data.id > console.log('Claim created:', claimId) > ``` > [tab] Python > > ```python theme={null} > import requests > > # Replace debtor_id with the ID from the previous step > debtor_id = '3c90c3cc-0d44-4b50-8888-8dd257363052' > > url = 'https://service.incaseof.law/openapi/claims' > headers = { > 'Authorization': 'Bearer YOUR_API_TOKEN_HERE', > 'Content-Type': 'application/json' > } > > payload = { > 'debtor_id': debtor_id > } > > response = requests.post(url, json=payload, headers=headers) > claim = response.json() > claim_id = claim['data']['id'] > print(f'Claim created: {claim_id}') > ``` ### Response Example ```json theme={null} { "success": true, "data": { "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "debtor_id": "3c90c3cc-0d44-4b50-8888-8dd257363052", "case_reference": "23B-2025-0042", "submission_state": "new", "collection_stage": "new", "created_at": "2025-10-11T10:35:00Z" } } ``` > [!NOTE] > > **Minimal payload**: The claim creation endpoint accepts a minimal payload. Financial details (amounts, dates, references) will be automatically extracted from invoices when you upload them via OCR processing. *** ## Workflow 3: Upload Invoice to Claim Upload an invoice PDF to a claim. The system will automatically extract invoice data using OCR. ### Upload PDF File > [tab] cURL > > ```bash theme={null} > # Replace CLAIM_ID with the ID from the previous step > curl -X POST 'https://service.incaseof.law/openapi/claims/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/invoices' \ > -H 'Authorization: Bearer YOUR_API_TOKEN_HERE' \ > -F 'file=@/path/to/invoice.pdf' \ > -F 'invoice_number=INV-2025-001' \ > -F 'total_amount=123.45' \ > -F 'maturity_date=2025-10-01' \ > -F 'issue_date=2025-09-15' > ``` > [tab] JavaScript > > ```javascript theme={null} > // Replace claimId with the ID from the previous step > const claimId = '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d' > > // Assuming you have a file input element > const fileInput = document.querySelector('input[type="file"]') > const file = fileInput.files[0] > > const formData = new FormData() > formData.append('file', file) > formData.append('invoice_number', 'INV-2025-001') > formData.append('total_amount', '123.45') > formData.append('maturity_date', '2025-10-01') > formData.append('issue_date', '2025-09-15') > > const response = await fetch( > `https://service.incaseof.law/openapi/claims/${claimId}/invoices`, > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_TOKEN_HERE' > // Don't set Content-Type header - browser will set it with boundary > }, > body: formData > } > ) > > const data = await response.json() > console.log('Invoice uploaded:', data.data.id) > ``` > [tab] Python > > ```python theme={null} > import requests > > # Replace claim_id with the ID from the previous step > claim_id = '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d' > > url = f'https://service.incaseof.law/openapi/claims/{claim_id}/invoices' > headers = { > 'Authorization': 'Bearer YOUR_API_TOKEN_HERE' > } > > # Open the PDF file > with open('invoice.pdf', 'rb') as pdf_file: > files = { > 'file': ('invoice.pdf', pdf_file, 'application/pdf') > } > data = { > 'invoice_number': 'INV-2025-001', > 'total_amount': '123.45', > 'maturity_date': '2025-10-01', > 'issue_date': '2025-09-15' > } > > response = requests.post(url, headers=headers, files=files, data=data) > invoice = response.json() > invoice_id = invoice['data']['id'] > print(f'Invoice uploaded: {invoice_id}') > ``` ### Response Example ```json theme={null} { "success": true, "data": { "id": "b7c2d6ba-9d2c-42b6-8e1f-4a8e3d9e9c77", "claim_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", "invoice_number": "INV-2025-001", "invoice_amount_gross": 123.45, "invoice_due_date": "2025-10-01", "invoice_issue_date": "2025-09-15", "created_at": "2025-10-11T10:40:00Z" } } ``` > [!WARNING] > > **PDF files only**: When uploading invoice files, only PDF format is accepted. Other file formats (images, Word, Excel, etc.) will be rejected. The original filename is automatically preserved. *** ## Complete Workflow Example Here's a complete example that ties everything together: > [tab] JavaScript > > ```javascript theme={null} > const API_BASE = 'https://service.incaseof.law/openapi' > const API_TOKEN = 'YOUR_API_TOKEN_HERE' > > async function createDebtorAndClaim() { > try { > // Step 1: Create a debtor > const debtorResponse = await fetch(`${API_BASE}/debtors`, { > method: 'POST', > headers: { > 'Authorization': `Bearer ${API_TOKEN}`, > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > acting_as: 'person', > debtor_type: 'privateperson', > person: { > salutation: 'mr', > first_name: 'Max', > last_name: 'Mustermann' > }, > addresses: [ > { > street: 'Hauptstrasse 1', > zip: '1010', > city: 'Wien', > country: 'AT', > is_primary: true > } > ], > communication_channels: [ > { > type: 'email', > value: 'max@example.com', > is_primary: true > } > ] > }) > }) > > const debtorData = await debtorResponse.json() > const debtorId = debtorData.data.id > console.log('Debtor created:', debtorId) > > // Step 2: Create a claim > const claimResponse = await fetch(`${API_BASE}/claims`, { > method: 'POST', > headers: { > 'Authorization': `Bearer ${API_TOKEN}`, > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > debtor_id: debtorId > }) > }) > > const claimData = await claimResponse.json() > const claimId = claimData.data.id > console.log('Claim created:', claimId) > > // Step 3: Upload invoice (PDF) > const formData = new FormData() > formData.append('file', invoiceFile) // Your PDF file > formData.append('invoice_number', 'INV-2025-001') > formData.append('total_amount', '123.45') > formData.append('maturity_date', '2025-10-01') > > const invoiceResponse = await fetch( > `${API_BASE}/claims/${claimId}/invoices`, > { > method: 'POST', > headers: { > 'Authorization': `Bearer ${API_TOKEN}` > }, > body: formData > } > ) > > const invoiceData = await invoiceResponse.json() > console.log('Invoice uploaded:', invoiceData.data.id) > > return { > debtorId, > claimId, > invoiceId: invoiceData.data.id > } > } catch (error) { > console.error('Error:', error) > throw error > } > } > ``` > [tab] Python > > ```python theme={null} > import requests > > API_BASE = 'https://service.incaseof.law/openapi' > API_TOKEN = 'YOUR_API_TOKEN_HERE' > > def create_debtor_and_claim(): > headers = { > 'Authorization': f'Bearer {API_TOKEN}', > 'Content-Type': 'application/json' > } > > try: > # Step 1: Create a debtor > debtor_payload = { > 'acting_as': 'person', > 'debtor_type': 'privateperson', > 'person': { > 'salutation': 'mr', > 'first_name': 'Max', > 'last_name': 'Mustermann' > }, > 'addresses': [ > { > 'street': 'Hauptstrasse 1', > 'zip': '1010', > 'city': 'Wien', > 'country': 'AT', > 'is_primary': True > } > ], > 'communication_channels': [ > { > 'type': 'email', > 'value': 'max@example.com', > 'is_primary': True > } > ] > } > > debtor_response = requests.post( > f'{API_BASE}/debtors', > json=debtor_payload, > headers=headers > ) > debtor_response.raise_for_status() > debtor_data = debtor_response.json() > debtor_id = debtor_data['data']['id'] > print(f'Debtor created: {debtor_id}') > > # Step 2: Create a claim > claim_payload = { > 'debtor_id': debtor_id > } > > claim_response = requests.post( > f'{API_BASE}/claims', > json=claim_payload, > headers=headers > ) > claim_response.raise_for_status() > claim_data = claim_response.json() > claim_id = claim_data['data']['id'] > print(f'Claim created: {claim_id}') > > # Step 3: Upload invoice (PDF) > upload_headers = { > 'Authorization': f'Bearer {API_TOKEN}' > } > > with open('invoice.pdf', 'rb') as pdf_file: > files = { > 'file': ('invoice.pdf', pdf_file, 'application/pdf') > } > data = { > 'invoice_number': 'INV-2025-001', > 'total_amount': '123.45', > 'maturity_date': '2025-10-01' > } > > invoice_response = requests.post( > f'{API_BASE}/claims/{claim_id}/invoices', > headers=upload_headers, > files=files, > data=data > ) > invoice_response.raise_for_status() > invoice_data = invoice_response.json() > invoice_id = invoice_data['data']['id'] > print(f'Invoice uploaded: {invoice_id}') > > return { > 'debtor_id': debtor_id, > 'claim_id': claim_id, > 'invoice_id': invoice_id > } > except requests.exceptions.RequestException as e: > print(f'Error: {e}') > raise > ``` *** ## Additional Common Operations ### List All Debtors > [tab] cURL > > ```bash theme={null} > curl -X GET 'https://service.incaseof.law/openapi/debtors' \ > -H 'Authorization: Bearer YOUR_API_TOKEN_HERE' > ``` > [tab] JavaScript > > ```javascript theme={null} > const response = await fetch('https://service.incaseof.law/openapi/debtors', { > headers: { > 'Authorization': 'Bearer YOUR_API_TOKEN_HERE' > } > }) > const data = await response.json() > console.log('Debtors:', data.data.debtors, 'of', data.data.total) > ``` > [tab] Python > > ```python theme={null} > response = requests.get( > 'https://service.incaseof.law/openapi/debtors', > headers={'Authorization': 'Bearer YOUR_API_TOKEN_HERE'} > ) > debtors = response.json() > print('Debtors:', debtors['data']['debtors'], 'of', debtors['data']['total']) > ``` ### Get a Specific Claim > [tab] cURL > > ```bash theme={null} > curl -X GET 'https://service.incaseof.law/openapi/claims/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d' \ > -H 'Authorization: Bearer YOUR_API_TOKEN_HERE' > ``` > [tab] JavaScript > > ```javascript theme={null} > const claimId = '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d' > const response = await fetch( > `https://service.incaseof.law/openapi/claims/${claimId}`, > { > headers: { > 'Authorization': 'Bearer YOUR_API_TOKEN_HERE' > } > } > ) > const data = await response.json() > console.log('Claim:', data.data) > ``` > [tab] Python > > ```python theme={null} > claim_id = '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d' > response = requests.get( > f'https://service.incaseof.law/openapi/claims/{claim_id}', > headers={'Authorization': 'Bearer YOUR_API_TOKEN_HERE'} > ) > claim = response.json() > print('Claim:', claim['data']) > ``` ### List Invoices for a Claim > [tab] cURL > > ```bash theme={null} > curl -X GET 'https://service.incaseof.law/openapi/claims/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/invoices' \ > -H 'Authorization: Bearer YOUR_API_TOKEN_HERE' > ``` > [tab] JavaScript > > ```javascript theme={null} > const claimId = '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d' > const response = await fetch( > `https://service.incaseof.law/openapi/claims/${claimId}/invoices`, > { > headers: { > 'Authorization': 'Bearer YOUR_API_TOKEN_HERE' > } > } > ) > const data = await response.json() > console.log('Invoices:', data.data) > ``` > [tab] Python > > ```python theme={null} > claim_id = '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d' > response = requests.get( > f'https://service.incaseof.law/openapi/claims/{claim_id}/invoices', > headers={'Authorization': 'Bearer YOUR_API_TOKEN_HERE'} > ) > invoices = response.json() > print('Invoices:', invoices['data']) > ``` *** ## Error Handling All API endpoints return errors in a consistent format: ```json theme={null} { "success": false, "message": "Error description here" } ``` ### Common HTTP Status Codes * **200 OK**: Request successful * **201 Created**: Resource created successfully * **400 Bad Request**: Invalid request data or validation error * **401 Unauthorized**: Missing or invalid API token * **404 Not Found**: Resource not found * **500 Internal Server Error**: Server error ### Example Error Handling > [tab] JavaScript > > ```javascript theme={null} > async function createDebtor(debtorData) { > const response = await fetch('https://service.incaseof.law/openapi/debtors', { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_TOKEN_HERE', > 'Content-Type': 'application/json' > }, > body: JSON.stringify(debtorData) > }) > > const data = await response.json() > > if (!response.ok) { > throw new Error(data.message || `HTTP ${response.status}`) > } > > return data.data > } > > // Usage > try { > const debtor = await createDebtor({ > acting_as: 'person', > // ... other fields > }) > console.log('Success:', debtor.id) > } catch (error) { > console.error('Error creating debtor:', error.message) > } > ``` > [tab] Python > > ```python theme={null} > import requests > > def create_debtor(debtor_data): > response = requests.post( > 'https://service.incaseof.law/openapi/debtors', > json=debtor_data, > headers={ > 'Authorization': 'Bearer YOUR_API_TOKEN_HERE', > 'Content-Type': 'application/json' > } > ) > > if not response.ok: > error_data = response.json() > raise Exception(error_data.get('message', f'HTTP {response.status_code}')) > > return response.json()['data'] > > # Usage > try: > debtor = create_debtor({ > 'acting_as': 'person', > # ... other fields > }) > print(f'Success: {debtor["id"]}') > except Exception as e: > print(f'Error creating debtor: {e}') > ``` *** ## Next Steps * Explore the full [API Reference](/api-reference/claims/create-claim) for detailed endpoint documentation * Check out [Debtors](/api-reference/debtors/create-debtor) endpoints * Learn about [Payments](/api-reference/payments/create-payment) and [Documents](/api-reference/documents/upload-document) * Set up [Partner & Revenue Sharing](/Partner-Workflow) for commission-based referral tracking Need help? Contact us at [info@incaseof.law](mailto:info@incaseof.law) # Welcome Source: https://documentation.incaseof.law/Welcome # Welcome to the incaseof.law API Automate your debt collection workflows end-to-end with our comprehensive Case Management API. ## What You Can Do: * Create and manage claims and debtors * Attach invoices and track payments * Monitor collection stages and statuses * Integrate seamlessly with your existing systems *** ## Getting Started ### Step 1: Request API Access If you don't have an API token yet: 1. Visit **[Request API Access](https://app.incaseof.law/openapi)** 2. Fill out the request form with your company details 3. Our team reviews your request (typically 24-48 hours) 4. Receive your API token via email ### Step 2: Authenticate Your Requests All API requests require a Bearer token in the Authorization header: ```bash theme={null} Authorization: Bearer ico_live_your_token_here ``` **Token Details (self-service request):** * Full API access to all endpoints * 1,000 requests per hour by default — the limit of your key is set when it is approved * 90-day validity (renewable) **Partner keys** (issued by the incaseof.law team for a partner integration): * Valid for **365 days** * Their own hourly limit, agreed with you * We are notified 30 days before a key expires and contact you. The key is then either **extended** (the same key keeps working) or we issue a **second key**, you switch over, and the old one is revoked — no downtime either way. * Build and test against the [Partner sandbox](/Partner-Sandbox) with a separate sandbox key. **Rate limit:** requests are counted per key and clock hour (UTC). Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix seconds). Over the limit, the API answers `429 Too Many Requests` with a `Retry-After` header (seconds until the next hour) — wait that long before retrying. ### Step 3: Start Making API Calls Try these endpoints: ```bash theme={null} # List all claims GET /openapi/claims # Create a debtor POST /openapi/debtors # Record a payment POST /openapi/claims/{claim_id}/payments ``` Use the **"Try It"** button on any endpoint page to test directly in your browser! *** ## Support Need help? * Email: [info@incaseof.law](mailto:info@incaseof.law) * View detailed examples in each endpoint documentation * Use the search bar to find specific endpoints Ready to integrate? Navigate to **Claims**, **Debtors**, or **Payments** to get started! # Create claim Source: https://documentation.incaseof.law/api-reference/claims/create-claim post /openapi/claims Create a new claim. The organisation is determined from your API key (partner keys: from `customer_id`). Financial, workflow and collection-stage fields are managed by incaseof.law and cannot be set here — upload the invoice to the claim afterwards (`POST /openapi/claims/{claim_id}/invoices` or `/invoices/manual`). **Partner keys:** `customer_id` is required; a `debtor_id` must be a debtor of your own customers. **Organisation keys:** `customer_id` is optional; `collection_basis` cannot be set. **Partner program (side effect):** the **first** claim created for a partner-created customer with a valid e-mail sends that customer an invitation to the incaseof.law portal. Later claims do not send again. # Decide on the judicial step Source: https://documentation.incaseof.law/api-reference/claims/create-lawsuit-decision post /openapi/claims/{claim_id}/lawsuit-decision The creditor's decision at `dunning_action_recommended` (or `dunning_action_filed`): `sue` takes the claim to court (a Mahnbescheid in Germany, a Mahnklage in Austria), `decline` does not. One decision per claim — a second one answers `400`. - The decision is recorded against your API key. - After `sue`, incaseof.law invoices the court fee to the **creditor** — to the e-mail address of the claim's customer — never to you as the partner. The court step itself is taken by the incaseof.law team. - A decision does not change the collection stage by itself; the answer is your receipt. The stage moves on as the court step progresses (webhook `claim.collection_stage_changed`). `400` when the claim is not at one of those two stages, a decision already exists, a lawyer is required but not named, a lawyer is named on a German claim, the amount exceeds the Austrian Mahnklage limit, or no Mahnverfahren is available for the debtor. # Estimate the judicial step Source: https://documentation.incaseof.law/api-reference/claims/estimate-lawsuit-decision get /openapi/claims/{claim_id}/lawsuit-decision/estimate What taking the claim to court would cost, and which rules a decision will be checked against. Call it when a claim reaches `dunning_action_recommended` (the webhook tells you) and before you send a decision. `decision_open` is true while a decision can be sent: the claim is at `dunning_action_recommended` or `dunning_action_filed` and no decision has been recorded yet. - Germany (`jurisdiction: DE`): a Mahnbescheid — court fee under the GKG, no lawyer through the platform (`lawyer_allowed: false`). - Austria (`AT`): a Mahnklage — a lawyer is required when `lawyer_required` is true (`streitwert`: 5 000 EUR or above; `no_org_cert`: the creditor has no ERV certificate), and then the decision must name one. Answers `400` when no Mahnverfahren is available for the debtor (a debtor outside the EU or in Denmark). # Get claim Source: https://documentation.incaseof.law/api-reference/claims/get-claim get /openapi/claims/{id} The claim with its debtor, invoices and the payments the debtor made. # Get the judicial-step decision Source: https://documentation.incaseof.law/api-reference/claims/get-lawsuit-decision get /openapi/claims/{claim_id}/lawsuit-decision The decision taken on this claim — through the API or by the creditor in the portal. `404` while none exists. # List claims Source: https://documentation.incaseof.law/api-reference/claims/list-claims get /openapi/claims The claims of your organisation (organisation key) or of all your customers (partner key; with `customer_id`, those of that customer's organisation only). Newest first, paged. # Update claim Source: https://documentation.incaseof.law/api-reference/claims/update-claim patch /openapi/claims/{id} Mark a claim disputed or fulfilled, or relink it to another of your customers. Only send the fields you change. **State is read-only.** `collection_stage`, `submission_state` and `status` are driven by the collection workflow, and `collection_basis` is fixed at creation: sending any of them answers `400 Validation failed`. A partner key may relink a claim to its own customers only (`403` otherwise) and cannot remove the customer (`customer_id: null` → `400`). # Create customer (or reuse the existing one) Source: https://documentation.incaseof.law/api-reference/customers/create-customer post /openapi/customers Create a customer — a creditor you work for. **`address` is required** — `street`, `zip`, `city` and `country` (ISO code of a European country). It is the creditor address on the collection letters and the court-fee invoice; a missing or empty line is a `400` that names it, e.g. `address.zip is required`. **Partner keys:** `partner_id` is optional (it defaults to your partner account; another partner's id → `403`). Without `customer_id` the customer gets an organisation of its own, created here. **Organisation keys:** the customer is created in your organisation; `partner_id` names the referring partner. **Reusing an existing client.** Send your own ID for the business as `partner_client_reference` and/or its VAT ID as `uid` on every call. Before creating, the API looks for a customer of *your* partner account — first by `partner_client_reference`, then by `uid`, and when neither matches, by the same `email` **and** the same `name` (case and spaces ignored), provided that customer's stored `partner_client_reference` / `uid` do not differ from the ones you sent: - match → the existing customer is returned with **HTTP 200** and `reused: true` (same `id` and `organization_id`; stored name, email and address are not changed — use PATCH for that). A key the existing customer does not have yet is added to it. - no match → a new customer is created, **HTTP 201**, `reused: false`. - `partner_client_reference` matches one customer and `uid` another → **HTTP 409**, nothing is created. Both keys are unique per partner account; another partner sending the same UID gets its own customer. Without either key, only name and e-mail identify the client: a business whose name or e-mail you send differently becomes a new customer — send `partner_client_reference` to make the match exact. The client's onboarding invitation is sent once, with the first claim of that customer. **Client e-mail that already has a login.** When `email` belongs to an existing incaseof.law user (e.g. one owner running two companies), no invitation is sent: that user is added to the new customer's organisation right away, gets a short e-mail that another company is now in their account, and sees it after the next login. The response then has `existing_user_linked: true`. Each company stays its own customer — keep storing one customer `id` per company. # Forward a provider confirmation Source: https://documentation.incaseof.law/api-reference/customers/create-provider-confirmation post /openapi/customers/{id}/provider-confirmation Forward the provider's one-time confirmation under § 1.5 lit. b of the cooperation agreement / GTC I.2c: the provider confirms that it hands over claims only where the patient's consent under the Annex 2 clause exists. Send the day the provider gave it, the person who confirmed it and the version of the consent clause the provider uses. ICO stores only this confirmation, never the consent itself. For a partner whose agreement requires it, nothing is sent to the debtors of this customer — no letter, SMS or e-mail, no court filing — until the confirmation is on file and the customer has accepted ICO's GTC and DPA. Each call stores a new record (a renewed confirmation is a new record); one is enough. Partner keys only (`403` for an organisation key); your own customers only (`404` otherwise). `confirmed_at` may not lie in the future (`400`). # Delete customer Source: https://documentation.incaseof.law/api-reference/customers/delete-customer delete /openapi/customers/{id} Delete a customer that nothing refers to. A customer that still has claims, debtors or revenue shares is not deleted (`409`, with the counts in the message) — the claims would lose their customer and you your access to them. # Get customer Source: https://documentation.incaseof.law/api-reference/customers/get-customer get /openapi/customers/{id} # List customers Source: https://documentation.incaseof.law/api-reference/customers/list-customers get /openapi/customers **Partner keys:** all your customers, in every organisation. **Organisation keys:** the customers of your organisation; `partner_id` narrows the list to one referring partner (partner keys ignore it). # Update customer Source: https://documentation.incaseof.law/api-reference/customers/update-customer patch /openapi/customers/{id} Update a customer. Only send the fields you change. Use it to add `partner_client_reference` / `uid` to a customer created without them; `null` clears a key. A key already held by another customer of your partner account → `409`. # Create debtor Source: https://documentation.incaseof.law/api-reference/debtors/create-debtor post /openapi/debtors Create a new debtor in your organisation (partner keys: in the organisation of `customer_id`, which is required). **Name mapping**: - A natural person: `acting_as: person`, `debtor_type: privateperson`, and the name split into `person.first_name` and `person.last_name` (not the whole name in `last_name`). `salutation` only when known. - **Salutation**: `mr` (Herr), `mrs` (Frau), `diverse` (Divers); German and English spellings such as `Herr`, `Frau`, `male`, `female`, `m`, `w`, `f`, `d` are accepted case-insensitively and stored as the code, also when sent as `person.gender`. Unknown gender → leave it out (no salutation; `diverse` is not a fallback). An unrecognised value is a `400` listing the accepted ones — see `SalutationInput`. - A company: `acting_as: company`, `debtor_type: protocolled_company` (registered in the Firmenbuch) or `unprotocolled_company`, and the name in `company.company_name`. - A debtor sent as `privateperson` whose name carries the legal form of an entity registered in the Firmenbuch (GmbH, AG, eGen, SE, SCE, EWIV, Sparkasse, Versicherungsverein, OG, KG, e.U.) is stored as a `protocolled_company` with that name; the response returns the stored debtor. - If you only hold the name in one field, send it in `person.last_name` and leave `first_name` empty. A case whose debtor is a `privateperson` without a first name is checked by our case managers (person or business, name split) before the first letter goes out. **Your keys**: `company.uid` (the business's EU VAT ID) and `partner_client_reference` (your own customer number for the debtor) are stored and returned by the `/openapi/debtors` endpoints. They are not used to find an existing debtor: every `POST` creates a new one. `iban`, `bic` and `person.salutation` may be `null` (= not given). # Get debtor Source: https://documentation.incaseof.law/api-reference/debtors/get-debtor get /openapi/debtors/{id} # List debtors Source: https://documentation.incaseof.law/api-reference/debtors/list-debtors get /openapi/debtors The debtors of your organisation (organisation key) or of all your customers (partner key; with `customer_id`, those of that customer's organisation only). # Update debtor Source: https://documentation.incaseof.law/api-reference/debtors/update-debtor patch /openapi/debtors/{id} Update a debtor. Only send the fields you change; `addresses` and `communication_channels` **replace** all existing entries. `customer_id` relinks the debtor to another of your customers **in the same organisation** (`400` for a customer in another organisation; partner keys: `403` for a customer of another partner, `400` for `null`). On a debtor that is a person, a `company` block turns it into a company only together with `company.company_name` (otherwise `400`); a block of nulls only (e.g. `company: { uid: null }`) is ignored. # Delete document Source: https://documentation.incaseof.law/api-reference/documents/delete-document delete /openapi/documents/{id} Delete a document that was uploaded through the API. Documents added by the creditor or by incaseof.law cannot be deleted through the API (`403`). A document the incaseof.law team has released to the debtor at any time, or that belongs to a claim taken to court — the creditor approved the court step, or a filing was recorded after the document was uploaded — is not erased: it disappears from the API and from every portal but is kept for the incaseof.law team (`data.retained: true`). Any other document is deleted permanently (`data.retained: false`). Either way, an invoice of the claim that was created from this document is deleted with it — unless a collection letter or an installment agreement of the claim is in force, the claim is closed or went to court, or it is the claim's last invoice; then the invoice stays and the claim's activity log says why. # Download document Source: https://documentation.incaseof.law/api-reference/documents/download-document get /openapi/documents/{id}/download The file itself, with its original filename in `Content-Disposition`. # List documents Source: https://documentation.incaseof.law/api-reference/documents/list-documents get /openapi/claims/{claim_id}/documents The documents of a claim you may see, newest first. # Upload document Source: https://documentation.incaseof.law/api-reference/documents/upload-document post /openapi/claims/{claim_id}/documents Upload a supporting document to a claim (any number per claim). **Upload:** `multipart/form-data` with a `file` part and the optional fields `documentType`, `description` and `visibility`. The fields may come before or after the file part. **Who sees the document:** - `visibility: creditor` (default) — the creditor organisation sees it in its customer portal. - `visibility: partner_only` — only your partner integration (and the incaseof.law team) sees it; partner API keys only. - The **debtor never sees** a document uploaded through the API. Only the incaseof.law team can release a document to the debtor portal. **File types:** PDF, Word (.doc, .docx), Excel (.xls, .xlsx), text (.txt), images (.png, .jpg, .jpeg, .gif, .webp). Other types answer `400`. **Size limit:** 50 MB (`413` above it). # Health check Source: https://documentation.incaseof.law/api-reference/health-check get /health Whether the API is up. Needs no API key — the `Authorization` header is ignored here. # Upload invoice PDF Source: https://documentation.incaseof.law/api-reference/invoices/create-invoice post /openapi/claims/{claim_id}/invoices Upload the PDF of an invoice the claim is based on. A new invoice is created for it; its amount adds to the claim's `total_claim_amount`. Fields you send are stored on that invoice; the PDF is read automatically for the ones you leave out. **Only PDF files** (`multipart/form-data`, a `file` part). The fields may come before or after the file part. Field names: `total_amount` is stored as `invoice_amount_gross`, `maturity_date` as `invoice_due_date`, `issue_date` as `invoice_issue_date`. Files over 50 MB answer `413`. An invoice partly paid before handover: send `total_amount` (the amount on the invoice) and `amount_paid` (optionally `last_payment_date`); the rules are those of the manual invoice endpoint. A refused combination answers `400` and stores nothing. Required fields and the health-data check of your partner agreement (see *Partner intake rules*) are applied before the PDF is stored: a refused upload stores nothing. `description` / `subject` is checked as the subject. > [!NOTE] > > This endpoint requires `multipart/form-data` with a PDF file upload. > The interactive playground cannot send file uploads; use Insomnia/Postman for testing. ## Overview Upload a PDF invoice and attach it to a claim. When you upload a PDF, it is stored and linked to the claim, and OCR attempts to extract invoice data and populate the invoice record. > [!WARNING] > > **PDF files only**: Only PDF format is accepted. Other file formats (images, Word, Excel, etc.) will be rejected. ### Request Format * Content-Type: `multipart/form-data` * Required field: `file` (**PDF only**) * Optional text fields: `invoice_number`, `total_amount`, `maturity_date`, `issue_date`, `invoice_issuer`, `invoice_recipient`, `subject`, `invoice_amount_net`, `creditor_reminder_fees_incurred`, `amount_paid`, `last_payment_date` ## Authentication Requires API Token authentication via Bearer token. ## Path Parameters **claim\_id** `string` *required* UUID of the claim you are attaching an invoice to ## Request Body (Multipart Form) **file** `file` *required* PDF invoice file to upload. Only PDF format is accepted. **invoice\_number** `string` Invoice number **total\_amount** `string` Gross amount of the invoice (maps to `invoice_amount_gross`) **maturity\_date** `string` Due date in ISO 8601 format (maps to `invoice_due_date`) **issue\_date** `string` Issue date in ISO 8601 format (maps to `invoice_issue_date`) **invoice\_issuer** `string` Invoice issuer name **invoice\_recipient** `string` Invoice recipient name **subject** `string` Optional subject/description **invoice\_amount\_net** `string` Net amount **creditor\_reminder\_fees\_incurred** `string` Reminder fees (still unpaid) **amount\_paid** `string` Amount the debtor already paid you on this invoice before handover. Requires `total_amount` and must be less than it. We collect only the rest; it is not recorded as a payment. A refused combination answers `400` and stores nothing. See the manual invoice endpoint for details. **last\_payment\_date** `string` Date of that payment (`YYYY-MM-DD`, not in the future). Requires `amount_paid`. ## Testing Instructions 1. Create a new request: Method `POST`, URL `/openapi/claims//invoices` 2. Auth tab: Type `Bearer`, Token = your API token 3. Body tab: Type `Multipart Form` * Add field `file` with type `File`, select your `.pdf` (original filename is automatically preserved) * Optional text fields: `invoice_number`, `total_amount`, `maturity_date`, `issue_date`, `invoice_issuer`, `invoice_recipient`, `subject`, `invoice_amount_net`, `creditor_reminder_fees_incurred`, `amount_paid`, `last_payment_date` 4. Send request and verify `201` response > [!NOTE] > > **Filename Preservation**: When using `multipart/form-data`, the original PDF filename is automatically preserved. > > The Mintlify playground cannot send `multipart/form-data` with files. Use Insomnia/Postman for testing. ## Examples ```bash cURL theme={null} curl -X POST \ 'https:///openapi/claims/3c90c3cc-0d44-4b50-8888-8dd257363052/invoices' \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -F 'file=@/path/to/invoice.pdf' \ -F 'invoice_number=INV-2025-001' \ -F 'total_amount=123.45' \ -F 'maturity_date=2025-10-01' \ -F 'issue_date=2025-09-15' \ -F 'invoice_issuer=Acme GmbH' \ -F 'invoice_recipient=John Doe' \ -F 'subject=Original invoice PDF' ``` ```javascript JavaScript theme={null} const formData = new FormData() formData.append('file', yourFileInput.files[0]) formData.append('invoice_number', 'INV-2025-001') formData.append('total_amount', '123.45') formData.append('maturity_date', '2025-10-01') formData.append('issue_date', '2025-09-15') formData.append('invoice_issuer', 'Acme GmbH') formData.append('invoice_recipient', 'John Doe') formData.append('subject', 'Original invoice PDF') const res = await fetch('https:///openapi/claims/3c90c3cc-0d44-4b50-8888-8dd257363052/invoices', { method: 'POST', headers: { Authorization: 'Bearer YOUR_API_TOKEN' }, body: formData, }) const json = await res.json() ``` ```python Python theme={null} import requests url = 'https:///openapi/claims/3c90c3cc-0d44-4b50-8888-8dd257363052/invoices' headers = { 'Authorization': 'Bearer YOUR_API_TOKEN' } files = { 'file': ('invoice.pdf', open('invoice.pdf', 'rb'), 'application/pdf') } data = { 'invoice_number': 'INV-2025-001', 'total_amount': '123.45', 'maturity_date': '2025-10-01', 'issue_date': '2025-09-15', 'invoice_issuer': 'Acme GmbH', 'invoice_recipient': 'John Doe', 'subject': 'Original invoice PDF', } response = requests.post(url, headers=headers, files=files, data=data) print(response.status_code, response.text) ``` ## Responses ```json Success theme={null} { "success": true, "data": { "id": "b7c2d6ba-9d2c-42b6-8e1f-4a8e3d9e9c77", "claim_id": "3c90c3cc-0d44-4b50-8888-8dd257363052", "invoice_number": "INV-2025-001", "invoice_amount_gross": 123.45, "invoice_due_date": "2025-10-01", "invoice_issue_date": "2025-09-15", "invoice_issuer": "Acme GmbH", "invoice_recipient": "John Doe", "subject": "Original invoice PDF", "created_at": "2025-10-11T10:30:00Z" } } ``` ```json Error - Claim Not Found theme={null} { "success": false, "message": "Claim not found" } ``` ```json Error - Invalid File Type theme={null} { "success": false, "message": "Invalid file type. Only PDF files are allowed for invoice uploads." } ``` ```json Error - No File Uploaded theme={null} { "success": false, "message": "Invalid request. This endpoint only supports PDF invoice uploads via multipart/form-data. Please use multipart/form-data with a file field. The original filename will be automatically preserved." } ``` ## Notes * This endpoint **only accepts PDF file uploads** via `multipart/form-data` * OCR runs on uploaded PDFs and may populate invoice fields automatically * The invoice amount will automatically update the claim's total\_claim\_amount via database triggers # Create invoice from data (no PDF) Source: https://documentation.incaseof.law/api-reference/invoices/create-invoice-manual post /openapi/claims/{claim_id}/invoices/manual Create an invoice from JSON, without a file. Every call creates **a new invoice** on the claim; its amounts add to the claim's `total_claim_amount`. No automatic reading runs on this path, so `data_extraction_status` is `manual`. Amounts take at most two decimal places. Reminder fees (`creditor_reminder_fees_incurred`) can no longer be added once a collection letter including them has gone out (`400`). **Partly paid before handover:** keep `invoice_amount_gross` at the amount on the invoice and send what the debtor already paid you in `amount_paid` (optionally with `last_payment_date`). We then collect only the open rest. Send reminder fees the debtor has paid only for the part still open. Do not report such a payment through `/payments` — that endpoint records money paid during collection. ## Overview Create an invoice by submitting the invoice data as structured **JSON**, without uploading a PDF document. Use this endpoint when you have no invoice file and want to pass all fields manually. Unlike the PDF upload endpoint, no OCR runs on this path, so the created invoice is marked with `data_extraction_status: "manual"`. The invoice amounts automatically update the claim's `total_claim_amount` via database triggers. > [!NOTE] > > Need to attach an actual PDF invoice (with OCR extraction)? Use > `POST /openapi/claims//invoices` (multipart/form-data) instead. ### Request Format * Content-Type: `application/json` * All fields are optional unless your partner agreement requires them (see *Partner intake rules* in the API description: `default_date`, `creditor_reminder_dates`, `contract_date`, `subject`). Amounts must be non-negative and dates must be valid ISO 8601 (`YYYY-MM-DD`); invalid values return a `400`. * `default_date`, `creditor_reminder_dates`, `default_basis` and `contract_date` state how and when the debtor fell into default. `default_basis: "bgb_286_3"` (default 30 days after the due date and receipt of the invoice, § 286 (3) BGB) needs no reminder dates; against a consumer it applies only if the invoice pointed this out. * If your agreement prohibits health data, `subject`, `invoice_issuer` and `invoice_recipient` are checked; a match returns `400 PROHIBITED_DATA` naming the field. ## Authentication Requires API Token authentication via Bearer token. ## Path Parameters **claim\_id** `string` *required* UUID of the claim you are attaching an invoice to ## Request Body (JSON) **invoice\_number** `string` Invoice number/reference **invoice\_issuer** `string` Name of the invoice issuer (creditor) **invoice\_recipient** `string` Name of the invoice recipient (debtor) **subject** `string` Invoice subject/description **invoice\_amount\_net** `number` Net invoice amount (before tax). Must be ≥ 0. **invoice\_amount\_gross** `number` Gross amount on the invoice. Must be ≥ 0. Feeds `claims.total_claim_amount` (minus `amount_paid`). **invoice\_issue\_date** `string` Invoice issue date in ISO 8601 format (`YYYY-MM-DD`) **invoice\_due\_date** `string` Invoice due date in ISO 8601 format (`YYYY-MM-DD`) **creditor\_reminder\_fees\_incurred** `number` Reminder fees already incurred by creditor and still unpaid. Must be ≥ 0. Feeds `claims.total_claim_amount`. **amount\_paid** `number` Amount the debtor already paid you on this invoice **before** you handed it over. Requires `invoice_amount_gross` in the same request and must be less than it (a fully paid invoice is not handed over). We collect only the open rest; interest and our collection fees are calculated on it, and the collection letter shows "invoice amount – paid – open". It is **not** recorded as a payment and sends no payment notification. **last\_payment\_date** `string` Date of the (last) payment counted in `amount_paid`, ISO 8601 (`YYYY-MM-DD`), not in the future. Requires `amount_paid`. Shown on the letter when given. ## Examples ```bash cURL theme={null} curl -X POST \ 'https:///openapi/claims/3c90c3cc-0d44-4b50-8888-8dd257363052/invoices/manual' \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "invoice_number": "RE-2026-0042", "invoice_issuer": "Muster GmbH", "invoice_recipient": "Max Mustermann", "subject": "Consulting services March 2026", "invoice_amount_net": 1000.00, "invoice_amount_gross": 1190.00, "invoice_issue_date": "2026-03-01", "invoice_due_date": "2026-03-15", "creditor_reminder_fees_incurred": 0 }' ``` ```javascript JavaScript theme={null} const res = await fetch( 'https:///openapi/claims/3c90c3cc-0d44-4b50-8888-8dd257363052/invoices/manual', { method: 'POST', headers: { Authorization: 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ invoice_number: 'RE-2026-0042', invoice_issuer: 'Muster GmbH', invoice_recipient: 'Max Mustermann', subject: 'Consulting services March 2026', invoice_amount_net: 1000.0, invoice_amount_gross: 1190.0, invoice_issue_date: '2026-03-01', invoice_due_date: '2026-03-15', creditor_reminder_fees_incurred: 0, }), } ) const json = await res.json() ``` ```python Python theme={null} import requests url = 'https:///openapi/claims/3c90c3cc-0d44-4b50-8888-8dd257363052/invoices/manual' headers = { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Content-Type': 'application/json', } payload = { 'invoice_number': 'RE-2026-0042', 'invoice_issuer': 'Muster GmbH', 'invoice_recipient': 'Max Mustermann', 'subject': 'Consulting services March 2026', 'invoice_amount_net': 1000.00, 'invoice_amount_gross': 1190.00, 'invoice_issue_date': '2026-03-01', 'invoice_due_date': '2026-03-15', 'creditor_reminder_fees_incurred': 0, } response = requests.post(url, headers=headers, json=payload) print(response.status_code, response.text) ``` ## Responses ```json Success theme={null} { "success": true, "data": { "id": "b7c2d6ba-9d2c-42b6-8e1f-4a8e3d9e9c77", "claim_id": "3c90c3cc-0d44-4b50-8888-8dd257363052", "invoice_number": "RE-2026-0042", "invoice_issuer": "Muster GmbH", "invoice_recipient": "Max Mustermann", "subject": "Consulting services March 2026", "invoice_amount_net": 1000.00, "invoice_amount_gross": 1190.00, "invoice_issue_date": "2026-03-01", "invoice_due_date": "2026-03-15", "creditor_reminder_fees_incurred": 0, "amount_paid": null, "last_payment_date": null, "amount_open": 1190.00, "data_extraction_status": "manual", "created_at": "2026-03-01T10:30:00Z" } } ``` ```json Error - Validation Failed theme={null} { "success": false, "error": "VALIDATION_ERROR", "message": "Validation failed", "details": [] } ``` ```json Error - Claim Not Found theme={null} { "success": false, "message": "Claim not found" } ``` ## Notes * This endpoint **only accepts JSON**; it does not handle file uploads. * No OCR runs; the invoice is stored with `data_extraction_status: "manual"`. * `invoice_amount_gross` (minus `amount_paid`) and `creditor_reminder_fees_incurred` automatically update the claim's `total_claim_amount` via database triggers. * **Partly paid before handover:** send the invoice amount in `invoice_amount_gross` and the paid part in `amount_paid`, e.g. `"invoice_amount_gross": 59.56, "amount_paid": 43.57, "last_payment_date": "2024-11-05"`. The response then shows `invoice_amount_gross: 59.56`, `amount_paid: 43.57`, `amount_open: 15.99`. Do not report such a payment through `/payments` — that endpoint records money paid during collection. Reminder fees the debtor has paid are sent only for the part still open. # List invoices Source: https://documentation.incaseof.law/api-reference/invoices/list-invoices get /openapi/claims/{claim_id}/invoices All invoices of a claim. # Record payment Source: https://documentation.incaseof.law/api-reference/payments/create-payment post /openapi/claims/{claim_id}/payments Record a payment the debtor made on this claim. **`invoice_number` is required** and says whom the debtor paid: - the number of one of the claim's **active collection letters** — the debtor paid incaseof.law on that letter; - `Other` — the debtor paid **you or the creditor directly**. The payment reduces the claim; incaseof.law then invoices its collection fees to the creditor. Any other number answers `400` with the claim's active letter numbers in the message. On a claim that has no collection letter yet, any value is accepted. The claim must have a debtor (`404` otherwise). # Get payment Source: https://documentation.incaseof.law/api-reference/payments/get-payment get /openapi/payments/{id} # List payments Source: https://documentation.incaseof.law/api-reference/payments/list-payments get /openapi/claims/{claim_id}/payments The payments the debtor made on this claim, newest first. # Collection Stage Events Source: https://documentation.incaseof.law/webhooks/claim-collection-stage-changed Fired whenever a claim moves to a new collection stage. Sent every time a claim moves to a new collection stage — including the very first stage assignment on claim creation (`from_stage` is `null` in that case). The event `type` you'll see in the body and in the `X-IcoLaw-Event` header is **`claim.collection_stage_changed`**. | Property | Value | | - | - | | **Event type** | `claim.collection_stage_changed` | | **HTTP method** | `POST` | | **Target URL** | Your configured webhook URL | | **Headers** | See [Webhooks Overview → Headers](/webhooks/overview#headers) | | **API version** | `2026-05-14` | *** ## Payload ```json theme={null} { "id": "evt_01HXYZ8K9MGV9C3K3F2K8AB12C", "type": "claim.collection_stage_changed", "created_at": "2026-05-14T11:30:00.000Z", "api_version": "2026-05-14", "data": { "claim_id": "5f3c1b22-3f4b-4d2e-9b1a-7c8e9d0f1a2b", "partner_reference": "INV-2024-00891", "from_stage": "first_demand_letter", "to_stage": "second_demand_letter", "changed_at": "2026-05-14T11:29:58.000Z" } } ``` ### Envelope fields **id** `string` *required* Stable event identifier (`evt_…`). The same `id` is reused for every retry of the same event — use it to deduplicate. It is **not** the value of the `X-IcoLaw-Delivery` header, which is a separate UUID, also stable across retries; dedupe on one of the two, consistently. **type** `string` *required* Always `claim.collection_stage_changed` for this event. **created\_at** `string (RFC 3339)` *required* Server-side timestamp at which the event was emitted. **api\_version** `string` *required* Payload contract version (`YYYY-MM-DD`). Currently `2026-05-14`. Pin this in your handler to be notified of non-additive shape changes before they reach production. ### `data` fields **data.claim\_id** `uuid` *required* ID of the claim whose stage just changed. Use it to look up the full claim via [`GET /openapi/claims/{id}`](/api-reference/claims/get-claim). **data.partner\_reference** `string | null` The `partner_reference` you provided when creating the claim through the API, surfaced verbatim so you can correlate back to your own system without an extra API call. For a claim created by incaseof.law, its `external_reference`. **data.from\_stage** `enum | null` *required* Previous collection stage. `null` on the very first stage assignment (claim creation). Possible values (14): `new`, `in_processing`, `first_demand_letter`, `second_demand_letter`, `third_demand_letter`, `installment_payment`, `installment_cancelled`, `dunning_action_recommended`, `exekutionsantrag_recommended`, `warten_auf_zinstermin`, `manuelle_pruefung`, `mzr_aufhebungserklaerung_sent`, `mzr_klage_recommended`, `closed` — see the [reference](#stage-value-reference) below. **data.to\_stage** `enum` *required* New collection stage that just took effect. Same value set as `from_stage` (excluding `null`). **data.changed\_at** `string (RFC 3339)` *required* When the stage transition was persisted server-side. Use this for reconciliation — see [Reconcile out-of-order events](/webhooks/overview#reconcile-out-of-order-events). *** ## Stage value reference | Value | Meaning | | - | - | | `new` | Claim just created, no action taken yet. | | `in_processing` | Initial intake / verification stage. | | `first_demand_letter` | First demand letter (CL1) sent. | | `second_demand_letter` | Second demand letter (CL2) sent. | | `third_demand_letter` | Third demand letter (CL3) sent. | | `installment_payment` | Debtor entered an installment agreement. | | `installment_cancelled` | Instalment agreement cancelled after a missed instalment (Terminsverlust). The debtor may still settle the missed instalment; no judicial step has been recommended yet. | | `dunning_action_recommended` | Out-of-court collection exhausted — judicial dunning recommended. | | `dunning_action_filed` | The judicial dunning action has been filed electronically: the Mahnklage for an Austrian claim, the application for a Mahnbescheid for a German one. Set automatically when the filing is dispatched — it records the transmission, not the court's acceptance; a claim filed before this stage existed stays at `dunning_action_recommended`. | | `exekutionsantrag_recommended` | Title obtained — enforcement (Exekutionsantrag) recommended. | | `warten_auf_zinstermin` | Tenancy claims only: waiting for the next rent due date. | | `manuelle_pruefung` | Tenancy claims only: manual legal review (e.g. after a payment during the tenancy procedure). | | `mzr_aufhebungserklaerung_sent` | Tenancy claims only: termination declaration (Aufhebungserklärung) sent. | | `mzr_klage_recommended` | Tenancy claims only: action for rent and eviction (Mietzins- und Räumungsklage) recommended. | | `closed` | Claim closed (paid, written off, withdrawn or otherwise resolved) — the reason comes with [`claim.status_changed`](/webhooks/claim-status-changed). | This is the complete list — the database accepts no other value. The four tenancy stages occur only on rental claims. *** ## Example: initial claim creation When a claim is first created the event has `from_stage: null`. This signal is useful for "ingest into our CRM" workflows. ```json theme={null} { "id": "evt_01HXYZ8K9MGV9C3K3F2K8AB12D", "type": "claim.collection_stage_changed", "created_at": "2026-05-14T09:00:01.000Z", "api_version": "2026-05-14", "data": { "claim_id": "5f3c1b22-3f4b-4d2e-9b1a-7c8e9d0f1a2b", "partner_reference": "INV-2024-00891", "from_stage": null, "to_stage": "new", "changed_at": "2026-05-14T09:00:00.500Z" } } ``` ## Example: first demand letter sent ```json theme={null} { "id": "evt_01HXYZ8K9MGV9C3K3F2K8AB12E", "type": "claim.collection_stage_changed", "created_at": "2026-05-18T08:30:00.000Z", "api_version": "2026-05-14", "data": { "claim_id": "5f3c1b22-3f4b-4d2e-9b1a-7c8e9d0f1a2b", "partner_reference": "INV-2024-00891", "from_stage": "in_processing", "to_stage": "first_demand_letter", "changed_at": "2026-05-18T08:29:55.000Z" } } ``` ## Example: claim closed ```json theme={null} { "id": "evt_01HXYZ8K9MGV9C3K3F2K8AB12F", "type": "claim.collection_stage_changed", "created_at": "2026-06-02T14:10:00.000Z", "api_version": "2026-05-14", "data": { "claim_id": "5f3c1b22-3f4b-4d2e-9b1a-7c8e9d0f1a2b", "partner_reference": "INV-2024-00891", "from_stage": "first_demand_letter", "to_stage": "closed", "changed_at": "2026-06-02T14:09:58.000Z" } } ``` *** ## Handler example (Node.js + Express) End-to-end: verify signature, deduplicate, dispatch. ```js theme={null} const express = require('express') const crypto = require('crypto') const app = express() const SECRET = process.env.WEBHOOK_SECRET const seen = new Map() // replace with Redis / DB in production // IMPORTANT: use raw body parser so the signature verifies against bytes app.post( '/webhooks/incaseof', express.raw({ type: 'application/json' }), async (req, res) => { const sig = req.headers['x-icolaw-signature'] || '' if (!verify(req.body, sig, SECRET)) { return res.status(401).end() } const deliveryId = req.headers['x-icolaw-delivery'] if (seen.has(deliveryId)) { return res.status(200).end() // already processed } seen.set(deliveryId, Date.now()) const event = JSON.parse(req.body.toString('utf8')) if (event.type === 'claim.collection_stage_changed') { await onStageChanged(event.data) } else if (event.type === 'claim.status_changed') { await onStatusChanged(event.data) } // Any other type: acknowledge and ignore — new types may be added. res.status(200).end() } ) async function onStageChanged(data) { // Reconcile against your local mirror by changed_at const local = await db.claims.get(data.claim_id) if (local?.last_stage_changed_at >= data.changed_at) return // stale event await db.claims.upsert({ id: data.claim_id, stage: data.to_stage, last_stage_changed_at: data.changed_at, }) // If you need details (debtor, amounts, etc) fetch via the API: // const claim = await icoApi.get(`/openapi/claims/${data.claim_id}`) } function verify(rawBody, header, secret) { // ... see Webhooks Overview → Reference implementations } app.listen(3000) ``` > [!TIP] > > Use the **"Send test event"** button in the admin UI to fire a synthetic event with `claim_id: "00000000-0000-0000-0000-000000000000"`. Filter that ID out in your real handler — it's intentionally a non-existent claim so you can sanity-check end-to-end without polluting your data. # Case Status Events Source: https://documentation.incaseof.law/webhooks/claim-status-changed Fired when a claim is closed (with the reason), disputed or reopened. Sent when the **case status** of a claim changes — and when a closed claim's closure reason changes. The case status has three values: `open`, `disputed`, `closed`. A closure carries its reason, so you can tell a claim paid in full from one written off. The event `type` you'll see in the body and in the `X-IcoLaw-Event` header is **`claim.status_changed`**. | Property | Value | | - | - | | **Event type** | `claim.status_changed` | | **HTTP method** | `POST` | | **Target URL** | Your configured webhook URL | | **Headers** | See [Webhooks Overview → Headers](/webhooks/overview#headers) | | **API version** | `2026-05-14` | It is not sent when a claim is created: every claim starts `open`. A closure also sends [`claim.collection_stage_changed`](/webhooks/claim-collection-stage-changed) (to `closed`); the two are enqueued together, the stage event first. *** ## Payload ```json theme={null} { "id": "evt_01HXYZ8K9MGV9C3K3F2K8AB13A", "type": "claim.status_changed", "created_at": "2026-09-22T10:15:02.000Z", "api_version": "2026-05-14", "data": { "claim_id": "5f3c1b22-3f4b-4d2e-9b1a-7c8e9d0f1a2b", "partner_reference": "INV-2024-00891", "from_status": "open", "to_status": "closed", "closure_reason": "paid", "changed_at": "2026-09-22T10:15:00.000Z" } } ``` The envelope (`id`, `type`, `created_at`, `api_version`) is the same as for every event — see [Collection Stage Events → Envelope fields](/webhooks/claim-collection-stage-changed#envelope-fields). ### `data` fields **data.claim\_id** `uuid` *required* ID of the claim. Look up the full claim via [`GET /openapi/claims/{id}`](/api-reference/claims/get-claim). **data.partner\_reference** `string | null` The `partner_reference` you provided when creating the claim through the API; for a claim created by incaseof.law, its `external_reference`. **data.from\_status** `enum` *required* The case status before the change: `open`, `disputed` or `closed`. **data.to\_status** `enum` *required* The case status now: `open`, `disputed` or `closed`. **data.closure\_reason** `enum | null` *required* Why the claim was closed — set when `to_status` is `closed`, `null` otherwise. See the [reference](#closure-reasons) below. **data.changed\_at** `string (RFC 3339)` *required* When the change was persisted server-side. *** ## Case status | Value | Meaning | | - | - | | `open` | Collection is running (any `collection_stage` other than `closed`). | | `disputed` | The claim is disputed (`claim_disputed`) and not closed. | | `closed` | The claim is closed (`collection_stage` is `closed`) — whether or not it was disputed. | | `from_status` → `to_status` | When | | - | - | | `open` → `closed` | Paid in full, or closed without payment | | `open` → `disputed` | The debtor disputes the claim — or you set `claim_disputed` through [`PATCH /openapi/claims/{id}`](/api-reference/claims/update-claim) | | `disputed` → `open` | The dispute flag is cleared | | `disputed` → `closed` | A disputed claim is closed | | `closed` → `open` / `disputed` | The claim is reopened | | `closed` → `closed` | The closure reason changed — a claim closed without payment was paid in full after all (`closure_reason: paid`) | ## Closure reasons | Value | Meaning | | - | - | | `paid` | Paid in full. | | `installment_plan` | Paid in full through an instalment plan. | | `written_off` | Closed without payment as uncollectable. | | `withdrawn` | The creditor called the case off. | | `disputed` | Closed because the claim is disputed. | | `merged` | Merged into another claim of the same creditor against the same debtor, before the first collection letter. The other claim continues in its place; this one receives no further events. The event names the continuing claim in `merged_into` (`claim_id`, `partner_reference`). | | `insolvency` | Insolvency proceedings were opened against the debtor. Collection outside the proceedings is no longer possible; the claim can only be filed in them. | `paid` and `installment_plan` follow from the payments; `written_off`, `withdrawn`, `disputed` and `insolvency` are recorded by the incaseof.law team when they close a claim that was not paid; `merged` when they merge claims. *** ## Reconciliation The same two values are on the claim itself: [`GET /openapi/claims/{id}`](/api-reference/claims/get-claim) and [`GET /openapi/claims`](/api-reference/claims/list-claims) return `case_status` and `closure_reason`. Failed deliveries are not re-sent — compare them with your mirror once a day (see [Webhooks Overview](/webhooks/overview)). Claims closed before this event existed have `closure_reason: null`. > [!NOTE] > > The claim's `status` field is an internal workflow value — a claim paid in full reads `paid` there, a claim closed without payment may still read `open`. Use `case_status` and `closure_reason`. *** ## Example: the debtor disputes the claim ```json theme={null} { "id": "evt_01HXYZ8K9MGV9C3K3F2K8AB13B", "type": "claim.status_changed", "created_at": "2026-09-22T08:00:01.000Z", "api_version": "2026-05-14", "data": { "claim_id": "5f3c1b22-3f4b-4d2e-9b1a-7c8e9d0f1a2b", "partner_reference": "INV-2024-00891", "from_status": "open", "to_status": "disputed", "closure_reason": null, "changed_at": "2026-09-22T08:00:00.000Z" } } ``` ## Example: the creditor withdraws a disputed claim ```json theme={null} { "id": "evt_01HXYZ8K9MGV9C3K3F2K8AB13C", "type": "claim.status_changed", "created_at": "2026-09-25T14:10:00.000Z", "api_version": "2026-05-14", "data": { "claim_id": "5f3c1b22-3f4b-4d2e-9b1a-7c8e9d0f1a2b", "partner_reference": "INV-2024-00891", "from_status": "disputed", "to_status": "closed", "closure_reason": "withdrawn", "changed_at": "2026-09-25T14:09:58.000Z" } } ``` A merged claim names the claim that continues it: ```json theme={null} { "type": "claim.status_changed", "data": { "claim_id": "9a1d…", "partner_reference": "INV-2024-00902", "from_status": "open", "to_status": "closed", "closure_reason": "merged", "changed_at": "2026-10-09T09:12:03.000Z", "merged_into": { "claim_id": "5f3c1b22-3f4b-4d2e-9b1a-7c8e9d0f1a2b", "partner_reference": "INV-2024-00891" } } } ``` # Webhooks Overview Source: https://documentation.incaseof.law/webhooks/overview Receive signed HTTP POSTs whenever a claim's collection stage or case status changes. incaseof.law pushes events to a partner-controlled HTTPS endpoint whenever a claim's lifecycle moves to a new stage. This lets you keep your local mirror of claim status in sync **without polling**. There are two event types: * [`claim.collection_stage_changed`](/webhooks/claim-collection-stage-changed) — the claim moved to a new collection stage; * [`claim.status_changed`](/webhooks/claim-status-changed) — the case status changed (`open`, `disputed`, `closed`), a closure with its reason (`paid`, `installment_plan`, `written_off`, `withdrawn`, `disputed`, `merged`, `insolvency`). Your endpoint receives every type — there is no per-type subscription. New types may be added by extending the `type` enum (the envelope shape stays stable): acknowledge an event whose `type` you do not know with a 2xx and ignore it. ```mermaid theme={null} flowchart LR A[Stage transition in incaseof.law] --> B[Sign payload with your secret] B --> C[POST to your HTTPS endpoint] C -->|2xx within 10s| D[Delivered ✓] C -->|non-2xx / timeout| E[Retry with backoff] E -->|after 6 attempts| F[Marked failed — not re-sent] ``` *** ## Setup Webhooks are configured by an incaseof.law administrator on your behalf: 1. The admin opens **Settings → Partners → Webhooks** and selects your organization. 2. They paste your HTTPS endpoint URL and click **Create webhook**. 3. incaseof.law generates a **signing secret** and displays it **once**. The admin forwards it to you over a secure channel. 4. Store the secret in your config — you'll use it to verify every incoming request (see [Signature verification](#signature-verification) below). > [!NOTE] > > The endpoint URL **must use HTTPS**. Plain HTTP is rejected at config time. *** ## Request format Every delivery is a `POST` to your configured URL with a JSON body. ### Headers | Header | Example | Notes | | - | - | - | | `Content-Type` | `application/json` | Always JSON. | | `User-Agent` | `incaseof.law-webhooks/1.0` | | | `X-IcoLaw-Event` | `claim.collection_stage_changed` | Mirrors the `type` field in the body. | | `X-IcoLaw-Delivery` | `8a7f12bb-…` (UUID) | **Stable across retries** of one event. Not the same value as the body `id`. | | `X-IcoLaw-Signature` | `t=1714385662,v1=5257a869e7ec…` | See below. | ### Envelope Every event uses the same envelope. The `data` field is shaped by `type`. ```json theme={null} { "id": "evt_01HXYZ8K9MGV9C3K3F2K8AB12C", "type": "claim.collection_stage_changed", "created_at": "2026-05-14T11:30:00.000Z", "api_version": "2026-05-14", "data": { /* event-specific payload */ } } ``` | Field | Type | Notes | | - | - | - | | `id` | string | Stable event ID (`evt_…`), the same on every retry. A different value from the `X-IcoLaw-Delivery` header — dedupe on one of the two, consistently. | | `type` | string | Event type. Drives the shape of `data`. | | `created_at` | RFC 3339 datetime | When we emitted the event. | | `api_version` | string (`YYYY-MM-DD`) | Payload contract version. Bumped on non-additive changes — pin this in your handler to be notified before breaking changes land. | | `data` | object | Event-specific payload — see the page for each event type. | *** ## Signature verification Each request includes an `X-IcoLaw-Signature` header of the form: ``` t=,v1= ``` Where: ``` v1 = HMAC_SHA256(secret, t + "." + raw_body) ``` The `secret` is the value the admin shared with you at setup time. ### Rules * **Reject** any request where `|now - t| > 5 minutes` (replay protection). * After a **secret rotation** only the new secret is valid — there is no overlap window (see [Secret rotation](#secret-rotation)). * Use a **constant-time** comparison (`crypto.timingSafeEqual` / `hmac.compare_digest`). * Verify against the **raw request body bytes**, not a re-serialised version — JSON key order matters for the HMAC. ### Reference implementations ```js Node.js theme={null} const crypto = require('crypto') function verify(rawBody, header, secret) { const parts = Object.fromEntries( header.split(',').map((p) => { const i = p.indexOf('=') return [p.slice(0, i), p.slice(i + 1)] }) ) const t = Number(parts.t) if (!Number.isFinite(t)) return false if (Math.abs(Date.now() / 1000 - t) > 300) return false // 5 min tolerance const expected = crypto .createHmac('sha256', secret) .update(`${t}.${rawBody}`, 'utf8') .digest('hex') return crypto.timingSafeEqual( Buffer.from(expected, 'hex'), Buffer.from(parts.v1 || '', 'hex') ) } ``` ```python Python theme={null} import hmac import hashlib import time def verify(raw_body: bytes, header: str, secret: str) -> bool: parts = dict(p.split("=", 1) for p in header.split(",")) try: t = int(parts["t"]) except (KeyError, ValueError): return False if abs(time.time() - t) > 300: # 5 min tolerance return False expected = hmac.new( secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256, ).hexdigest() return hmac.compare_digest(expected, parts.get("v1", "")) ``` ```go Go theme={null} package webhook import ( "crypto/hmac" "crypto/sha256" "encoding/hex" "strconv" "strings" "time" ) func Verify(rawBody []byte, header, secret string) bool { parts := map[string]string{} for _, p := range strings.Split(header, ",") { if i := strings.Index(p, "="); i > 0 { parts[p[:i]] = p[i+1:] } } t, err := strconv.ParseInt(parts["t"], 10, 64) if err != nil { return false } if abs(time.Now().Unix()-t) > 300 { return false } mac := hmac.New(sha256.New, []byte(secret)) mac.Write([]byte(strconv.FormatInt(t, 10) + ".")) mac.Write(rawBody) expected := hex.EncodeToString(mac.Sum(nil)) provided, err := hex.DecodeString(parts["v1"]) if err != nil { return false } expectedB, _ := hex.DecodeString(expected) return hmac.Equal(expectedB, provided) } func abs(n int64) int64 { if n < 0 { return -n }; return n } ``` *** ## Secret rotation Either party can request a secret rotation through the admin team. When rotated: 1. A **new** signing secret is generated and shown to the admin once; the admin forwards it to you. 2. From that moment **every delivery is signed with the new secret only**. There is no overlap window in which the previous secret still verifies. 3. Deliveries your handler rejects until you have deployed the new secret are retried on the [retry schedule](#response--retry-policy) — the last attempt comes about **7 h 12 min** after the first (30 s + 2 min + 10 min + 1 h + 6 h). Agree a time for the rotation with the admin and deploy the new secret within that time, and nothing is lost. *** ## Response & retry policy Return any **2xx** status code within **10 seconds** to acknowledge the event. Anything else — non-2xx, timeout, connection error — is treated as a failure and triggers the next retry. Deliveries are sent by a job that runs every **30 seconds**, so each time below can be up to 30 seconds later. | Attempt | When | | :-: | :- | | 1 | 0–30 seconds after the stage change | | 2 | 30 seconds after attempt 1 failed | | 3 | 2 minutes after attempt 2 | | 4 | 10 minutes after attempt 3 | | 5 | 1 hour after attempt 4 | | 6 | 6 hours after attempt 5 | After the 6th attempt fails, the delivery is marked **failed** and is visible to the incaseof.law team. It is **not sent again** — failed deliveries are not re-fired. Reconcile once a day through [`GET /openapi/claims`](/api-reference/claims/list-claims) (compare `collection_stage` with your mirror), so a missed event cannot leave your data behind. ### While your webhook is disabled No events are queued for a disabled webhook: stage changes in that time are **not delivered later**, and deliveries still pending when it was disabled are marked failed. After it is re-enabled, reconcile through the API. > [!WARNING] > > Your handler must respond within **10 seconds**. If you need to do heavy work, return 2xx immediately and process the event asynchronously (e.g. push the body to a queue and return 202). *** ## Best practices ### Deduplicate The same `X-IcoLaw-Delivery` UUID (and the same body `id`) will arrive multiple times if any attempt fails and is retried. Persist the IDs you've already processed and short-circuit duplicates — pick one of the two and use it consistently: ```js theme={null} if (await store.has(req.headers['x-icolaw-delivery'])) { return res.status(200).end() // already processed } ``` ### Reconcile out-of-order events Webhooks are eventually consistent. A retried older event can arrive after a newer one. Always reconcile by `data.claim_id` + `data.changed_at` rather than assuming arrival order: ```js theme={null} if (existing.last_stage_changed_at >= event.data.changed_at) return // stale ``` ### Don't trust the payload for sensitive fields The webhook payload deliberately contains **no debtor PII** (no name, no email, no address, no claim amount). If your downstream logic needs those fields, call [`GET /openapi/claims/{id}`](/api-reference/claims/get-claim) with your API token after receiving the event. This keeps the webhook signal-only and avoids exposing debtor data on whichever network your receiver sits on. ### Verify before you parse Verify the signature **before** doing anything else with the body — including JSON parsing. Reject with `401 Unauthorized` on signature mismatch. *** ## What's NOT included | Concern | Reason | | - | - | | Debtor name, email, address | PII boundary — fetch via the API if needed. | | Claim amounts | Same — fetch via the API. | | Granular email / postal / SendGrid events | Out of scope for v1. The webhook signals stage transitions only. | | Multiple URLs per partner | One webhook per partner in v1. Fan-out is a future schema change. | *** ## Next steps * See the [Collection Stage Events](/webhooks/claim-collection-stage-changed) reference for the payload shape and example bodies. * Test the integration end-to-end by asking your admin to use the **"Send test event"** button in the webhooks tab — it fires a synthetic event with a fixed `claim_id` (`00000000-…-000000000000`) so you can easily filter test traffic in your handler.