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 and Collection Partner 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 within the same data classification. A production case and a test case may share the same value, but a duplicate within production or within test data is rejected at case creation. (The specific error contract differs by API: the Referral Partner API's batch case-creation flow reports it as a DuplicateReference entry inside FailedCases.)

Webhook Correlation

Webhook payloads include caseId and reference, but not your creditorReference — with one exception: the Referral Partner API's case.created payload does include creditorReference. (The Referral Partner API's case.updated and case.closed payloads, and all Customer API webhook payloads, omit it.) The Referral Partner API's cases.replay_failed event also carries creditorReference — but no caseId or reference, because no case was created. 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, Collection Partner API
reference	GET /cases/case-reference/{reference}	Customer API, Collection Partner API
creditorReference	GET /cases/by-creditor-reference/{creditorReference}	Customer API
creditorReference	GET /cases/by-creditor-reference?reference={reference}&creditorId={creditorId}	Collection Partner API

These lookups return the same case-detail shape as GET /cases/{id}. They return 404 when no matching case exists within the authenticated caller's scope. Customer API lookups are scoped to the authenticated creditor; Collection Partner API lookups are scoped to the authenticated partner, and its creditorReference lookup also requires creditorId. Invalid or missing required identifiers return 400.

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