Skip to main content
Collection Partner API

Cases

Base URL
https://collectionpartner-api.debitura.com
Authentication
API key in the XApiKey header

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

  • Pageinteger
  • PageSizeinteger
  • DebtorIdsarray of uuids
  • Idsarray of uuids
  • Statusesarray 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).

  • DivisionIdsarray of uuids

    Optional list of division IDs to filter by

  • Sortstring

    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.

  • includeTestCasesboolean

    When true, includes test/demo cases where the caller is the owner (either as collection partner or as managing partner). Defaults to false.

Returns

200 List returned

  • pageobjectRequired

    Stable v1 pagination metadata shared by public list responses.

  • casesarray of objectsnullable

    V1 Invoice DTO for external partner APIs

Errors

400Invalid query parameters (returns specific validation errors)

See Error handling.

GET/cases
curl https://collectionpartner-api.debitura.com/cases \
  -H "XApiKey: $DEBITURA_API_KEY"
Response
{
  "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
      }
    }
  ]
}

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

  • iduuidRequired

Returns

200 Case found

  • iduuid
  • dateCreateddatetime
  • dateUpdateddatetimenullable
  • referencestringnullable
  • creditorReferencestringnullable
  • creditorCommentsstringnullable
  • claimDescriptionstringnullable
  • grossAmountnumber
  • remaindernumber
  • interestFeesnumber
  • reminderFeesnumber
  • collectionFeesnumber
  • totalAddedFeesnumber
  • currencystringnullable
  • isTestCaseboolean
  • lifecyclestringnullable
  • dueDatedatetime
  • datedatetime
  • dateFinisheddatetimenullable
  • dateCollectionStarteddatetimenullable
  • closeCodestringnullable
  • currentEngagementPhasestringnullable

    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.

  • claimTypestringnullable

    The type of claim for this case (e.g. "Unpaid Invoice", "Loan Repayment", "Breach of Contract"). Null if not set.

  • creditorDivisionIduuidnullable
  • debtorobject

    V1 Debtor DTO for external partner APIs. The debtor is the party that owes the debt.

  • collectionPartnerobject

    V1 Collection Partner DTO for external partner APIs

  • creditorobject

    Creditor (client) information for external partner APIs. Represents the party that the debtor owes money to.

  • bankAccountobject

    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)
  • blendedAgeUpliftPointsnumbernullable

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

  • preLegalSuccessFeenumbernullable

    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.

  • solutionUrlstringnullableDeprecated

    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.

  • signingHandoffobject

    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.

  • exclusivePeriodEndDatedatetimenullable

    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.

  • disputeStatusstringnullable

    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.

  • validationobject

    Stable v1 validation summary used by ordinary and list mappings.

  • assignedUserobject

    Represents the creditor team member assigned to a case.

  • allocationOutstandingobject

    Outstanding amount per bucket on the case: each bucket's total minus the payments allocated to it.

Errors

400ID missing, empty, or ID is not a collection case
404Case not found, deleted, or not assigned to you as collection partner

See Error handling.

GET/cases/{id}
curl https://collectionpartner-api.debitura.com/cases/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31 \
  -H "XApiKey: $DEBITURA_API_KEY"
Response
{
  "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
  }
}

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

  • caseReferencestringRequired

Returns

200 Case found

  • iduuid
  • dateCreateddatetime
  • dateUpdateddatetimenullable
  • referencestringnullable
  • creditorReferencestringnullable
  • creditorCommentsstringnullable
  • claimDescriptionstringnullable
  • grossAmountnumber
  • remaindernumber
  • interestFeesnumber
  • reminderFeesnumber
  • collectionFeesnumber
  • totalAddedFeesnumber
  • currencystringnullable
  • isTestCaseboolean
  • lifecyclestringnullable
  • dueDatedatetime
  • datedatetime
  • dateFinisheddatetimenullable
  • dateCollectionStarteddatetimenullable
  • closeCodestringnullable
  • currentEngagementPhasestringnullable

    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.

  • claimTypestringnullable

    The type of claim for this case (e.g. "Unpaid Invoice", "Loan Repayment", "Breach of Contract"). Null if not set.

  • creditorDivisionIduuidnullable
  • debtorobject

    V1 Debtor DTO for external partner APIs. The debtor is the party that owes the debt.

  • collectionPartnerobject

    V1 Collection Partner DTO for external partner APIs

  • creditorobject

    Creditor (client) information for external partner APIs. Represents the party that the debtor owes money to.

  • bankAccountobject

    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)
  • blendedAgeUpliftPointsnumbernullable

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

  • preLegalSuccessFeenumbernullable

    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.

  • solutionUrlstringnullableDeprecated

    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.

  • signingHandoffobject

    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.

  • exclusivePeriodEndDatedatetimenullable

    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.

  • disputeStatusstringnullable

    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.

  • validationobject

    Stable v1 validation summary used by ordinary and list mappings.

  • assignedUserobject

    Represents the creditor team member assigned to a case.

  • allocationOutstandingobject

    Outstanding amount per bucket on the case: each bucket's total minus the payments allocated to it.

Errors

400Reference missing or reference is not a collection case
404Reference not found or not assigned to you as collection partner

See Error handling.

GET/cases/case-reference/{caseReference}
curl https://collectionpartner-api.debitura.com/cases/case-reference/INV-2026-0042 \
  -H "XApiKey: $DEBITURA_API_KEY"
Response
{
  "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
  }
}

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

  • referencestringRequired

Returns

200 Case found

  • iduuid
  • dateCreateddatetime
  • dateUpdateddatetimenullable
  • referencestringnullable
  • creditorReferencestringnullable
  • creditorCommentsstringnullable
  • claimDescriptionstringnullable
  • grossAmountnumber
  • remaindernumber
  • interestFeesnumber
  • reminderFeesnumber
  • collectionFeesnumber
  • totalAddedFeesnumber
  • currencystringnullable
  • isTestCaseboolean
  • lifecyclestringnullable
  • dueDatedatetime
  • datedatetime
  • dateFinisheddatetimenullable
  • dateCollectionStarteddatetimenullable
  • closeCodestringnullable
  • currentEngagementPhasestringnullable

    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.

  • claimTypestringnullable

    The type of claim for this case (e.g. "Unpaid Invoice", "Loan Repayment", "Breach of Contract"). Null if not set.

  • creditorDivisionIduuidnullable
  • debtorobject

    V1 Debtor DTO for external partner APIs. The debtor is the party that owes the debt.

  • collectionPartnerobject

    V1 Collection Partner DTO for external partner APIs

  • creditorobject

    Creditor (client) information for external partner APIs. Represents the party that the debtor owes money to.

  • bankAccountobject

    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)
  • blendedAgeUpliftPointsnumbernullable

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

  • preLegalSuccessFeenumbernullable

    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.

  • solutionUrlstringnullableDeprecated

    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.

  • signingHandoffobject

    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.

  • exclusivePeriodEndDatedatetimenullable

    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.

  • disputeStatusstringnullable

    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.

  • validationobject

    Stable v1 validation summary used by ordinary and list mappings.

  • assignedUserobject

    Represents the creditor team member assigned to a case.

  • allocationOutstandingobject

    Outstanding amount per bucket on the case: each bucket's total minus the payments allocated to it.

Errors

400Reference missing or empty
404No case found with this partner reference

See Error handling.

GET/cases/by-partner-reference/{reference}
curl https://collectionpartner-api.debitura.com/cases/by-partner-reference/INV-2026-0042 \
  -H "XApiKey: $DEBITURA_API_KEY"
Response
{
  "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
  }
}

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

  • referencesstring

Returns

200 Dictionary of reference to case — no response body.

Errors

400References parameter missing, empty, or exceeds maximum

See Error handling.

GET/cases/by-partner-reference
curl https://collectionpartner-api.debitura.com/cases/by-partner-reference \
  -H "XApiKey: $DEBITURA_API_KEY"
Response
{}

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

  • referencestring
  • creditorIduuid

Returns

200 Case found

  • iduuid
  • dateCreateddatetime
  • dateUpdateddatetimenullable
  • referencestringnullable
  • creditorReferencestringnullable
  • creditorCommentsstringnullable
  • claimDescriptionstringnullable
  • grossAmountnumber
  • remaindernumber
  • interestFeesnumber
  • reminderFeesnumber
  • collectionFeesnumber
  • totalAddedFeesnumber
  • currencystringnullable
  • isTestCaseboolean
  • lifecyclestringnullable
  • dueDatedatetime
  • datedatetime
  • dateFinisheddatetimenullable
  • dateCollectionStarteddatetimenullable
  • closeCodestringnullable
  • currentEngagementPhasestringnullable

    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.

  • claimTypestringnullable

    The type of claim for this case (e.g. "Unpaid Invoice", "Loan Repayment", "Breach of Contract"). Null if not set.

  • creditorDivisionIduuidnullable
  • debtorobject

    V1 Debtor DTO for external partner APIs. The debtor is the party that owes the debt.

  • collectionPartnerobject

    V1 Collection Partner DTO for external partner APIs

  • creditorobject

    Creditor (client) information for external partner APIs. Represents the party that the debtor owes money to.

  • bankAccountobject

    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)
  • blendedAgeUpliftPointsnumbernullable

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

  • preLegalSuccessFeenumbernullable

    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.

  • solutionUrlstringnullableDeprecated

    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.

  • signingHandoffobject

    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.

  • exclusivePeriodEndDatedatetimenullable

    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.

  • disputeStatusstringnullable

    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.

  • validationobject

    Stable v1 validation summary used by ordinary and list mappings.

  • assignedUserobject

    Represents the creditor team member assigned to a case.

  • allocationOutstandingobject

    Outstanding amount per bucket on the case: each bucket's total minus the payments allocated to it.

Errors

400Reference or creditorId missing or empty
404No case found for this reference + creditor combination, or not assigned to you

See Error handling.

GET/cases/by-creditor-reference
curl https://collectionpartner-api.debitura.com/cases/by-creditor-reference \
  -H "XApiKey: $DEBITURA_API_KEY"
Response
{
  "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
  }
}

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

  • iduuidRequired

Returns

200 Timeline returned

  • itemsarray of objectsnullableRequired

    Chronological list of events on the case.

  • currentEngagementPhasestringnullable

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

Errors

400Case ID missing or empty
404Case not found or not assigned to you as collection partner

See Error handling.

GET/cases/{id}/timeline
curl https://collectionpartner-api.debitura.com/cases/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31/timeline \
  -H "XApiKey: $DEBITURA_API_KEY"
Response
{
  "items": [
    {
      "date": "2026-10-01T14:05:00Z",
      "type": "string",
      "title": "string",
      "description": "string",
      "relatedCases": [
        {
          "id": {},
          "reference": {}
        }
      ],
      "actor": {
        "type": "string",
        "name": "Muster GmbH"
      }
    }
  ],
  "currentEngagementPhase": "string"
}

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

  • iduuidRequired

Returns

200 Chats returned (empty array if no messages) — a list of the objects below.

  • iduuid
  • dateCreateddatetime
  • dateUpdateddatetimenullable
  • roleenumDeprecated

    Deprecated: kept as a number and never removed, but not extended — read roleLabel instead. Sender role: 0 = Partner, 1 = Creditor, 2 = ManagedByPartner.

    One of012
  • roleLabelstringnullable

    The sender role, readable. Always one of "Partner", "Creditor" or "Managed by partner" — these values are stable.

  • messagestringnullable
  • isSeenboolean
  • userobject

Errors

400Case ID missing or empty
404Case not found or not assigned to you as collection partner

See Error handling.

GET/cases/{id}/chats
curl https://collectionpartner-api.debitura.com/cases/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31/chats \
  -H "XApiKey: $DEBITURA_API_KEY"
Response
[
  {
    "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"
    }
  }
]

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

  • iduuidRequired

Headers

  • Idempotency-Keystring

    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

  • messagestringRequired

    The chat message content to send.

    Max 10000 characters
  • userIduuidnullableDeprecated

    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.

  • userEmailstringnullable

    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

Returns

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

  • iduuid
  • dateCreateddatetime
  • dateUpdateddatetimenullable
  • roleenumDeprecated

    Deprecated: kept as a number and never removed, but not extended — read roleLabel instead. Sender role: 0 = Partner, 1 = Creditor, 2 = ManagedByPartner.

    One of012
  • roleLabelstringnullable

    The sender role, readable. Always one of "Partner", "Creditor" or "Managed by partner" — these values are stable.

  • messagestringnullable
  • isSeenboolean
  • userobject

Errors

400Validation error — missing fields, invalid userId, or invalid request body
404Case not found or not assigned to this collection partner
500Internal server error

See Error handling.

POST/cases/{id}/chats
curl -X POST https://collectionpartner-api.debitura.com/cases/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31/chats \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Please provide the signed contract for this case.",
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "userEmail": "john.doe@example.com"
  }'
Response
{
  "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"
  }
}

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

  • iduuidRequired

Returns

200 Payments returned (may be empty array) — a list of the objects below.

  • iduuid
  • dateCreateddatetime
  • dateUpdateddatetimenullable
  • datedatetime
  • grossAmountnumber
  • recipientstringnullableRequired
  • methodstringnullableRequired
  • currencystringnullableRequired
  • invoiceobjectRequired

Errors

400Case ID missing or empty
404Case not found or not assigned to you as collection partner

See Error handling.

GET/cases/{id}/payments
curl https://collectionpartner-api.debitura.com/cases/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31/payments \
  -H "XApiKey: $DEBITURA_API_KEY"
Response
[
  {
    "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"
    }
  }
]

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

  • iduuidRequired

Headers

  • Idempotency-Keystring

    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

  • datedatetimeRequired

    Payment date (when payment was received). Provide date only without time component.

  • paymentAmountnumberRequired

    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
  • payoutCreditornumbernullable

    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
  • payoutCollectionPartnernumbernullable

    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
  • paymentRecipientstringRequired

    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.
  • commissionPaymentStatusstringnullable

    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
  • closeCaseboolean

    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.

Returns

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

  • paymentIduuid
  • caseReferencestringnullableRequired
  • datedatetime
  • paymentAmountnumber
  • payoutCreditornumber
  • payoutCollectionPartnernumber
  • paymentRecipientstringnullableRequired
  • commissionPaymentStatusstringnullableRequired
  • closeCaseboolean
  • caseClosedboolean
  • closeCodestringnullable
  • remainingAmountnumber
  • clientCommissionInvoiceobject

    Whether and how a commission invoice can be raised for this payment's payout, and the state of the current one if it exists.

  • warningsarray of stringsnullable

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

Errors

400Invalid request (validation errors)
404Case not found or not assigned to you
409A request with this Idempotency-Key is already in progress. Retry after the indicated delay.
422The Idempotency-Key has already been used with a different request body.
500Server error occurred

See Error handling.

POST/cases/{id}/payments
curl -X POST https://collectionpartner-api.debitura.com/cases/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31/payments \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-07-31",
    "paymentAmount": 5000,
    "payoutCreditor": 4000,
    "payoutCollectionPartner": 1000,
    "paymentRecipient": "Creditor",
    "commissionPaymentStatus": "Paid",
    "closeCase": false
  }'
Response
{
  "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"
  ]
}

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

  • iduuidRequired

Returns

200 Files retrieved successfully (may be empty array) — a list of the objects below.

  • iduuid
  • dateCreateddatetime
  • dateUpdateddatetime
  • caseIduuid
  • entityTypestringnullable
  • entityIduuid
  • fileNamestringnullable
  • urlstringnullable
  • descriptionstringnullable
  • documentTypestringnullable

Errors

400Case ID missing or empty
404Case not found or not assigned to you as collection partner
500Server error occurred while retrieving files

See Error handling.

GET/cases/{id}/files
curl https://collectionpartner-api.debitura.com/cases/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31/files \
  -H "XApiKey: $DEBITURA_API_KEY"
Response
[
  {
    "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"
  }
]

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

  • iduuidRequired

Headers

  • Idempotency-Keystring

    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 bodymultipart/form-data

  • Filefile

    The file to upload. Required. Allowed extensions: .pdf .doc .docx .xls .xlsx .jpg .jpeg .png .txt .zip .csv .eml Maximum size: 25 MB.

  • DocumentTypestring

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

  • Descriptionstring

    Optional free-text description / label for the file (max 500 characters).

Returns

200 File uploaded successfully

  • iduuid
  • dateCreateddatetime
  • dateUpdateddatetime
  • caseIduuid
  • entityTypestringnullable
  • entityIduuid
  • fileNamestringnullable
  • urlstringnullable
  • descriptionstringnullable
  • documentTypestringnullable

Errors

400Invalid request — missing file, unsupported extension, or request validation error
404Case not found or not assigned to this collection partner
409Case is Merged and cannot accept new files
413File exceeds the 25 MB size limit
415Unsupported file extension
500Internal server error

See Error handling.

POST/cases/{id}/files
curl -X POST https://collectionpartner-api.debitura.com/cases/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31/files \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -F "file=@invoice.pdf"
Response
{
  "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"
}

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

  • iduuidRequired

Request body

  • descriptionstringRequired

    Note content

    Max 10000 characters
  • eventDatedatetimenullable

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

Returns

200 Note created successfully

  • iduuid
  • caseReferencestringnullableRequired
  • titlestringnullableRequired
  • descriptionstringnullable
  • visibilitystringnullableRequired
  • createdAtdatetime
  • eventDatedatetimenullable

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

  • createdByobject

Errors

400Invalid request (missing required fields, EventDate in the future, or validation errors)
404Case not found or not assigned to you
500Server error occurred

See Error handling.

POST/cases/{id}/notes
curl -X POST https://collectionpartner-api.debitura.com/cases/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31/notes \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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
{
  "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"
  }
}

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

  • iduuidRequired
  • paymentIduuidRequired

Request body

  • datedatetimeRequired

    Payment date (when payment was received). Provide date only without time component.

  • paymentAmountnumberRequired

    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
  • payoutCreditornumbernullable

    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
  • payoutCollectionPartnernumbernullable

    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
  • paymentRecipientstringRequired

    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.
  • commissionPaymentStatusstringnullable

    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.

  • reopenCaseIfNeededboolean

    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.

Returns

200 Payment updated successfully

  • iduuid
  • dateCreateddatetime
  • dateUpdateddatetimenullable
  • datedatetime
  • grossAmountnumber
  • recipientstringnullableRequired
  • methodstringnullableRequired
  • currencystringnullableRequired
  • invoiceobjectRequired

Errors

400Invalid request (validation errors)
404Case or payment not found / not assigned to you
409Edit would reopen the case; resend with reopenCaseIfNeeded=true
422Payment has already been invoiced and cannot be edited
500Server error occurred

See Error handling.

PUT/cases/{id}/payments/{paymentId}
curl -X PUT https://collectionpartner-api.debitura.com/cases/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31/payments/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31 \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2025-11-19",
    "paymentAmount": 5000,
    "payoutCreditor": 4000,
    "payoutCollectionPartner": 1000,
    "paymentRecipient": "Creditor",
    "commissionPaymentStatus": "Paid",
    "reopenCaseIfNeeded": false
  }'
Response
{
  "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"
  }
}

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

  • iduuidRequired
  • paymentIduuidRequired

Query parameters

  • reopenCaseIfNeededboolean

Returns

204 Payment deleted successfully — no response body.

Errors

400Invalid request
404Case or payment not found / not assigned to you
409Deletion would reopen the case; resend with reopenCaseIfNeeded=true
422Payment has already been invoiced and cannot be deleted
500Server error occurred

See Error handling.

DELETE/cases/{id}/payments/{paymentId}
curl -X DELETE https://collectionpartner-api.debitura.com/cases/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31/payments/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31 \
  -H "XApiKey: $DEBITURA_API_KEY"
Response

204 Payment deleted successfully. No response body.

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

  • iduuidRequired

Request body

  • closeCodestringRequired

    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)
  • commentstringnullable

    Optional comment explaining the closure (recommended for 'Other' close code)

    Max 2000 characters

Returns

200 Case closed successfully

  • caseReferencestringnullableRequired
  • closeCodestringnullableRequired
  • closeCodeDescriptionstringnullableRequired
  • commentstringnullable
  • closedAtdatetime
  • closedByobject
  • finalOutstandingAmountnumber
  • totalPaymentsnumber
  • totalRecoverednumber

Errors

400Invalid request (validation errors)
404Case not found or not assigned to you
500Server error occurred

See Error handling.

POST/cases/{id}/close
curl -X POST https://collectionpartner-api.debitura.com/cases/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31/close \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "closeCode": "Paid",
    "comment": "Case closed after full payment received via bank transfer on 2025-11-19"
  }'
Response
{
  "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
}

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

  • iduuidRequired

Request body

  • welcomeMessagestringRequired

    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
  • userIduuidnullableDeprecated

    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.

  • userEmailstringnullable

    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
  • collectionPartnerReferencestringnullable

    Your internal reference number for this case (optional). Stored on the case and visible in the partner portal.

    Max 128 characters
  • assignedUserIduuidnullableDeprecated

    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.

  • assignedUserEmailstringnullable

    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
  • interestFeesnumber

    Interest fees on this case, in the case currency. Defaults to 0.00 if not provided.

    Min 0
  • reminderFeesnumber

    Reminder fees on this case, in the case currency. Defaults to 0.00 if not provided.

    Min 0
  • collectionFeesnumber

    Collection fees on this case, in the case currency. Defaults to 0.00 if not provided.

    Min 0

Returns

200 Case activated successfully

  • caseIduuid

    The case ID.

  • caseReferencestringnullable

    The Debitura case reference (e.g. 'Q8OAXF3W').

  • statusstringnullable

    The new lifecycle status of the case.

  • activatedAtdatetime

    UTC timestamp when the case was activated.

  • collectionPartnerReferencestringnullable

    Your internal reference number for this case, if provided.

Errors

400Validation error — case not in PendingVerification, requires custom terms, invalid assignedUserId, or invalid request body
404Case not found or not assigned to this collection partner
500Internal server error

See Error handling.

POST/cases/{id}/start
curl -X POST https://collectionpartner-api.debitura.com/cases/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31/start \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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
{
  "caseId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "caseReference": "INV-2026-0042",
  "status": "string",
  "activatedAt": "2026-10-01T14:05:00Z",
  "collectionPartnerReference": "INV-2026-0042"
}

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

  • iduuidRequired

Request body

  • grossAmountnumbernullable

    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
  • interestFeesnumber

    Interest fees on this case, in the case currency.

    Min 0
  • reminderFeesnumber

    Reminder fees on this case, in the case currency.

    Min 0
  • collectionFeesnumber

    Collection fees on this case, in the case currency.

    Min 0
  • confirmPriceChangeboolean

    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.

  • keepIntentionalRateboolean

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

Returns

200 Fees updated successfully

  • caseIduuid

    The case ID.

  • grossAmountnumber

    Updated principal claim amount (gross amount), in the case currency.

  • interestFeesnumber

    Updated interest fees, in the case currency.

  • reminderFeesnumber

    Updated reminder fees, in the case currency.

  • collectionFeesnumber

    Updated collection fees, in the case currency.

  • totalAddedFeesnumber

    Sum of all fee types.

  • recalculatedSuccessFeenumbernullable

    Recalculated success fee after the principal update. Null if no collection partner is assigned or if the principal was not changed.

  • remaindernumber

    Outstanding remainder after the update (principal + fees − payments).

Errors

400Validation 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.
404Case not found or not assigned to this collection partner
409Price-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).
500Internal server error

See Error handling.

PUT/cases/{id}/fees
curl -X PUT https://collectionpartner-api.debitura.com/cases/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31/fees \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "grossAmount": 1000,
    "interestFees": 25.5,
    "reminderFees": 10,
    "collectionFees": 50,
    "confirmPriceChange": false,
    "keepIntentionalRate": false
  }'
Response
{
  "caseId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "grossAmount": 2500,
  "interestFees": 2500,
  "reminderFees": 2500,
  "collectionFees": 2500,
  "totalAddedFees": 2500,
  "recalculatedSuccessFee": 2500,
  "remainder": 1.5
}

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

  • iduuidRequired

Returns

200 Chain returned

  • engagementStartDatedatetime

    Start date of the initial exclusivity engagement.

  • currentEndDatedatetime

    Current end date of the exclusive period (after any extensions).

  • daysRemaininginteger

    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.

  • statusstringnullable

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

  • extensionsarray of objectsnullable

    Each extension event that occurred within the current engagement, in chronological order. Empty for cases that have never had an extension triggered.

Errors

400ID missing, empty, or ID is not a collection case
404Case not found, not assigned to you, or no collection period exists

See Error handling.

GET/cases/{id}/exclusive-period
curl https://collectionpartner-api.debitura.com/cases/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31/exclusive-period \
  -H "XApiKey: $DEBITURA_API_KEY"
Response
{
  "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"
    }
  ]
}

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

  • iduuidRequired

Returns

200 Full validation status returned

  • needsInfoboolean
  • creditorRespondedAtdatetimenullable
  • itemsarray of objectsnullable

Errors

400ID missing, empty, or not a collection case
404Case not found or not accessible

See Error handling.

GET/cases/{id}/validation
curl https://collectionpartner-api.debitura.com/cases/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31/validation \
  -H "XApiKey: $DEBITURA_API_KEY"
Response
{
  "needsInfo": true,
  "creditorRespondedAt": "2026-10-01T14:05:00Z",
  "items": [
    {
      "resolutionArea": "string",
      "description": "string"
    }
  ]
}