Source: https://docs.debitura.com/collection-partners/integration-guides/create-a-managed-case
# Create a Managed Case
Submit a collection case on behalf of your client through the Collection Partner API. For one invoice, send `amountToRecover` and `dueDate`; for multiple or part-paid invoices, send `claimLines` and leave out every amount field.
This guide assumes you have [authenticated with the Collection Partner API](https://docs.debitura.com/collection-partners/getting-started/authentication.md). Before implementing, understand the [three claim amount and age modes](https://docs.debitura.com/developer-concepts/claim-amount-and-age.md). The same `claimLines` contract is also available on Customer and Referral Partner case-creation routes.
## Create Your Represented Client
Before submitting cases for a client, create a represented client once and reuse its ID on every case you submit for them going forward:
```http
POST https://collectionpartner-api.debitura.com/managed-clients
XApiKey: YOUR_API_KEY
Idempotency-Key: YOUR_UNIQUE_KEY
Content-Type: application/json
{
"companyName": "Acme Services Inc",
"address": "500 Market Street",
"city": "San Francisco",
"countryAlpha2": "US",
"authorityAccepted": true,
"authorityVersion": "represented-client-v1"
}
```
The response returns a stable `id`. Store it and send it as `clientId` on every `POST /managed-cases` request for this client instead of repeating the creditor's company details:
```http
POST https://collectionpartner-api.debitura.com/managed-cases
XApiKey: YOUR_API_KEY
Idempotency-Key: YOUR_UNIQUE_KEY
Content-Type: application/json
{
"clientId": "4ef67280-17b6-43d8-89e6-bcf71092f539",
"currencyCode": "USD",
"date": "2025-04-18",
"dueDate": "2025-05-18",
"amountToRecover": 1500.00,
"creditorReference": "INV-1001",
"debtor": {
"type": "Company",
"name": "Pacific Trading LLC",
"contactPerson": "John Smith",
"countryAlpha2": "US",
"stateAlpha2": "CA"
}
}
```
`authorityAccepted` must be `true`, confirming your company has authority from this client to create and manage collection cases on its behalf, and `authorityVersion` must match the version currently in effect. Call `GET /managed-clients/capability` to read the current `authorityVersion`/`authorityWording`. Its `managedPartnerCaseCreationEnabled` flag is `true`.
For the full field list, length limits, and every response code, see [`POST /managed-clients`](https://docs.debitura.com/api/collection-partner-api/managed-clients.md#create-a-represented-client) and the other [represented-client endpoints](https://docs.debitura.com/collection-partners/concepts/managed-cases.md#api-endpoints).
Deprecated: inline creditor fields
The `creditorCompanyName` / `creditorCountryAlpha2` (or `creditorCountry`) fields used in the examples below still work, but they are the **deprecated fallback**: every call creates a brand-new client record, so the same client submitted across 10 cases ends up with 10 separate company records instead of one. Responses created this way carry a `Deprecation: true` header. Use `clientId` for anything you build going forward — send either `clientId` or the creditor company fields, never both.
## Choose the Request Shape
Start with the shape that matches the data in your accounting system:
| Your claim | Send | How Debitura determines age |
| --- | --- | --- |
| One invoice | `amountToRecover` + `dueDate` | Uses the case-level due date as a coarser pricing input |
| Your system already calculates cumulative age totals | `amountToRecover` + the 6/12/24-month fields | Uses the age distribution you provide |
| Multiple invoices or any pre-handover part-payment | `claimLines` | Sums the open balances and derives exact age totals from each line's due date |
These are the three shared [claim amount and age modes](https://docs.debitura.com/developer-concepts/claim-amount-and-age.md), applied here to managed-case creation.
Recommended for multiple or part-paid invoices
Send `claimLines`. Each line maps naturally to an unpaid invoice in your accounting system, and Debitura calculates both the total and its age distribution.
## Option 1: Send One Amount and Due Date
For a simple claim with one invoice, send the outstanding principal in `amountToRecover` and its payment deadline in `dueDate`.
```http
POST https://collectionpartner-api.debitura.com/managed-cases
XApiKey: YOUR_API_KEY
Idempotency-Key: YOUR_UNIQUE_KEY
Content-Type: application/json
{
"creditorCompanyName": "Acme Services Inc",
"creditorCountryAlpha2": "US",
"currencyCode": "USD",
"date": "2025-04-18",
"dueDate": "2025-05-18",
"amountToRecover": 1500.00,
"creditorReference": "INV-1001",
"debtor": {
"type": "Company",
"name": "Pacific Trading LLC",
"contactPerson": "John Smith",
"countryAlpha2": "US",
"stateAlpha2": "CA"
}
}
```
`amountToRecover` is the principal still owed when you submit the case. Do not include interest, reminder fees, or collection fees in this value.
A single `dueDate` is a coarser pricing input than invoice-level dates. If the same claim is sent with `claimLines`, its quote can differ because Debitura can determine the exact amount beyond each age threshold.
## Option 2: Send Cumulative Age Totals
Use the age fields when your integration already calculates how much of the outstanding principal is more than 6, 12, and 24 months overdue.
```http
POST https://collectionpartner-api.debitura.com/managed-cases
XApiKey: YOUR_API_KEY
Idempotency-Key: YOUR_UNIQUE_KEY
Content-Type: application/json
{
"creditorCompanyName": "Acme Services Inc",
"creditorCountryAlpha2": "US",
"currencyCode": "USD",
"date": "2024-01-10",
"dueDate": "2024-02-10",
"amountToRecover": 15000.00,
"amountToRecoverOver6Months": 9000.00,
"amountToRecoverOver12Months": 6000.00,
"amountToRecoverOver24Months": 2000.00,
"creditorReference": "BATCH-2042",
"debtor": {
"type": "Company",
"name": "Pacific Trading LLC",
"contactPerson": "John Smith",
"countryAlpha2": "US",
"stateAlpha2": "CA"
}
}
```
The age fields are **cumulative**, not separate slices. In this example, the 9,000 over 6 months already includes the 6,000 over 12 months, which already includes the 2,000 over 24 months.
Calculate each field from the invoice due dates as of the day you submit the request:
| Field | Include an open balance when it is |
| --- | --- |
| `amountToRecoverOver6Months` | More than 180 full days overdue |
| `amountToRecoverOver12Months` | More than 365 full days overdue |
| `amountToRecoverOver24Months` | More than 730 full days overdue |
The thresholds use strict “more than” comparisons: an invoice at exactly 180, 365, or 730 days is not yet included in that bucket. It enters on day 181, 366, or 731.
The values must follow this hierarchy:
```text
amountToRecover
≥ amountToRecoverOver6Months
≥ amountToRecoverOver12Months
≥ amountToRecoverOver24Months
≥ 0
```
The 12- and 24-month fields must be sent together. The 6-month field is optional, but if you send it, you must also send both the 12- and 24-month fields. A case-level `dueDate` may be included alongside the age totals; Debitura uses the cumulative distribution for age pricing and keeps `dueDate` as the case-level payment deadline.
Use net outstanding amounts everywhere
Do not calculate age fields from original invoice values while calculating `amountToRecover` after payments or credit notes. The age fields and total must describe the same outstanding principal. If the claim has been part-paid, use `claimLines` instead.
## Option 3: Send Claim Lines
For multiple invoices or a claim paid in part before handover, send one line per unpaid invoice. Debitura derives `amountToRecover` and every cumulative age field from the lines.
```http
POST https://collectionpartner-api.debitura.com/managed-cases
XApiKey: YOUR_API_KEY
Idempotency-Key: YOUR_UNIQUE_KEY
Content-Type: application/json
{
"creditorCompanyName": "Acme Services Inc",
"creditorCountryAlpha2": "US",
"currencyCode": "USD",
"date": "2024-01-02",
"claimLines": [
{
"dueDate": "2024-01-15",
"amount": 423.42,
"reference": "INV-1001"
},
{
"dueDate": "2025-05-02",
"amount": 700.87,
"reference": "INV-1042"
}
],
"comments": "INV-1001: original 500.00, payment 76.58, open 423.42. INV-1042: open 700.87.",
"creditorReference": "BATCH-2042",
"debtor": {
"type": "Company",
"name": "Pacific Trading LLC",
"contactPerson": "John Smith",
"countryAlpha2": "US",
"stateAlpha2": "CA"
}
}
```
The first invoice originally carried 500.00, but the debtor already paid 76.58. Its line amount is therefore the **open balance of 423.42**, not the original invoice value.
Debitura calculates this request as follows:
```text
amountToRecover = 423.42 + 700.87 = 1,124.29
age totals = sum of the open balances beyond each age threshold
```
Choose one principal source
When you send `claimLines`, omit `amountToRecover` and all three `amountToRecoverOver...Months` fields. Sending both modes returns `400 Bad Request`.
You may still send case-level fields such as `date`, `dueDate`, `comments`, and `creditorReference`.
### Claim Line Rules
| Field | Rule |
| --- | --- |
| `dueDate` | Required. Must be on or after `2000-01-01` and cannot be in the future |
| `amount` | Required. Open balance must be greater than zero and have at most two decimal places |
| `reference` | Optional invoice number. An exact duplicate reference within the request is rejected |
Send no more than 1,000 lines. Leave fully settled invoices out instead of sending a zero amount.
If you omit the case-level `dueDate`, Debitura sets it to the oldest `claimLines[].dueDate`. In that mode, the required case-level `date` must be on or before the oldest line due date; the oldest invoice's issue date is a natural value to use. If you send an explicit case-level `dueDate`, the normal case-level `date`/`dueDate` validation applies instead.
### What the Collecting Partner Sees
Claim lines are used once to calculate the case amount and price. Debitura does not store them or show them to the collecting partner.
Include a readable invoice breakdown in `comments` when the collecting partner needs it. Upload the underlying invoices after creation using the [managed-case file endpoint](https://docs.debitura.com/collection-partners/integration-guides/upload-files.md).
## Handle Validation Errors
Invalid field combinations and claim-line values return `400 Bad Request`. Line errors identify the array position, which lets you map them back to the invoice in your source system:
```json
{
"ClaimLines[2].DueDate": [
"Due date must be in the past"
]
}
```
The most common conflict returns this guidance:
```json
{
"ClaimLines": [
"Send either claimLines or the amount fields, not both. With claimLines we compute the amounts for you."
]
}
```
### Represented Client Errors
Requests that mix the two creditor-identification modes, or reference a client you cannot use, fail before any case is created:
| Situation | Status | Shape |
| --- | --- | --- |
| `clientId` sent together with `creditorCompanyName`, `creditorCountryAlpha2`, or `creditorCountry` | `400 Bad Request` | Field-keyed dictionary, e.g. `{"CreditorCompanyName": ["Send either ClientId or the creditor company fields, not both."]}` |
| `clientId` doesn't exist, isn't yours, or was deleted | `404 Not Found` | `{"error": "NotFound", "message": "No company found with this ID.", "businessErrors": [{"type": "NotFound", "message": "No company found with this ID.", "solutionUrl": ""}]}` |
| `creditorReference` already used for this client | `422 Unprocessable Entity` | `{"businessErrors": [{"type": "DuplicateCreditorReference", "message": "Must be unique", "solutionUrl": ""}], "CreditorReference": ["Must be unique"]}` |
The `creditorReference` conflict is scoped to the client itself — the same reference is fine for a different client. The deprecated inline mode creates a fresh client on every call, so it never hits this conflict.
For the complete request and response schemas, see [`POST /managed-cases`](https://docs.debitura.com/api/collection-partner-api/managed-cases.md#create-case-as-managing-partner).
After creation, [upload supporting files](https://docs.debitura.com/collection-partners/integration-guides/upload-files.md) and monitor the case through the [managed-case endpoints](https://docs.debitura.com/collection-partners/concepts/managed-cases.md#api-endpoints).