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 `Private`
`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). Matching is case-insensitive (e.g., "California" and "california" both work), but abbreviations like "Calif" will not match. Always prefer stateAlpha2 for reliability.

Optional Fields

Claim Details

Field	Type	Description
`dueDate`	date	Invoice due date. Must be on or after `date` and must not be in the future.
`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
`amountToRecoverOver6Months`	decimal	Optional. Portion more than 6 months (180 days) overdue. Can only be provided alongside Over12 and Over24. Must be ≥ `amountToRecoverOver12Months`.
`amountToRecoverOver12Months`	decimal	Portion of `amountToRecover` that is more than 12 months overdue
`amountToRecoverOver24Months`	decimal	Portion of `amountToRecover` that is more than 24 months overdue

amountToRecoverOver12Months and amountToRecoverOver24Months must be provided together or omitted entirely. The 24-month amount must be ≤ the 12-month amount.

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

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

Key Behaviors

Age is measured from due date, not issue date. "Overdue" means calendar days from the invoice's original due date to the submission date. An invoice issued 8 months ago but due 2 weeks ago is 2 weeks overdue — not 8 months.

amountToRecover is always evaluated as a single combined total. When you bundle multiple invoices into one case, Debitura treats the combined amountToRecover as a single claim — not as individual invoices. Submit separate cases if you need each invoice evaluated independently.

Pending Contracts

By default, the API returns 422 if required agreements (SDCA, PoA) are unsigned. Set allowPendingContracts to create the case in PendingContractSigning status instead:

{
  "allowPendingContracts": true,
  ...
}

When true, cases with unsigned contracts are created in PendingContractSigning status instead of being rejected. The case transitions automatically to PendingVerificationInternal once contracts are signed.

The response includes solutionUrl directly — use it to redirect your user to complete signing without a separate API call. When contracts are already signed, solutionUrl is null.

Defaults to false — unsigned contracts return 422 with a solutionUrl for signing.

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",
  "lifecycle": "Active",
  "isTestCase": false,
  "grossAmount": 5000.00,
  "currency": "EUR",
  "debtor": {
    "name": "Example GmbH",
    "countryAlpha2": "DE"
  },
  "collectionPartner": {
    "name": "Partner Name",
    "officeEmail": "info@partner.com",
    "officePhone": "+49 30 12345678",
    "publicSite": "https://partner.com"
  },
  "dateCreated": "2025-01-20T10:30:00Z"
}

When allowPendingContracts: true and contracts are unsigned, the response looks like:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "reference": "Q8OAXF3W",
  "lifecycle": "PendingContractSigning",
  ...
}

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.
lifecycle — Current case state (typically Active once a partner is assigned, or PendingContractSigning when allowPendingContracts: true and contracts are unsigned).
collectionPartner — The assigned collection partner (if matched). Contains name, officeEmail, officePhone, publicSite.

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
`amountToRecover` is zero or negative	Must be greater than 0
`date` is in the future	Use a date on or before today
`dueDate` before `date`	Ensure due date is on or after invoice date
`dueDate` is in the future	Due date must be on or before today
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
`creditorReference` exceeds 50 characters	Truncate to max 50 characters
Invalid `currencyCode`	Use valid ISO 4217 currency code
Age bucket field mismatch (only Over12 or Over24 provided)	Always send 12- and 24-month fields together
Age bucket values violate hierarchical rules	Over24 ≤ Over12 ≤ Over6 ≤ total; all must be non-negative

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, or set `allowPendingContracts: true` to accept the case in `PendingContractSigning` status. See how to sign agreements.
`MissingPowerOfAttorney`	Power of Attorney with the collection partner not signed	Sign the PoA when prompted in the portal, or set `allowPendingContracts: true`.
`MissingKycVerification`	Director identity verification required by the collection partner. Only returned for bearer token authentication (referral partner flow) — `XApiKey` callers are not affected.	Redirect the user to the `solutionUrl` to complete KYC. See KYC Verification.
`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.
Demo account blocked	Demo accounts cannot create cases via the API	Use the Debitura portal to create cases on demo accounts.

The 422 error response is wrapped in a businessErrors array:

{
  "businessErrors": [
    {
      "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

Partner Assignment - Debitura matches your case to a collection partner based on the debtor's jurisdiction, amount, and currency.
Contract Check - If you haven't signed the required agreements (SDCA, PoA with the specific partner), the result depends on your request:
- Default (allowPendingContracts: false) — Returns 422 with a solutionUrl link to complete signing.
- allowPendingContracts: true — Case is accepted in PendingContractSigning status. The solutionUrl in the response points to the signing page. It transitions automatically once contracts are signed.
Webhook Notification - A case.created event is sent to your configured webhook endpoint.
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.

Overview​

Request​

Required Fields​

Debtor Object (Required Fields)​

Optional Fields​

Claim Details​

Debtor Object (Optional Fields)​

Creditor Reference and Duplicate Prevention​

Client Divisions​

Age Bucket Pricing​

Key Behaviors​

Pending Contracts​

Test Mode​

Response​

Error Handling​

Validation Errors (400)​

Business Errors (422)​

What Happens After Creation​