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. Before implementing, understand the three claim amount and age modes. 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:

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:

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 first to confirm client creation is available for your account and to read the current authorityVersion/authorityWording — if creation is disabled, that endpoint's managedPartnerCaseCreationEnabled flag is false and a create attempt returns 409 FeatureDisabled.

For the full field list, length limits, and every response code, see POST /managed-clients and the other represented-client 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, 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.

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.

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:

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.

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:

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.

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:

{
  "ClaimLines[2].DueDate": [
    "Due date must be in the past"
  ]
}

The most common conflict returns this guidance:

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

After creation, upload supporting files and monitor the case through the managed-case endpoints.

Create Your Represented Client​

Choose the Request Shape​

Option 1: Send One Amount and Due Date​

Option 2: Send Cumulative Age Totals​

Option 3: Send Claim Lines​

Claim Line Rules​

What the Collecting Partner Sees​

Handle Validation Errors​

Represented Client Errors​