Skip to main content
Collection Partner API

Managed cases

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

Preview managed-case routing.

POST/managed-cases/preview

Optional, read-only snapshot. HasPreLegalPartner describes a routing candidate, not permission to create a case. No match may lead to internal review and potentially network quotes on submission; neither acceptance nor a quote is guaranteed. Full validation, agreements and admission rules still apply on creation. No client, case or routing reservation is created by this endpoint. Send outstanding principal, currency and debtor type/country/state; invoice lines and pricing inputs are not evaluated. Model-binding errors use ValidationProblemDetails.

marketMinimumAmount is the smallest claim the market takes for this debtor country and type (never below the platform minimum of 100 USD). applicableMinimumAmount is not populated by this endpoint.

Examples

Matched — request {"amountToRecover": 15000, "currencyCode": "USD", "debtor": {"type": "Company", "countryAlpha2": "US", "stateAlpha2": "NY"}} → response {"hasPreLegalPartner": true, "collectionPartnerId": "...", "routingSource": "Automatic", "marketMinimumAmount": 500, "marketMinimumCurrencyCode": "USD"}.

No match, amount below minimum — request {"amountToRecover": 175, "currencyCode": "USD", "debtor": {"type": "Company", "countryAlpha2": "US", "stateAlpha2": "NY"}} → response {"hasPreLegalPartner": false, "ineligibilityReasonCode": "AmountBelowMinimum", "marketMinimumAmount": 500, "marketMinimumCurrencyCode": "USD"}.

No match, no geographic coverage — request {"amountToRecover": 2000, "currencyCode": "USD", "debtor": {"type": "Company", "countryAlpha2": "VN"}} → response {"hasPreLegalPartner": false, "ineligibilityReasonCode": "NoGeographicCoverage", "marketMinimumAmount": null}.

Excluded for this client — request with a clientId excluded from every remaining candidate → response {"hasPreLegalPartner": false, "ineligibilityReasonCode": "ExcludedForClient"}.

Explicit override — request {"amountToRecover": 2000, "currencyCode": "USD", "collectionPartnerId": "(a partner id)", "debtor": {...}} → response {"hasPreLegalPartner": true, "collectionPartnerId": "(the same id)", "routingSource": "Requested"}.

Degraded FX — an unquotable request currency still returns a selected candidate where one exists: response {"hasPreLegalPartner": true, "routingSource": "Automatic", "ineligibilityReasonCode": "EligibilityUndetermined", "amountCheckUnavailable": true, "marketMinimumAmount": null}.

Request body

  • amountToRecovernumberRequired

    Positive outstanding principal in CurrencyCode. For invoice lines, send their summed outstanding balance.

  • currencyCodestringRequired

    Supported three-letter ISO currency code, for example USD or EUR.

    3–3 characters
  • debtorobjectRequired

    Simplified debtor information for case preview. Only includes the minimum fields required for partner routing and eligibility checking.

  • clientIduuidnullable

    Optional represented client owned by your partner account. Omit to preview a new inline client without creating one.

  • collectionPartnerIduuidnullable

    Optional explicit receiving partner. Takes precedence over automatic and test-case routing.

  • isTestboolean

    Preview test routing. Without an explicit receiving partner, test/demo cases route to your own partner account.

Returns

200 OK

  • hasPreLegalPartnerboolean

    Whether a routing destination is selected now. Does not certify acceptance of the case.

  • collectionPartnerIduuidnullable

    Selected candidate, or null when no pre-legal partner was selected.

  • routingSourceenumnullable

    How the candidate was selected. Null when no candidate was selected.

    One ofAutomaticClientConfiguredRequestedSelfManagednull
  • jurisdictionobject

    Geographic jurisdiction information for the case.

  • ineligibilityReasonCodestringnullable

    Stable matching reason code. May be EligibilityUndetermined even with a selected candidate when amount checks were unavailable.

  • ineligibilityReasonstringnullable

    Matching diagnosis, not a refusal of case admission.

  • applicableMinimumAmountnumbernullable

    Not populated by this endpoint (always null): a managed claim without a partner is not refused, and no amount is suggested. Use MarketMinimumAmount for the market floor.

  • applicableMinimumCurrencyCodestringnullable

    Always null on this endpoint; see ApplicableMinimumAmount.

  • marketMinimumAmountnumbernullable

    Smallest claim the marketplace takes for this jurisdiction and debtor type, in the request currency: the lowest partner floor, never below the platform minimum of 100 USD. A market statement, returned whether or not a partner is selected. Not the admission rules applied when a case is created. Null when no partner covers the market or the amount cannot be priced (see AmountCheckUnavailable).

  • marketMinimumCurrencyCodestringnullable

    Currency of MarketMinimumAmount.

  • amountCheckUnavailableboolean

    Amount conditions could not be fully evaluated. May be true even when a candidate is selected.

Errors

400Bad Request
401Unauthorized
404Not Found
500Internal Server Error

See Error handling.

POST/managed-cases/preview
curl -X POST https://collectionpartner-api.debitura.com/managed-cases/preview \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountToRecover": 2500,
    "currencyCode": "EUR",
    "debtor": {
      "type": "string",
      "countryAlpha2": "DE"
    }
  }'
Response
{
  "hasPreLegalPartner": true,
  "collectionPartnerId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "routingSource": "Automatic",
  "jurisdiction": {
    "id": 3,
    "name": "Muster GmbH",
    "countryAlpha2": "DE",
    "stateAlpha2": null
  },
  "ineligibilityReasonCode": null,
  "ineligibilityReason": null,
  "applicableMinimumAmount": 2500,
  "applicableMinimumCurrencyCode": "EUR",
  "marketMinimumAmount": 2500,
  "marketMinimumCurrencyCode": "EUR",
  "amountCheckUnavailable": true
}

List managed cases

GET/managed-cases

Returns a paginated list of cases where you are the managing partner (submitted on behalf of your clients).

What is a Managing Partner? A managing partner is a collection partner that submits cases on behalf of their own clients but forwards the actual debt recovery work to another collection partner in Debitura's network. You remain your client's point of contact while leveraging Debitura's global network of 500+ partners across 183 jurisdictions.

Why Become a Managing Partner?

  • Serve clients globally without physical presence in every jurisdiction
  • Maintain client relationships while outsourcing collection work
  • Access Debitura's vetted partner network
  • Earn commission on successful recoveries
  • Provide full-service debt recovery to your clients

Your Role as Managing Partner:

  • Submit cases on behalf of your clients (via API or partner portal)
  • Monitor case progress and recovery status (read-only access)
  • Communicate with the collection partner through case chat
  • Receive updates on payments and case status
  • Invoice your clients and remit payments

Note: This endpoint shows cases YOU submitted. For cases where you are actively collecting, use the /cases endpoint instead.

Partner Portal View: These cases appear in the 'Cases Submitted' section of the partner portal.

Pagination:

  • page (default: 1) - Page number, starting from 1
  • pageSize (default: 10, max: 100) - Number of results per page

Filters:

  • statuses - Filter by case lifecycle status (comma-separated list) Valid values: PendingContractSigning, PendingVerificationInternal, PendingVerification, NeedsAdditionalDetails, Leads, LeadsQuoteGiven, Active, Paused, Closed
  • divisionIds - Filter by your client division IDs (comma-separated GUIDs)
  • debtorIds - Filter by specific debtor IDs (comma-separated GUIDs)
  • ids - Filter by specific case IDs (comma-separated GUIDs)

Sorting:

  • sort - Sort field and direction (format: 'field:direction') Examples: 'date:desc', 'amount:asc', 'debtorName:asc'

Response:

  • Returns InvoiceListApiDTO with page metadata and cases array
  • Each case includes collection partner information (who is actually collecting)
  • Page metadata includes: totalResults, currentPage, skipped, pageSize

Query parameters

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

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/managed-cases
curl https://collectionpartner-api.debitura.com/managed-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
      }
    }
  ]
}

Create case as managing partner

POST/managed-cases

Two ways to name the creditor — send one, never both:

  • clientId (standard). Create the client once with POST /managed-clients, then send its id as clientId on every case for that client. All of its cases land on the same client record.
  • creditorCompanyName + country (deprecated). Still works, so existing integrations never break, but it creates a new client record on every call. Responses in this mode carry a Deprecation: true header. No removal date is set.

Sending clientId together with any creditor company field is rejected with a 400. A clientId that is not one of your represented clients returns 404. With clientId, a CreditorReference already used on that client is rejected as a duplicate. clientId replaces CreditorCompanyName and the creditor country in the required fields below.

Creates a collection case on behalf of your client (or yourself) through the Debitura platform.

Understanding the Creditor Field: The creditor is the party that the debtor owes money to. This can be:

  • Your client's company - When you're submitting cases on behalf of clients you represent
  • Your own company - When you're submitting your own debt collection cases

How It Works:

  1. You provide the creditor's basic information (company name + country)
  2. Debitura creates a creditor record (if one doesn't exist)
  3. The collection case is created under that creditor
  4. You are set as the managing partner
  5. The case is automatically assigned to a collection partner based on jurisdiction

Managing Partner Benefits:

  • Submit cases on behalf of your clients via API
  • Maintain your client relationships
  • Leverage Debitura's global partner network
  • Monitor case progress through read-only access
  • Provide full-service debt recovery to your clients

Required Fields:

  • CreditorCompanyName - The company name of who the debtor owes money to
  • CreditorCountryAlpha2 OR CreditorCountry - Creditor's country (provide either code or name)
  • CurrencyCode - Case currency (e.g., 'USD', 'EUR', 'DKK')
  • Date - Invoice issue date
  • AmountToRecover - Claim amount
  • Debtor - Complete debtor information with jurisdiction

Debtor Rules:

  • debtor.type must be "Company" or "Private" (case-insensitive)
    • Company → debtor.name is mandatory (company name)
    • Private → debtor.name is mandatory (individual's full name)
  • For Company debtors, debtor.contactPerson is required
  • debtor.country (or debtor.countryAlpha2) is always required
  • debtor.stateAlpha2 is required for US cases - provide the two-letter state code (e.g., "CA", "NY"). For non-US cases, this field is optional.
  • debtor.state is a general-purpose region field (not used for US jurisdiction resolution)

Optional Fields:

  • DueDate - Invoice due date
  • AmountToRecoverOver6Months - Cumulative amount more than 6 months overdue (includes 12+ and 24+)
  • AmountToRecoverOver12Months - Cumulative amount more than 12 months overdue (includes 24+)
  • AmountToRecoverOver24Months - Cumulative amount more than 24 months overdue
  • ClaimLines - The unpaid invoices making up the claim (see below)
  • Comments - Additional notes
  • ClaimDescription - Description of the claim
  • CreditorReference - Your client's internal reference
  • CollectionPartnerId - Override automatic partner matching
  • IsTest - Mark as test case (excluded from production metrics)

Submitting Claim Lines (recommended for multi-invoice claims): Instead of totalling the claim yourself, send the unpaid invoices and let us do the arithmetic:

"claimLines": [
  { "dueDate": "2024-01-15", "amount": 423.42, "reference": "INV-1001" },
  { "dueDate": "2025-05-02", "amount": 700.87, "reference": "INV-1042" }
]
  • amount is the outstanding balance on that invoice — what the debtor still owes on it, already net of payments received and credit notes issued. It is not the invoice's original face value. Leave fully settled invoices out; every amount must be greater than zero, with at most 2 decimals.
  • We derive AmountToRecover and all three age buckets from the lines, so send claimLines instead of AmountToRecover and the AmountToRecoverOver6/12/24Months fields. Sending both is a 400.
  • Use claimLines whenever the debtor has already part-paid: it is the only way to express an honest age profile on a part-paid claim, because the buckets are then computed on the same outstanding balances the total is computed on.
  • claimLines prices on exact age data. Sending a single DueDate instead is an approximation and can produce a different quote for the same claim.
  • claimLines is a pricing input only. It is not stored and is not shown to the collecting partner — include a per-invoice breakdown in Comments if the partner needs to see one.
  • Maximum 1000 lines. Per-line errors are returned keyed by index, e.g. ClaimLines[2].DueDate.
  • If you omit the case-level DueDate, it is set to the oldest due date across your lines — so in that case Date must not be later than the earliest claimLines dueDate, or the request is rejected with a 400 on Date. Send an explicit DueDate if you need a different case due date.

Response: Returns the created case details including the case ID, reference number, and assignment information.

Important Notes:

  • The 12+ and 24+ fields must be supplied together. The 6+ field is optional, but when supplied it requires both other buckets.
  • Cumulative values must satisfy AmountToRecover ≥ 6+ ≥ 12+ ≥ 24+. DueDate may coexist with age buckets.
  • Creditor records are created fresh each time (no duplicate detection)
  • Contract requirements are automatically bypassed
  • Production cases enter Debitura's internal verification before proceeding to the assigned collection partner
  • Test cases bypass internal verification because delayed auto-validation is only scheduled for production cases
  • Cases appear in your 'Managed Cases' list
  • You have read-only access to monitor case progress

Headers

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

  • clientIduuidnullable

    The client this case belongs to. Create the client once with POST /managed-clients and send its id here; every case you submit for that client then lands on the same record. Send either ClientId or the creditor company fields below, never both.

  • creditorCompanyNamestringnullableDeprecated

    Deprecated. Use ClientId: create the client once with POST /managed-clients. This mode still works and creates a new client record on every call. Creditor company name for this case. If you're submitting cases on behalf of your clients, use your client's company name. If you're submitting your own cases, use your own partner company name.

  • creditorCountryAlpha2stringnullableDeprecated

    Deprecated. Use ClientId: create the client once with POST /managed-clients. This mode still works and creates a new client record on every call. Creditor country code (ISO 3166-1 alpha-2 format). Either this or CreditorCountry is required.

  • creditorCountrystringnullableDeprecated

    Deprecated. Use ClientId: create the client once with POST /managed-clients. This mode still works and creates a new client record on every call. Creditor country name. Either this or CreditorCountryAlpha2 is required.

  • currencyCodestringRequired

    Currency code for the case (ISO 4217 format)

  • datedatetimeRequired

    Invoice issue date. Provide date only without time component.

  • dueDatedatetimenullable

    Invoice due date. Provide date only without time component.

  • commentsstringnullable

    Optional comments about the case. Use this to provide context about payment attempts, communication history, or other relevant information.

    Max 4000 characters
  • claimDescriptionstringnullable

    Client provided description of the services or goods delivered

    Max 4000 characters
  • creditorReferencestringnullable

    Client's internal reference for the case (e.g., invoice number)

    Max 50 characters
  • debtorobjectRequired

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

  • amountToRecovernumber

    Total amount to recover from debtor (in the specified currency).

    Required unless you send ClaimLines, in which case this must be omitted or 0 — the server derives the total by summing the outstanding balance of every claim line. Sending both a non-zero AmountToRecover and ClaimLines is rejected, because the two would disagree.

  • amountToRecoverOver6Monthsnumbernullable

    Optional cumulative portion of AmountToRecover that is more than 6 months overdue. Includes the 12+ and 24+ month amounts and must be supplied together with both fields.

  • amountToRecoverOver12Monthsnumbernullable

    Optional cumulative portion of AmountToRecover that is more than 12 months overdue. Includes the 24+ month amount and must be supplied together with AmountToRecoverOver24Months.

  • amountToRecoverOver24Monthsnumbernullable

    Optional cumulative portion of AmountToRecover that is more than 24 months overdue. Must be supplied together with AmountToRecoverOver12Months.

  • claimLinesarray of objectsnullable

    Optional: the unpaid invoices making up this claim, one line per invoice, each carrying its own outstanding balance and payment deadline. When supplied, the server derives AmountToRecover and all three cumulative age buckets from these lines, so send them instead of — never alongside — AmountToRecover and the AmountToRecoverOver6/12/24Months fields. Supplying both is rejected with a 400. Use this whenever the debtor has already part-paid the claim: the buckets are then computed on the same outstanding balances the total is computed on, so the age profile stays honest. Maximum 1000 lines. When DueDate is omitted on the case, it is derived as the oldest line due date.

  • isTestboolean

    When true, creates a test case that IS persisted to the database but marked as test data. Test cases are excluded from production metrics and can be easily filtered or deleted. Use this for integration testing and development.

  • tagstringnullable

    Optional tag for scoped test data grouping (e.g. "suite-run-{uuid}"). Use this to group test cases created by a single CI pipeline run so they can be bulk-deleted via DELETE /test/cases?tag={tag} without affecting parallel runs. Only meaningful when IsTest is true. Max 100 characters.

    Max 100 characters
  • collectionPartnerIduuidnullable

    Optional: Specify a collection partner ID to handle this case. When provided, this partner is used instead of automatic partner matching. The partner must be active and have coverage for the debtor's jurisdiction.

Returns

200 Case created successfully

  • 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

400Invalid request data (field validation errors)
404clientId is not one of your represented clients
409Conflict - an idempotent request with this key is still in progress
422Business rule violation (e.g., no partner available for jurisdiction)
500Internal server error

See Error handling.

POST/managed-cases
curl -X POST https://collectionpartner-api.debitura.com/managed-cases \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "creditorCompanyName": "Acme Services Inc",
    "creditorCountry": "United States",
    "currencyCode": "USD",
    "amountToRecover": 15000,
    "amountToRecoverOver6Months": 9000,
    "amountToRecoverOver12Months": 6000,
    "amountToRecoverOver24Months": 2000,
    "date": "2026-05-01",
    "dueDate": "2026-05-15",
    "claimDescription": "Software development services - Project Alpha",
    "comments": "Invoice INV-2024-1234 for custom ERP system development. Payment 90 days overdue despite multiple reminders. Client confirmed services received but cited cash flow issues.",
    "creditorReference": "INV-2024-1234",
    "isTest": false,
    "debtor": {
      "type": "Company",
      "name": "Pacific Trading LLC",
      "contactPerson": "John Smith",
      "companyRegistrationNumber": "47-1234567",
      "address": "123 Market Street, Suite 400",
      "zipCode": "94105",
      "city": "San Francisco",
      "stateAlpha2": "CA",
      "country": "United States",
      "email": "accounts@pacifictrading.com",
      "phone": "+1 415 555 0123"
    }
  }'
Response
{
  "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 managed case by ID

GET/managed-cases/{id}

Returns detailed information for a case you submitted on behalf of your client (where you are the managing partner).

Access Control: This endpoint only returns cases where YOU are the managing partner. If you are the collection partner on a case, use /cases/{id} instead.

Response Includes:

  • Case details (reference, amount, currency, status)
  • Debtor information
  • Your client information (the creditor)
  • Collection partner details (who is actively collecting this case)
  • Financial breakdown
  • Case progress and timeline summary

Monitoring Your Cases: As the managing partner, you have read-only access to monitor progress while the collection partner handles the actual recovery work.

Path parameters

  • 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 submitted by you as managing partner

See Error handling.

GET/managed-cases/{id}
curl https://collectionpartner-api.debitura.com/managed-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 managed case by reference

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

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

Use Case: Use this endpoint when you have the Debitura case reference but not the GUID. Helpful for customer service integrations or when your clients reference cases by the Debitura reference number.

Access Control: Only returns cases where you are the managing partner.

Path parameters

  • 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 submitted by you as managing partner

See Error handling.

GET/managed-cases/case-reference/{caseReference}
curl https://collectionpartner-api.debitura.com/managed-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 managed case timeline

GET/managed-cases/{id}/timeline

Returns the complete chronological event history for a case you submitted as managing partner.

Timeline Events Include:

  • Case submission and acceptance
  • Assignment to collection partner
  • Status changes and lifecycle transitions
  • Payment recordings
  • Communication events between collection partner and creditor
  • Collection partner updates and notes

Managing Partner Transparency: The timeline provides full visibility into the collection partner's activities, allowing you to monitor progress and keep your clients informed.

Response shape:

  • items — chronological list of timeline events
  • currentEngagementPhase — current phase of the active engagement: "Pre-legal", "Legal", or "Enforcement". Null when no active engagement exists.

Use Case: Use this to track case progress, update your clients on status, or audit collection partner activities.

Path parameters

  • 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 submitted by you as managing partner

See Error handling.

GET/managed-cases/{id}/timeline
curl https://collectionpartner-api.debitura.com/managed-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 managed case chats

GET/managed-cases/{id}/chats

Returns all chat messages for a case you submitted, in chronological order.

Chat Participants (for Managed Cases):

  • Managing partner (you) - Your messages to the collection partner
  • Collection partner - Messages from the partner actively collecting the case
  • Your client (creditor) - Messages from the client you represent
  • Debitura support - System notifications and support messages

Communication Flow: As the managing partner, you can participate in case discussions to:

  • Coordinate with the collection partner
  • Provide additional information about the debtor
  • Relay questions from your client
  • Stay updated on collection progress

Use Case: Monitor collection partner communications, coordinate case strategy, or extract conversation history to share with your clients.

Note: Managing partners have limited write access - you can read and send messages but cannot modify case details or add payments.

Path parameters

  • 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 submitted by you as managing partner

See Error handling.

GET/managed-cases/{id}/chats
curl https://collectionpartner-api.debitura.com/managed-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"
    }
  }
]

Fetch managed case payments

GET/managed-cases/{id}/payments

Returns all payments recorded on a case you submitted as managing partner.

Payment Information Includes:

  • Payment amount, currency, and date
  • Payment type and method
  • Payment status (recorded by collection partner)
  • Allocation breakdown (principal, interest, fees)
  • Payout details (amounts to creditor and collection partner)

What This Endpoint Shows: As a managing partner, you can monitor all payment activity on cases you submitted for your clients. This endpoint provides visibility into:

  • What the collection partner has recovered from the debtor
  • How recovered amounts are allocated (principal vs. interest vs. fees)
  • The collection partner's success fee on each payment
  • Payment history and timeline

Important: This endpoint is for monitoring and client reporting purposes. Your financial arrangements with your clients (billing, commissions, etc.) are managed outside of Debitura's platform. The payment data shown here represents what the collection partner recovered and their fees, not any commissions or payments to you as the managing partner.

Use Case: Monitor recovery progress, reconcile payments with your records, track case performance, or provide payment status updates to your clients.

Note: On production cases, only the assigned collection partner can record new payments. For test cases (isTestCase: true), managing partners can record payments via POST /managed-cases/{id}/payments.

Path parameters

  • 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 submitted by you as managing partner

See Error handling.

GET/managed-cases/{id}/payments
curl https://collectionpartner-api.debitura.com/managed-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"
    }
  }
]

Record a payment on a test case (managing partner)

POST/managed-cases/{id}/payments

Records a payment on a test case you submitted as managing partner.

Test-Only Restriction: This endpoint only works on cases created with isTestCase: true. Attempting to record a payment on a production case returns a 400 error. For production cases, the assigned collection partner must use POST /cases/{id}/payments.

Purpose: Allows managing partners (e.g. Get-Systems) to test their full payment integration end-to-end — including webhook delivery, lifecycle transitions, and remainder updates — without involving the collection partner.

Payout Handling: A payout record is created automatically with the full payment amount going to the creditor and zero to the collection partner. CommissionPaymentStatus is set to Unpaid.

Webhooks: Payment webhooks fire normally, making this useful for end-to-end integration testing.

CloseCase: If closeCase=true and the payment amount is less than the outstanding balance, a 400 is returned.

Path parameters

  • iduuidRequired

Request body

  • datedatetimeRequired

    Payment date (when payment was received).

  • paymentAmountnumberRequired

    Total payment amount received.

    Min 0.01
  • closeCaseboolean

    Whether to close the case after recording this payment (default: false). If true and payment < invoice remainder, returns validation error.

Returns

200 Payment recorded successfully

  • paymentIduuid
  • caseReferencestringnullableRequired
  • datedatetime
  • paymentAmountnumber
  • caseClosedboolean
  • remainingAmountnumber

Errors

400Invalid request or production case
404Case not found or not submitted by you as managing partner
500Server error

See Error handling.

POST/managed-cases/{id}/payments
curl -X POST https://collectionpartner-api.debitura.com/managed-cases/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31/payments \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2025-11-19",
    "paymentAmount": 5000,
    "closeCase": false
  }'
Response
{
  "paymentId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "caseReference": "INV-2026-0042",
  "date": "2026-10-01T14:05:00Z",
  "paymentAmount": 2500,
  "caseClosed": true,
  "remainingAmount": 2500
}

Edit a payment on a test case (managing partner)

PUT/managed-cases/{id}/payments/{paymentId}

Edits a payment on a test case you submitted as managing partner.

Test-Only Restriction: like recording a payment, this only works on cases created with isTestCase: true. Production cases return a 400 — the assigned collection partner must edit via PUT /cases/{id}/payments/{paymentId}.

Invoiced payments are frozen: an already-invoiced payment cannot be edited and returns 422.

Reopen consent: if the edit leaves a previously closed (Paid) case with an outstanding balance, the case is reopened only when reopenCaseIfNeeded: true; otherwise the request returns 409 Conflict.

Path parameters

  • 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 or production case
404Case or payment not found / not submitted by you
409Edit would reopen the case; resend with reopenCaseIfNeeded=true
422Payment has already been invoiced and cannot be edited
500Server error

See Error handling.

PUT/managed-cases/{id}/payments/{paymentId}
curl -X PUT https://collectionpartner-api.debitura.com/managed-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 test case (managing partner)

DELETE/managed-cases/{id}/payments/{paymentId}

Deletes a payment from a test case you submitted as managing partner, reverting its effect on the case balance and cascading the payout deletion. A durable audit record is retained.

Test-Only Restriction: only works on cases created with isTestCase: true. Production cases return a 400 — the assigned collection partner must delete via DELETE /cases/{id}/payments/{paymentId}.

Invoiced payments are frozen: an already-invoiced payment cannot be deleted and returns 422.

Reopen consent: if the deletion leaves a previously closed (Paid) case with an outstanding balance, the case is reopened only when reopenCaseIfNeeded=true; otherwise the request returns 409 Conflict.

Path parameters

  • iduuidRequired
  • paymentIduuidRequired

Query parameters

  • reopenCaseIfNeededboolean

Returns

204 Payment deleted successfully — no response body.

Errors

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

See Error handling.

DELETE/managed-cases/{id}/payments/{paymentId}
curl -X DELETE https://collectionpartner-api.debitura.com/managed-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.

Get managed case files

GET/managed-cases/{id}/files

Returns all documents and files attached to a case you submitted as managing partner.

File Access for Managing Partners: You can view files uploaded by:

  • Your client (the creditor you represent)
  • The collection partner handling the case
  • Debitura support team
  • Yourself (files you uploaded when submitting the case)

File Types Include:

  • OriginalInvoice - The initial claim documentation
  • ProofOfDelivery - Delivery confirmations
  • Contract - Agreements between creditor and debtor
  • Correspondence - Email and letter communications
  • PaymentProof - Payment receipts
  • CourtDocuments - Legal filings
  • Other - Miscellaneous supporting documents

Use Case:

  • Review evidence and supporting documents
  • Download files to share with your client
  • Verify document completeness before escalation
  • Build client-facing portals showing case documentation

Note: File URLs are temporary signed links that expire. Call this endpoint again to generate fresh download links if needed.

Upload additional ordinary case documents with POST /managed-cases/{id}/files.

Path parameters

  • 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 submitted by you as managing partner
500Server error occurred while retrieving files

See Error handling.

GET/managed-cases/{id}/files
curl https://collectionpartner-api.debitura.com/managed-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 managed case

POST/managed-cases/{id}/files

Uploads one ordinary case document to a case you submitted as managing partner.

Access: The authenticated partner must match the case's managing partner. This is separate from the collecting-partner upload route.

Status gate: Allowed on every lifecycle except Merged, including Closed.

File requirements: Maximum 25 MB. Allowed filename extensions are .pdf .doc .docx .xls .xlsx .jpg .jpeg .png .txt .zip .csv .eml.

Optional fields: Description is limited to 500 characters.

DocumentType is case-insensitive. Omit it when the type is unknown; the file is stored as not specified and returned as null. Valid values: OriginalInvoice, AccountStatement, Contract, TermsAndConditions, ProofOfDelivery, DemandLetter, Correspondence, PaymentProof, CourtDocument, IdentityDocument, Miscellaneous. Legacy names remain accepted for existing integrations: DebtorDocuments, CreditorDocuments, PartnerDocuments. Unknown names, numeric values, and AutoGeneratedSummary are rejected with 400 and error InvalidDocumentType.

Use Idempotency-Key to retry safely. An identical replay returns the original response. Separate uploads with the same filename are stored independently and cannot overwrite one another.

Path parameters

  • 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

400Missing file or invalid request
404Case not found or not managed by this partner
409Case is merged or idempotent request is in progress
413File exceeds 25 MB
415Unsupported file extension
422Idempotency-Key reused with a different request
500Internal server error

See Error handling.

POST/managed-cases/{id}/files
curl -X POST https://collectionpartner-api.debitura.com/managed-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"
}