Source: https://docs.debitura.com/api/collection-partner-api/cases

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

<a id="list-collection-cases"></a>

## List collection cases.

`GET /cases`

Returns a paginated list of cases where you are the **collection partner** (actively collecting the debt).

**What is a Collection Partner?**
A collection partner is an agency or law firm that performs the actual debt recovery work. When you appear as the collection partner on a case, you are responsible for:
- Contacting the debtor and attempting recovery
- Managing the case lifecycle and status updates
- Recording payments and fees
- Uploading documents and evidence
- Communicating with the creditor through the case chat

**Note:** This endpoint shows cases where you are collecting. For cases you submitted on behalf of your own clients (where you are the managing partner), use the `/managed-cases` endpoint instead.

**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: PendingVerification, NeedsAdditionalDetails, Leads, LeadsQuoteGiven, Active, Paused, Closed
  **Note:** Partner-specific statuses only. Internal platform statuses like 'PendingContractSigning' or 'PendingVerificationInternal' are not available here — cases in those stages are hidden from every collection-partner-facing endpoint until Debitura's internal verification clears, regardless of assignment.
- divisionIds - Filter by creditor division IDs (comma-separated GUIDs)
- debtorIds - Filter by specific debtor IDs (comma-separated GUIDs)
- ids - Filter by specific case IDs (comma-separated GUIDs)
- includeTestCases - When true, includes test/demo cases owned by the caller. Defaults to false.

**Sorting:**
- Additional case sort fields: PaymentTotalSum, CurrentPhase, CollectionPartner, Jurisdiction,
  ManagedByPartner, CreditorDivision, AssignedCollectorUser, AssignedCreditorUser,
  AssignedManagingPartnerUser, ReferralPartner. Names and phase refer to the values visible to your firm,
  including frozen withdrawal records. Unknown keys return HTTP 400; tied values use stable case/withdrawal IDs.
- sort - Sort field and direction (format: 'field:direction')
  Examples: 'date:desc', 'amount:asc', 'debtorName:asc'

**Response:**
- Returns InvoiceListApiDTO with page metadata and cases array
- 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.
- `includeTestCases` (boolean): When true, includes test/demo cases where the caller is the owner (either as collection partner
or as managing partner). Defaults to false.

### 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="fetch-case-by-id"></a>

## Fetch case by ID

`GET /cases/{id}`

Returns detailed case information for a specific case ID (GUID).

**Access Control:**
Only returns cases where you are the collection partner, or test/demo cases where you are the managing partner. For managed production cases, use `/managed-cases/{id}` instead.

**Response Includes:**
- Case details (reference, amount, currency, status, lifecycle stage)
- Debtor information (name, address, contact details, company/private type)
- Creditor information
- Collection partner assignment details
- Financial breakdown (principal, interest, fees)
- Important dates (creation, assignment, due dates)
- Geographic information (jurisdiction, country)

### 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 assigned to you as collection 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="fetch-case-by-reference"></a>

## Fetch case by reference

`GET /cases/case-reference/{caseReference}`

Returns detailed case information using the Debitura case reference (e.g., 'Q8OAXF3W').

**Use Case:**
Use this endpoint when you have the Debitura case reference (visible in the partner portal and emails) but not the GUID. This is helpful for customer service integrations or when referencing cases in communications.

**Access Control:**
Only returns cases where you are the collection partner, or test/demo cases where you are the managing partner. For managed production cases, use `/managed-cases/case-reference/{reference}`.

### 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 assigned to you as collection 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="fetch-a-single-case-by-the-collection-partner-s-own-reference-id"></a>

## Fetch a single case by the collection partner's own reference ID.

`GET /cases/by-partner-reference/{reference}`

Returns detailed case information using the collection partner's own reference (the `CollectionPartnerReference` field set during case activation).

**Use Case:**
Use this endpoint when you have your own internal case reference and want to look up the corresponding Debitura case. This is useful for integrating your case management system with Debitura.

**Matching:**
Exact string match only. Combined references like '112179442 & 112179443' must be queried with the full combined string.

**Access Control:**
Only returns cases where you are the collection partner and the case is a production collection case.

### Path parameters

- `reference` (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 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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

No case found with this partner reference

- `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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="batch-lookup-of-cases-by-the-collection-partner-s-own-reference"></a>

## Batch lookup of cases by the collection partner's own reference IDs.

`GET /cases/by-partner-reference`

Returns a dictionary mapping each partner reference to its corresponding case details.

**Use Case:**
Use this endpoint to look up multiple cases at once using your own internal reference IDs. This is more efficient than making individual calls for each reference.

**Parameters:**
- references (required) - Comma-separated list of partner reference strings (max 100)

**Matching:**
Exact string match only. References not found or not assigned to you are omitted from the response (no error).

**Response:**
A dictionary where keys are the partner reference strings and values are the case details. Missing references are silently omitted.

### Query parameters

- `references` (string): 

### Response 200

Dictionary of reference to case

```json
{}
```

### Response 400

References parameter missing, empty, or exceeds maximum

- `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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="fetch-a-single-case-by-creditor-reference-scoped-to-a-specific-c"></a>

## Fetch a single case by creditor reference, scoped to a specific creditor and partner.

`GET /cases/by-creditor-reference`

Returns detailed case information using the creditor's own reference (`CreditorReference`) scoped to a specific creditor.

**Use Case:**
Use this endpoint when you have the creditor's reference (e.g. from an invoice file or payment import) and need to look up the corresponding Debitura case. Because `CreditorReference` is only unique within a single creditor, you must also supply `creditorId` to make the lookup unambiguous.

**Matching:**
Exact string match on `CreditorReference`. The case must also belong to the specified creditor and be assigned to the calling partner.

**Access Control:**
Only returns production collection cases where you are the collection partner. The `creditorId` parameter scopes the lookup to a specific creditor — you can only retrieve cases for creditors whose cases are assigned to you.

### Query parameters

- `reference` (string): 
- `creditorId` (uuid): 

### 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 or creditorId 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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

No case found for this reference + creditor combination, or not assigned to 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="fetch-case-timeline"></a>

## Fetch case timeline

`GET /cases/{id}/timeline`

Returns the complete chronological event history for a case along with the current engagement phase.

**Timeline Events Include:**
- Case assignment to collection partner
- Status changes and lifecycle transitions
- Payment recordings
- Document uploads
- Communication events
- Fee additions
- Manual updates and notes
- System-generated events

**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, understand case history, audit actions, or display activity to users. Timeline events are ordered chronologically and include timestamps, event types, titles, and descriptions.

**Note:** Timeline is filtered to show partner-relevant events only.

### 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 assigned to you as collection 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="fetch-case-chats"></a>

## Fetch case chats

`GET /cases/{id}/chats`

Returns all chat messages for a case in chronological order.

**Chat Participants:**
- Collection partner (you) - Messages from your team
- Creditor - Messages from the client who owns the debt
- Debitura support - System notifications and support messages
- Managing partner (if applicable) - Messages from the partner who submitted the case

**Message Details Include:**
- Message content and timestamp
- Sender information (name, role)
- Message type (text, system notification, file attachment reference)
- Read status and delivery information

**Use Case:**
Use this endpoint to build case communication interfaces, retrieve conversation history, or integrate case discussions into your systems. Perfect for customer service tools or partner portals.

**Availability:** Cases awaiting Debitura approval or contract signing are not available to collection partners, even if a partner has already been assigned.

**Note:** If the case has no thread or messages, an empty array is returned.

### 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 assigned to you as collection 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="send-a-chat-message-on-a-case"></a>

## Send a chat message on a case

`POST /cases/{id}/chats`

Posts a new chat message on a case, visible to both the collection partner and the creditor.

**Message Details:**
- The message is attributed to the team member identified by `userId`
- The creditor will receive an email notification about the new message
- A task is created in the Debitura platform for the creditor to review the message
- Messages appear in the case chat timeline in chronological order

**Prerequisites:**
- The case must exist and be assigned to you as collection partner
- The case must have passed Debitura approval and contract signing
- For a test or demo managed case, the managing partner may save case context during review
- The `userId` must be a valid user ID from `GET /users` belonging to your team

**Use Case:**
Use this endpoint to communicate with creditors about case progress, request additional information, or provide status updates. Messages sent via this endpoint are equivalent to messages sent through the partner portal chat.

### Path parameters

- `id` (uuid, required): 

### Headers

- `Idempotency-Key` (string): Optional idempotency key (max 255 characters). If the same key is reused with an identical message body within 24 hours, the originally created chat message is returned instead of posting a duplicate. The key is scoped per partner, case, and message body — reusing it with a different body posts a new message rather than returning a conflict.
  Max 255 characters.

### Request body (application/json)

- `message` (string, required): The chat message content to send.
  Max 10000 characters.
- `userId` (uuid, nullable, deprecated): ID of the team member sending this message.
Must be a valid user ID from GET /users belonging to your team.
Deprecated: use UserEmail instead. At least one of UserId or UserEmail must be provided.
- `userEmail` (string, nullable): Email address of the team member sending this message.
Must correspond to an active member of your team (same account as the API key).
Preferred over UserId. At least one of UserEmail or UserId must be provided.
  Email address.

```json
{
  "message": "Please provide the signed contract for this case.",
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "userEmail": "john.doe@example.com"
}
```

### Response 200

Chat message sent successfully (or duplicate idempotency key — existing response returned)

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

Validation error — missing fields, invalid userId, or invalid request body

- `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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 assigned to this collection 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="fetch-case-payments"></a>

## Fetch case payments

`GET /cases/{id}/payments`

Returns all payments recorded on a specific case.

**Payment Information Includes:**
- Payment amount and currency
- Payment date (when received)
- Payment type (full payment, partial payment, settlement)
- Payment method (bank transfer, card, cash, etc.)
- Payment status (pending, confirmed, reconciled)
- Reference information
- Allocation breakdown (principal, interest, fees)

**Use Case:**
Use this endpoint to:
- Track payment history for a case
- Reconcile payments with your records
- Display payment status to users
- Calculate outstanding balances
- Generate financial reports

**Note:** Only payments associated with this specific case are returned. All payments are returned in reverse chronological order (newest first).

### 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 assigned to you as collection 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="create-a-payment-on-a-case"></a>

## Create a payment on a case

`POST /cases/{id}/payments`

Records a payment received for a collection case.

**Use Case:**
Use this endpoint when you receive a payment from the debtor. Provide the payment amount and, in the normal case, nothing else for the split — **omit both PayoutCreditor and PayoutCollectionPartner** and Debitura computes the creditor/partner split server-side from the case's pricing terms (success fee). This is the default and recommended usage for almost every integration.

**Advanced override — PayoutCreditor / PayoutCollectionPartner:**
Supplying both fields lets you dictate the split explicitly instead of using the computed one. This is an **advanced, opt-in override** for legitimate edge cases (e.g. a negotiated split where the collection partner already holds funds) — it is not the normal path and most integrations should never set it. When supplied:
- Both fields are required together, and MUST sum to PaymentAmount (within 0.01 tolerance).
- The response's `Warnings` array surfaces (without blocking the request) if the split allocates zero to the creditor, or if the case had no outstanding balance before this payment — both are signs of a misconfigured or duplicate payment and should be reviewed.

**Currency:** Payment must be in the same currency as the invoice. The currency is automatically determined from the case.

**PaymentRecipient Options:**
- **Creditor** - Payment was received by the creditor (your client). When using this option, you MUST also specify CommissionPaymentStatus.
- **CollectionPartner** - Payment was received by you (the collection partner). Commission is automatically marked as Paid since you already have the funds.

**CommissionPaymentStatus:**
This field tracks whether the collection partner's commission has been paid. It's only required when PaymentRecipient is 'Creditor'.
- **Paid** - The creditor has already paid your commission
- **Unpaid** - The creditor has not yet paid your commission

Note: When PaymentRecipient is 'CollectionPartner', this field is automatically set to 'Paid' since you already have the money.

**Critical Validation:**
- PayoutCreditor and PayoutCollectionPartner are optional but must be supplied together. When supplied, they MUST equal PaymentAmount (within 0.01 tolerance). When omitted (recommended), the split is computed from the case terms.
- An explicit split that zeroes the creditor, or that is supplied on an already-settled (zero-remainder) case, is accepted but surfaced as a warning in the response — not blocked.
- CommissionPaymentStatus is required only if PaymentRecipient is 'Creditor'

**Payment Flow:**
1. Full Payment (payment >= outstanding):
   - If CloseCase=true → closes case with 'Paid' status
   - If CloseCase=false → case remains open

2. Partial Payment (payment < outstanding):
   - The payment is recorded regardless of CloseCase. The case is NOT closed (CloseCase is honoured only when the payment fully settles the balance) and no error is returned.
   - To close on a partial payment, use the close endpoint with the PartiallyPaid close code.

### 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 (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 — omit by default.**
            
Normal usage is to leave this (and PayoutCollectionPartner) unset: the split is then computed
server-side from the case's pricing terms (success fee), which is correct for almost every
integration. Setting this is an **advanced, opt-in override** for legitimate edge cases (e.g. a
negotiated split where the collection partner already holds funds) — most callers should never
need it. When supplied, PayoutCollectionPartner must also be supplied and the two must sum to
PaymentAmount. A zero value here (entire payment routed to the partner), or an explicit split
supplied on a case that already has no outstanding balance, is accepted but surfaced as a
warning in the response (`CreatePaymentResponse.Warnings`) rather than rejected — review
these warnings, as they are signs of a misconfigured or duplicate payment.
  Min 0.
- `payoutCollectionPartner` (number, nullable): Amount to be kept by collection partner (commission). **Optional — omit by default.**
            
Normal usage is to leave this (and PayoutCreditor) unset: the split is then computed
server-side from the case's pricing terms (success fee), which is correct for almost every
integration. Setting this is an **advanced, opt-in override** for legitimate edge cases (e.g. a
negotiated split where the collection partner already holds funds) — most callers should never
need it. When supplied, PayoutCreditor must also be supplied and the two must sum to
PaymentAmount. See PayoutCreditor (above) for the soft-guard warnings this can trigger.
  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.
- **Platform**: Payment was received by Debitura platform. Commission is automatically marked as paid.
- **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 or Platform, this field is ignored and commission is automatically marked as Paid.
            
**Valid values:**
- **Paid**: Commission has been paid to collection partner
- **Unpaid**: Commission has not yet been paid to collection partner
- `closeCase` (boolean): Request to close the case as "Paid" if this payment fully settles the outstanding balance (default: false).
If true and payment >= invoice remainder, the case is closed with "Paid" status.
If true and payment < invoice remainder, the payment is still recorded but the case is left open
(no error). To close a case with a partial payment, use the close endpoint with the PartiallyPaid close code.

```json
{
  "date": "2026-07-31",
  "paymentAmount": 5000,
  "payoutCreditor": 4000,
  "payoutCollectionPartner": 1000,
  "paymentRecipient": "Creditor",
  "commissionPaymentStatus": "Paid",
  "closeCase": false
}
```

### Response 200

Payment created successfully (or duplicate Idempotency-Key — the original response is replayed). Check the Warnings array for non-blocking advisory notices (e.g. about an explicit payout-split override).

- `paymentId` (uuid): 
- `caseReference` (string, required, nullable): 
- `date` (datetime): 
- `paymentAmount` (number): 
- `payoutCreditor` (number): 
- `payoutCollectionPartner` (number): 
- `paymentRecipient` (string, required, nullable): 
- `commissionPaymentStatus` (string, required, nullable): 
- `closeCase` (boolean): 
- `caseClosed` (boolean): 
- `closeCode` (string, nullable): 
- `remainingAmount` (number): 
- `clientCommissionInvoice` (object): Whether and how a commission invoice can be raised for this payment's payout, and the state of the
current one if it exists.
- `clientCommissionInvoice.payoutId` (uuid): 
- `clientCommissionInvoice.paymentId` (uuid): 
- `clientCommissionInvoice.caseId` (uuid): 
- `clientCommissionInvoice.caseReference` (string, nullable): 
- `clientCommissionInvoice.clientId` (uuid): 
- `clientCommissionInvoice.clientName` (string, nullable): 
- `clientCommissionInvoice.flowOwner` (enum): Who settles this payout's commission. ManualSettlement: settled outside commission invoicing.
CommissionInvoice: settled through a commission invoice.
  Values: `ManualSettlement`, `CommissionInvoice`.
- `clientCommissionInvoice.commissionStatus` (string, nullable): 
- `clientCommissionInvoice.paymentRecipient` (string, nullable): 
- `clientCommissionInvoice.recordedCommissionAmount` (number): Commission recorded in Debitura for this payout.
- `clientCommissionInvoice.commissionOutstandingAmount` (number, nullable): Remaining commission after bank reconciliation; null for an ordinary source.
- `clientCommissionInvoice.lockedAmount` (number, deprecated): Deprecated compatibility name for RecordedCommissionAmount. Existing Collection
Partner API integrations may still read this member.
- `clientCommissionInvoice.currencyCode` (string, nullable): 
- `clientCommissionInvoice.currentInvoiceId` (uuid, nullable): 
- `clientCommissionInvoice.currentInvoiceNumber` (string, nullable): 
- `clientCommissionInvoice.origin` (enum, nullable): How the current invoice document was created.
  Values: `Generated`, `Uploaded`, `null`.
- `clientCommissionInvoice.documentState` (enum, nullable): The state of the current invoice document.
  Values: `Draft`, `Issued`, `Voided`, `Superseded`, `null`.
- `clientCommissionInvoice.deliveryState` (enum, nullable): Whether the current invoice has been sent to the client.
  Values: `NotSent`, `Sent`, `Failed`, `null`.
- `clientCommissionInvoice.settlementState` (enum, nullable): Whether the current invoice has been paid.
  Values: `Unpaid`, `Paid`, `Reconciled`, `PartiallyReconciled`, `null`.
- `clientCommissionInvoice.issueDate` (datetime, nullable): 
- `clientCommissionInvoice.dueDate` (datetime, nullable): 
- `clientCommissionInvoice.mayStart` (boolean): 
- `clientCommissionInvoice.ineligibilityCode` (enum, nullable): Why a commission invoice cannot be raised for this payout. NotEnabled: commission invoicing is not
enabled. HandledOutsideInvoicing: this payout's commission is settled outside commission invoicing.
NoClientRelationship: no commission-invoicing relationship exists with this client. PaymentNotToClient:
the payment was not made to the client. CommissionAlreadySettled: the commission is already paid or
credited. NotEligible: not eligible for another reason.
  Values: `NotEnabled`, `HandledOutsideInvoicing`, `NoClientRelationship`, `PaymentNotToClient`, `CommissionAlreadySettled`, `NotEligible`, `null`.
- `clientCommissionInvoice.allowedActions` (array of enums, nullable): An action currently available on this payout's commission invoice.
  Values: `Download`, `Issue`, `MarkPaid`, `Void`, `Correct`, `Send`, `RetrySend`, `CreateGenerated`, `CreateUploaded`, `View`, `ReplaceDocument`.
- `warnings` (array of strings, nullable): Non-blocking warnings about this payment. Always present (empty when there is nothing to flag).
Currently populated only when an explicit PayoutCreditor/PayoutCollectionPartner override was
supplied and (a) it allocates zero to the creditor, or (b) the case already had no outstanding
balance before this payment — both are signs of a misconfigured or duplicate payment. The
payment is still recorded; these are advisory only, not errors. Review and resolve out of band
if unexpected (e.g. via the case's Payments view in the Partner Portal, or by contacting
Debitura support).

```json
{
  "paymentId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "caseReference": "INV-2026-0042",
  "date": "2026-10-01T14:05:00Z",
  "paymentAmount": 2500,
  "payoutCreditor": 1.5,
  "payoutCollectionPartner": 1.5,
  "paymentRecipient": "string",
  "commissionPaymentStatus": "string",
  "closeCase": true,
  "caseClosed": true,
  "closeCode": "string",
  "remainingAmount": 2500,
  "clientCommissionInvoice": {
    "payoutId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
    "paymentId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
    "caseId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
    "caseReference": "INV-2026-0042",
    "clientId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
    "clientName": "Muster GmbH",
    "flowOwner": "ManualSettlement",
    "commissionStatus": "string",
    "paymentRecipient": "string",
    "recordedCommissionAmount": 2500,
    "commissionOutstandingAmount": 2500,
    "lockedAmount": 2500,
    "currencyCode": "EUR",
    "currentInvoiceId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
    "currentInvoiceNumber": "string",
    "origin": "Generated",
    "documentState": "Draft",
    "deliveryState": "NotSent",
    "settlementState": "Unpaid",
    "issueDate": "2026-10-01T14:05:00Z",
    "dueDate": "2026-10-01T14:05:00Z",
    "mayStart": true,
    "ineligibilityCode": "NotEnabled",
    "allowedActions": [
      "Download"
    ]
  },
  "warnings": [
    "string"
  ]
}
```

### Response 400

Invalid request (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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 assigned to 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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

A request with this Idempotency-Key is already in progress. Retry after the indicated delay.

- `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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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

The Idempotency-Key has already been used with a different request body.

- `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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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

- `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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="get-case-files"></a>

## Get case files

`GET /cases/{id}/files`

Returns all documents and files attached to a case.

**Document type:** `documentType` holds the same values the upload endpoint accepts for `DocumentType`,
`AutoGeneratedSummary` for a summary the platform generated, or `null` when the uploader did not specify a type.

**File Information Includes:**
- File ID and case ID
- File name and description/label
- Document type classification
- Upload timestamps (created, updated)
- Download URL (temporary, signed link)
- File metadata

**Use Case:**
Use this endpoint to:
- Retrieve evidence and supporting documents
- Display case files in partner portals
- Download documents for offline review
- Build document management interfaces
- Audit document completeness

**Note:** File URLs are temporary signed links that expire after a period. Generate new URLs by calling this endpoint again if links expire.

### 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 assigned to you as collection 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="upload-a-file-to-a-case"></a>

## Upload a file to a case

`POST /cases/{id}/files`

Uploads a file and attaches it to a case. Mirrors the file upload action available in the Partner portal.

**Access:** Collection partners only. Managing partners are rejected.

**Status gate:** Allowed on all non-Merged statuses, including Closed. Only Merged cases are rejected.

**File requirements:**
- Maximum size: 25 MB
- Allowed extensions: `.pdf` `.doc` `.docx` `.xls` `.xlsx` `.jpg` `.jpeg` `.png` `.txt` `.zip` `.csv` `.eml`

**DocumentType (optional):**
Omit it when the type is unknown; the file is stored as not specified and returned as `null`.
Values are case-insensitive: 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.

The file is immediately visible to the creditor.

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

Invalid request — missing file, unsupported extension, or request validation 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 assigned to this collection 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 and cannot accept new 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 the 25 MB size limit

- `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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="create-a-note-on-a-case"></a>

## Create a note on a case

`POST /cases/{id}/notes`

Creates a new note/comment on a collection case.

**Use Case:**
Use this endpoint to document activities, record conversations, add reminders, or log any relevant information about the case. Notes are automatically shared with the creditor.

**Validation:**
- Description is required (max 10000 characters)
- EventDate must not be in the future (if provided)

**EventDate:**
Supply EventDate to back-date the note to the time the event actually occurred. For example, if a phone call happened three days ago, pass that date so the timeline reflects the real event order. Omit for real-time notes.

### Path parameters

- `id` (uuid, required): 

### Request body (application/json)

- `description` (string, required): Note content
  Max 10000 characters.
- `eventDate` (datetime, nullable): The date when the event actually occurred. Must not be in the future.
When provided, the note will appear at this date in the timeline instead of the upload time.
This is useful for importing historical events (e.g. a phone call that happened last week).
Omit or set to null to use the current time (default behaviour).

```json
{
  "description": "Called debtor on 2025-11-19. They acknowledged the debt and promised to pay within 7 days. Will follow up on 2025-11-26.",
  "eventDate": "2025-11-14T09:30:00Z"
}
```

### Response 200

Note created successfully

- `id` (uuid): 
- `caseReference` (string, required, nullable): 
- `title` (string, required, nullable): 
- `description` (string, nullable): 
- `visibility` (string, required, nullable): 
- `createdAt` (datetime): 
- `eventDate` (datetime, nullable): The event date provided at creation time. Null if no EventDate was supplied,
meaning the note was recorded in real-time (CreatedAt reflects the actual event time).
- `createdBy` (object): 
- `createdBy.userId` (integer): 
- `createdBy.userName` (string, required, nullable): 

```json
{
  "id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "caseReference": "INV-2026-0042",
  "title": "string",
  "description": "string",
  "visibility": "string",
  "createdAt": "2026-10-01T14:05:00Z",
  "eventDate": "2026-10-01T14:05:00Z",
  "createdBy": {
    "userId": 3,
    "userName": "Muster GmbH"
  }
}
```

### Response 400

Invalid request (missing required fields, EventDate in the future, or 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 assigned to 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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

- `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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="edit-a-payment-on-a-case"></a>

## Edit a payment on a case

`PUT /cases/{id}/payments/{paymentId}`

Edits an existing payment on a collection case. Mirrors the payout-split semantics of the create-payment endpoint.

**Payout Split:** supply both PayoutCreditor and PayoutCollectionPartner to set the split explicitly (they must sum to PaymentAmount), or omit both to have it recomputed from the case's pricing terms.

**Invoiced payments are frozen:** a payment whose payout has already been invoiced (Stripe/QBO) cannot be edited and returns **422 Unprocessable Entity**. This protects the issued accounting entry from silent drift.

**Reopen consent:** if the edit lowers the payment so a previously closed (Paid) case is left with a positive outstanding balance, the case must be reopened. By default this returns **409 Conflict**; resend with `reopenCaseIfNeeded: true` to confirm — the case is reopened to Active and a `case.updated` webhook fires.

### 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 (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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 assigned to 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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

- `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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="delete-a-payment-on-a-case"></a>

## Delete a payment on a case

`DELETE /cases/{id}/payments/{paymentId}`

Deletes a payment from a collection case, reverting its effect on the case balance and cascading the payout deletion. A durable audit record of the deletion is retained.

**Invoiced payments are frozen:** a payment whose payout has already been invoiced (Stripe/QBO) cannot be deleted and returns **422 Unprocessable Entity**.

**Reopen consent:** if deleting the payment leaves a previously closed (Paid) case with a positive outstanding balance, the case must be reopened. By default this returns **409 Conflict**; resend with `reopenCaseIfNeeded=true` to confirm — the case is reopened to Active and a `case.updated` webhook fires.

### Path parameters

- `id` (uuid, required): 
- `paymentId` (uuid, required): 

### Query parameters

- `reopenCaseIfNeeded` (boolean): 

### Response 204

Payment deleted successfully

### Response 400

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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 assigned to 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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

- `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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="close-a-case"></a>

## Close a case

`POST /cases/{id}/close`

Closes a collection case with a specified close code.

**Use Case:**
Use this endpoint to formally close a case when collection is complete or cannot continue. The close code determines the reason and impacts reporting.

**Close Code Validation:**
- **Paid**: Requires at least one payment AND total payments >= outstanding amount
- **PartiallyPaid**: Requires at least one payment AND total payments < outstanding amount
- **All other codes**: No payment requirements

**Valid Close Codes:**
- **Paid** - Full payment received from debtor
- **PartiallyPaid** - Some payment received but not full amount
- **DebtorInsolventBankrupt** - Debtor declared bankruptcy or insolvent
- **DebtorUntraceable** - Unable to locate or contact debtor
- **DisputedLegalActionDeclinedByClient** - Debt disputed, creditor declined legal action
- **WithdrawnByClient** - Creditor requested case withdrawal
- **PreLegalExhaustedNoPayment** - All pre-legal attempts exhausted without payment
- **StatuteOfLimitationsExpired** - Legal time limit to collect has passed
- **SettlementRejectedByClient** - Proposed settlement rejected by creditor
- **UnresponsiveClient** - Creditor not responding to collection partner
- **UneconomicalToPursue** - Continued collection is not economically justified
- **Other** - Other reason (please provide comment)

### Path parameters

- `id` (uuid, required): 

### Request body (application/json)

- `closeCode` (string, required): Close code/reason for closing the case.
            
**Valid close codes:**
- **Paid**: Full payment received from debtor
- **PartiallyPaid**: Some payment received but not full amount
- **DebtorInsolventBankrupt**: Debtor declared bankruptcy or insolvent
- **DebtorUntraceable**: Unable to locate or contact debtor
- **DisputedLegalActionDeclinedByClient**: Debt disputed, creditor declined legal action
- **WithdrawnByClient**: Creditor requested case withdrawal
- **PreLegalExhaustedNoPayment**: All pre-legal attempts exhausted without payment
- **StatuteOfLimitationsExpired**: Legal time limit to collect has passed
- **SettlementRejectedByClient**: Proposed settlement rejected by creditor
- **UnresponsiveClient**: Creditor not responding to collection partner
- **UneconomicalToPursue**: Recovery cost exceeds claim value
- **Other**: Other reason (please provide comment)
- `comment` (string, nullable): Optional comment explaining the closure (recommended for 'Other' close code)
  Max 2000 characters.

```json
{
  "closeCode": "Paid",
  "comment": "Case closed after full payment received via bank transfer on 2025-11-19"
}
```

### Response 200

Case closed successfully

- `caseReference` (string, required, nullable): 
- `closeCode` (string, required, nullable): 
- `closeCodeDescription` (string, required, nullable): 
- `comment` (string, nullable): 
- `closedAt` (datetime): 
- `closedBy` (object): 
- `closedBy.userId` (integer): 
- `closedBy.userName` (string, required, nullable): 
- `finalOutstandingAmount` (number): 
- `totalPayments` (number): 
- `totalRecovered` (number): 

```json
{
  "caseReference": "INV-2026-0042",
  "closeCode": "string",
  "closeCodeDescription": "string",
  "comment": "Payment plan agreed with the debtor.",
  "closedAt": "2026-10-01T14:05:00Z",
  "closedBy": {
    "userId": 3,
    "userName": "Muster GmbH"
  },
  "finalOutstandingAmount": 2500,
  "totalPayments": 2500,
  "totalRecovered": 2500
}
```

### Response 400

Invalid request (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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 assigned to 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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

- `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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="activate-a-case-from-pendingverification"></a>

## Activate a case from PendingVerification

`POST /cases/{id}/start`

Transitions a case from `PendingVerification` → `Active`, officially accepting it for debt collection.

**Prerequisites:**
- The case must be in `PendingVerification` status (returns 400 otherwise)
- The case must not require custom terms (non-standard agreement). Cases outside the standard pre-legal scope — where the claim type is not an unpaid invoice or loan repayment, or where a dispute exists — require negotiation in the partner portal and cannot be activated via this API (returns 400 with a descriptive error).
- The `userId` must be a valid user ID from `GET /users` belonging to your team (returns 400 if not found)
- The `assignedUserId`, if provided, must also be a valid user ID from `GET /users` belonging to your team (returns 400 if not found)

**What happens on activation:**
1. Case lifecycle transitions to Active
2. A welcome message is sent to the creditor via email notification, attributed to the user identified by `userId`
3. The welcome message is posted as a chat message in the case thread, attributed to the user identified by `userId`
4. Any pending verification tasks are automatically resolved

**Fee fields:**
The `interestFees`, `reminderFees`, and `collectionFees` fields update the corresponding fee amounts on the case, in the case currency. Default to 0.00 if not provided.

**userId vs assignedUserId:**
`userId` is required and identifies who is sending the welcome message (the actor). `assignedUserId` is optional and identifies who the case is assigned to for ongoing handling. They can be the same person or different team members. Use `GET /users` to retrieve valid user IDs.

### Path parameters

- `id` (uuid, required): 

### Request body (application/json)

- `welcomeMessage` (string, required): Welcome message sent to the creditor upon case activation.
This message is included in the email notification sent to the creditor and posted in the case chat.
  Max 5000 characters.
- `userId` (uuid, nullable, deprecated): ID of the team member who is sending this welcome message and activating the case.
Used to attribute the chat message and email communication.
Must be a valid user ID from GET /users. Returns 400 if the user is not found in your team.
Deprecated: use UserEmail instead. At least one of UserId or UserEmail must be provided.
- `userEmail` (string, nullable): Email address of the team member who is sending this welcome message and activating the case.
Must correspond to an active member of your team.
Preferred over UserId. At least one of UserEmail or UserId must be provided.
  Email address.
- `collectionPartnerReference` (string, nullable): Your internal reference number for this case (optional).
Stored on the case and visible in the partner portal.
  Max 128 characters.
- `assignedUserId` (uuid, nullable, deprecated): ID of the team member to assign as the case handler (optional).
Can be the same as UserId or a different team member.
Must be a valid user ID from GET /users. Returns 400 if the user is not found in your team.
Deprecated: use AssignedUserEmail instead.
- `assignedUserEmail` (string, nullable): Email address of the team member to assign as the case handler (optional).
Must correspond to an active member of your team.
Preferred over AssignedUserId.
  Email address.
- `interestFees` (number): Interest fees on this case, in the case currency. Defaults to 0.00 if not provided.
  Min 0.
- `reminderFees` (number): Reminder fees on this case, in the case currency. Defaults to 0.00 if not provided.
  Min 0.
- `collectionFees` (number): Collection fees on this case, in the case currency. Defaults to 0.00 if not provided.
  Min 0.

```json
{
  "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "welcomeMessage": "We have received your case and will begin collection proceedings. You will receive regular updates on progress.",
  "collectionPartnerReference": "GET-2025-0042",
  "assignedUserId": null,
  "interestFees": 0,
  "reminderFees": 100,
  "collectionFees": 0
}
```

### Response 200

Case activated successfully

- `caseId` (uuid): The case ID.
- `caseReference` (string, nullable): The Debitura case reference (e.g. 'Q8OAXF3W').
- `status` (string, nullable): The new lifecycle status of the case.
- `activatedAt` (datetime): UTC timestamp when the case was activated.
- `collectionPartnerReference` (string, nullable): Your internal reference number for this case, if provided.

```json
{
  "caseId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "caseReference": "INV-2026-0042",
  "status": "string",
  "activatedAt": "2026-10-01T14:05:00Z",
  "collectionPartnerReference": "INV-2026-0042"
}
```

### Response 400

Validation error — case not in PendingVerification, requires custom terms, invalid assignedUserId, or invalid request body

- `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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 assigned to this collection 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="update-case-fees-and-or-principal"></a>

## Update case fees and/or principal

`PUT /cases/{id}/fees`

Updates the interest, reminder, and collection fees — and optionally the principal (GrossAmount) — on a case.

All provided values replace the current values. The `grossAmount` field is optional and backward-compatible: omitting it leaves the principal unchanged.

Fees typically change over time as collection activity progresses — for example due to legal costs, attorney fees, investigation charges, or other events.

**When `grossAmount` is supplied:**
- Both increases and decreases are allowed (no restriction on direction)
- The pre-legal success fee (commission) is silently recalculated and returned in the response
- The outstanding remainder is recalculated to reflect the new principal
- A timeline audit event is written recording the change (From/To principal and fees)

**Prerequisites:**
- The case must be assigned to this collection partner
- The case must **not** be Closed or Merged (returns 400 otherwise)
- All amounts must be ≥ 0 (negative values rejected)

### Path parameters

- `id` (uuid, required): 

### Request body (application/json)

- `grossAmount` (number, nullable): Principal claim amount (gross amount) in the case currency.
Optional — omit to leave the principal unchanged (fees-only update, backward-compatible).
Both increases and decreases are allowed; must be ≥ 0.
  Min 0.
- `interestFees` (number): Interest fees on this case, in the case currency.
  Min 0.
- `reminderFees` (number): Reminder fees on this case, in the case currency.
  Min 0.
- `collectionFees` (number): Collection fees on this case, in the case currency.
  Min 0.
- `confirmPriceChange` (boolean): The "Change to standard" resolution. When a principal edit on a <em>standard-rate</em> case would
move the success fee by more than 0.1 percentage points (a bracket crossing), the first request
returns HTTP 409 with the proposed old/new rate instead of applying the change. Resubmit the same
request with this set to `true` to confirm and apply the re-price. Leaving it `false`
(the default) on an unaffected edit has no effect.
            
On a case with a deliberately-set rate (an accepted quote or a manual
override), partners can never override a special agreement via this API. Sending this flag on such a
case is REJECTED with HTTP 400 — resubmit with KeepIntentionalRate=`true` to apply
the edit and keep the special rate. Only Debitura can change a special rate.
- `keepIntentionalRate` (boolean): The "Keep special rate" resolution. When the case carries a deliberately-set rate (an accepted
quote or a manual override) that the edit would otherwise prompt about, resubmit with this set to
`true` to apply the edit while preserving the existing rate. On this external Partner API a
special rate is preserve-only: this is the ONLY way to apply an edit to such a case — sending
ConfirmPriceChange instead is rejected with HTTP 400. Ignored for a plain bracket
crossing on a non-intentional rate (use ConfirmPriceChange there).

```json
{
  "grossAmount": 1000,
  "interestFees": 25.5,
  "reminderFees": 10,
  "collectionFees": 50,
  "confirmPriceChange": false,
  "keepIntentionalRate": false
}
```

### Response 200

Fees updated successfully

- `caseId` (uuid): The case ID.
- `grossAmount` (number): Updated principal claim amount (gross amount), in the case currency.
- `interestFees` (number): Updated interest fees, in the case currency.
- `reminderFees` (number): Updated reminder fees, in the case currency.
- `collectionFees` (number): Updated collection fees, in the case currency.
- `totalAddedFees` (number): Sum of all fee types.
- `recalculatedSuccessFee` (number, nullable): Recalculated success fee after the principal update. Null if no collection partner is
assigned or if the principal was not changed.
- `remainder` (number): Outstanding remainder after the update (principal + fees − payments).

```json
{
  "caseId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "grossAmount": 2500,
  "interestFees": 2500,
  "reminderFees": 2500,
  "collectionFees": 2500,
  "totalAddedFees": 2500,
  "recalculatedSuccessFee": 2500,
  "remainder": 1.5
}
```

### Response 400

Validation error — invalid values, case is Closed or Merged, or confirmPriceChange=true was sent on a deliberately-set rate (accepted quote / manual override), which is preserve-only on this API — resubmit with keepIntentionalRate=true instead.

- `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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 assigned to this collection 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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

Price-change confirmation required — the principal edit would move the success fee by >0.1%. For a standard rate, resubmit with confirmPriceChange=true to re-price. For a deliberately-set rate (accepted quote / manual override) the rate is preserve-only: resubmit with keepIntentionalRate=true to apply the edit and keep the special rate — partners cannot override it (sending confirmPriceChange=true on such a case is rejected with 400).

- `caseId` (uuid): The case ID.
- `confirmationRequired` (boolean): Always `true` on this response. Lets clients branch on the response shape without
inspecting the HTTP status code.
- `isIntentionalRate` (boolean): True when the rate is a deliberately-set rate (accepted quote or manual override) rather than a plain
bracket crossing. When true the client resolves the 409 with `KeepIntentionalRate = true` only
(the rate is preserve-only; `ConfirmPriceChange = true` is rejected with 400). When false only
`ConfirmPriceChange = true` applies (re-price). Lets the consumer branch without parsing
Message.
- `currentSuccessFee` (number, nullable): The success fee percentage currently on the case (before the edit).
- `proposedSuccessFee` (number): The success fee percentage that would apply if the edit is confirmed.
- `warning` (string, nullable): Optional warning surfaced alongside the confirmation — e.g. when the principal is lowered on a
case that already has payments (register a payment instead).
Null when there is no warning.
- `message` (string, nullable): Human-readable explanation of why confirmation is required.

```json
{
  "caseId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "confirmationRequired": true,
  "isIntentionalRate": true,
  "currentSuccessFee": 2500,
  "proposedSuccessFee": 2500,
  "warning": null,
  "message": "Payment plan agreed with the debtor."
}
```

### 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="get-exclusive-collection-period-chain"></a>

## Get exclusive collection period chain

`GET /cases/{id}/exclusive-period`

Returns the full exclusive collection period chain for a case, including the initial period and any extensions triggered by debtor actions (promise to pay, payment agreement, or actual payment).

### Path parameters

- `id` (uuid, required): 

### Response 200

Chain returned

- `engagementStartDate` (datetime): Start date of the initial exclusivity engagement.
- `currentEndDate` (datetime): Current end date of the exclusive period (after any extensions).
- `daysRemaining` (integer): Days remaining until the period ends. Negative when the period has naturally expired.
Zero when the engagement was terminated early (partner change or withdrawal),
regardless of the original end date.
- `status` (string, nullable): Current status of the exclusive period: Active, Expired, or Terminated.
Active — partner has exclusive rights.
Expired — period ended naturally (time elapsed or case resolved).
Terminated — period was ended early (partner change, withdrawal, etc.).
- `extensions` (array of objects, nullable): Each extension event that occurred within the current engagement, in chronological order.
Empty for cases that have never had an extension triggered.
- `extensions[].type` (string, nullable): What triggered this extension: PromiseToPay, PaymentAgreement, Payment, or Manual.
- `extensions[].eventDate` (datetime): When the extension period started (i.e. when the trigger event occurred).
- `extensions[].newEndDate` (datetime): The new period end date after this extension was applied.

```json
{
  "engagementStartDate": "2026-10-01T14:05:00Z",
  "currentEndDate": "2026-10-01T14:05:00Z",
  "daysRemaining": 3,
  "status": "string",
  "extensions": [
    {
      "type": "string",
      "eventDate": "2026-10-01T14:05:00Z",
      "newEndDate": "2026-10-01T14:05:00Z"
    }
  ]
}
```

### 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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, not assigned to you, or no collection period exists

- `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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```

<a id="get-full-validation-detail-for-a-case"></a>

## Get full validation detail for a case

`GET /cases/{id}/validation`

Returns the full creditor-facing validation status for a case, including the resolution area and description for each outstanding item.

**When to call:** Check `validation.needsInfo` on `GET /cases/{id}`. If `true`, call this endpoint to retrieve the item-level breakdown of what must be supplied.

**Access Control:** Same as `GET /cases/{id}` — only accessible when you are the collection partner (or managing partner on test cases).

**Safety:** Only creditor-facing resolution areas are returned. Internal areas (InternalReview, AdminReview) and sensitive fields (Rationale, Confidence) are never exposed.

### Path parameters

- `id` (uuid, required): 

### Response 200

Full validation status returned

- `needsInfo` (boolean): 
- `creditorRespondedAt` (datetime, nullable): 
- `items` (array of objects, nullable): 
- `items[].resolutionArea` (string, nullable): 
- `items[].description` (string, nullable): 

```json
{
  "needsInfo": true,
  "creditorRespondedAt": "2026-10-01T14:05:00Z",
  "items": [
    {
      "resolutionArea": "string",
      "description": "string"
    }
  ]
}
```

### Response 400

ID missing, empty, or 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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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 accessible

- `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 <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> 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/…"
    }
  ]
}
```