Cases

Query parameters

• FromDatedatetime

  Filter cases from this date (inclusive, based on case creation date). ISO 8601 format.

• ToDatedatetime

  Filter cases to this date (inclusive, based on case creation date). ISO 8601 format.

• ExternalTenantIdstring

  Filter by specific client's external tenant ID

• Statusesarray of strings

  Filter by case lifecycle status(es). Multiple values can be provided. Accepts enum names (e.g. "Active", "Closed") or descriptions (e.g. "More Info Required").

• Querystring

  Search query across case reference, creditor reference, and debtor name

• WaitingOnstring

  Filter held cases by Client or Debitura. Numeric values are not accepted.

• Pageinteger

  Page number (1-indexed)

  Min 1
• PageSizeinteger

  Number of results per page (default: 10, max: 100)

  1 to 100
• CountryIdsarray of integers

  Filter by debtor country ID(s). Multiple values can be provided. Only cases where the debtor's country matches one of the specified IDs are returned.

• CollectionPartnerIdsarray of uuids

  Filter by collection partner ID(s). Multiple values can be provided. Only cases assigned to one of the specified collection partners are returned.

• Sortstring

  Sort field and direction. Format: "field[:asc|desc]" Supported fields: DateCreated, GrossAmount, DueDate Examples: "DateCreated:desc", "GrossAmount:asc" Default: DateCreated:desc

Returns

200 Cases retrieved successfully

• pageobject

  Paging metadata describing a paged result set.

  +Show 5 child attributes
• casesarray of objectsnullable

  A debt collection case as seen by a referral partner, with your ExternalTenantId on Client.

  +Show 19 child attributes
• summaryobject
  +Show 4 child attributes

Errors

See Error handling.

Path parameters

• iduuidRequired

Returns

200 Case retrieved successfully

• iduuid
• referencestringnullable
• creditorReferencestringnullable
• clientobject

  Client (creditor) info with referral-partner-specific ExternalTenantId.

  +Show 4 child attributes
• debtorobject

  Debtor info for the case.

  +Show 2 child attributes
• grossAmountnumber
• remaindernumber
• currencystringnullable
• lifecyclestringnullable
• closeCodestringnullable
• currentEngagementPhasestringnullable

  The current phase of the case's engagement: "Pre-legal", "Legal", or "Enforcement". Null means no active engagement — see CurrentEngagementPhase for full semantics (not monotonic, persists after case closure).

• dateCreateddatetime
• dueDatedatetime
• dateCollectionStarteddatetimenullable
• dateFinisheddatetimenullable
• validationobject

  The case's current validation status: whether information is needed, and what to supply.

  +Show 3 child attributes
• holdobject

  Allowlisted referral visibility; never attach validation entities or internal diagnostics.

  +Show 4 child attributes
• collectionPartnerstringnullable

  Display name of the collection partner handling this case (e.g. "Oriel Collections"). Null if no collection partner has been assigned yet.

• expectedReferralRatePercentagenumbernullable

  The expected referral fee rate as a percentage (e.g. 70.0 = 70%). Uses the per-assignment override when set, otherwise the referral link's snapshotted rate (frozen at link creation time). Null when no collection partner has been assigned yet.

• potentialRevenueobject

  Breakdown of potential revenue if the full case amount is collected. All amounts are in USD; percentages are displayed as whole numbers (e.g. 9.5 = 9.5%).

  +Show 7 child attributes

Errors

See Error handling.

Path parameters

• caseIduuidRequired

Query parameters

• sendChatNotificationboolean

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

Returns

200 File uploaded successfully — no response body.

Errors

See Error handling.

Request body

• amountToRecovernumber

  The TOTAL amount to recover for this case. This represents the full principal amount across all invoices (if multiple invoices are bundled).

  For multi-invoice cases with different ages, you can optionally provide age breakdown fields (AmountToRecoverOver12Months and AmountToRecoverOver24Months) to enable blended age-based pricing.

  If age breakdown fields are omitted, the preview will show base pricing without age surcharge calculation.

  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.

• currencyCodestringRequired

  ISO 4217 currency code for the amount (e.g., "DKK", "EUR", "USD")

  3–3 characters
• debtorobjectRequired

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

  +Show 3 child attributes
• amountToRecoverOver6Monthsnumbernullable

  OPTIONAL - MULTI-INVOICE AGE BUCKET PRICING (PRICING ZONE 180-DAY THRESHOLD)

  The portion of AmountToRecover that is more than 6 months (180 days) overdue. This includes amounts that are 12+ and 24+ months overdue.

  This field is optional and can only be provided alongside AmountToRecoverOver12Months and AmountToRecoverOver24Months. It enables precise pricing tier selection based on the 180-day threshold. When omitted, the system falls back to deriving the threshold from AmountToRecoverOver12Months.

  Validation rules:

  • Must be ≤ AmountToRecover
  • Must be ≥ AmountToRecoverOver12Months
• amountToRecoverOver12Monthsnumbernullable

  OPTIONAL - MULTI-INVOICE AGE BUCKET PRICING

  The portion of AmountToRecover that is more than 12 months overdue. This includes amounts that are 24+ months overdue.

  If provided, AmountToRecoverOver24Months must also be provided. Both fields must be provided together or both omitted.

  Used to calculate blended age uplift for multi-invoice cases:

  • Amount under 12 months = AmountToRecover - AmountToRecoverOver12Months
  • Amount 12-24 months = AmountToRecoverOver12Months - AmountToRecoverOver24Months
  • Amount over 24 months = AmountToRecoverOver24Months

  Blended uplift formula: ((A12-A24)×10 + A24×20) / AmountToRecover where A12 = AmountToRecoverOver12Months, A24 = AmountToRecoverOver24Months

  Validation rules:

  • Must be ≤ AmountToRecover
  • Must be ≥ AmountToRecoverOver24Months
• amountToRecoverOver24Monthsnumbernullable

  OPTIONAL - MULTI-INVOICE AGE BUCKET PRICING

  The portion of AmountToRecover that is more than 24 months overdue.

  If provided, AmountToRecoverOver12Months must also be provided. Both fields must be provided together or both omitted.

  Used to calculate blended age uplift for multi-invoice cases. See AmountToRecoverOver12Months for full details on the calculation.

  Validation rules:

  • Must be ≤ AmountToRecoverOver12Months
  • Must be ≤ AmountToRecover
• 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 and prices on them, so send them instead of — never alongside — AmountToRecover, the AmountToRecoverOver6/12/24Months fields, or DueDate. Supplying any of those together with ClaimLines 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. Claim lines are a pricing input only and are never stored.

  +Show 3 child attributes
• dueDatedatetimenullable

  Optional invoice due date. Mutually exclusive with age bucket fields and with ClaimLines. If provided, Debitura computes the age surcharge internally — no need to calculate age buckets. Cannot be a future date.

• returnUrlstringnullable

  Optional: URL the creditor user should land on after completing any pending signing chain (SDCA upgrade / PoA / JPA / KYC) on the Debitura Creditors app. Embedded, URL-encoded, into PreviewCaseResponseApiViewModel.Result.SigningHandoff.CombinedSigningUrl (when at least one signing-related required action is present) and into BusinessErrorResponseApiDTO.SigningHandoff.CombinedSigningUrl / InvoiceDto.SigningHandoff.CombinedSigningUrl on POST /cases.

  Must be an absolute http(s) URL. Values that fail validation (relative URLs, non-http schemes, header-injection characters) are silently dropped — the combined URL is still emitted but without the returnUrl query parameter, and the Creditors app falls back to its own safe in-app default landing.

  Additive. Existing integrations that omit this field see the same behaviour as before.

  Max 2048 characters

Returns

200 Preview completed

• isEligibleboolean

  Whether the case is eligible for collection (a partner is available in the requested jurisdiction). If false, check IneligibilityReason for details.

• ineligibilityReasonstringnullable

  Explanation of why the case is not eligible (only present when IsEligible = false). Branch on IneligibilityReasonCode rather than on this text, which may be reworded.

• ineligibilityReasonCodestringnullable

  Stable machine-readable reason, present whenever IneligibilityReason is One of: NoGeographicCoverage, AmountBelowMinimum, AmountAboveMaximum, DebtorTypeNotCovered, NotCoveredByPartnerRules, ExcludedForClient, EligibilityUndetermined.

  Only NoGeographicCoverage means we have no partner in the jurisdiction. AmountBelowMinimum means the geography IS covered and only the claim amount fell short — do not advise the client to correct their address. EligibilityUndetermined is a transient failure on our side.

• applicableMinimumAmountnumbernullable

  What this claim would have to reach to be accepted, in the currency of the request; never below the platform minimum of 100 USD. Only present when no partner was matched, and not when the request currency cannot be priced. Null when no partner covering this case declares a minimum.

• applicableMinimumCurrencyCodestringnullable

  ISO code that ApplicableMinimumAmount is expressed in.

• marketMinimumAmountnumbernullable

  The smallest claim the marketplace takes for this jurisdiction and debtor type, in the currency of the request: the lowest partner floor, never below the platform minimum of 100 USD. A statement about the market, not about this claim: it is returned whether or not a partner was selected, and does not depend on the claim amount or on the caller. It is not the admission rules applied when a case is created. Null when no partner covers the market or the amount cannot be priced.

• marketMinimumCurrencyCodestringnullable

  ISO code that MarketMinimumAmount is expressed in.

• amountCheckUnavailableboolean

  True when a currency conversion needed to evaluate the claim amount was unavailable, so the amount-based part of this answer was NOT actually checked It can be true on an eligible answer: a partner matched only because amount conditions failed open while rates were down. Treat such an answer as provisional and retry rather than relying on the floor having been applied.

• jurisdictionobject

  Geographic jurisdiction information for the case.

  +Show 4 child attributes
• pricingPreviewobject

  Estimated pricing for the case, including age-based surcharges.

  +Show 6 child attributes
• requiresKycVerificationboolean

  Whether the resolved collection partner requires KYC verification before cases can be submitted. When true, the creditor must complete KYC verification before case creation. Use the case creation endpoint with a creditor ID to determine whether KYC is already on file.

• pendingActionsarray of objectsnullable

  Structured list of actions the creditor will need to complete before (or as part of) submitting cases for the matched collection partner. Always present — empty when nothing is pending.

  At preview time the request is creditor-less, so this list reflects the matched partner's hard requirements (e.g. PoA per partner, KYC if the partner is configured for it). Creditor-specific items such as SDCA upgrade are returned only when the API has creditor context.

  Additive over RequiresKycVerification — old clients that only read RequiresKycVerification are unaffected.

  +Show 3 child attributes
• combinedSigningUrlstringnullable

  Always null on /cases/preview because preview is creditor-less — no concrete creditor signing state exists to chain. The structured PendingActions array on this response indicates which step types the matched partner will require ahead of onboarding.

  The canonical placement for the combined-signing URL on POST /cases responses is the nested SigningHandoff envelope (a SigningHandoffDto on both BusinessErrorResponseApiDTO and InvoiceDto). The combined URL is populated on POST /cases responses, where the creditor IS identified: <list type="bullet"><item><description>422 with at least one signing-related business error (MissingDebtCollectionContract, MissingPowerOfAttorney, MissingKycVerification) — see BusinessErrorResponseApiDTO.SigningHandoff.CombinedSigningUrl.</description></item><item><description>200 with AllowPendingContracts=true when signings remain — see InvoiceDto.SigningHandoff.CombinedSigningUrl.</description></item></list> Both POST surfaces use the same Creditors-app /Signing/PendingContracts entry point and walk the SDCA-upgrade → PoA → JPA → KYC chain end-to-end.

  This flat CombinedSigningUrl field on /cases/preview is preserved as-is for backward compatibility (it is always null in practice).

Errors

See Error handling.