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; claimLines is currently available only on POST /managed-cases.

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. The case-level date is still required and must be on or before that oldest due date; the oldest invoice's issue date is a natural value to use. Send an explicit case-level dueDate only when your system has a deliberate value for the bundled case.

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

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.

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​