Preview Case Pricing

Look up the Debitura success fee for a potential case before your client onboards. No case is created and no client account is required.

Overview

Call POST /cases/preview to check whether a jurisdiction is covered and what the success fee will be. Use this in your sales or onboarding flow to show clients their expected fee upfront, or to gate the onboarding flow based on coverage.

Pricing returned reflects your referral partner's agreed rate — including zone pricing where applicable.

Business context: See Success Fees for how Debitura calculates pricing, including age-based surcharge tiers.

Implementation

Check eligibility and pricing

POST https://referral-api.debitura.com/cases/preview
XApiKey: YOUR_API_KEY
Content-Type: application/json

{
  "amountToRecover": 50000,
  "currencyCode": "GBP",
  "debtor": {
    "type": "Company",
    "countryAlpha2": "GB"
  }
}

For US debtors, debtor.stateAlpha2 is required to resolve the correct jurisdiction (e.g. "CA", "NY").

Read the response

Eligible:

{
  "isEligible": true,
  "ineligibilityReason": null,
  "requiresKycVerification": false,
  "jurisdiction": {
    "id": 42,
    "name": "United Kingdom",
    "countryAlpha2": "GB",
    "stateAlpha2": null
  },
  "pricingPreview": {
    "baseSuccessFeePercentage": 18.0,
    "ageSurchargePercentage": 0.0,
    "totalSuccessFeePercentage": 18.0,
    "currencyCode": "GBP",
    "pricingSource": "Standard agreement",
    "pricingSourceDescription": "18% success fee — Standard Debitura collection rates (International zone, $10,000–$49,999 tier)"
  },
  "pendingActions": [
    { "type": "PoA", "collectionPartnerId": "8a4f9c0e-..." }
  ],
  "combinedSigningUrl": null
}

requiresKycVerification indicates whether the matched collection partner requires KYC verification before cases can be submitted. When true, submit KYC data via the KYC Verification endpoint before creating cases.

The response also includes a pendingActions array that lists the signing-related steps the matched partner will require ahead of onboarding (typically a per-creditor Power of Attorney, plus a Kyc entry when the matched partner requires it). The list is always present and empty when nothing is pending. Each entry has the shape { "type": "PoA" | "Kyc", "collectionPartnerId": "<guid>" }. Because the preview is creditor-less, creditor-specific items such as SDCA upgrade are not included here — they surface on POST /cases via the signingHandoff object.

The response also carries a top-level combinedSigningUrl field, which is reserved for future use and always null on POST /cases/preview. The chain-walking URL is only emitted on POST /cases responses (where the creditor is identified) — see Case Submission.

You may pass an optional returnUrl on the request body. It is accepted on /cases/preview for forward compatibility and to keep the request shape identical to POST /cases, but it is never read by the preview endpoint — the controller has no dependency on the URL-safety logic used elsewhere, so returnUrl has no effect on the preview response regardless of its value. It has a 2048-character max length; exceeding it triggers standard model validation and returns an automatic 400, it is not silently dropped.

totalSuccessFeePercentage is the definitive rate to use — it is baseSuccessFeePercentage + ageSurchargePercentage with all age adjustments already applied. Show this to clients and use it in calculations.

pricingSource tells you which pricing rule was applied. pricingSourceDescription gives a human-readable explanation including the fee, zone, and bracket. Possible pricingSource values:

Value	Meaning
`Standard agreement`	Default Debitura SDCA rates
`Creditor custom pricing`	Custom rate agreed between creditor and partner
`Managing partner custom pricing`	Custom rate agreed between managing partner and partner
`Jurisdiction custom pricing`	Referral partner zone rate for a specific jurisdiction
`Partner custom pricing`	Collection partner's own custom rate brackets
`Accepted quote`	Custom quote for legal or non-standard cases

Ineligible:

jurisdiction is always present — it reflects the resolved jurisdiction even when no partner is available there. When isEligible is false, pricingPreview is null and ineligibilityReason explains why.

{
  "isEligible": false,
  "ineligibilityReason": "We don't have an exclusive pre-legal partner in the provided jurisdiction.",
  "jurisdiction": {
    "id": 15,
    "name": "Greenland",
    "countryAlpha2": "GL",
    "stateAlpha2": null
  },
  "pricingPreview": null
}

Do not proceed to onboarding for ineligible cases.

Age-based pricing

By default, the endpoint returns the base rate only. Claim Amount and Age explains the three supported aging modes:

Single invoice — pass dueDate (simplest)
Multi-invoice ledger — pass claimLines and let Debitura derive the total and age buckets (recommended)
Pre-calculated portfolio — pass amountToRecover and cumulative age bucket fields

dueDate, age bucket fields, and claimLines are mutually exclusive on pricing preview.

Single invoice: pass dueDate

Pass the invoice due date as an ISO 8601 date string (YYYY-MM-DD). Debitura computes the age surcharge internally — no bucket arithmetic needed.

Example — single invoice, 14 months overdue:

POST https://referral-api.debitura.com/cases/preview
XApiKey: YOUR_API_KEY
Content-Type: application/json

{
  "amountToRecover": 50000,
  "currencyCode": "GBP",
  "dueDate": "2024-01-15",
  "debtor": {
    "type": "Company",
    "countryAlpha2": "GB"
  }
}

Response:

{
  "isEligible": true,
  "ineligibilityReason": null,
  "requiresKycVerification": true,
  "jurisdiction": {
    "id": 42,
    "name": "United Kingdom",
    "countryAlpha2": "GB",
    "stateAlpha2": null
  },
  "pricingPreview": {
    "baseSuccessFeePercentage": 18.0,
    "ageSurchargePercentage": 8.0,
    "totalSuccessFeePercentage": 26.0,
    "currencyCode": "GBP",
    "pricingSource": "Standard agreement",
    "pricingSourceDescription": "18% success fee — Standard Debitura collection rates (International zone, $10,000–$49,999 tier)"
  }
}

Portfolio: blended age pricing

For portfolios with invoices at different ages, pass the portion of the total that falls into each age bucket. amountToRecoverOver12Months and amountToRecoverOver24Months must always be provided together.

amountToRecoverOver6Months is optional — it improves zone tier accuracy for the 180-day threshold and must satisfy:

Can only be provided alongside both amountToRecoverOver12Months and amountToRecoverOver24Months
Must be >= amountToRecoverOver12Months (the 6-month bucket includes the 12-month bucket)
Must be <= amountToRecover (must be a subset of the total)

Example — portfolio with mixed ages:

POST https://referral-api.debitura.com/cases/preview
XApiKey: YOUR_API_KEY
Content-Type: application/json

{
  "amountToRecover": 100000,
  "currencyCode": "GBP",
  "amountToRecoverOver6Months": 60000,
  "amountToRecoverOver12Months": 40000,
  "amountToRecoverOver24Months": 15000,
  "debtor": {
    "type": "Company",
    "countryAlpha2": "GB"
  }
}

The blended ageSurchargePercentage and resulting totalSuccessFeePercentage are calculated automatically.

Portfolio: pass claim lines

When you have invoice-level outstanding balances, send those invoices instead of calculating the total and buckets yourself:

{
  "currencyCode": "GBP",
  "claimLines": [
    { "dueDate": "2024-01-15", "amount": 423.42, "reference": "INV-1001" },
    { "dueDate": "2025-05-02", "amount": 700.87, "reference": "INV-1042" }
  ],
  "debtor": {
    "type": "Company",
    "countryAlpha2": "GB"
  }
}

Each amount is the invoice's outstanding balance after payments and credit notes. Omit amountToRecover, dueDate, and all age bucket fields when sending claimLines. The endpoint accepts at most 1,000 lines and returns indexed validation keys such as ClaimLines[2].DueDate.

Error handling

Status	Field	Cause	Action
`401`	—	Missing or invalid `XApiKey`	Verify the API key is present in the request header
`400`	`amountToRecover`	Zero or negative	Validate positive numbers before calling
`400`	`debtor.type`	Value other than `Company` or `Private`	Check the debtor type mapping in your system
`400`	`debtor.countryAlpha2`	Unrecognised country code	Validate against ISO 3166-1 alpha-2
`400`	`debtor.countryAlpha2`	US debtor missing `stateAlpha2`	Require `stateAlpha2` when `countryAlpha2` is `US`
`400`	`currencyCode`	Not a recognised 3-letter ISO 4217 code	Validate length (must be exactly 3 chars) and value
`400`	`dueDate`	Future date	Due date cannot be in the future
`400`	`dueDate`	Combined with any age bucket field	Use `dueDate` or age bucket fields — not both
`400`	`claimLines`	Empty, over 1,000 lines, or combined with another amount-and-age mode	Send 1–1,000 lines and omit `amountToRecover`, `dueDate`, and age bucket fields
`400`	`ClaimLines[n].amount`	Zero, negative, or more than 2 decimal places	Send the positive outstanding balance with at most 2 decimal places
`400`	`ClaimLines[n].dueDate`	Missing, before 2000-01-01, or in the future	Send a valid invoice due date
`400`	`amountToRecoverOver12Months`	Provided without `amountToRecoverOver24Months` (or vice versa)	Always send the 12- and 24-month fields together
`400`	`amountToRecoverOver6Months`	Provided without `amountToRecoverOver12Months` and `amountToRecoverOver24Months`	Over6 requires both 12- and 24-month fields
`400`	`amountToRecoverOver6Months`	Less than `amountToRecoverOver12Months`	The 6-month bucket must include the 12-month bucket
`400`	`amountToRecoverOver6Months`	Exceeds `amountToRecover`	Age bucket values must be subsets of the total
`400`	`amountToRecoverOver12Months`	Exceeds `amountToRecover`	Age bucket values must be subsets of the total
`400`	`amountToRecoverOver24Months`	Exceeds `amountToRecoverOver12Months`	The 24-month bucket must be a subset of the 12-month bucket
`400`	any age field	Negative value	All age bucket values must be non-negative

400 responses come in three shapes:

Field-keyed { "fieldName": ["error message"] } — age-bucket and dueDate validation.
Structured ApiErrorResponseDto { "error", "message", "businessErrors": [] } — value-level business validations (amountToRecover, debtor.type, currencyCode, debtor.countryAlpha2/state).
ASP.NET ProblemDetails — model-binding errors (e.g. wrong field type, malformed JSON).

Once pricing is confirmed, continue with Client Onboarding. See the Preview case pricing API reference for the full request and response schema.

Overview​

Implementation​

Check eligibility and pricing​

Read the response​

Age-based pricing​

Single invoice: pass dueDate​

Portfolio: blended age pricing​

Portfolio: pass claim lines​

Error handling​