Source: https://docs.debitura.com/clients/integration-guides/track-case-status

# Track Case Status

Monitor case progress through webhooks or polling.

**Business context:** See [Case Status & Email Updates](https://support.debitura.com/en/articles/13886054-clients-case-status-email-updates-explained) for what each status change means operationally.

<a id="key-fields"></a>

## Key Fields

| Field | Description |
| --- | --- |
| `lifecycle` | Current state (e.g., `Active`, `Paused`, `Closed`) |
| `closeCode` | Outcome reason (only when `Closed`) |
| `currentEngagementPhase` | Collection track: `Pre-legal`, `Legal`, `Enforcement`, or `null`. A separate axis from `lifecycle` — see [Engagement Phase](https://docs.debitura.com/developer-concepts/engagement-phase.md). |

See [Case Lifecycle](https://docs.debitura.com/developer-concepts/case-lifecycle.md) for all lifecycle states and close codes.

<a id="webhooks-recommended"></a>

## Webhooks (Recommended)

Subscribe to `case.updated` and `case.closed` events for real-time notifications.

See [Webhooks](https://docs.debitura.com/clients/integration-guides/webhooks.md) for setup, payloads, and event details.

<a id="polling"></a>

## Polling

Query the case endpoint when you need current status:

```http
GET https://customer-api.debitura.com/cases/{caseId}
XApiKey: YOUR_API_KEY
```

For bulk checks, filter by lifecycle:

```http
GET https://customer-api.debitura.com/cases?statuses=Active
XApiKey: YOUR_API_KEY
```

<a id="look-up-a-case-by-your-own-reference"></a>

### Look up a case by your own reference

If you only know your `creditorReference` (the value you sent on case creation), use the dedicated lookup endpoint instead of paginating `/cases`:

```http
GET https://customer-api.debitura.com/cases/by-creditor-reference/{creditorReference}
XApiKey: YOUR_API_KEY
```

Returns the same case object as `GET /cases/{caseId}`. Returns `404` if no case matches the reference for the calling creditor, and `400` if the reference is empty. See [Case Identifiers](https://docs.debitura.com/developer-concepts/case-identifiers.md) for when to use each identifier.

<a id="send-chat-messages"></a>

## Send chat messages

Reply to the collection partner from your own UI with `POST /cases/{id}/chats` on the Customer API:

```http
POST https://customer-api.debitura.com/cases/{id}/chats
XApiKey: YOUR_API_KEY
Content-Type: application/json

{
  "message": "Attached the signed delivery note from January.",
  "userEmail": "agent@acme.com"
}
```

Identify the sending team member with **either** `userEmail` **or** `userId` — at least one is required. `userEmail` is the recommended form: pass the email of an active member of your team. The legacy `userId` (UUID) field still works but is deprecated. List valid users with `GET /users` on the Customer API. If neither field is provided, the request returns `400` with error `MissingUserIdentifier`. The message appears as a creditor message to the collection partner. Subscribe to the [`chat.created`](https://docs.debitura.com/clients/integration-guides/webhooks.md#chatcreated) webhook to receive partner replies in real time.

To track payments as they land on cases, see [Payments and Reconciliation](https://docs.debitura.com/clients/integration-guides/payments-and-reconciliation.md).

<a id="exclusive-collection-period"></a>

## Exclusive collection period

Every case response from `GET /cases/{caseId}` includes an `exclusivePeriodEndDate` field (ISO 8601, `null` if no period applies).

**Business context:** See [Collection period & exclusivity](https://support.debitura.com/en/articles/13638743-collection-period-exclusivity-what-it-means-and-when-you-can-withdraw-a-case) for what this means and when a case can be withdrawn.

For the full chain with extension history, call the dedicated endpoint:

```http
GET https://customer-api.debitura.com/cases/{caseId}/exclusive-period
XApiKey: YOUR_API_KEY
```

```json
{
  "engagementStartDate": "2025-07-15T00:00:00Z",
  "currentEndDate": "2026-07-15T00:00:00Z",
  "daysRemaining": 65,
  "status": "Active",
  "extensions": [
    {
      "type": "Payment",
      "eventDate": "2025-10-20T00:00:00Z",
      "newEndDate": "2026-07-15T00:00:00Z"
    }
  ]
}
```

| Field | Description |
| --- | --- |
| `status` | `Active`, `Expired`, or `Terminated`. `Expired` means `currentEndDate` has passed; `Terminated` means the period ended early (partner change or withdrawal). The response derives `Active`/`Expired` from the date, so resolving a case does not by itself force this field to `Expired`. |
| `daysRemaining` | Days until `currentEndDate`, negative after expiry. Always `0` for a `Terminated` period. |
| `extensions[].type` | What triggered the extension: `Payment`, `PromiseToPay`, `PaymentAgreement`, or `Manual` |

Returns `404` when the case has no collection period (quote-based cases or cases not yet assigned to a partner).