Cases

Create collection case

Creates a new collection case for debt collection.

Test Mode:

Set isTest=true to create a test case (case IS created in the database but marked as test data)
Test cases are excluded from production metrics and can be easily filtered or deleted
Use test mode for integration testing and development

Debtor Rules:

debtor.type must be "Company" or "Private"
- Company → debtor.name is mandatory (company name)
- Private → debtor.name is mandatory (person's full name)

Geographic Rules:

debtor.countryAlpha2 (ISO 3166-1 alpha-2) is always required
debtor.state is a free-text region description
For US debtors: debtor.stateAlpha2 (two-letter state code) is also required – debtor.state is ignored in that scenario
Customer API submissions are limited to cases that match an exclusive pre-legal partner. If no eligible partner matches, the API returns 422 and does not create a case. The interactive portal's custom-quote/network-lead fallback is not available through this API.

Claim Amount and Aging — three ways to send it:

amountToRecover plus a single dueDate
amountToRecover plus the cumulative amountToRecoverOver6/12/24Months buckets
claimLines[] — send the unpaid invoices and let us do the arithmetic (recommended for multi-invoice claims)

"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 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 due date, or the request is rejected with a 400 on date. Send an explicit dueDate if you need a different case due date.

Optional Parameters:

creditorDivisionId - Assign case to a specific division (for multi-division creditors)
collectionPartnerId - Override automatic partner assignment with a specific collection partner
skipDebituraVerification - Skip internal verification steps (advanced use)
skipCreationEmails - Deprecated: accepted for backwards compatibility but ignored server-side. Creation emails are always suppressed in favour of the hourly CasesStarted digest
allowPendingContracts - Accept cases with unsigned contracts in 'PendingContractSigning' status instead of returning 422

Error Responses:

400: Field validation errors (returns JSON object with field names as keys and error arrays as values)
422: Business rule violations (returns BusinessErrorResponseApiDTO with type, message, and solutionUrl)
500: Server errors

post/cases

Headers

Idempotency-Keystring

Optional 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 Type: "IdempotencyConflict". Field-level 400 validation errors are not stored, so you may fix the request and retry with the same key.

Request body

currencyCodestring nullable required

datestring date-time

dueDatestring date-time nullable

commentsstring nullable

Optional comments about the case, e.g. payment history or communication context.

claimDescriptionstring nullable

Client provided description of the claim

creditorReferencestring nullable

creditorDivisionIdstring uuid nullable

amountToRecovernumber double

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, age uplift will be calculated from the invoice due date (single-invoice pricing).

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.

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

skipDebituraVerificationboolean

This skips the 'Pending verification' for Debitura and puts case straight to partner

skipCreationEmailsboolean

Deprecated — this field is accepted for backwards compatibility but is ignored server-side. Creation emails are always suppressed; the hourly CasesStarted digest is the single notification channel for all entry points.

allowPendingContractsboolean

When true, cases with unsigned contracts (SDCA/POA) are accepted in 'PendingContractSigning' status instead of being rejected with 422. The case transitions automatically once contracts are signed. Default: false (unsigned contracts return 422).

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.

tagstring nullable

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.

collectionPartnerIdstring uuid nullable

Optional: Specify a collection partner ID to handle this case. When provided, this partner will be used regardless of lead agent matching rules. The partner must be active and have coverage for the debtor's jurisdiction.

assignedUserEmailstring email nullable

Optional: Email address of the creditor team member to assign as the case owner. When provided, email notifications for this case will be sent only to this user instead of all team members. Must correspond to an active member of your team.

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 BusinessErrorResponseApiDTO.SigningHandoff.CombinedSigningUrl (on 422 with pending signings) and InvoiceDto.SigningHandoff.CombinedSigningUrl (on 200 when AllowPendingContracts=true with signings remaining).

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

{
  "currencyCode": "EUR",
  "amountToRecover": 4000,
  "date": "2026-03-01",
  "dueDate": "2026-03-09",
  "claimDescription": "Custom mobile app development services",
  "comments": "Outstanding invoice INV 2024 00789 for custom mobile app development delivered 15 Nov 2024; payment 60 days overdue despite two reminders.",
  "creditorReference": "INV‑2024‑00789",
  "isTest": true,
  "debtor": {
    "type": "Company",
    "name": "Acme Corp",
    "contactPerson": "John Doe",
    "companyRegistrationNumber": "12345678",
    "address": "123 Business Street",
    "zipCode": "1000",
    "city": "Lisbon",
    "state": "Lisbon",
    "countryAlpha2": "PT",
    "email": "billing@acme‑corp.com",
    "phone": "+351 123 456 789"
  }
}

Response

Case created

idstring uuid

dateCreatedstring date-time

dateUpdatedstring date-time nullable

referencestring nullable

creditorReferencestring nullable

creditorCommentsstring nullable

claimDescriptionstring nullable

grossAmountnumber double

remaindernumber double

interestFeesnumber double

reminderFeesnumber double

collectionFeesnumber double

totalAddedFeesnumber double

currencystring nullable

isTestCaseboolean

lifecyclestring nullable

dueDatestring date-time

datestring date-time

dateFinishedstring date-time nullable

dateCollectionStartedstring date-time nullable

closeCodestring nullable

currentEngagementPhasestring nullable

The current phase of the case's engagement: "Pre-legal", "Legal", or "Enforcement". A different axis from Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto.Lifecycle/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto.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.

claimTypestring nullable

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

creditorDivisionIdstring uuid nullable

blendedAgeUpliftPointsnumber double nullable

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

preLegalSuccessFeenumber double nullable

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.

solutionUrlstring nullable

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.

exclusivePeriodEndDatestring date-time nullable

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.

disputeStatusstring nullable

Whether the claim is disputed by the debtor. Returns the description of Debitura.Domain.Model.Receiveables.Invoices.Enums.ClaimDisputeStatus: "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.

Example response

{
  "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"
  }
}