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.

reference is an 8-character human-readable code. Use it in your UI and when contacting support. 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 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
id	GET /cases/{id}
reference	GET /cases/case-reference/{reference}
creditorReference	No direct endpoint—use your stored mapping or list cases

For webhook payload details, see Webhooks. For handling duplicates and retries, see Idempotency.