Source: https://docs.debitura.com/clients/integration-guides/create-a-case

# Create a Case

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

<a id="overview"></a>

## 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](https://support.debitura.com/en/articles/13638265-case-eligibility-what-types-of-debt-debitura-accepts-and-minimum-requirements).

Choose how to provide the principal and its age before building the request. [Claim Amount and Age](https://docs.debitura.com/developer-concepts/claim-amount-and-age.md) compares a single due date, cumulative age buckets, and invoice-level claim lines, including which modes this endpoint currently accepts.

<a id="preview-eligibility-before-submitting"></a>

## Preview eligibility before submitting

Call `POST /cases/preview` with the same principal, currency and debtor jurisdiction before creating the case. A partner match must also pass the monetary admission checks used by `POST /cases`. The preview's `result.isEligible` can be `true` while signing actions remain; complete `result.requiredActions` before submitting.

When monetary admission refuses a matched claim, the preview returns `200` with `result.isEligible: false`, `result.ineligibilityReasonCode: "AmountBelowMinimum"` and an additive `result.admissionMinimum`. This illustrative EUR example assumes 1 EUR = 1.10 USD; preview uses current rates:

```json
{
  "rule": "UnitedStatesMinimum",
  "amountUsd": 500.00,
  "amount": 454.55,
  "currencyCode": "EUR"
}
```

| Field | Meaning |
| --- | --- |
| `rule` | `UnitedStatesMinimum`, or `PlatformMinimum` for the configured client/partner/platform minimum. |
| `amountUsd` | The minimum principal in USD. |
| `amount` | Its equivalent in the request currency, rounded upward to two decimal places. |
| `currencyCode` | Currency of `amount`. |

Minimum refusals return no partner assignment, pricing or signing actions. `admissionMinimum` is null when admission did not reject the amount. It is separate from `applicableMinimumAmount` (an unmatched claim's matching hint) and `marketMinimumAmount` (a market statement). Branch on the reason code and structured fields, not the human-readable reason.

If `result.amountCheckUnavailable` is `true`, a required currency conversion could not be evaluated: treat eligibility as provisional and retry. Creation checks the current configuration and rates again. The Customer API offers no network/custom-quote fallback; unmatched claims remain ineligible at every amount, including amounts above the quote flow's minimum.

<a id="request"></a>

## Request

```http
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"
  }
}
```

<a id="required-fields"></a>

## 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; omit when `claimLines` supplies the total. |
| `debtor` | object | Debtor information (see below) |

<a id="debtor-object-required-fields"></a>

### 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 is matched case-insensitively against Debitura's English short country name (e.g. `United States`, `Czechia`), with a small set of common aliases accepted (e.g. `UK`, `USA`, `Holland`, `Czech Republic`); other variations or misspellings 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.

<a id="optional-fields"></a>

## Optional Fields

<a id="claim-details"></a>

### 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 and test/live classification; see the duplicate-prevention rules below. |

<a id="debtor-object-optional-fields"></a>

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

<a id="assign-a-team-member"></a>

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

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

When set, the assigned user is echoed back on the case object under `assignedUser` (see [Response](https://docs.debitura.com/clients/integration-guides/create-a-case.md#response)) and on subsequent `GET /cases/{id}` reads.

<a id="creditor-reference-and-duplicate-prevention"></a>

## Creditor Reference and Duplicate Prevention

The `creditorReference` field prevents duplicate collection cases for the same creditor and data classification. Test and production cases may share a reference. A case closed as `CaseNeverStartedInternal` under an archived, non-deleted referral-partner link no longer reserves that reference. Other duplicates return `422 Unprocessable Entity`.

Duplicate-reference prevention does not replay the original response. For replay-safe retries, send an `Idempotency-Key` on `POST /cases` and reuse the same key with the identical body within its 24-hour replay window. Without the header, query for an existing case with that reference after an ambiguous timeout before retrying. See [Idempotency](https://docs.debitura.com/developer-concepts/idempotency.md) for the complete retry contract.

<a id="client-divisions"></a>

## Client Divisions

If your organization uses [divisions](https://docs.debitura.com/clients/concepts/client-divisions.md) to segment cases by business unit, brand, or legal entity, specify the division when creating a case:

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

List your division IDs with `GET /divisions` (or create one with `POST /divisions`); they are also visible in the Debitura portal.

<a id="age-bucket-pricing"></a>

## 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](https://docs.debitura.com/developer-concepts/claim-amount-and-age.md) to choose between a case-level due date and cumulative age totals. This affects the [success fee calculation](https://support.debitura.com/en/articles/13429835-success-fees-how-pricing-is-calculated-claim-size-region-age).

| 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.

```json
{
  "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.

<a id="key-behaviors"></a>

### 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](https://docs.debitura.com/developer-concepts/claim-amount-and-age.md).

<a id="pending-contracts"></a>

## Pending Contracts

By default, the API returns `422` if required agreements ([SDCA](https://support.debitura.com/en/articles/13443289-standard-debt-collection-agreement-sdca-key-terms), [PoA](https://support.debitura.com/en/articles/13634377-contracts-signatures-sdca-poa-and-the-legal-framework-overview)) are unsigned. Set `allowPendingContracts` to create the case in the `Pending contract signing` state instead:

```json
{
  "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](https://docs.debitura.com/developer-concepts/case-lifecycle.md#lifecycle-states) 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`.

<a id="test-mode"></a>

## Test Mode

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

```json
{
  "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](https://docs.debitura.com/developer-concepts/test-cases.md) for details.

<a id="response"></a>

## Response

A successful request returns `200 OK` with the created case:

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "reference": "Q8OAXF3W",
  "creditorReference": "INV-2025-001",
  "lifecycle": "Pending Verification Internal",
  "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": null
  },
  "dateCreated": "2025-01-20T10:30:00Z"
}
```

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

```json
{
  "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. New matched cases normally start in `Pending Verification Internal` (`Pending Verification` if internal verification is bypassed), or `Pending contract signing` when accepted with unsigned contracts.
-   `collectionPartner` — The assigned collection partner (if matched). Contains `name`, `officeEmail`, `officePhone`; `publicSite` is present but `null` in this response.
-   `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](https://docs.debitura.com/developer-concepts/case-identifiers.md) for details on when to use each identifier.

<a id="error-handling"></a>

## Error Handling

<a id="validation-errors-400"></a>

### Validation Errors (400)

Returned when request data is invalid. Not exhaustive — each error names the field:

| 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](https://docs.debitura.com/clients/integration-guides/create-a-case.md#debtor-object-optional-fields) — 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` |

<a id="business-errors-422"></a>

### 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 collection case with this `creditorReference` already exists for the creditor within the same test/live classification | Use a unique reference or query existing cases. |
| `MissingDebtCollectionContract` | [SDCA](https://support.debitura.com/en/articles/13443289-standard-debt-collection-agreement-sdca-key-terms) 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](https://support.debitura.com/en/articles/13887135-clients-how-to-sign-agreements-sdca-poa-and-access-signed-documents). |
| `MissingPowerOfAttorney` | [Power of Attorney](https://support.debitura.com/en/articles/13634377-contracts-signatures-sdca-poa-and-the-legal-framework-overview) 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](https://docs.debitura.com/referral-partners/integration-guides/kyc-verification.md). |
| No collection partner for jurisdiction | No collection partner covers this [jurisdiction](https://support.debitura.com/en/articles/13638070-countries-jurisdictions-coverage-local-rules-and-missing-partner-coverage). This is not currently returned as a typed `NoPartnerAvailable` business error — see below. | 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. |
| `CollectionPartnerNotFound` | The `collectionPartnerId` override does not exist or is deleted | Omit the override or use a valid collection partner ID. |
| `IdempotencyConflict` | `Idempotency-Key` reused with a different body | Use a new key for a different request. See [Idempotency](https://docs.debitura.com/developer-concepts/idempotency.md). |

The signing errors and `CreditorBlocked` are returned as a typed `businessErrors` array (`type`/`message`/`solutionUrl`, plus `signingHandoff`). A duplicate `creditorReference` and an unknown `collectionPartnerId` return a typed `businessErrors` entry (`DuplicateCreditorReference` / `CollectionPartnerNotFound`) alongside a legacy field key (dual-write).

```json
{
  "businessErrors": [
    {
      "type": "MissingDebtCollectionContract",
      "message": "Debt collection contract not signed yet.",
      "solutionUrl": "https://app.debitura.com/SignTerms"
    }
  ],
  "signingHandoff": {
    "combinedSigningUrl": "https://app.debitura.com/Signing/PendingContracts?returnUrl=..."
  }
}
```

The no-partner-for-jurisdiction and demo-account cases return a legacy untyped field dict keyed `BusinessRule` (PascalCase), with no `type` or `solutionUrl`, for example:

```json
{
  "BusinessRule": [
    "We don't have an exclusive pre‑legal partner in the provided jurisdiction"
  ]
}
```

A duplicate `creditorReference` returns:

```json
{
  "businessErrors": [
    {
      "type": "DuplicateCreditorReference",
      "message": "Must be unique",
      "solutionUrl": ""
    }
  ],
  "CreditorReference": ["Must be unique"]
}
```

For error response formats, see [Error Handling](https://docs.debitura.com/developer-concepts/error-handling.md).

<a id="what-happens-after-creation"></a>

## 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), 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.
3.  **Webhook Notification** - A `case.created` event is sent to your configured [webhook endpoint](https://docs.debitura.com/clients/integration-guides/webhooks.md).
    
4.  **Collection Begins** - The partner starts the collection process according to their workflow. Track progress via [webhooks](https://docs.debitura.com/clients/integration-guides/webhooks.md) or [polling](https://docs.debitura.com/clients/integration-guides/track-case-status.md).
    

To understand how cases progress through the collection process, see [Case Lifecycle](https://docs.debitura.com/developer-concepts/case-lifecycle.md).