Source: https://docs.debitura.com/api/collection-partner-api/managed-cases
# Managed cases — Collection Partner API
Base URL: `https://collectionpartner-api.debitura.com`
Authentication: `XApiKey` API key; see [authentication](https://docs.debitura.com/developer-concepts/authentication.md).
Generated from [OpenAPI](https://docs.debitura.com/openapi/collection-partner-api.json). Examples are schema illustrations, not observed responses. Complete schemas, including recursive types, are in OpenAPI.
## Preview managed-case routing.
`POST /managed-cases/preview`
Optional, read-only snapshot. HasPreLegalPartner describes a routing candidate, not permission to
create a case. No match may lead to internal review and potentially network quotes on submission;
neither acceptance nor a quote is guaranteed. Full validation, agreements and admission rules
still apply on creation. No client, case or routing reservation is created by this endpoint.
Send outstanding principal, currency and debtor type/country/state; invoice lines and pricing
inputs are not evaluated. Model-binding errors use ValidationProblemDetails.
`marketMinimumAmount` is the smallest claim the market takes for this debtor country and type (never
below the platform minimum of 100 USD). `applicableMinimumAmount` is not populated by this endpoint.
**Examples**
**Matched** — request `{"amountToRecover": 15000, "currencyCode": "USD", "debtor": {"type": "Company", "countryAlpha2": "US", "stateAlpha2": "NY"}}`
→ response `{"hasPreLegalPartner": true, "collectionPartnerId": "...", "routingSource": "Automatic", "marketMinimumAmount": 500, "marketMinimumCurrencyCode": "USD"}`.
**No match, amount below minimum** — request `{"amountToRecover": 175, "currencyCode": "USD", "debtor": {"type": "Company", "countryAlpha2": "US", "stateAlpha2": "NY"}}`
→ response `{"hasPreLegalPartner": false, "ineligibilityReasonCode": "AmountBelowMinimum", "marketMinimumAmount": 500, "marketMinimumCurrencyCode": "USD"}`.
**No match, no geographic coverage** — request `{"amountToRecover": 2000, "currencyCode": "USD", "debtor": {"type": "Company", "countryAlpha2": "VN"}}`
→ response `{"hasPreLegalPartner": false, "ineligibilityReasonCode": "NoGeographicCoverage", "marketMinimumAmount": null}`.
**Excluded for this client** — request with a `clientId` excluded from every remaining candidate
→ response `{"hasPreLegalPartner": false, "ineligibilityReasonCode": "ExcludedForClient"}`.
**Explicit override** — request `{"amountToRecover": 2000, "currencyCode": "USD", "collectionPartnerId": "(a partner id)", "debtor": {...}}`
→ response `{"hasPreLegalPartner": true, "collectionPartnerId": "(the same id)", "routingSource": "Requested"}`.
**Degraded FX** — an unquotable request currency still returns a selected candidate where one exists:
response `{"hasPreLegalPartner": true, "routingSource": "Automatic", "ineligibilityReasonCode": "EligibilityUndetermined", "amountCheckUnavailable": true, "marketMinimumAmount": null}`.
### Request body (application/json)
- `amountToRecover` (number, required): Positive outstanding principal in CurrencyCode. For invoice lines, send their summed outstanding balance.
- `currencyCode` (string, required): Supported three-letter ISO currency code, for example USD or EUR.
3–3 characters.
- `debtor` (object, required): Simplified debtor information for case preview.
Only includes the minimum fields required for partner routing and eligibility checking.
- `debtor.type` (string, required): Debtor type. Valid values: "Company" or "Private"
This affects partner selection as different partners may specialize in B2B vs B2C collection.
- `debtor.countryAlpha2` (string, required): Country code (ISO 3166-1 alpha-2 format, e.g., "DK", "US", "PL")
Used to determine jurisdiction and available collection partners.
2–2 characters.
- `debtor.stateAlpha2` (string, nullable): US state code (e.g., "CA", "NY")
REQUIRED for United States cases only, as US partner coverage is state-specific.
Optional for other countries.
2–2 characters.
- `clientId` (uuid, nullable): Optional represented client owned by your partner account. Omit to preview a new inline client without creating one.
- `collectionPartnerId` (uuid, nullable): Optional explicit receiving partner. Takes precedence over automatic and test-case routing.
- `isTest` (boolean): Preview test routing. Without an explicit receiving partner, test/demo cases route to your own partner account.
```json
{
"amountToRecover": 2500,
"currencyCode": "EUR",
"debtor": {
"type": "string",
"countryAlpha2": "DE"
}
}
```
### Response 200
OK
- `hasPreLegalPartner` (boolean): Whether a routing destination is selected now. Does not certify acceptance of the case.
- `collectionPartnerId` (uuid, nullable): Selected candidate, or null when no pre-legal partner was selected.
- `routingSource` (enum, nullable): How the candidate was selected. Null when no candidate was selected.
Values: `Automatic`, `ClientConfigured`, `Requested`, `SelfManaged`, `null`.
- `jurisdiction` (object): Geographic jurisdiction information for the case.
- `jurisdiction.id` (integer): Internal jurisdiction identifier.
- `jurisdiction.name` (string, nullable): Display name of the jurisdiction (e.g., "Denmark", "United States - California").
- `jurisdiction.countryAlpha2` (string, nullable): ISO 3166-1 alpha-2 country code.
- `jurisdiction.stateAlpha2` (string, nullable): ISO 3166-2 state/region code (only for countries with state-level routing like the US).
- `ineligibilityReasonCode` (string, nullable): Stable matching reason code. May be EligibilityUndetermined even with a selected candidate when amount checks were unavailable.
- `ineligibilityReason` (string, nullable): Matching diagnosis, not a refusal of case admission.
- `applicableMinimumAmount` (number, nullable): Not populated by this endpoint (always null): a managed claim without a partner is not refused, and no amount is suggested. Use MarketMinimumAmount for the market floor.
- `applicableMinimumCurrencyCode` (string, nullable): Always null on this endpoint; see ApplicableMinimumAmount.
- `marketMinimumAmount` (number, nullable): Smallest claim the marketplace takes for this jurisdiction and debtor type, in the request currency: the lowest partner floor, never below the platform minimum of 100 USD. A market statement, returned whether or not a partner is selected. Not the admission rules applied when a case is created. Null when no partner covers the market or the amount cannot be priced (see AmountCheckUnavailable).
- `marketMinimumCurrencyCode` (string, nullable): Currency of MarketMinimumAmount.
- `amountCheckUnavailable` (boolean): Amount conditions could not be fully evaluated. May be true even when a candidate is selected.
```json
{
"hasPreLegalPartner": true,
"collectionPartnerId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"routingSource": "Automatic",
"jurisdiction": {
"id": 3,
"name": "Muster GmbH",
"countryAlpha2": "DE",
"stateAlpha2": null
},
"ineligibilityReasonCode": null,
"ineligibilityReason": null,
"applicableMinimumAmount": 2500,
"applicableMinimumCurrencyCode": "EUR",
"marketMinimumAmount": 2500,
"marketMinimumCurrencyCode": "EUR",
"amountCheckUnavailable": true
}
```
### Response 400
Bad Request
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 401
Unauthorized
- `type` (string, nullable):
- `title` (string, nullable):
- `status` (integer, nullable):
- `detail` (string, nullable):
- `instance` (string, nullable):
```json
{
"type": "string",
"title": "string",
"status": 3,
"detail": "string",
"instance": "string"
}
```
### Response 404
Not Found
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 500
Internal Server Error
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
## List managed cases
`GET /managed-cases`
Returns a paginated list of cases where you are the **managing partner** (submitted on behalf of your clients).
**What is a Managing Partner?**
A managing partner is a collection partner that submits cases on behalf of their own clients but forwards the actual debt recovery work to another collection partner in Debitura's network. You remain your client's point of contact while leveraging Debitura's global network of 500+ partners across 183 jurisdictions.
**Why Become a Managing Partner?**
- Serve clients globally without physical presence in every jurisdiction
- Maintain client relationships while outsourcing collection work
- Access Debitura's vetted partner network
- Earn commission on successful recoveries
- Provide full-service debt recovery to your clients
**Your Role as Managing Partner:**
- Submit cases on behalf of your clients (via API or partner portal)
- Monitor case progress and recovery status (read-only access)
- Communicate with the collection partner through case chat
- Receive updates on payments and case status
- Invoice your clients and remit payments
**Note:** This endpoint shows cases YOU submitted. For cases where you are actively collecting, use the `/cases` endpoint instead.
**Partner Portal View:** These cases appear in the 'Cases Submitted' section of the partner portal.
**Pagination:**
- page (default: 1) - Page number, starting from 1
- pageSize (default: 10, max: 100) - Number of results per page
**Filters:**
- statuses - Filter by case lifecycle status (comma-separated list)
Valid values: PendingContractSigning, PendingVerificationInternal, PendingVerification,
NeedsAdditionalDetails, Leads, LeadsQuoteGiven, Active, Paused, Closed
- divisionIds - Filter by your client division IDs (comma-separated GUIDs)
- debtorIds - Filter by specific debtor IDs (comma-separated GUIDs)
- ids - Filter by specific case IDs (comma-separated GUIDs)
**Sorting:**
- sort - Sort field and direction (format: 'field:direction')
Examples: 'date:desc', 'amount:asc', 'debtorName:asc'
**Response:**
- Returns InvoiceListApiDTO with page metadata and cases array
- Each case includes collection partner information (who is actually collecting)
- Page metadata includes: totalResults, currentPage, skipped, pageSize
### Query parameters
- `Page` (integer):
- `PageSize` (integer):
- `DebtorIds` (array of uuids):
- `Ids` (array of uuids):
- `Statuses` (array of strings): Filter by case lifecycle status. Valid values: PendingContractSigning, PendingVerificationInternal,
PendingVerification, NeedsAdditionalDetails, Leads, LeadsQuoteGiven, Active, Paused, Closed, Merged
(case-insensitive; both name and description forms accepted).
- `DivisionIds` (array of uuids): Optional list of division IDs to filter by
- `Sort` (string): Optional sorting string "Field[:asc|desc][,Field2[:asc|desc]]…".
Valid sort fields: DateCreated, DateUpdated, DateFinished, DateCollectionStarted,
DueDate, Date, GrossAmount, Remainder, InterestFees, CollectionFees, ReminderFees,
Lifecycle, CloseCode. Examples: 'DateCreated:desc', 'DueDate:asc'. Unknown fields are silently ignored.
### Response 200
List returned
- `page` (object, required): Stable v1 pagination metadata shared by public list responses.
- `page.totalResults` (integer):
- `page.pageSize` (integer):
- `page.currentPage` (integer):
- `page.responseCount` (integer):
- `page.totalPages` (integer):
- `cases` (array of objects, nullable): V1 Invoice DTO for external partner APIs
- `cases[].id` (uuid):
- `cases[].dateCreated` (datetime):
- `cases[].dateUpdated` (datetime, nullable):
- `cases[].reference` (string, nullable):
- `cases[].creditorReference` (string, nullable):
- `cases[].creditorComments` (string, nullable):
- `cases[].claimDescription` (string, nullable):
- `cases[].grossAmount` (number):
- `cases[].remainder` (number):
- `cases[].interestFees` (number):
- `cases[].reminderFees` (number):
- `cases[].collectionFees` (number):
- `cases[].totalAddedFees` (number):
- `cases[].currency` (string, nullable):
- `cases[].isTestCase` (boolean):
- `cases[].lifecycle` (string, nullable):
- `cases[].dueDate` (datetime):
- `cases[].date` (datetime):
- `cases[].dateFinished` (datetime, nullable):
- `cases[].dateCollectionStarted` (datetime, nullable):
- `cases[].closeCode` (string, nullable):
- `cases[].currentEngagementPhase` (string, nullable): The current phase of the case's engagement: "Pre-legal", "Legal", or "Enforcement".
A different axis from Lifecycle/CloseCode — an Active case can be
in any of the three phases.
Null means "no active engagement" (e.g. lead / quoting / pre-contract-signing / unassigned, or
a data-consistency gap) — this is a distinct third state, NOT a synonym for Pre-legal. Most
cases legitimately read Pre-legal; phase only leaves Pre-legal on legal/enforcement quote flows.
Not guaranteed to be monotonic: an admin correction can move phase backwards (e.g. Legal back
to Pre-legal).
Persists after case closure — reflects the case's last-known engagement phase, not the current
Lifecycle. Note: this is a different field from a lead quote's own offered phase (the phase a
partner's quote proposes to work the case at, if this case ever went through a quote flow) —
this field is the case-level phase of its actual engagement, not a quote's terms.
- `cases[].claimType` (string, nullable): The type of claim for this case (e.g. "Unpaid Invoice", "Loan Repayment", "Breach of Contract").
Null if not set.
- `cases[].creditorDivisionId` (uuid, nullable):
- `cases[].debtor` (object): V1 Debtor DTO for external partner APIs.
The debtor is the party that owes the debt.
- `cases[].debtor.type` (string, required): Debtor type. Valid values: "Company" or "Private" (case-insensitive)
- `cases[].debtor.name` (string, required): Debtor name (company name or person's full name)
- `cases[].debtor.contactPerson` (string, nullable): Contact person at the company (required for companies, not used for persons)
- `cases[].debtor.companyRegistrationNumber` (string, nullable): Company registration number (VAT number, CVR, org number, etc.)
- `cases[].debtor.address` (string, nullable): Street address
- `cases[].debtor.zipCode` (string, nullable): Postal/ZIP code
- `cases[].debtor.city` (string, nullable): City name
- `cases[].debtor.state` (string, nullable): State/region/province name
- `cases[].debtor.stateAlpha2` (string, nullable): US state: two-letter code (e.g., "CA"), ISO 3166-2 format (e.g., "US-CA"), or full name (e.g., "California")
- `cases[].debtor.countryAlpha2` (string, nullable): Country code (ISO 3166-1 alpha-2 format)
- `cases[].debtor.country` (string, nullable): Country name
- `cases[].debtor.email` (string, nullable): Email address for debtor contact
- `cases[].debtor.phone` (string, nullable): Phone number (include country code)
- `cases[].collectionPartner` (object): V1 Collection Partner DTO for external partner APIs
- `cases[].collectionPartner.name` (string, nullable):
- `cases[].collectionPartner.officeEmail` (string, nullable):
- `cases[].collectionPartner.officePhone` (string, nullable):
- `cases[].collectionPartner.publicSite` (string, nullable):
- `cases[].collectionPartner.surveyCadenceMode` (enum, deprecated): Deprecated: kept as a number and never removed, but not extended. Survey-generation cadence: 0 = Standard
(rolling monthly survey), 1 = DecisionPointOnly (no rolling surveys). Your own cadence is available by name on GET /me.
Values: `0`, `1`.
- `cases[].creditor` (object): Creditor (client) information for external partner APIs.
Represents the party that the debtor owes money to.
- `cases[].creditor.id` (uuid): Unique identifier for the creditor
- `cases[].creditor.companyName` (string, nullable): Company name of the creditor
- `cases[].creditor.companyRegistrationNumber` (string, nullable): Company registration number (CVR, VAT number, etc.)
- `cases[].creditor.officeEmail` (string, nullable): Primary office email address
- `cases[].creditor.officePhone` (string, nullable): Primary office phone number
- `cases[].creditor.address` (string, nullable): Street address
- `cases[].creditor.city` (string, nullable): City
- `cases[].creditor.zipCode` (string, nullable): Postal/ZIP code
- `cases[].creditor.state` (string, nullable): State or region (if applicable)
- `cases[].creditor.country` (string, nullable): Country name
- `cases[].creditor.division` (object): Creditor division information for external partner APIs.
Represents a specific division or department within a creditor organization.
- `cases[].creditor.division.id` (uuid): Unique identifier for the division
- `cases[].creditor.division.name` (string, nullable): Name of the division
- `cases[].bankAccount` (object): Bank account information for partner API.
Full details provided as partners need this to:
1. Provide payment instructions to debtors (when debtor pays client directly)
2. Execute payouts to clients (when partner receives payment and pays out remainder)
- `cases[].bankAccount.id` (integer): Bank account identifier
- `cases[].bankAccount.label` (string, nullable): User-friendly label (e.g., "Main EUR Account")
- `cases[].bankAccount.scheme` (string, nullable): Account scheme: IBAN, SWIFT, or LOCAL
- `cases[].bankAccount.currencyCode` (string, nullable): Currency code (ISO 4217)
- `cases[].bankAccount.bankCountryCode` (string, nullable): Bank country code (ISO Alpha-2)
- `cases[].bankAccount.accountHolderName` (string, nullable): Account holder name (beneficiary)
- `cases[].bankAccount.iban` (string, nullable): IBAN (for IBAN scheme accounts)
- `cases[].bankAccount.bic` (string, nullable): BIC/SWIFT code (for IBAN and SWIFT scheme accounts)
- `cases[].bankAccount.accountNumber` (string, nullable): Account number (for SWIFT and LOCAL scheme accounts)
- `cases[].bankAccount.localIdentifier` (string, nullable): Local identifier (for LOCAL scheme accounts, e.g., sort code + account number)
- `cases[].bankAccount.localIdentifierType` (string, nullable): Type of local identifier (e.g., "Sort Code", "Routing Number")
- `cases[].bankAccount.bankName` (string, nullable): Bank name (optional)
- `cases[].bankAccount.bankAddress` (string, nullable): Bank address (optional)
- `cases[].bankAccount.bankCity` (string, nullable): Bank city (optional)
- `cases[].bankAccount.bankZipCode` (string, nullable): Bank zip/postal code (optional)
- `cases[].bankAccount.bankState` (string, nullable): Bank state/region (optional)
- `cases[].blendedAgeUpliftPoints` (number, nullable): MULTI-INVOICE AGE BUCKET PRICING
Calculated blended age uplift percentage points (0-20) for multi-invoice cases.
Shows the additional fee percentage added due to invoice age.
Formula: ((A12-A24)×10 + A24×20) / Total Principal
Null for single-invoice cases (age uplift is calculated from due date instead).
- `cases[].preLegalSuccessFee` (number, nullable): PRE-LEGAL SUCCESS FEE
The total pre-legal success fee percentage for this case.
Includes base fee + age-based uplift (blended or single-invoice).
Null if pricing has not been calculated yet or if case is not in pre-legal phase.
Example: 20.5 represents 20.5% success fee.
- `cases[].solutionUrl` (string, nullable, deprecated): When the case is created with allowPendingContracts=true and required contracts are unsigned,
this URL points to the signing page. Null when contracts are already signed or not applicable.
- `cases[].signingHandoff` (object): Partner-facing handoff metadata for a creditor's pending signing chain.
Returned on POST /cases responses (422 with pending-signing errors,
or 200 with AllowPendingContracts=true when signings remain).
Designed as an envelope so future fields (expiration, suggested email
copy, etc.) can be added without polluting the parent DTO.
- `cases[].signingHandoff.combinedSigningUrl` (string, nullable): Single signing entry URL that walks the creditor through every
pending step (SDCA upgrade → PoA → JPA → KYC) on the Creditors app
and returns to the partner-supplied returnUrl when done.
- `cases[].exclusivePeriodEndDate` (datetime, nullable): The date the exclusive collection period ends (or ended).
Null if no collection period has been created for this case (e.g. custom-terms cases).
Use GET /cases/{id}/exclusive-period for the full chain including extensions.
- `cases[].disputeStatus` (string, nullable): Whether the claim is disputed by the debtor.
One of: "Yes, the claim is disputed", "No, the claim is not disputed", or "Don't Know".
Null when the dispute status has not been set on the case.
- `cases[].validation` (object): Stable v1 validation summary used by ordinary and list mappings.
- `cases[].validation.needsInfo` (boolean):
- `cases[].assignedUser` (object): Represents the creditor team member assigned to a case.
- `cases[].assignedUser.email` (string, nullable): The assigned user's email address.
- `cases[].assignedUser.name` (string, nullable): The assigned user's full name.
- `cases[].allocationOutstanding` (object): Outstanding amount per bucket on the case: each bucket's total minus the payments allocated to it.
- `cases[].allocationOutstanding.principal` (number):
- `cases[].allocationOutstanding.interest` (number):
- `cases[].allocationOutstanding.reminderFees` (number):
- `cases[].allocationOutstanding.collectionFees` (number):
```json
{
"page": {
"totalResults": 42,
"pageSize": 25,
"currentPage": 1,
"responseCount": 42,
"totalPages": 1
},
"cases": [
{
"id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"dateCreated": "2026-10-01T14:05:00Z",
"dateUpdated": "2026-10-01T14:05:00Z",
"reference": "INV-2026-0042",
"creditorReference": "INV-2026-0042",
"creditorComments": "Payment plan agreed with the debtor.",
"claimDescription": "string",
"grossAmount": 2500,
"remainder": 1.5,
"interestFees": 2500,
"reminderFees": 2500,
"collectionFees": 2500,
"totalAddedFees": 2500,
"currency": "EUR",
"isTestCase": true,
"lifecycle": "string",
"dueDate": "2026-10-01T14:05:00Z",
"date": "2026-10-01T14:05:00Z",
"dateFinished": "2026-10-01T14:05:00Z",
"dateCollectionStarted": "2026-10-01T14:05:00Z",
"closeCode": "string",
"currentEngagementPhase": "string",
"claimType": "string",
"creditorDivisionId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"debtor": {
"type": "Company",
"name": "Pacific Trading LLC",
"contactPerson": "John Smith",
"companyRegistrationNumber": "47-1234567",
"address": "123 Market Street, Suite 400",
"zipCode": "94105",
"city": "San Francisco",
"state": "California",
"stateAlpha2": "CA",
"countryAlpha2": "US",
"country": "United States",
"email": "accounts@pacifictrading.com",
"phone": "+1 415 555 0123"
},
"collectionPartner": {
"name": "Muster GmbH",
"officeEmail": "finance@example.com",
"officePhone": "+49 30 1234567",
"publicSite": "string",
"surveyCadenceMode": 0
},
"creditor": {
"id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"companyName": "Muster GmbH",
"companyRegistrationNumber": "DE123456789",
"officeEmail": "finance@example.com",
"officePhone": "+49 30 1234567",
"address": "Friedrichstraße 68",
"city": "Berlin",
"zipCode": "10115",
"state": "string",
"country": "Germany",
"division": {
"id": {},
"name": {}
}
},
"bankAccount": {
"id": 3,
"label": "string",
"scheme": "string",
"currencyCode": "EUR",
"bankCountryCode": "DE",
"accountHolderName": "Muster GmbH",
"iban": "string",
"bic": "string",
"accountNumber": "string",
"localIdentifier": "string",
"localIdentifierType": "string",
"bankName": "Muster GmbH",
"bankAddress": "Friedrichstraße 68",
"bankCity": "Berlin",
"bankZipCode": "10115",
"bankState": "string"
},
"blendedAgeUpliftPoints": 1.5,
"preLegalSuccessFee": 2500,
"solutionUrl": "https://app.debitura.com/…",
"signingHandoff": {
"combinedSigningUrl": "https://app.debitura.com/…"
},
"exclusivePeriodEndDate": "2026-10-01T14:05:00Z",
"disputeStatus": "string",
"validation": {
"needsInfo": true
},
"assignedUser": {
"email": "finance@example.com",
"name": "Muster GmbH"
},
"allocationOutstanding": {
"principal": 1.5,
"interest": 1.5,
"reminderFees": 2500,
"collectionFees": 2500
}
}
]
}
```
### Response 400
Invalid query parameters (returns specific validation errors)
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
## Create case as managing partner
`POST /managed-cases`
**Two ways to name the creditor — send one, never both:**
- **clientId (standard).** Create the client once with `POST /managed-clients`, then send its id as
`clientId` on every case for that client. All of its cases land on the same client record.
- **creditorCompanyName + country (deprecated).** Still works, so existing integrations never break,
but it creates a **new client record on every call**. Responses in this mode carry a
`Deprecation: true` header. No removal date is set.
Sending `clientId` together with any creditor company field is rejected with a 400. A `clientId` that is
not one of your represented clients returns 404. With `clientId`, a CreditorReference already used on
that client is rejected as a duplicate. `clientId` replaces CreditorCompanyName and the creditor country
in the required fields below.
Creates a collection case on behalf of your client (or yourself) through the Debitura platform.
**Understanding the Creditor Field:**
The creditor is the party that the debtor owes money to. This can be:
- **Your client's company** - When you're submitting cases on behalf of clients you represent
- **Your own company** - When you're submitting your own debt collection cases
**How It Works:**
1. You provide the creditor's basic information (company name + country)
2. Debitura creates a creditor record (if one doesn't exist)
3. The collection case is created under that creditor
4. You are set as the managing partner
5. The case is automatically assigned to a collection partner based on jurisdiction
**Managing Partner Benefits:**
- Submit cases on behalf of your clients via API
- Maintain your client relationships
- Leverage Debitura's global partner network
- Monitor case progress through read-only access
- Provide full-service debt recovery to your clients
**Required Fields:**
- CreditorCompanyName - The company name of who the debtor owes money to
- CreditorCountryAlpha2 OR CreditorCountry - Creditor's country (provide either code or name)
- CurrencyCode - Case currency (e.g., 'USD', 'EUR', 'DKK')
- Date - Invoice issue date
- AmountToRecover - Claim amount
- Debtor - Complete debtor information with jurisdiction
**Debtor Rules:**
- debtor.type must be "Company" or "Private" (case-insensitive)
- Company → debtor.name is mandatory (company name)
- Private → debtor.name is mandatory (individual's full name)
- For Company debtors, debtor.contactPerson is required
- debtor.country (or debtor.countryAlpha2) is always required
- debtor.stateAlpha2 is **required for US cases** - provide the two-letter state code (e.g., "CA", "NY"). For non-US cases, this field is optional.
- debtor.state is a general-purpose region field (not used for US jurisdiction resolution)
**Optional Fields:**
- DueDate - Invoice due date
- AmountToRecoverOver6Months - Cumulative amount more than 6 months overdue (includes 12+ and 24+)
- AmountToRecoverOver12Months - Cumulative amount more than 12 months overdue (includes 24+)
- AmountToRecoverOver24Months - Cumulative amount more than 24 months overdue
- ClaimLines - The unpaid invoices making up the claim (see below)
- Comments - Additional notes
- ClaimDescription - Description of the claim
- CreditorReference - Your client's internal reference
- CollectionPartnerId - Override automatic partner matching
- IsTest - Mark as test case (excluded from production metrics)
**Submitting Claim Lines (recommended for multi-invoice claims):**
Instead of totalling the claim yourself, send the unpaid invoices and let us do the arithmetic:
```
"claimLines": [
{ "dueDate": "2024-01-15", "amount": 423.42, "reference": "INV-1001" },
{ "dueDate": "2025-05-02", "amount": 700.87, "reference": "INV-1042" }
]
```
- amount is the **outstanding balance** on that invoice — what the debtor still owes on it, already
net of payments received and credit notes issued. It is not the invoice's original face value.
Leave fully settled invoices out; every amount must be greater than zero, with at most 2 decimals.
- We derive AmountToRecover and all three age buckets from the lines, so send claimLines **instead of**
AmountToRecover and the AmountToRecoverOver6/12/24Months fields. Sending both is a 400.
- Use claimLines whenever the debtor has already part-paid: it is the only way to express an honest
age profile on a part-paid claim, because the buckets are then computed on the same outstanding
balances the total is computed on.
- claimLines prices on exact age data. Sending a single DueDate instead is an approximation and can
produce a different quote for the same claim.
- claimLines is a pricing input only. It is not stored and is not shown to the collecting partner —
include a per-invoice breakdown in Comments if the partner needs to see one.
- Maximum 1000 lines. Per-line errors are returned keyed by index, e.g. `ClaimLines[2].DueDate`.
- If you omit the case-level DueDate, it is set to the oldest due date across your lines — so in that
case Date must not be later than the earliest claimLines dueDate, or the request is rejected with a
400 on Date. Send an explicit DueDate if you need a different case due date.
**Response:**
Returns the created case details including the case ID, reference number, and assignment information.
**Important Notes:**
- The 12+ and 24+ fields must be supplied together. The 6+ field is optional, but when supplied it requires both other buckets.
- Cumulative values must satisfy AmountToRecover ≥ 6+ ≥ 12+ ≥ 24+. DueDate may coexist with age buckets.
- Creditor records are created fresh each time (no duplicate detection)
- Contract requirements are automatically bypassed
- Production cases enter Debitura's internal verification before proceeding to the assigned collection partner
- Test cases bypass internal verification because delayed auto-validation is only scheduled for production cases
- Cases appear in your 'Managed Cases' list
- You have read-only access to monitor case progress
### Headers
- `Idempotency-Key` (string): Optional non-empty, non-whitespace idempotency key (max 255 characters) for safely retrying this request. If a previous request used the same key with an identical body, the original terminal response is replayed verbatim. Reusing the key with a different body returns 422 with `businessErrors[0].type: "IdempotencyConflict"`. Field-level 400 validation errors are not stored, so you may fix the request and retry with the same key.
Max 255 characters.
### Request body (application/json)
- `clientId` (uuid, nullable): The client this case belongs to. Create the client once with POST /managed-clients and
send its id here; every case you submit for that client then lands on the same record.
Send either ClientId or the creditor company fields below, never both.
- `creditorCompanyName` (string, nullable, deprecated): Deprecated. Use ClientId: create the client once with POST /managed-clients. This mode still works and creates a new client record on every call. Creditor company name for this case.
If you're submitting cases on behalf of your clients, use your client's company name.
If you're submitting your own cases, use your own partner company name.
- `creditorCountryAlpha2` (string, nullable, deprecated): Deprecated. Use ClientId: create the client once with POST /managed-clients. This mode still works and creates a new client record on every call. Creditor country code (ISO 3166-1 alpha-2 format). Either this or CreditorCountry is required.
- `creditorCountry` (string, nullable, deprecated): Deprecated. Use ClientId: create the client once with POST /managed-clients. This mode still works and creates a new client record on every call. Creditor country name. Either this or CreditorCountryAlpha2 is required.
- `currencyCode` (string, required): Currency code for the case (ISO 4217 format)
- `date` (datetime, required): Invoice issue date. Provide date only without time component.
- `dueDate` (datetime, nullable): Invoice due date. Provide date only without time component.
- `comments` (string, nullable): Optional comments about the case. Use this to provide context about payment attempts, communication history, or other relevant information.
Max 4000 characters.
- `claimDescription` (string, nullable): Client provided description of the services or goods delivered
Max 4000 characters.
- `creditorReference` (string, nullable): Client's internal reference for the case (e.g., invoice number)
Max 50 characters.
- `debtor` (object, required): V1 Debtor DTO for external partner APIs.
The debtor is the party that owes the debt.
- `debtor.type` (string, required): Debtor type. Valid values: "Company" or "Private" (case-insensitive)
- `debtor.name` (string, required): Debtor name (company name or person's full name)
- `debtor.contactPerson` (string, nullable): Contact person at the company (required for companies, not used for persons)
- `debtor.companyRegistrationNumber` (string, nullable): Company registration number (VAT number, CVR, org number, etc.)
- `debtor.address` (string, nullable): Street address
- `debtor.zipCode` (string, nullable): Postal/ZIP code
- `debtor.city` (string, nullable): City name
- `debtor.state` (string, nullable): State/region/province name
- `debtor.stateAlpha2` (string, nullable): US state: two-letter code (e.g., "CA"), ISO 3166-2 format (e.g., "US-CA"), or full name (e.g., "California")
- `debtor.countryAlpha2` (string, nullable): Country code (ISO 3166-1 alpha-2 format)
- `debtor.country` (string, nullable): Country name
- `debtor.email` (string, nullable): Email address for debtor contact
- `debtor.phone` (string, nullable): Phone number (include country code)
- `amountToRecover` (number): Total amount to recover from debtor (in the specified currency).
Required unless you send ClaimLines, in which case this must be omitted or 0 — the server
derives the total by summing the outstanding balance of every claim line. Sending both a
non-zero AmountToRecover and ClaimLines is rejected, because the two would disagree.
- `amountToRecoverOver6Months` (number, nullable): Optional cumulative portion of AmountToRecover that is more than 6 months overdue.
Includes the 12+ and 24+ month amounts and must be supplied together with both fields.
- `amountToRecoverOver12Months` (number, nullable): Optional cumulative portion of AmountToRecover that is more than 12 months overdue.
Includes the 24+ month amount and must be supplied together with AmountToRecoverOver24Months.
- `amountToRecoverOver24Months` (number, nullable): Optional cumulative portion of AmountToRecover that is more than 24 months overdue.
Must be supplied together with AmountToRecoverOver12Months.
- `claimLines` (array of objects, nullable): Optional: the unpaid invoices making up this claim, one line per invoice, each carrying its
own outstanding balance and payment deadline.
When supplied, the server derives AmountToRecover and all three cumulative age buckets from
these lines, so send them instead of — never alongside — AmountToRecover and the
AmountToRecoverOver6/12/24Months fields. Supplying both is rejected with a 400.
Use this whenever the debtor has already part-paid the claim: the buckets are then computed
on the same outstanding balances the total is computed on, so the age profile stays honest.
Maximum 1000 lines. When DueDate is omitted on the case, it is derived as the oldest line due date.
- `claimLines[].dueDate` (datetime, required, nullable): Payment deadline of this invoice. Provide date only without time component.
Must be on or after 2000-01-01 and must not be in the future.
- `claimLines[].amount` (number, required): The outstanding balance on this invoice in the case currency — what the debtor still owes on it,
already net of any payments the debtor has made and net of any credit notes issued against it.
This is not the invoice's original face value.
Must be greater than zero with at most 2 decimal places; omit invoices that are fully settled.
- `claimLines[].reference` (string, nullable): Optional: your own invoice number for this line. Used only to make validation errors readable
and to reject the same invoice being sent twice. It is not stored and not shown to anyone.
- `isTest` (boolean): When true, creates a test case that IS persisted to the database but marked as test data.
Test cases are excluded from production metrics and can be easily filtered or deleted.
Use this for integration testing and development.
- `tag` (string, nullable): Optional tag for scoped test data grouping (e.g. "suite-run-{uuid}").
Use this to group test cases created by a single CI pipeline run so they can be
bulk-deleted via DELETE /test/cases?tag={tag} without affecting parallel runs.
Only meaningful when IsTest is true. Max 100 characters.
Max 100 characters.
- `collectionPartnerId` (uuid, nullable): Optional: Specify a collection partner ID to handle this case.
When provided, this partner is used instead of automatic partner matching.
The partner must be active and have coverage for the debtor's jurisdiction.
```json
{
"creditorCompanyName": "Acme Services Inc",
"creditorCountry": "United States",
"currencyCode": "USD",
"amountToRecover": 15000,
"amountToRecoverOver6Months": 9000,
"amountToRecoverOver12Months": 6000,
"amountToRecoverOver24Months": 2000,
"date": "2026-05-01",
"dueDate": "2026-05-15",
"claimDescription": "Software development services - Project Alpha",
"comments": "Invoice INV-2024-1234 for custom ERP system development. Payment 90 days overdue despite multiple reminders. Client confirmed services received but cited cash flow issues.",
"creditorReference": "INV-2024-1234",
"isTest": false,
"debtor": {
"type": "Company",
"name": "Pacific Trading LLC",
"contactPerson": "John Smith",
"companyRegistrationNumber": "47-1234567",
"address": "123 Market Street, Suite 400",
"zipCode": "94105",
"city": "San Francisco",
"stateAlpha2": "CA",
"country": "United States",
"email": "accounts@pacifictrading.com",
"phone": "+1 415 555 0123"
}
}
```
### Response 200
Case created successfully
- `id` (uuid):
- `dateCreated` (datetime):
- `dateUpdated` (datetime, nullable):
- `reference` (string, nullable):
- `creditorReference` (string, nullable):
- `creditorComments` (string, nullable):
- `claimDescription` (string, nullable):
- `grossAmount` (number):
- `remainder` (number):
- `interestFees` (number):
- `reminderFees` (number):
- `collectionFees` (number):
- `totalAddedFees` (number):
- `currency` (string, nullable):
- `isTestCase` (boolean):
- `lifecycle` (string, nullable):
- `dueDate` (datetime):
- `date` (datetime):
- `dateFinished` (datetime, nullable):
- `dateCollectionStarted` (datetime, nullable):
- `closeCode` (string, nullable):
- `currentEngagementPhase` (string, nullable): The current phase of the case's engagement: "Pre-legal", "Legal", or "Enforcement".
A different axis from Lifecycle/CloseCode — an Active case can be
in any of the three phases.
Null means "no active engagement" (e.g. lead / quoting / pre-contract-signing / unassigned, or
a data-consistency gap) — this is a distinct third state, NOT a synonym for Pre-legal. Most
cases legitimately read Pre-legal; phase only leaves Pre-legal on legal/enforcement quote flows.
Not guaranteed to be monotonic: an admin correction can move phase backwards (e.g. Legal back
to Pre-legal).
Persists after case closure — reflects the case's last-known engagement phase, not the current
Lifecycle. Note: this is a different field from a lead quote's own offered phase (the phase a
partner's quote proposes to work the case at, if this case ever went through a quote flow) —
this field is the case-level phase of its actual engagement, not a quote's terms.
- `claimType` (string, nullable): The type of claim for this case (e.g. "Unpaid Invoice", "Loan Repayment", "Breach of Contract").
Null if not set.
- `creditorDivisionId` (uuid, nullable):
- `debtor` (object): V1 Debtor DTO for external partner APIs.
The debtor is the party that owes the debt.
- `debtor.type` (string, required): Debtor type. Valid values: "Company" or "Private" (case-insensitive)
- `debtor.name` (string, required): Debtor name (company name or person's full name)
- `debtor.contactPerson` (string, nullable): Contact person at the company (required for companies, not used for persons)
- `debtor.companyRegistrationNumber` (string, nullable): Company registration number (VAT number, CVR, org number, etc.)
- `debtor.address` (string, nullable): Street address
- `debtor.zipCode` (string, nullable): Postal/ZIP code
- `debtor.city` (string, nullable): City name
- `debtor.state` (string, nullable): State/region/province name
- `debtor.stateAlpha2` (string, nullable): US state: two-letter code (e.g., "CA"), ISO 3166-2 format (e.g., "US-CA"), or full name (e.g., "California")
- `debtor.countryAlpha2` (string, nullable): Country code (ISO 3166-1 alpha-2 format)
- `debtor.country` (string, nullable): Country name
- `debtor.email` (string, nullable): Email address for debtor contact
- `debtor.phone` (string, nullable): Phone number (include country code)
- `collectionPartner` (object): V1 Collection Partner DTO for external partner APIs
- `collectionPartner.name` (string, nullable):
- `collectionPartner.officeEmail` (string, nullable):
- `collectionPartner.officePhone` (string, nullable):
- `collectionPartner.publicSite` (string, nullable):
- `collectionPartner.surveyCadenceMode` (enum, deprecated): Deprecated: kept as a number and never removed, but not extended. Survey-generation cadence: 0 = Standard
(rolling monthly survey), 1 = DecisionPointOnly (no rolling surveys). Your own cadence is available by name on GET /me.
Values: `0`, `1`.
- `creditor` (object): Creditor (client) information for external partner APIs.
Represents the party that the debtor owes money to.
- `creditor.id` (uuid): Unique identifier for the creditor
- `creditor.companyName` (string, nullable): Company name of the creditor
- `creditor.companyRegistrationNumber` (string, nullable): Company registration number (CVR, VAT number, etc.)
- `creditor.officeEmail` (string, nullable): Primary office email address
- `creditor.officePhone` (string, nullable): Primary office phone number
- `creditor.address` (string, nullable): Street address
- `creditor.city` (string, nullable): City
- `creditor.zipCode` (string, nullable): Postal/ZIP code
- `creditor.state` (string, nullable): State or region (if applicable)
- `creditor.country` (string, nullable): Country name
- `creditor.division` (object): Creditor division information for external partner APIs.
Represents a specific division or department within a creditor organization.
- `creditor.division.id` (uuid): Unique identifier for the division
- `creditor.division.name` (string, nullable): Name of the division
- `bankAccount` (object): Bank account information for partner API.
Full details provided as partners need this to:
1. Provide payment instructions to debtors (when debtor pays client directly)
2. Execute payouts to clients (when partner receives payment and pays out remainder)
- `bankAccount.id` (integer): Bank account identifier
- `bankAccount.label` (string, nullable): User-friendly label (e.g., "Main EUR Account")
- `bankAccount.scheme` (string, nullable): Account scheme: IBAN, SWIFT, or LOCAL
- `bankAccount.currencyCode` (string, nullable): Currency code (ISO 4217)
- `bankAccount.bankCountryCode` (string, nullable): Bank country code (ISO Alpha-2)
- `bankAccount.accountHolderName` (string, nullable): Account holder name (beneficiary)
- `bankAccount.iban` (string, nullable): IBAN (for IBAN scheme accounts)
- `bankAccount.bic` (string, nullable): BIC/SWIFT code (for IBAN and SWIFT scheme accounts)
- `bankAccount.accountNumber` (string, nullable): Account number (for SWIFT and LOCAL scheme accounts)
- `bankAccount.localIdentifier` (string, nullable): Local identifier (for LOCAL scheme accounts, e.g., sort code + account number)
- `bankAccount.localIdentifierType` (string, nullable): Type of local identifier (e.g., "Sort Code", "Routing Number")
- `bankAccount.bankName` (string, nullable): Bank name (optional)
- `bankAccount.bankAddress` (string, nullable): Bank address (optional)
- `bankAccount.bankCity` (string, nullable): Bank city (optional)
- `bankAccount.bankZipCode` (string, nullable): Bank zip/postal code (optional)
- `bankAccount.bankState` (string, nullable): Bank state/region (optional)
- `blendedAgeUpliftPoints` (number, nullable): MULTI-INVOICE AGE BUCKET PRICING
Calculated blended age uplift percentage points (0-20) for multi-invoice cases.
Shows the additional fee percentage added due to invoice age.
Formula: ((A12-A24)×10 + A24×20) / Total Principal
Null for single-invoice cases (age uplift is calculated from due date instead).
- `preLegalSuccessFee` (number, nullable): PRE-LEGAL SUCCESS FEE
The total pre-legal success fee percentage for this case.
Includes base fee + age-based uplift (blended or single-invoice).
Null if pricing has not been calculated yet or if case is not in pre-legal phase.
Example: 20.5 represents 20.5% success fee.
- `solutionUrl` (string, nullable, deprecated): When the case is created with allowPendingContracts=true and required contracts are unsigned,
this URL points to the signing page. Null when contracts are already signed or not applicable.
- `signingHandoff` (object): Partner-facing handoff metadata for a creditor's pending signing chain.
Returned on POST /cases responses (422 with pending-signing errors,
or 200 with AllowPendingContracts=true when signings remain).
Designed as an envelope so future fields (expiration, suggested email
copy, etc.) can be added without polluting the parent DTO.
- `signingHandoff.combinedSigningUrl` (string, nullable): Single signing entry URL that walks the creditor through every
pending step (SDCA upgrade → PoA → JPA → KYC) on the Creditors app
and returns to the partner-supplied returnUrl when done.
- `exclusivePeriodEndDate` (datetime, nullable): The date the exclusive collection period ends (or ended).
Null if no collection period has been created for this case (e.g. custom-terms cases).
Use GET /cases/{id}/exclusive-period for the full chain including extensions.
- `disputeStatus` (string, nullable): Whether the claim is disputed by the debtor.
One of: "Yes, the claim is disputed", "No, the claim is not disputed", or "Don't Know".
Null when the dispute status has not been set on the case.
- `validation` (object): Stable v1 validation summary used by ordinary and list mappings.
- `validation.needsInfo` (boolean):
- `assignedUser` (object): Represents the creditor team member assigned to a case.
- `assignedUser.email` (string, nullable): The assigned user's email address.
- `assignedUser.name` (string, nullable): The assigned user's full name.
- `allocationOutstanding` (object): Outstanding amount per bucket on the case: each bucket's total minus the payments allocated to it.
- `allocationOutstanding.principal` (number):
- `allocationOutstanding.interest` (number):
- `allocationOutstanding.reminderFees` (number):
- `allocationOutstanding.collectionFees` (number):
```json
{
"id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"dateCreated": "2026-10-01T14:05:00Z",
"dateUpdated": "2026-10-01T14:05:00Z",
"reference": "INV-2026-0042",
"creditorReference": "INV-2026-0042",
"creditorComments": "Payment plan agreed with the debtor.",
"claimDescription": "string",
"grossAmount": 2500,
"remainder": 1.5,
"interestFees": 2500,
"reminderFees": 2500,
"collectionFees": 2500,
"totalAddedFees": 2500,
"currency": "EUR",
"isTestCase": true,
"lifecycle": "string",
"dueDate": "2026-10-01T14:05:00Z",
"date": "2026-10-01T14:05:00Z",
"dateFinished": "2026-10-01T14:05:00Z",
"dateCollectionStarted": "2026-10-01T14:05:00Z",
"closeCode": "string",
"currentEngagementPhase": "string",
"claimType": "string",
"creditorDivisionId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"debtor": {
"type": "Company",
"name": "Pacific Trading LLC",
"contactPerson": "John Smith",
"companyRegistrationNumber": "47-1234567",
"address": "123 Market Street, Suite 400",
"zipCode": "94105",
"city": "San Francisco",
"state": "California",
"stateAlpha2": "CA",
"countryAlpha2": "US",
"country": "United States",
"email": "accounts@pacifictrading.com",
"phone": "+1 415 555 0123"
},
"collectionPartner": {
"name": "Muster GmbH",
"officeEmail": "finance@example.com",
"officePhone": "+49 30 1234567",
"publicSite": "string",
"surveyCadenceMode": 0
},
"creditor": {
"id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"companyName": "Muster GmbH",
"companyRegistrationNumber": "DE123456789",
"officeEmail": "finance@example.com",
"officePhone": "+49 30 1234567",
"address": "Friedrichstraße 68",
"city": "Berlin",
"zipCode": "10115",
"state": "string",
"country": "Germany",
"division": {
"id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"name": "Muster GmbH"
}
},
"bankAccount": {
"id": 3,
"label": "string",
"scheme": "string",
"currencyCode": "EUR",
"bankCountryCode": "DE",
"accountHolderName": "Muster GmbH",
"iban": "string",
"bic": "string",
"accountNumber": "string",
"localIdentifier": "string",
"localIdentifierType": "string",
"bankName": "Muster GmbH",
"bankAddress": "Friedrichstraße 68",
"bankCity": "Berlin",
"bankZipCode": "10115",
"bankState": "string"
},
"blendedAgeUpliftPoints": 1.5,
"preLegalSuccessFee": 2500,
"solutionUrl": "https://app.debitura.com/…",
"signingHandoff": {
"combinedSigningUrl": "https://app.debitura.com/…"
},
"exclusivePeriodEndDate": "2026-10-01T14:05:00Z",
"disputeStatus": "string",
"validation": {
"needsInfo": true
},
"assignedUser": {
"email": "finance@example.com",
"name": "Muster GmbH"
},
"allocationOutstanding": {
"principal": 1.5,
"interest": 1.5,
"reminderFees": 2500,
"collectionFees": 2500
}
}
```
### Response 400
Invalid request data (field validation errors)
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 404
clientId is not one of your represented clients
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 409
Conflict - an idempotent request with this key is still in progress
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 422
Business rule violation (e.g., no partner available for jurisdiction)
- `businessErrors` (array of objects, nullable): List of business errors that must be resolved before the case can be created.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
- `signingHandoff` (object): Partner-facing handoff metadata for a creditor's pending signing chain.
Returned on POST /cases responses (422 with pending-signing errors,
or 200 with AllowPendingContracts=true when signings remain).
Designed as an envelope so future fields (expiration, suggested email
copy, etc.) can be added without polluting the parent DTO.
- `signingHandoff.combinedSigningUrl` (string, nullable): Single signing entry URL that walks the creditor through every
pending step (SDCA upgrade → PoA → JPA → KYC) on the Creditors app
and returns to the partner-supplied returnUrl when done.
```json
{
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
],
"signingHandoff": {
"combinedSigningUrl": "https://app.debitura.com/…"
}
}
```
### Response 500
Internal server error
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
## Fetch managed case by ID
`GET /managed-cases/{id}`
Returns detailed information for a case you submitted on behalf of your client (where you are the managing partner).
**Access Control:**
This endpoint only returns cases where YOU are the managing partner. If you are the collection partner on a case, use `/cases/{id}` instead.
**Response Includes:**
- Case details (reference, amount, currency, status)
- Debtor information
- Your client information (the creditor)
- Collection partner details (who is actively collecting this case)
- Financial breakdown
- Case progress and timeline summary
**Monitoring Your Cases:**
As the managing partner, you have read-only access to monitor progress while the collection partner handles the actual recovery work.
### Path parameters
- `id` (uuid, required):
### Response 200
Case found
- `id` (uuid):
- `dateCreated` (datetime):
- `dateUpdated` (datetime, nullable):
- `reference` (string, nullable):
- `creditorReference` (string, nullable):
- `creditorComments` (string, nullable):
- `claimDescription` (string, nullable):
- `grossAmount` (number):
- `remainder` (number):
- `interestFees` (number):
- `reminderFees` (number):
- `collectionFees` (number):
- `totalAddedFees` (number):
- `currency` (string, nullable):
- `isTestCase` (boolean):
- `lifecycle` (string, nullable):
- `dueDate` (datetime):
- `date` (datetime):
- `dateFinished` (datetime, nullable):
- `dateCollectionStarted` (datetime, nullable):
- `closeCode` (string, nullable):
- `currentEngagementPhase` (string, nullable): The current phase of the case's engagement: "Pre-legal", "Legal", or "Enforcement".
A different axis from Lifecycle/CloseCode — an Active case can be
in any of the three phases.
Null means "no active engagement" (e.g. lead / quoting / pre-contract-signing / unassigned, or
a data-consistency gap) — this is a distinct third state, NOT a synonym for Pre-legal. Most
cases legitimately read Pre-legal; phase only leaves Pre-legal on legal/enforcement quote flows.
Not guaranteed to be monotonic: an admin correction can move phase backwards (e.g. Legal back
to Pre-legal).
Persists after case closure — reflects the case's last-known engagement phase, not the current
Lifecycle. Note: this is a different field from a lead quote's own offered phase (the phase a
partner's quote proposes to work the case at, if this case ever went through a quote flow) —
this field is the case-level phase of its actual engagement, not a quote's terms.
- `claimType` (string, nullable): The type of claim for this case (e.g. "Unpaid Invoice", "Loan Repayment", "Breach of Contract").
Null if not set.
- `creditorDivisionId` (uuid, nullable):
- `debtor` (object): V1 Debtor DTO for external partner APIs.
The debtor is the party that owes the debt.
- `debtor.type` (string, required): Debtor type. Valid values: "Company" or "Private" (case-insensitive)
- `debtor.name` (string, required): Debtor name (company name or person's full name)
- `debtor.contactPerson` (string, nullable): Contact person at the company (required for companies, not used for persons)
- `debtor.companyRegistrationNumber` (string, nullable): Company registration number (VAT number, CVR, org number, etc.)
- `debtor.address` (string, nullable): Street address
- `debtor.zipCode` (string, nullable): Postal/ZIP code
- `debtor.city` (string, nullable): City name
- `debtor.state` (string, nullable): State/region/province name
- `debtor.stateAlpha2` (string, nullable): US state: two-letter code (e.g., "CA"), ISO 3166-2 format (e.g., "US-CA"), or full name (e.g., "California")
- `debtor.countryAlpha2` (string, nullable): Country code (ISO 3166-1 alpha-2 format)
- `debtor.country` (string, nullable): Country name
- `debtor.email` (string, nullable): Email address for debtor contact
- `debtor.phone` (string, nullable): Phone number (include country code)
- `collectionPartner` (object): V1 Collection Partner DTO for external partner APIs
- `collectionPartner.name` (string, nullable):
- `collectionPartner.officeEmail` (string, nullable):
- `collectionPartner.officePhone` (string, nullable):
- `collectionPartner.publicSite` (string, nullable):
- `collectionPartner.surveyCadenceMode` (enum, deprecated): Deprecated: kept as a number and never removed, but not extended. Survey-generation cadence: 0 = Standard
(rolling monthly survey), 1 = DecisionPointOnly (no rolling surveys). Your own cadence is available by name on GET /me.
Values: `0`, `1`.
- `creditor` (object): Creditor (client) information for external partner APIs.
Represents the party that the debtor owes money to.
- `creditor.id` (uuid): Unique identifier for the creditor
- `creditor.companyName` (string, nullable): Company name of the creditor
- `creditor.companyRegistrationNumber` (string, nullable): Company registration number (CVR, VAT number, etc.)
- `creditor.officeEmail` (string, nullable): Primary office email address
- `creditor.officePhone` (string, nullable): Primary office phone number
- `creditor.address` (string, nullable): Street address
- `creditor.city` (string, nullable): City
- `creditor.zipCode` (string, nullable): Postal/ZIP code
- `creditor.state` (string, nullable): State or region (if applicable)
- `creditor.country` (string, nullable): Country name
- `creditor.division` (object): Creditor division information for external partner APIs.
Represents a specific division or department within a creditor organization.
- `creditor.division.id` (uuid): Unique identifier for the division
- `creditor.division.name` (string, nullable): Name of the division
- `bankAccount` (object): Bank account information for partner API.
Full details provided as partners need this to:
1. Provide payment instructions to debtors (when debtor pays client directly)
2. Execute payouts to clients (when partner receives payment and pays out remainder)
- `bankAccount.id` (integer): Bank account identifier
- `bankAccount.label` (string, nullable): User-friendly label (e.g., "Main EUR Account")
- `bankAccount.scheme` (string, nullable): Account scheme: IBAN, SWIFT, or LOCAL
- `bankAccount.currencyCode` (string, nullable): Currency code (ISO 4217)
- `bankAccount.bankCountryCode` (string, nullable): Bank country code (ISO Alpha-2)
- `bankAccount.accountHolderName` (string, nullable): Account holder name (beneficiary)
- `bankAccount.iban` (string, nullable): IBAN (for IBAN scheme accounts)
- `bankAccount.bic` (string, nullable): BIC/SWIFT code (for IBAN and SWIFT scheme accounts)
- `bankAccount.accountNumber` (string, nullable): Account number (for SWIFT and LOCAL scheme accounts)
- `bankAccount.localIdentifier` (string, nullable): Local identifier (for LOCAL scheme accounts, e.g., sort code + account number)
- `bankAccount.localIdentifierType` (string, nullable): Type of local identifier (e.g., "Sort Code", "Routing Number")
- `bankAccount.bankName` (string, nullable): Bank name (optional)
- `bankAccount.bankAddress` (string, nullable): Bank address (optional)
- `bankAccount.bankCity` (string, nullable): Bank city (optional)
- `bankAccount.bankZipCode` (string, nullable): Bank zip/postal code (optional)
- `bankAccount.bankState` (string, nullable): Bank state/region (optional)
- `blendedAgeUpliftPoints` (number, nullable): MULTI-INVOICE AGE BUCKET PRICING
Calculated blended age uplift percentage points (0-20) for multi-invoice cases.
Shows the additional fee percentage added due to invoice age.
Formula: ((A12-A24)×10 + A24×20) / Total Principal
Null for single-invoice cases (age uplift is calculated from due date instead).
- `preLegalSuccessFee` (number, nullable): PRE-LEGAL SUCCESS FEE
The total pre-legal success fee percentage for this case.
Includes base fee + age-based uplift (blended or single-invoice).
Null if pricing has not been calculated yet or if case is not in pre-legal phase.
Example: 20.5 represents 20.5% success fee.
- `solutionUrl` (string, nullable, deprecated): When the case is created with allowPendingContracts=true and required contracts are unsigned,
this URL points to the signing page. Null when contracts are already signed or not applicable.
- `signingHandoff` (object): Partner-facing handoff metadata for a creditor's pending signing chain.
Returned on POST /cases responses (422 with pending-signing errors,
or 200 with AllowPendingContracts=true when signings remain).
Designed as an envelope so future fields (expiration, suggested email
copy, etc.) can be added without polluting the parent DTO.
- `signingHandoff.combinedSigningUrl` (string, nullable): Single signing entry URL that walks the creditor through every
pending step (SDCA upgrade → PoA → JPA → KYC) on the Creditors app
and returns to the partner-supplied returnUrl when done.
- `exclusivePeriodEndDate` (datetime, nullable): The date the exclusive collection period ends (or ended).
Null if no collection period has been created for this case (e.g. custom-terms cases).
Use GET /cases/{id}/exclusive-period for the full chain including extensions.
- `disputeStatus` (string, nullable): Whether the claim is disputed by the debtor.
One of: "Yes, the claim is disputed", "No, the claim is not disputed", or "Don't Know".
Null when the dispute status has not been set on the case.
- `validation` (object): Stable v1 validation summary used by ordinary and list mappings.
- `validation.needsInfo` (boolean):
- `assignedUser` (object): Represents the creditor team member assigned to a case.
- `assignedUser.email` (string, nullable): The assigned user's email address.
- `assignedUser.name` (string, nullable): The assigned user's full name.
- `allocationOutstanding` (object): Outstanding amount per bucket on the case: each bucket's total minus the payments allocated to it.
- `allocationOutstanding.principal` (number):
- `allocationOutstanding.interest` (number):
- `allocationOutstanding.reminderFees` (number):
- `allocationOutstanding.collectionFees` (number):
```json
{
"id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"dateCreated": "2026-10-01T14:05:00Z",
"dateUpdated": "2026-10-01T14:05:00Z",
"reference": "INV-2026-0042",
"creditorReference": "INV-2026-0042",
"creditorComments": "Payment plan agreed with the debtor.",
"claimDescription": "string",
"grossAmount": 2500,
"remainder": 1.5,
"interestFees": 2500,
"reminderFees": 2500,
"collectionFees": 2500,
"totalAddedFees": 2500,
"currency": "EUR",
"isTestCase": true,
"lifecycle": "string",
"dueDate": "2026-10-01T14:05:00Z",
"date": "2026-10-01T14:05:00Z",
"dateFinished": "2026-10-01T14:05:00Z",
"dateCollectionStarted": "2026-10-01T14:05:00Z",
"closeCode": "string",
"currentEngagementPhase": "string",
"claimType": "string",
"creditorDivisionId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"debtor": {
"type": "Company",
"name": "Pacific Trading LLC",
"contactPerson": "John Smith",
"companyRegistrationNumber": "47-1234567",
"address": "123 Market Street, Suite 400",
"zipCode": "94105",
"city": "San Francisco",
"state": "California",
"stateAlpha2": "CA",
"countryAlpha2": "US",
"country": "United States",
"email": "accounts@pacifictrading.com",
"phone": "+1 415 555 0123"
},
"collectionPartner": {
"name": "Muster GmbH",
"officeEmail": "finance@example.com",
"officePhone": "+49 30 1234567",
"publicSite": "string",
"surveyCadenceMode": 0
},
"creditor": {
"id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"companyName": "Muster GmbH",
"companyRegistrationNumber": "DE123456789",
"officeEmail": "finance@example.com",
"officePhone": "+49 30 1234567",
"address": "Friedrichstraße 68",
"city": "Berlin",
"zipCode": "10115",
"state": "string",
"country": "Germany",
"division": {
"id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"name": "Muster GmbH"
}
},
"bankAccount": {
"id": 3,
"label": "string",
"scheme": "string",
"currencyCode": "EUR",
"bankCountryCode": "DE",
"accountHolderName": "Muster GmbH",
"iban": "string",
"bic": "string",
"accountNumber": "string",
"localIdentifier": "string",
"localIdentifierType": "string",
"bankName": "Muster GmbH",
"bankAddress": "Friedrichstraße 68",
"bankCity": "Berlin",
"bankZipCode": "10115",
"bankState": "string"
},
"blendedAgeUpliftPoints": 1.5,
"preLegalSuccessFee": 2500,
"solutionUrl": "https://app.debitura.com/…",
"signingHandoff": {
"combinedSigningUrl": "https://app.debitura.com/…"
},
"exclusivePeriodEndDate": "2026-10-01T14:05:00Z",
"disputeStatus": "string",
"validation": {
"needsInfo": true
},
"assignedUser": {
"email": "finance@example.com",
"name": "Muster GmbH"
},
"allocationOutstanding": {
"principal": 1.5,
"interest": 1.5,
"reminderFees": 2500,
"collectionFees": 2500
}
}
```
### Response 400
ID missing, empty, or ID is not a collection case
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 404
Case not found, deleted, or not submitted by you as managing partner
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
## Fetch managed case by reference
`GET /managed-cases/case-reference/{caseReference}`
Returns detailed case information using the Debitura case reference (e.g., 'Q8OAXF3W') for cases you submitted.
**Use Case:**
Use this endpoint when you have the Debitura case reference but not the GUID. Helpful for customer service integrations or when your clients reference cases by the Debitura reference number.
**Access Control:**
Only returns cases where you are the managing partner.
### Path parameters
- `caseReference` (string, required):
### Response 200
Case found
- `id` (uuid):
- `dateCreated` (datetime):
- `dateUpdated` (datetime, nullable):
- `reference` (string, nullable):
- `creditorReference` (string, nullable):
- `creditorComments` (string, nullable):
- `claimDescription` (string, nullable):
- `grossAmount` (number):
- `remainder` (number):
- `interestFees` (number):
- `reminderFees` (number):
- `collectionFees` (number):
- `totalAddedFees` (number):
- `currency` (string, nullable):
- `isTestCase` (boolean):
- `lifecycle` (string, nullable):
- `dueDate` (datetime):
- `date` (datetime):
- `dateFinished` (datetime, nullable):
- `dateCollectionStarted` (datetime, nullable):
- `closeCode` (string, nullable):
- `currentEngagementPhase` (string, nullable): The current phase of the case's engagement: "Pre-legal", "Legal", or "Enforcement".
A different axis from Lifecycle/CloseCode — an Active case can be
in any of the three phases.
Null means "no active engagement" (e.g. lead / quoting / pre-contract-signing / unassigned, or
a data-consistency gap) — this is a distinct third state, NOT a synonym for Pre-legal. Most
cases legitimately read Pre-legal; phase only leaves Pre-legal on legal/enforcement quote flows.
Not guaranteed to be monotonic: an admin correction can move phase backwards (e.g. Legal back
to Pre-legal).
Persists after case closure — reflects the case's last-known engagement phase, not the current
Lifecycle. Note: this is a different field from a lead quote's own offered phase (the phase a
partner's quote proposes to work the case at, if this case ever went through a quote flow) —
this field is the case-level phase of its actual engagement, not a quote's terms.
- `claimType` (string, nullable): The type of claim for this case (e.g. "Unpaid Invoice", "Loan Repayment", "Breach of Contract").
Null if not set.
- `creditorDivisionId` (uuid, nullable):
- `debtor` (object): V1 Debtor DTO for external partner APIs.
The debtor is the party that owes the debt.
- `debtor.type` (string, required): Debtor type. Valid values: "Company" or "Private" (case-insensitive)
- `debtor.name` (string, required): Debtor name (company name or person's full name)
- `debtor.contactPerson` (string, nullable): Contact person at the company (required for companies, not used for persons)
- `debtor.companyRegistrationNumber` (string, nullable): Company registration number (VAT number, CVR, org number, etc.)
- `debtor.address` (string, nullable): Street address
- `debtor.zipCode` (string, nullable): Postal/ZIP code
- `debtor.city` (string, nullable): City name
- `debtor.state` (string, nullable): State/region/province name
- `debtor.stateAlpha2` (string, nullable): US state: two-letter code (e.g., "CA"), ISO 3166-2 format (e.g., "US-CA"), or full name (e.g., "California")
- `debtor.countryAlpha2` (string, nullable): Country code (ISO 3166-1 alpha-2 format)
- `debtor.country` (string, nullable): Country name
- `debtor.email` (string, nullable): Email address for debtor contact
- `debtor.phone` (string, nullable): Phone number (include country code)
- `collectionPartner` (object): V1 Collection Partner DTO for external partner APIs
- `collectionPartner.name` (string, nullable):
- `collectionPartner.officeEmail` (string, nullable):
- `collectionPartner.officePhone` (string, nullable):
- `collectionPartner.publicSite` (string, nullable):
- `collectionPartner.surveyCadenceMode` (enum, deprecated): Deprecated: kept as a number and never removed, but not extended. Survey-generation cadence: 0 = Standard
(rolling monthly survey), 1 = DecisionPointOnly (no rolling surveys). Your own cadence is available by name on GET /me.
Values: `0`, `1`.
- `creditor` (object): Creditor (client) information for external partner APIs.
Represents the party that the debtor owes money to.
- `creditor.id` (uuid): Unique identifier for the creditor
- `creditor.companyName` (string, nullable): Company name of the creditor
- `creditor.companyRegistrationNumber` (string, nullable): Company registration number (CVR, VAT number, etc.)
- `creditor.officeEmail` (string, nullable): Primary office email address
- `creditor.officePhone` (string, nullable): Primary office phone number
- `creditor.address` (string, nullable): Street address
- `creditor.city` (string, nullable): City
- `creditor.zipCode` (string, nullable): Postal/ZIP code
- `creditor.state` (string, nullable): State or region (if applicable)
- `creditor.country` (string, nullable): Country name
- `creditor.division` (object): Creditor division information for external partner APIs.
Represents a specific division or department within a creditor organization.
- `creditor.division.id` (uuid): Unique identifier for the division
- `creditor.division.name` (string, nullable): Name of the division
- `bankAccount` (object): Bank account information for partner API.
Full details provided as partners need this to:
1. Provide payment instructions to debtors (when debtor pays client directly)
2. Execute payouts to clients (when partner receives payment and pays out remainder)
- `bankAccount.id` (integer): Bank account identifier
- `bankAccount.label` (string, nullable): User-friendly label (e.g., "Main EUR Account")
- `bankAccount.scheme` (string, nullable): Account scheme: IBAN, SWIFT, or LOCAL
- `bankAccount.currencyCode` (string, nullable): Currency code (ISO 4217)
- `bankAccount.bankCountryCode` (string, nullable): Bank country code (ISO Alpha-2)
- `bankAccount.accountHolderName` (string, nullable): Account holder name (beneficiary)
- `bankAccount.iban` (string, nullable): IBAN (for IBAN scheme accounts)
- `bankAccount.bic` (string, nullable): BIC/SWIFT code (for IBAN and SWIFT scheme accounts)
- `bankAccount.accountNumber` (string, nullable): Account number (for SWIFT and LOCAL scheme accounts)
- `bankAccount.localIdentifier` (string, nullable): Local identifier (for LOCAL scheme accounts, e.g., sort code + account number)
- `bankAccount.localIdentifierType` (string, nullable): Type of local identifier (e.g., "Sort Code", "Routing Number")
- `bankAccount.bankName` (string, nullable): Bank name (optional)
- `bankAccount.bankAddress` (string, nullable): Bank address (optional)
- `bankAccount.bankCity` (string, nullable): Bank city (optional)
- `bankAccount.bankZipCode` (string, nullable): Bank zip/postal code (optional)
- `bankAccount.bankState` (string, nullable): Bank state/region (optional)
- `blendedAgeUpliftPoints` (number, nullable): MULTI-INVOICE AGE BUCKET PRICING
Calculated blended age uplift percentage points (0-20) for multi-invoice cases.
Shows the additional fee percentage added due to invoice age.
Formula: ((A12-A24)×10 + A24×20) / Total Principal
Null for single-invoice cases (age uplift is calculated from due date instead).
- `preLegalSuccessFee` (number, nullable): PRE-LEGAL SUCCESS FEE
The total pre-legal success fee percentage for this case.
Includes base fee + age-based uplift (blended or single-invoice).
Null if pricing has not been calculated yet or if case is not in pre-legal phase.
Example: 20.5 represents 20.5% success fee.
- `solutionUrl` (string, nullable, deprecated): When the case is created with allowPendingContracts=true and required contracts are unsigned,
this URL points to the signing page. Null when contracts are already signed or not applicable.
- `signingHandoff` (object): Partner-facing handoff metadata for a creditor's pending signing chain.
Returned on POST /cases responses (422 with pending-signing errors,
or 200 with AllowPendingContracts=true when signings remain).
Designed as an envelope so future fields (expiration, suggested email
copy, etc.) can be added without polluting the parent DTO.
- `signingHandoff.combinedSigningUrl` (string, nullable): Single signing entry URL that walks the creditor through every
pending step (SDCA upgrade → PoA → JPA → KYC) on the Creditors app
and returns to the partner-supplied returnUrl when done.
- `exclusivePeriodEndDate` (datetime, nullable): The date the exclusive collection period ends (or ended).
Null if no collection period has been created for this case (e.g. custom-terms cases).
Use GET /cases/{id}/exclusive-period for the full chain including extensions.
- `disputeStatus` (string, nullable): Whether the claim is disputed by the debtor.
One of: "Yes, the claim is disputed", "No, the claim is not disputed", or "Don't Know".
Null when the dispute status has not been set on the case.
- `validation` (object): Stable v1 validation summary used by ordinary and list mappings.
- `validation.needsInfo` (boolean):
- `assignedUser` (object): Represents the creditor team member assigned to a case.
- `assignedUser.email` (string, nullable): The assigned user's email address.
- `assignedUser.name` (string, nullable): The assigned user's full name.
- `allocationOutstanding` (object): Outstanding amount per bucket on the case: each bucket's total minus the payments allocated to it.
- `allocationOutstanding.principal` (number):
- `allocationOutstanding.interest` (number):
- `allocationOutstanding.reminderFees` (number):
- `allocationOutstanding.collectionFees` (number):
```json
{
"id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"dateCreated": "2026-10-01T14:05:00Z",
"dateUpdated": "2026-10-01T14:05:00Z",
"reference": "INV-2026-0042",
"creditorReference": "INV-2026-0042",
"creditorComments": "Payment plan agreed with the debtor.",
"claimDescription": "string",
"grossAmount": 2500,
"remainder": 1.5,
"interestFees": 2500,
"reminderFees": 2500,
"collectionFees": 2500,
"totalAddedFees": 2500,
"currency": "EUR",
"isTestCase": true,
"lifecycle": "string",
"dueDate": "2026-10-01T14:05:00Z",
"date": "2026-10-01T14:05:00Z",
"dateFinished": "2026-10-01T14:05:00Z",
"dateCollectionStarted": "2026-10-01T14:05:00Z",
"closeCode": "string",
"currentEngagementPhase": "string",
"claimType": "string",
"creditorDivisionId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"debtor": {
"type": "Company",
"name": "Pacific Trading LLC",
"contactPerson": "John Smith",
"companyRegistrationNumber": "47-1234567",
"address": "123 Market Street, Suite 400",
"zipCode": "94105",
"city": "San Francisco",
"state": "California",
"stateAlpha2": "CA",
"countryAlpha2": "US",
"country": "United States",
"email": "accounts@pacifictrading.com",
"phone": "+1 415 555 0123"
},
"collectionPartner": {
"name": "Muster GmbH",
"officeEmail": "finance@example.com",
"officePhone": "+49 30 1234567",
"publicSite": "string",
"surveyCadenceMode": 0
},
"creditor": {
"id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"companyName": "Muster GmbH",
"companyRegistrationNumber": "DE123456789",
"officeEmail": "finance@example.com",
"officePhone": "+49 30 1234567",
"address": "Friedrichstraße 68",
"city": "Berlin",
"zipCode": "10115",
"state": "string",
"country": "Germany",
"division": {
"id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"name": "Muster GmbH"
}
},
"bankAccount": {
"id": 3,
"label": "string",
"scheme": "string",
"currencyCode": "EUR",
"bankCountryCode": "DE",
"accountHolderName": "Muster GmbH",
"iban": "string",
"bic": "string",
"accountNumber": "string",
"localIdentifier": "string",
"localIdentifierType": "string",
"bankName": "Muster GmbH",
"bankAddress": "Friedrichstraße 68",
"bankCity": "Berlin",
"bankZipCode": "10115",
"bankState": "string"
},
"blendedAgeUpliftPoints": 1.5,
"preLegalSuccessFee": 2500,
"solutionUrl": "https://app.debitura.com/…",
"signingHandoff": {
"combinedSigningUrl": "https://app.debitura.com/…"
},
"exclusivePeriodEndDate": "2026-10-01T14:05:00Z",
"disputeStatus": "string",
"validation": {
"needsInfo": true
},
"assignedUser": {
"email": "finance@example.com",
"name": "Muster GmbH"
},
"allocationOutstanding": {
"principal": 1.5,
"interest": 1.5,
"reminderFees": 2500,
"collectionFees": 2500
}
}
```
### Response 400
Reference missing or reference is not a collection case
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 404
Reference not found or not submitted by you as managing partner
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
## Fetch managed case timeline
`GET /managed-cases/{id}/timeline`
Returns the complete chronological event history for a case you submitted as managing partner.
**Timeline Events Include:**
- Case submission and acceptance
- Assignment to collection partner
- Status changes and lifecycle transitions
- Payment recordings
- Communication events between collection partner and creditor
- Collection partner updates and notes
**Managing Partner Transparency:**
The timeline provides full visibility into the collection partner's activities, allowing you to monitor progress and keep your clients informed.
**Response shape:**
- `items` — chronological list of timeline events
- `currentEngagementPhase` — current phase of the active engagement: "Pre-legal", "Legal", or "Enforcement". Null when no active engagement exists.
**Use Case:**
Use this to track case progress, update your clients on status, or audit collection partner activities.
### Path parameters
- `id` (uuid, required):
### Response 200
Timeline returned
- `items` (array of objects, required, nullable): Chronological list of events on the case.
- `items[].date` (datetime):
- `items[].type` (string, required, nullable):
- `items[].title` (string, required, nullable):
- `items[].description` (string, required, nullable):
- `items[].relatedCases` (array of objects, nullable): Related cases that the authenticated timeline viewer may open. Merge timeline entries
use these safe references instead of exposing persisted case identifiers in text.
- `items[].relatedCases[].id` (uuid):
- `items[].relatedCases[].reference` (string, required, nullable):
- `items[].actor` (object): Represents the actor (person or system) that performed a timeline action.
- `items[].actor.type` (string, required, nullable): The type of actor. One of: "System", "Creditor user", "Partner user".
- `items[].actor.name` (string, nullable): Display name of the actor, if available.
- `currentEngagementPhase` (string, nullable): The current engagement phase of the case, sourced from CaseEngagement.CurrentPhase.
Possible values: "Pre-legal", "Legal", "Enforcement".
Null when no active engagement exists (e.g. case not yet assigned to a partner).
```json
{
"items": [
{
"date": "2026-10-01T14:05:00Z",
"type": "string",
"title": "string",
"description": "string",
"relatedCases": [
{
"id": {},
"reference": {}
}
],
"actor": {
"type": "string",
"name": "Muster GmbH"
}
}
],
"currentEngagementPhase": "string"
}
```
### Response 400
Case ID missing or empty
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 404
Case not found or not submitted by you as managing partner
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
## Fetch managed case chats
`GET /managed-cases/{id}/chats`
Returns all chat messages for a case you submitted, in chronological order.
**Chat Participants (for Managed Cases):**
- Managing partner (you) - Your messages to the collection partner
- Collection partner - Messages from the partner actively collecting the case
- Your client (creditor) - Messages from the client you represent
- Debitura support - System notifications and support messages
**Communication Flow:**
As the managing partner, you can participate in case discussions to:
- Coordinate with the collection partner
- Provide additional information about the debtor
- Relay questions from your client
- Stay updated on collection progress
**Use Case:**
Monitor collection partner communications, coordinate case strategy, or extract conversation history to share with your clients.
**Note:** Managing partners have limited write access - you can read and send messages but cannot modify case details or add payments.
### Path parameters
- `id` (uuid, required):
### Response 200
Chats returned (empty array if no messages)
- `id` (uuid):
- `dateCreated` (datetime):
- `dateUpdated` (datetime, nullable):
- `role` (enum, deprecated): Deprecated: kept as a number and never removed, but not extended — read `roleLabel` instead.
Sender role: 0 = Partner, 1 = Creditor, 2 = ManagedByPartner.
Values: `0`, `1`, `2`.
- `roleLabel` (string, nullable): The sender role, readable. Always one of "Partner", "Creditor" or "Managed by partner" — these
values are stable.
- `message` (string, nullable):
- `isSeen` (boolean):
- `user` (object):
- `user.id` (integer):
- `user.dateCreated` (datetime, nullable):
- `user.dateUpdated` (datetime, nullable):
- `user.firstName` (string, nullable):
- `user.lastName` (string, nullable):
- `user.email` (string, required, nullable):
```json
[
{
"id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"dateCreated": "2026-10-01T14:05:00Z",
"dateUpdated": "2026-10-01T14:05:00Z",
"role": 0,
"roleLabel": "string",
"message": "Payment plan agreed with the debtor.",
"isSeen": true,
"user": {
"id": 3,
"dateCreated": "2026-10-01T14:05:00Z",
"dateUpdated": "2026-10-01T14:05:00Z",
"firstName": "Anna",
"lastName": "Schmidt",
"email": "finance@example.com"
}
}
]
```
### Response 400
Case ID missing or empty
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 404
Case not found or not submitted by you as managing partner
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
## Fetch managed case payments
`GET /managed-cases/{id}/payments`
Returns all payments recorded on a case you submitted as managing partner.
**Payment Information Includes:**
- Payment amount, currency, and date
- Payment type and method
- Payment status (recorded by collection partner)
- Allocation breakdown (principal, interest, fees)
- Payout details (amounts to creditor and collection partner)
**What This Endpoint Shows:**
As a managing partner, you can monitor all payment activity on cases you submitted for your clients. This endpoint provides visibility into:
- What the collection partner has recovered from the debtor
- How recovered amounts are allocated (principal vs. interest vs. fees)
- The collection partner's success fee on each payment
- Payment history and timeline
**Important:** This endpoint is for monitoring and client reporting purposes. Your financial arrangements with your clients (billing, commissions, etc.) are managed outside of Debitura's platform. The payment data shown here represents what the collection partner recovered and their fees, not any commissions or payments to you as the managing partner.
**Use Case:**
Monitor recovery progress, reconcile payments with your records, track case performance, or provide payment status updates to your clients.
**Note:** On production cases, only the assigned collection partner can record new payments. For test cases (isTestCase: true), managing partners can record payments via `POST /managed-cases/{id}/payments`.
### Path parameters
- `id` (uuid, required):
### Response 200
Payments returned (may be empty array)
- `id` (uuid):
- `dateCreated` (datetime):
- `dateUpdated` (datetime, nullable):
- `date` (datetime):
- `grossAmount` (number):
- `recipient` (string, required, nullable):
- `method` (string, required, nullable):
- `currency` (string, required, nullable):
- `invoice` (object, required):
- `invoice.status` (string, required, nullable):
- `invoice.reference` (string, required, nullable):
- `invoice.invoiceId` (uuid):
```json
[
{
"id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"dateCreated": "2026-10-01T14:05:00Z",
"dateUpdated": "2026-10-01T14:05:00Z",
"date": "2026-10-01T14:05:00Z",
"grossAmount": 2500,
"recipient": "string",
"method": "string",
"currency": "EUR",
"invoice": {
"status": "string",
"reference": "INV-2026-0042",
"invoiceId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31"
}
}
]
```
### Response 400
Case ID missing or empty
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 404
Case not found or not submitted by you as managing partner
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
## Record a payment on a test case (managing partner)
`POST /managed-cases/{id}/payments`
Records a payment on a test case you submitted as managing partner.
**Test-Only Restriction:**
This endpoint only works on cases created with `isTestCase: true`. Attempting to record a payment on a production case returns a 400 error. For production cases, the assigned collection partner must use `POST /cases/{id}/payments`.
**Purpose:**
Allows managing partners (e.g. Get-Systems) to test their full payment integration end-to-end — including webhook delivery, lifecycle transitions, and remainder updates — without involving the collection partner.
**Payout Handling:**
A payout record is created automatically with the full payment amount going to the creditor and zero to the collection partner. CommissionPaymentStatus is set to Unpaid.
**Webhooks:**
Payment webhooks fire normally, making this useful for end-to-end integration testing.
**CloseCase:**
If `closeCase=true` and the payment amount is less than the outstanding balance, a 400 is returned.
### Path parameters
- `id` (uuid, required):
### Request body (application/json)
- `date` (datetime, required): Payment date (when payment was received).
- `paymentAmount` (number, required): Total payment amount received.
Min 0.01.
- `closeCase` (boolean): Whether to close the case after recording this payment (default: false).
If true and payment < invoice remainder, returns validation error.
```json
{
"date": "2025-11-19",
"paymentAmount": 5000,
"closeCase": false
}
```
### Response 200
Payment recorded successfully
- `paymentId` (uuid):
- `caseReference` (string, required, nullable):
- `date` (datetime):
- `paymentAmount` (number):
- `caseClosed` (boolean):
- `remainingAmount` (number):
```json
{
"paymentId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"caseReference": "INV-2026-0042",
"date": "2026-10-01T14:05:00Z",
"paymentAmount": 2500,
"caseClosed": true,
"remainingAmount": 2500
}
```
### Response 400
Invalid request or production case
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 404
Case not found or not submitted by you as managing partner
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 500
Server error
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
## Edit a payment on a test case (managing partner)
`PUT /managed-cases/{id}/payments/{paymentId}`
Edits a payment on a test case you submitted as managing partner.
**Test-Only Restriction:** like recording a payment, this only works on cases created with `isTestCase: true`. Production cases return a 400 — the assigned collection partner must edit via `PUT /cases/{id}/payments/{paymentId}`.
**Invoiced payments are frozen:** an already-invoiced payment cannot be edited and returns **422**.
**Reopen consent:** if the edit leaves a previously closed (Paid) case with an outstanding balance, the case is reopened only when `reopenCaseIfNeeded: true`; otherwise the request returns **409 Conflict**.
### Path parameters
- `id` (uuid, required):
- `paymentId` (uuid, required):
### Request body (application/json)
- `date` (datetime, required): Payment date (when payment was received). Provide date only without time component.
- `paymentAmount` (number, required): Total payment amount received.
When both PayoutCreditor and PayoutCollectionPartner are supplied they must sum to this amount.
When both are omitted, the split is computed server-side from the case's pricing terms.
Min 0.01.
- `payoutCreditor` (number, nullable): Amount to be paid out to creditor. **Optional.**
When omitted (along with PayoutCollectionPartner), the split is computed server-side from the
case's pricing terms (success fee). When supplied, PayoutCollectionPartner must also be supplied
and the two must sum to PaymentAmount.
Min 0.
- `payoutCollectionPartner` (number, nullable): Amount to be kept by collection partner (commission). **Optional.**
When omitted (along with PayoutCreditor), the split is computed server-side from the
case's pricing terms (success fee). When supplied, PayoutCreditor must also be supplied
and the two must sum to PaymentAmount.
Min 0.
- `paymentRecipient` (string, required): Who received the payment.
**Valid values:**
- **Creditor**: Payment was received by the creditor (client). When used, you must also specify CommissionPaymentStatus.
- **CollectionPartner**: Payment was received by the collection partner. Commission is automatically marked as paid.
- `commissionPaymentStatus` (string, nullable): Commission payment status. **Required only if PaymentRecipient is Creditor.**
When PaymentRecipient is CollectionPartner, this field is ignored and commission is automatically marked as Paid.
**Valid values:** Paid, Unpaid.
- `reopenCaseIfNeeded` (boolean): Consent to reopen the case if this edit lowers the payment so a previously closed (Paid)
case is left with a positive outstanding balance.
When the edit would reopen the case and this flag is `false` (default), the request is
rejected with HTTP 409 Conflict. Resend with `true` to confirm the reopen — the case is
reopened to Active and a `case.updated` webhook fires.
```json
{
"date": "2025-11-19",
"paymentAmount": 5000,
"payoutCreditor": 4000,
"payoutCollectionPartner": 1000,
"paymentRecipient": "Creditor",
"commissionPaymentStatus": "Paid",
"reopenCaseIfNeeded": false
}
```
### Response 200
Payment updated successfully
- `id` (uuid):
- `dateCreated` (datetime):
- `dateUpdated` (datetime, nullable):
- `date` (datetime):
- `grossAmount` (number):
- `recipient` (string, required, nullable):
- `method` (string, required, nullable):
- `currency` (string, required, nullable):
- `invoice` (object, required):
- `invoice.status` (string, required, nullable):
- `invoice.reference` (string, required, nullable):
- `invoice.invoiceId` (uuid):
```json
{
"id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"dateCreated": "2026-10-01T14:05:00Z",
"dateUpdated": "2026-10-01T14:05:00Z",
"date": "2026-10-01T14:05:00Z",
"grossAmount": 2500,
"recipient": "string",
"method": "string",
"currency": "EUR",
"invoice": {
"status": "string",
"reference": "INV-2026-0042",
"invoiceId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31"
}
}
```
### Response 400
Invalid request or production case
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 404
Case or payment not found / not submitted by you
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 409
Edit would reopen the case; resend with reopenCaseIfNeeded=true
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 422
Payment has already been invoiced and cannot be edited
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 500
Server error
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
## Delete a payment on a test case (managing partner)
`DELETE /managed-cases/{id}/payments/{paymentId}`
Deletes a payment from a test case you submitted as managing partner, reverting its effect on the case balance and cascading the payout deletion. A durable audit record is retained.
**Test-Only Restriction:** only works on cases created with `isTestCase: true`. Production cases return a 400 — the assigned collection partner must delete via `DELETE /cases/{id}/payments/{paymentId}`.
**Invoiced payments are frozen:** an already-invoiced payment cannot be deleted and returns **422**.
**Reopen consent:** if the deletion leaves a previously closed (Paid) case with an outstanding balance, the case is reopened only when `reopenCaseIfNeeded=true`; otherwise the request returns **409 Conflict**.
### Path parameters
- `id` (uuid, required):
- `paymentId` (uuid, required):
### Query parameters
- `reopenCaseIfNeeded` (boolean):
### Response 204
Payment deleted successfully
### Response 400
Invalid request or production case
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 404
Case or payment not found / not submitted by you
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 409
Deletion would reopen the case; resend with reopenCaseIfNeeded=true
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 422
Payment has already been invoiced and cannot be deleted
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 500
Server error
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
## Get managed case files
`GET /managed-cases/{id}/files`
Returns all documents and files attached to a case you submitted as managing partner.
**File Access for Managing Partners:**
You can view files uploaded by:
- Your client (the creditor you represent)
- The collection partner handling the case
- Debitura support team
- Yourself (files you uploaded when submitting the case)
**File Types Include:**
- OriginalInvoice - The initial claim documentation
- ProofOfDelivery - Delivery confirmations
- Contract - Agreements between creditor and debtor
- Correspondence - Email and letter communications
- PaymentProof - Payment receipts
- CourtDocuments - Legal filings
- Other - Miscellaneous supporting documents
**Use Case:**
- Review evidence and supporting documents
- Download files to share with your client
- Verify document completeness before escalation
- Build client-facing portals showing case documentation
**Note:** File URLs are temporary signed links that expire. Call this endpoint again to generate fresh download links if needed.
Upload additional ordinary case documents with `POST /managed-cases/{id}/files`.
### Path parameters
- `id` (uuid, required):
### Response 200
Files retrieved successfully (may be empty array)
- `id` (uuid):
- `dateCreated` (datetime):
- `dateUpdated` (datetime):
- `caseId` (uuid):
- `entityType` (string, nullable):
- `entityId` (uuid):
- `fileName` (string, nullable):
- `url` (string, nullable):
- `description` (string, nullable):
- `documentType` (string, nullable):
```json
[
{
"id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"dateCreated": "2026-10-01T14:05:00Z",
"dateUpdated": "2026-10-01T14:05:00Z",
"caseId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"entityType": "string",
"entityId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"fileName": "Muster GmbH",
"url": "https://app.debitura.com/…",
"description": "string",
"documentType": "string"
}
]
```
### Response 400
Case ID missing or empty
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 404
Case not found or not submitted by you as managing partner
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 500
Server error occurred while retrieving files
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
## Upload a file to a managed case
`POST /managed-cases/{id}/files`
Uploads one ordinary case document to a case you submitted as managing partner.
**Access:** The authenticated partner must match the case's managing partner. This is separate from the collecting-partner upload route.
**Status gate:** Allowed on every lifecycle except Merged, including Closed.
**File requirements:** Maximum 25 MB. Allowed filename extensions are `.pdf` `.doc` `.docx` `.xls` `.xlsx` `.jpg` `.jpeg` `.png` `.txt` `.zip` `.csv` `.eml`.
**Optional fields:** `Description` is limited to 500 characters.
`DocumentType` is case-insensitive. Omit it when the type is unknown; the file is stored as not specified and returned as `null`.
Valid values: OriginalInvoice, AccountStatement, Contract, TermsAndConditions, ProofOfDelivery, DemandLetter,
Correspondence, PaymentProof, CourtDocument, IdentityDocument, Miscellaneous.
Legacy names remain accepted for existing integrations: DebtorDocuments, CreditorDocuments, PartnerDocuments.
Unknown names, numeric values, and AutoGeneratedSummary are rejected with 400 and error InvalidDocumentType.
Use `Idempotency-Key` to retry safely. An identical replay returns the original response. Separate uploads with the same filename are stored independently and cannot overwrite one another.
### Path parameters
- `id` (uuid, required):
### Headers
- `Idempotency-Key` (string): Optional non-empty, non-whitespace idempotency key (max 255 characters) for safely retrying this request. If a previous request used the same key with an identical body, the original terminal response is replayed verbatim. Reusing the key with a different body returns 422 with `businessErrors[0].type: "IdempotencyConflict"`. Field-level 400 validation errors are not stored, so you may fix the request and retry with the same key.
Max 255 characters.
### Request body (multipart/form-data)
- `File` (file): The file to upload. Required.
Allowed extensions: .pdf .doc .docx .xls .xlsx .jpg .jpeg .png .txt .zip .csv .eml
Maximum size: 25 MB.
- `DocumentType` (string): Optional document type, case-insensitive. Omit (or pass null) when you do not know it; the file is then stored as not specified.
Valid values: OriginalInvoice, AccountStatement, Contract, TermsAndConditions, ProofOfDelivery, DemandLetter,
Correspondence, PaymentProof, CourtDocument, IdentityDocument, Miscellaneous.
Still accepted for existing integrations: DebtorDocuments, CreditorDocuments, PartnerDocuments.
Any other value is rejected with 400 and error "InvalidDocumentType".
- `Description` (string): Optional free-text description / label for the file (max 500 characters).
### Response 200
File uploaded successfully
- `id` (uuid):
- `dateCreated` (datetime):
- `dateUpdated` (datetime):
- `caseId` (uuid):
- `entityType` (string, nullable):
- `entityId` (uuid):
- `fileName` (string, nullable):
- `url` (string, nullable):
- `description` (string, nullable):
- `documentType` (string, nullable):
```json
{
"id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"dateCreated": "2026-10-01T14:05:00Z",
"dateUpdated": "2026-10-01T14:05:00Z",
"caseId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"entityType": "string",
"entityId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
"fileName": "Muster GmbH",
"url": "https://app.debitura.com/…",
"description": "string",
"documentType": "string"
}
```
### Response 400
Missing file or invalid request
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 404
Case not found or not managed by this partner
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 409
Case is merged or idempotent request is in progress
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 413
File exceeds 25 MB
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 415
Unsupported file extension
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 422
Idempotency-Key reused with a different request
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```
### Response 500
Internal server error
- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this specific error (e.g., sign a contract).
Partners who want a single URL that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.
```json
{
"error": null,
"message": "Payment plan agreed with the debtor.",
"businessErrors": [
{
"type": "string",
"message": "Payment plan agreed with the debtor.",
"solutionUrl": "https://app.debitura.com/…"
}
]
}
```