Case Submission

Submit debt collection cases for your linked clients using the Customer API.

Overview

After onboarding a client, you submit cases through the Customer API (not the Referral Partner API). This is the two-API architecture in action:

Mint a bearer token via the Referral Partner API
Submit the case via the Customer API using that token
Revenue is automatically attributed to your partnership

Step 1: Mint a Bearer Token

POST /oauth/token HTTP/1.1
Host: referral-api.debitura.com
XApiKey: YOUR_API_KEY
Content-Type: application/json

{
  "externalTenantId": "your-client-id"
}

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "tokenType": "Bearer",
  "expiresIn": 1800
}

The token is valid for 30 minutes and scoped to this specific client. See Authentication for caching and retry patterns.

Client must be onboarded

Token minting returns 404 if there is no active, non-archived client link for the supplied externalTenantId — typically because the client was never created or the link has been withdrawn/archived. A token is issued as soon as a non-deleted, non-archived link exists; it does not require the SDCA to be signed. Unsigned-contract handling happens later at case submission via allowPendingContracts (422 / PendingContractSigning), not at token minting.

Step 2: Submit the Case

Use the bearer token with the Customer API (different base URL):

POST /cases HTTP/1.1
Host: customer-api.debitura.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "currencyCode": "EUR",
  "amountToRecover": 5000.00,
  "date": "2025-06-01",
  "dueDate": "2025-07-01",
  "claimDescription": "Invoice INV-2025-001 for consulting services",
  "debtor": {
    "type": "Company",
    "name": "Debtor GmbH",
    "contactPerson": "Hans Mueller",
    "address": "Hauptstrasse 10",
    "city": "Munich",
    "zipCode": "80331",
    "countryAlpha2": "DE",
    "email": "billing@debtor.de"
  }
}

The case is automatically attributed to your partnership because you used a bearer token minted through the Referral Partner API.

Key fields

Field	Required	Notes
`currencyCode`	Yes	ISO 4217 (EUR, GBP, USD, etc.)
`amountToRecover`	Yes	Total principal amount
`date`	Yes	Invoice date (must not be in the future)
`dueDate`	No	When payment was due. Must not be in the future (today is allowed) and not earlier than `date`
`debtor.type`	Yes	`"Company"` or `"Private"`
`debtor.name`	Yes	Legal name
`debtor.countryAlpha2`	Yes	ISO 3166-1 alpha-2
`debtor.stateAlpha2`	US only	Required for US debtors (e.g. `"CA"`, `"NY"`)
`isTest`	No	Set `true` for test cases that won't trigger real collection

For the complete field reference and debtor validation rules, see Create a Case.

isTest vs isTestCase

You send isTest in the request body. The API returns isTestCase in the response. They represent the same flag -- the naming differs between request and response models.

Handling Pending Signing After Submission

When the linked client has not yet signed the SDCA or another required contract and the request is sent with allowPendingContracts: true, the case is created in the PendingContractSigning lifecycle and the response includes a signingHandoff object:

{
  "lifecycle": "PendingContractSigning",
  "signingHandoff": {
    "combinedSigningUrl": "https://app.debitura.com/Signing/PendingContracts?returnUrl=..."
  },
  ...
}

Use signingHandoff.combinedSigningUrl to render a signing prompt before the user can continue. The URL walks the full pending chain (SDCA upgrade → PoA → JPA → KYC) in one flow, so no client-side decision logic is needed. When everything is already signed, signingHandoff is null.

Pass returnUrl (absolute http(s) URL, max 2048 chars) on the POST /cases request to deep-link the user back to your app once signing is complete. Invalid values are silently dropped and the URL falls back to the Creditors-app default landing.

After a successful signing completion, Debitura appends completed=true to your returnUrl before redirecting (e.g. https://yourapp.com/done?completed=true). If the user abandons the flow without completing it, the redirect happens without this parameter. Use this to distinguish completed flows from abandoned ones.

For pricing previews before submission, see Preview Case Pricing — the preview endpoint reports which signing steps the matched partner will require via a pendingActions array.

Submitting Cases During Onboarding

You can include cases directly in the POST /clients request. Debitura validates all cases upfront:

If all cases are valid and have matching collection partners, they're created alongside the client
Cases without available partners are reported in CaseResults.FailedCases (the client is still created)
If validation errors exist (missing fields, duplicate references), the entire request returns 400

This is useful for platforms where the user submits their first invoice at the same time as signing up.

See Client Onboarding — Including Cases for details.

Uploading Files to a Case

Upload supporting documents to an existing case with POST /cases/{caseId}/files on the Referral Partner API. The case must belong to one of your linked clients.

POST https://referral-api.debitura.com/cases/{caseId}/files?sendChatNotification=true
XApiKey: YOUR_API_KEY
Content-Type: multipart/form-data

file: <binary>

Parameter	Type	Notes
`file`	form-data	Max 25 MB. Allowed extensions: `.pdf`, `.doc`, `.docx`, `.xls`, `.xlsx`, `.csv`, `.txt`, `.jpg`, `.jpeg`, `.png`
`sendChatNotification`	query (bool)	Defaults to `true`. When `true`, a system chat message (`"System message: New file uploaded under 'Files': <filename>"`) is posted to the case thread so the assigned collection partner sees the upload in-app. Set `false` for silent uploads

Returns 200 on success with { id, fileName, dateCreated }. Returns 404 if the case is not linked to one of your clients, 413 if the file exceeds 25 MB, and 415 for unsupported file types.

Submitting KYC Verification

Submit director identity data for a linked client with POST /clients/{externalTenantId}/kyc-verification. See KYC Verification for the payload. Returns 201 Created with the saved KYC record, or 404 if the client is not linked to your partner account.

The endpoint supports an optional ?sendChatNotification=true (default true) query flag. When enabled, a system chat message ("System message: KYC/AML information provided — find it under the 'KYC Status' section") is posted on each of the client's cases that are not yet closed (Active, Paused, or NeedsAdditionalDetails lifecycle) and are assigned to a collection partner that requires KYC. Cases assigned to partners that don't require KYC are skipped, and closed cases are never touched. Pass false to submit silently.

Tracking Cases

After submission, track cases using either API:

What you need	API	Endpoint
All cases across all clients	Referral Partner	`GET /cases` (with API key)
Single case detail	Customer	`GET /cases/{id}` (with bearer token)
Real-time updates	Referral Partner	Webhooks (`case.created`, `case.updated`, `case.closed`)

Error Handling

Status	Common causes
`400`	Missing required fields, invalid debtor data, duplicate creditor reference
`401`	Expired bearer token — mint a new one and retry
`422`	Business rule violation (e.g. `MissingKycVerification`, `MissingPowerOfAttorney`, unsupported jurisdiction)

For 422 errors related to KYC, see KYC Verification.

See Create a Case for the full Customer API field reference and validation rules. See Preview Pricing to check the success fee before submitting, Webhooks to get notified when case status changes, and Revenue Tracking to track your earnings from submitted cases.

Overview​

Step 1: Mint a Bearer Token​

Step 2: Submit the Case​

Key fields​

Handling Pending Signing After Submission​

Submitting Cases During Onboarding​

Uploading Files to a Case​

Submitting KYC Verification​

Tracking Cases​

Error Handling​