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.

Choose how to provide the principal and its age before building the request. Claim Amount and Age compares a single due date, cumulative age buckets, and invoice-level claim lines, including which modes this endpoint currently 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. Max 200 characters. Validation errors for this field are keyed `Debtor.CompanyName`, for both company and private debtors.
`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. Max 50 characters.
`zipCode`	string	Postal/ZIP code
`stateAlpha2`	string	ISO 3166-2 state code. Required for US debtors.
`email`	string	Debtor's email address. Max 250 characters.
`phone`	string	Phone number with country code. Max 100 characters.
`contactPerson`	string	Contact person name (for companies). Max 200 characters.

Field lengths: A value longer than its limit returns 400 with a message naming the field, the limit, and the length received — for example Phone must not exceed 100 characters (received 118). The debtor length checks run as a group, so all of them in one request come back in a single response. Limits on top-level fields such as creditorReference, comments, claimDescription and assignedUserEmail are enforced earlier and stop the request before the debtor is examined, so those surface on their own and in a different message format. Truncate or map long values in your own system before submitting.

Assign a Team Member

Optionally assign the new case to a member of your team. Pass their email address — they must be an active member of your creditor account.

Field	Type	Description
`assignedUserEmail`	string	Email of the team member to assign the case to. Must belong to an active user on your account, otherwise the request returns `400`. List valid emails with `GET /users` on the Customer API.

{
  "assignedUserEmail": "agent@acme.com",
  ...
}

When set, the assigned user is echoed back on the case object under assignedUser (see Response) and on subsequent GET /cases/{id} reads.

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 422 Unprocessable Entity.

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",
  ...
}

Division IDs are currently available only through the Debitura portal. 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. First read Claim Amount and Age to choose between a case-level due date and cumulative age totals. 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.

Choose the amount-and-age mode that matches your source data. Send amountToRecover with one dueDate for a single invoice. For a multi-invoice case, send claimLines with each invoice's outstanding balance and due date so Debitura derives the combined total and age distribution. Use cumulative age buckets only when your system already calculates them. See Claim Amount and Age.

Pending Contracts

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

{
  "allowPendingContracts": true,
  "returnUrl": "https://app.example.com/cases/created",
  ...
}

When true, cases with unsigned contracts are created in the pending-contract-signing state instead of being rejected. The case transitions automatically to the internal verification state once contracts are signed.

Lifecycle is a description string

The lifecycle field in responses and webhook payloads carries a human-readable description, not a stable code. The pending-contract-signing state serializes as "Pending contract signing", and the internal verification state serializes as "Pending Verification Internal" (not the PascalCase enum names). Match on these exact strings. See Case Lifecycle for the full set of values.

When signing is still pending, the response includes a signingHandoff object whose combinedSigningUrl is a single, context-aware URL that lands the user on the right signing page (combined SDCA + PoA, PoA only, or the multi-partner overview, depending on what is outstanding). Use it to redirect your user to complete signing without a separate API call or any client-side decision logic. When everything is already signed, signingHandoff is null.

Field	Type	Description
`allowPendingContracts`	bool	Defaults to `false`. When `true`, unsigned contracts no longer cause a `422` — the case is accepted in the `Pending contract signing` state and the response carries a `signingHandoff`.
`returnUrl`	string (optional)	Absolute `http://` or `https://` URL the user is redirected back to after completing the signing chain. Embedded into `signingHandoff.combinedSigningUrl`. Max 2048 characters. Relative URLs, non-http(s) schemes, and values containing header-injection characters are silently dropped — the combined URL is still emitted but without the `returnUrl` query parameter, and the Creditors app falls back to its own default landing. Omit to land the user on their Debitura dashboard after signing.

The legacy top-level solutionUrl field is still returned for backwards compatibility but is deprecated in favour of signingHandoff.combinedSigningUrl. solutionUrl only points at the first pending step; signingHandoff.combinedSigningUrl walks the full chain (SDCA upgrade → PoA → JPA → KYC) end-to-end. New integrations should read signingHandoff.combinedSigningUrl.

Test Mode

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

{
  "isTest": true,
  ...
}

Test cases are persisted to the database and still go through partner assignment, but they are flagged as test data and excluded from production metrics. They can be easily filtered or deleted. 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": "Pending contract signing",
  "signingHandoff": {
    "combinedSigningUrl": "https://app.debitura.com/Signing/PendingContracts?returnUrl=..."
  },
  ...
}

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 as a human-readable description string (typically Active once a partner is assigned, or Pending contract signing when allowPendingContracts: true and contracts are unsigned).
collectionPartner — The assigned collection partner (if matched). Contains name, officeEmail, officePhone, publicSite.
assignedUser — The team member the case is assigned to, when assignedUserEmail was provided. Contains email and name. Omitted (or null) when no one is assigned.

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
`creditorReference` exceeds 50 characters	Truncate to max 50 characters
A debtor field exceeds its maximum length	Keep within the limits listed under Debtor Object — the message names the field, the limit, and the length received
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
`assignedUserEmail` does not match an active team member	Use an email returned by `GET /users`

Business Errors (422)

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

The Customer API accepts cases for the standard SDCA/exclusive pre-legal collection flow. If no eligible exclusive partner matches the jurisdiction, amount, debtor type, and other routing criteria, Debitura returns 422 and does not create a case. The custom-quote flow offered interactively in the Debitura portal is not available through the Customer API.

Error Type	Meaning	Resolution
Duplicate `creditorReference`	A case with this `creditorReference` already exists for the creditor	Use a unique reference or query existing cases.
`MissingDebtCollectionContract`	SDCA not signed	Sign the agreement in the portal, or set `allowPendingContracts: true` to accept the case in the `Pending contract signing` state. 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.
No collection partner for jurisdiction	No collection partner covers this jurisdiction. This is not currently returned as a typed `NoPartnerAvailable` business error — see below.	Contact Debitura support or check coverage for the debtor's country.
Creditor account blocked	Your account is blocked. This is not currently returned as a typed `CreditorBlocked` business error — see below.	Contact Debitura support.
Demo account blocked	Demo accounts cannot create cases via the API	Use the Debitura portal to create cases on demo accounts.

Only the signing-related errors above (MissingDebtCollectionContract, MissingPowerOfAttorney, MissingKycVerification) are wrapped in a typed businessErrors array with a type/message/solutionUrl shape:

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

The no-partner-for-jurisdiction, blocked-creditor, demo-account, and duplicate-creditorReference cases instead return the legacy untyped field-error shape — a plain Dictionary<string, string[]> with no type or solutionUrl, for example:

{
  "businessRule": [
    "We don't have an exclusive pre-legal partner in the provided jurisdiction"
  ]
}

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 the Pending contract signing state. Read signingHandoff.combinedSigningUrl to redirect the user through the full signing chain. The case 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)​

Assign a Team Member​

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​