v1

latestOpenAPI 3.0.42026-08-042281222.0 KB

PreviewCases

Preview case pricing

Preview the success fee pricing for a potential case without creating it.

What This Endpoint Returns:

IsEligible - Whether the case can be submitted (partner available in this jurisdiction)
PricingPreview - Estimated success fee with base rate and any age-based surcharges
Jurisdiction - Geographic details for the matched jurisdiction

Use This To:

Show your clients the Debitura success fee before they onboard
Check if a jurisdiction is supported before starting the onboarding flow
Display age-adjusted pricing for aged debt portfolios

Required Fields:

AmountToRecover - Total principal amount
CurrencyCode - ISO 4217 currency code (e.g., 'GBP', 'EUR', 'USD')
Debtor.Type - 'Company' or 'Private'
Debtor.CountryAlpha2 - ISO 3166-1 alpha-2 country code
Debtor.StateAlpha2 - Required for US cases only (e.g., 'CA', 'NY')

Age-Based Pricing (Optional)

Single invoice — pass dueDate: The simplest way to get age-adjusted pricing. Provide the invoice due date (ISO 8601, e.g. 2024-01-15) and Debitura computes the age surcharge internally. Cannot be a future date. Mutually exclusive with age bucket fields.

Multi-invoice portfolio — pass age buckets: For portfolios with invoices at different ages, pass the portion of the total that falls into each age bracket:

AmountToRecoverOver12Months and AmountToRecoverOver24Months must be provided together
AmountToRecoverOver6Months is optional but improves pricing tier accuracy at the 180-day threshold; can only be provided alongside the 12/24-month fields, must be >= AmountToRecoverOver12Months, and must be <= AmountToRecover

dueDate and age bucket fields are mutually exclusive — use one or the other. When no age fields are provided, base pricing is returned without age surcharge.

Important Notes:

This endpoint does NOT create a case — it only previews pricing
Pricing is based on the referral partner's agreed rate (jurisdiction pricing zone rate if applicable)
No creditor or client account is needed

post/cases/preview

Request body

amountToRecovernumber double required

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.

currencyCodestring required

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

amountToRecoverOver6Monthsnumber double nullable

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

amountToRecoverOver12Monthsnumber double nullable

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

amountToRecoverOver24Monthsnumber double nullable

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

dueDatestring date-time nullable

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

returnUrlstring nullable

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.

Example request

{
  "amountToRecover": 4000,
  "currencyCode": "EUR",
  "debtor": {
    "type": "Company",
    "countryAlpha2": "PT"
  },
  "dueDate": "2026-04-22"
}

Response

Preview completed

isEligibleboolean

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

ineligibilityReasonstring nullable

Explanation of why the case is not eligible (only present when IsEligible = false). Common reasons: "We don't have an exclusive pre-legal partner in the provided jurisdiction."

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.

combinedSigningUrlstring nullable

Always null on /cases/preview because preview is creditor-less — no concrete creditor signing state exists to chain. The structured Debitura.Web.ReferralPartnerApi.Models.Cases.ReferralPartnerPreviewCaseResponse.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).