Create a Case

Submit a debt collection case to Debitura via the Customer API.

Overview

Creating a case initiates the collection process. Debitura validates the case data, matches it to a collection partner based on the debtor's jurisdiction, and begins the collection workflow.

Before creating cases via API, ensure you understand what types of debt Debitura accepts.

Request

POST /cases
Content-Type: application/json
XApiKey: YOUR_API_KEY

{
  "currencyCode": "EUR",
  "date": "2025-01-15",
  "dueDate": "2025-02-15",
  "amountToRecover": 5000.00,
  "creditorReference": "INV-2025-001",
  "claimDescription": "Consulting services - January 2025",
  "debtor": {
    "type": "Company",
    "name": "Example GmbH",
    "companyRegistrationNumber": "HRB 12345",
    "address": "Hauptstrasse 1",
    "city": "Berlin",
    "zipCode": "10115",
    "countryAlpha2": "DE",
    "email": "accounts@example.de",
    "phone": "+49 30 12345678"
  }
}

Required Fields

Field	Type	Description
currencyCode	string	ISO 4217 currency code (e.g., EUR, USD, DKK)
date	date	Invoice date. Cannot be in the future.
amountToRecover	decimal	Principal amount to collect. Must be greater than 0.
debtor	object	Debtor information (see below)

Debtor Object (Required Fields)

Field	Type	Description
type	string	Company or Person
name	string	Company name or person's full name
address	string	Street address
city	string	City
countryAlpha2	string	ISO 3166-1 alpha-2 country code (e.g., DE, US, DK)
country	string	Country name (alternative to countryAlpha2)

Country resolution: Provide either countryAlpha2 (preferred) or country name. If both are provided, countryAlpha2 takes precedence.

Use Alpha-2 Codes

When using country (name) instead of countryAlpha2, the name must match the official English country name exactly. Variations, abbreviations, or misspellings will fail validation. Always prefer countryAlpha2 to avoid issues.

US debtors require stateAlpha2 (e.g., CA, NY, TX). Debitura uses this to determine the correct jurisdiction and collection partner.

State resolution: If stateAlpha2 is not provided, the system attempts to resolve from the state field (full state name). This requires an exact, case-sensitive match (e.g., "California" works, but "california" or "Calif" will not). Always prefer stateAlpha2 for reliability.

Optional Fields

Claim Details

Field	Type	Description
dueDate	date	Invoice due date. Must be on or after date.
claimDescription	string	Description of the debt (e.g., "Consulting services")
comments	string	Internal notes visible to the collection partner
creditorReference	string	Your internal reference (e.g., invoice number). Must be unique per creditor.

Debtor Object (Optional Fields)

Field	Type	Description
companyRegistrationNumber	string	VAT number, CVR, org number, etc.
zipCode	string	Postal/ZIP code
stateAlpha2	string	ISO 3166-2 state code. Required for US debtors.
email	string	Debtor's email address
phone	string	Phone number with country code
contactPerson	string	Contact person name (for companies)

Creditor Reference and Duplicate Prevention

The creditorReference field serves as a duplicate prevention mechanism. If you attempt to create a case with a reference that already exists for your account, the API returns 400 Bad Request.

This is duplicate prevention, not true idempotency. If a request times out, query for existing cases with that reference before retrying. See Idempotency for safe retry patterns.

Client Divisions

If your organization uses divisions to segment cases by business unit, brand, or legal entity, specify the division when creating a case:

{
  "creditorDivisionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  ...
}

Note: Division IDs are currently available only through the Debitura portal. To integrate with divisions, coordinate with your team to obtain the IDs you need before implementing.

Age Bucket Pricing

For multi-invoice cases where portions of the debt have different ages, Debitura supports age-based pricing. This affects the success fee calculation.

Field	Type	Description
amountToRecoverOver12Months	decimal	Portion of amountToRecover that is more than 12 months overdue
amountToRecoverOver24Months	decimal	Portion of amountToRecover that is more than 24 months overdue

Both fields must be provided together or omitted entirely. The 24-month amount must be less than or equal to the 12-month amount.

{
  "amountToRecover": 10000.00,
  "amountToRecoverOver12Months": 4000.00,
  "amountToRecoverOver24Months": 1000.00,
  ...
}

In this example: 6,000 is under 12 months old, 3,000 is 12-24 months old, and 1,000 is over 24 months old.

Test Mode

Create test cases to validate your integration without triggering real collection activity:

{
  "isTest": true,
  ...
}

Test cases are persisted but excluded from partner assignment, notifications, and metrics. See Test Cases for details.

Response

A successful request returns 200 OK with the created case:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "reference": "Q8OAXF3W",
  "creditorReference": "INV-2025-001",
  "status": "Active",
  "isTestCase": false,
  "debtor": {
    "name": "Example GmbH",
    "countryAlpha2": "DE"
  },
  "amounts": {
    "principal": 5000.00,
    "currency": "EUR"
  },
  "collectionPartner": {
    "id": "...",
    "name": "Partner Name"
  },
  "dateCreated": "2025-01-20T10:30:00Z"
}

Key fields:

• id — Debitura's internal case ID (UUID). Use this for API calls and webhook correlation.
• reference — Debitura's human-readable reference (e.g., Q8OAXF3W). Use for display and support.
• creditorReference — Your reference, echoed back from the request.
• status — Initial status (typically Active once partner is assigned)
• collectionPartner — The assigned collection partner (if matched)

See Case Identifiers for details on when to use each identifier.

Error Handling

Validation Errors (400)

Returned when request data is invalid:

Cause	Resolution
Missing required field	Include all required fields
date is in the future	Use a date on or before today
dueDate before date	Ensure due date is on or after invoice date
Invalid countryAlpha2	Use valid ISO 3166-1 alpha-2 code
US debtor without stateAlpha2	Include state code for US debtors
Duplicate creditorReference	Use a unique reference or query existing cases
Invalid currencyCode	Use valid ISO 4217 currency code

Business Errors (422)

Returned when the request is valid but cannot be processed due to business rules:

Error Type	Meaning	Resolution
MissingDebtCollectionContract	SDCA not signed	Sign the agreement in the portal. See how to sign agreements.
MissingPowerOfAttorney	Power of Attorney with the collection partner not signed	Sign the PoA when prompted in the portal.
NoPartnerAvailable	No collection partner covers this jurisdiction	Contact Debitura support or check coverage for the debtor's country.
CreditorBlocked	Your account is blocked	Contact Debitura support.

The error response includes a solutionUrl when applicable:

{
  "type": "MissingDebtCollectionContract",
  "message": "Standard Debt Collection Agreement must be signed before creating cases.",
  "solutionUrl": "https://app.debitura.com/settings/contracts"
}

For error response formats, see Error Handling.

What Happens After Creation

1. Partner Assignment - Debitura matches your case to a collection partner based on the debtor's jurisdiction, amount, and currency.

2. Contract Check - If you haven't signed the required agreements (SDCA, PoA with the specific partner), you'll receive a 422 error with a link to complete signing.

3. Webhook Notification - A case.created event is sent to your configured webhook endpoint.

4. Collection Begins - The partner starts the collection process according to their workflow. Track progress via webhooks or polling.

To understand how cases progress through the collection process, see Case Lifecycle.