Source: https://docs.debitura.com/developer-concepts/case-identifiers

# 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 |

<a id="how-they-work"></a>

## 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](https://docs.debitura.com/clients/integration-guides/webhooks.md), [Referral Partner API webhooks](https://docs.debitura.com/referral-partners/integration-guides/webhooks.md)).

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

<a id="webhook-correlation"></a>

## 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**

```text
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**

```text
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.

<a id="lookup-endpoints"></a>

## 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](https://docs.debitura.com/clients/integration-guides/webhooks.md) or [Referral Partner API](https://docs.debitura.com/referral-partners/integration-guides/webhooks.md) webhooks guide. For handling duplicates and retries, see [Idempotency](https://docs.debitura.com/developer-concepts/idempotency.md).