Case Identifiers

Every case has three identifiers. Use the right one for each situation.

Field	Source	Example	Use For
id	Debitura	3fa85f64-5717-4562-b3fc-2c963f66afa6	API calls, webhook correlation
reference	Debitura	Q8OAXF3W	Display, support conversations
creditorReference	You	INV-2024-001	Your internal tracking

How They Work

id is the UUID assigned when you create a case. Use it for API operations (GET /cases/{id}) and correlating webhook events (Customer API webhooks, Referral Partner API webhooks).

reference is an 8-character human-readable code. Use it in your UI and when contacting support. On the Customer API you can also look up cases by reference: GET /cases/case-reference/{reference}.

creditorReference is your identifier (typically an invoice number). It must be unique per creditor (enforced at case creation — a duplicate value returns a DuplicateReference validation error) and prevents duplicate case creation.

Webhook Correlation

Webhook payloads include caseId and reference, but not your creditorReference. To correlate events back to your system:

Option 1: Store a mapping when creating cases

1. POST /cases with creditorReference: "INV-2024-00789"
2. Response includes id: "abc-123-..."
3. Store mapping: { debituraCaseId: "abc-123-...", yourRef: "INV-2024-00789" }
4. When webhook arrives with caseId, look up yourRef from the mapping

Option 2: Fetch on demand

1. Receive webhook with caseId: "abc-123-..."
2. GET /cases/abc-123-...
3. Response includes creditorReference: "INV-2024-00789"

Option 1 is faster (no API call per webhook). Option 2 is simpler if you don't want to maintain a mapping table.

Lookup Endpoints

Identifier	Endpoint	Available in
id	GET /cases/{id}	Customer API, Referral Partner API
reference	GET /cases/case-reference/{reference}	Customer API
creditorReference	GET /cases/by-creditor-reference/{creditorReference}	Customer API

Both lookup-by-reference endpoints return the same InvoiceApiDTO shape as GET /cases/{id} and return 404 when no matching case is found for the authenticated creditor. The by-creditor-reference endpoint additionally returns 400 when the path value is empty.

For webhook payload details, see the Customer API or Referral Partner API webhooks guide. For handling duplicates and retries, see Idempotency.