Quick Start Guide - Case Management API

Get started with the incaseof.law API in minutes. This guide walks you through the most common workflows with practical code examples.

Prerequisites

API Token: Get your API token from the incaseof.law Admin dashboard (Settings → API Tokens)
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:

Authorization: Bearer YOUR_API_TOKEN_HERE

Example Request Setup

cURL
JavaScript
Python

curl -X GET 'https://service.incaseof.law/openapi/debtors' \
  -H 'Authorization: Bearer YOUR_API_TOKEN_HERE'

const response = await fetch('https://service.incaseof.law/openapi/debtors', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN_HERE',
    'Content-Type': 'application/json'
  }
})

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

cURL
JavaScript
Python

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": "[email protected]",
        "is_primary": true
      },
      {
        "type": "phone",
        "value": "+43 123 456789"
      }
    ]
  }'

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: '[email protected]',
        is_primary: true
      },
      {
        type: 'phone',
        value: '+43 123 456789'
      }
    ]
  })
})

const data = await response.json()
console.log('Debtor created:', data.data.id)

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': '[email protected]',
            '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

cURL
JavaScript
Python

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": "[email protected]",
        "is_primary": true
      }
    ],
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX"
  }'

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: '[email protected]',
        is_primary: true
      }
    ],
    iban: 'DE89370400440532013000',
    bic: 'COBADEFFXXX'
  })
})

const data = await response.json()
const debtorId = data.data.id
console.log('Company debtor created:', debtorId)

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': '[email protected]',
            '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

{
  "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"
  }
}

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.

cURL
JavaScript
Python

# 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"
  }'

// 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)

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

{
  "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"
  }
}

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

cURL
JavaScript
Python

# 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'

// 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)

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

{
  "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"
  }
}

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:

JavaScript
Python

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: '[email protected]',
            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
  }
}

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': '[email protected]',
                    '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

cURL
JavaScript
Python

curl -X GET 'https://service.incaseof.law/openapi/debtors' \
  -H 'Authorization: Bearer YOUR_API_TOKEN_HERE'

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)

response = requests.get(
    'https://service.incaseof.law/openapi/debtors',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN_HERE'}
)
debtors = response.json()
print('Debtors:', debtors['data'])

Get a Specific Claim

cURL
JavaScript
Python

curl -X GET 'https://service.incaseof.law/openapi/claims/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d' \
  -H 'Authorization: Bearer YOUR_API_TOKEN_HERE'

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)

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

cURL
JavaScript
Python

curl -X GET 'https://service.incaseof.law/openapi/claims/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/invoices' \
  -H 'Authorization: Bearer YOUR_API_TOKEN_HERE'

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)

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:

{
  "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

JavaScript
Python

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)
}

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 for detailed endpoint documentation
Check out Debtors endpoints
Learn about Payments and Documents
Set up Partner & Revenue Sharing for commission-based referral tracking

Need help? Contact us at [email protected]

​Prerequisites

​Authentication

​Example Request Setup

​Workflow 1: Create a Debtor

​Step 1: Create a Person Debtor

​Step 2: Create a Company Debtor

​Response Example

​Workflow 2: Create a Claim

​Response Example

​Workflow 3: Upload Invoice to Claim

​Upload PDF File

​Response Example

​Complete Workflow Example

​Additional Common Operations

​List All Debtors

​Get a Specific Claim

​List Invoices for a Claim

​Error Handling

​Common HTTP Status Codes

​Example Error Handling

​Next Steps

Prerequisites

Authentication

Example Request Setup

Workflow 1: Create a Debtor

Step 1: Create a Person Debtor

Step 2: Create a Company Debtor

Response Example

Workflow 2: Create a Claim

Response Example

Workflow 3: Upload Invoice to Claim

Upload PDF File

Response Example

Complete Workflow Example

Additional Common Operations

List All Debtors

Get a Specific Claim

List Invoices for a Claim

Error Handling

Common HTTP Status Codes

Example Error Handling

Next Steps