Source: https://docs.debitura.com/developer-concepts/engagement-phase

# Engagement Phase

Reference for the `currentEngagementPhase` field returned by the Customer, Referral Partner, and Collection Partner APIs.

<a id="what-it-is"></a>

## What it is

`currentEngagementPhase` indicates which collection track a case's active engagement has reached: `Pre-legal`, `Legal`, `Enforcement`, or `null`.

This is a **separate axis from case status** (`lifecycle`) and `closeCode` — see [Case Lifecycle](https://docs.debitura.com/developer-concepts/case-lifecycle.md). A case can be `Active` in any of the three phases, and a case's phase does not change just because the case closes.

| Status | Phase | Meaning |
| --- | --- | --- |
| `Active` | `Enforcement` | Case is actively being worked, currently at the enforcement stage |
| `Active` | `Pre-legal` | Case is actively being worked, still amicable collection |
| `Closed` | `Legal` | Case closed while it was at the legal stage — phase does not reset on closure |
| `Paused` | `Pre-legal` | Case temporarily paused, no phase change from pausing |

Don't infer case status from phase, or phase from status — read both fields independently.

<a id="values"></a>

## Values

| API Value | Meaning |
| --- | --- |
| `Pre-legal` | Amicable collection — demand letters, calls, negotiation |
| `Legal` | Pursuing an enforceable title — lawsuit, payment order, court judgment |
| `Enforcement` | Exercising an existing title — wage garnishment, bailiff, asset seizure |
| `null` | No active engagement exists yet for this case |

<a id="null-is-not-the-same-as-pre-legal"></a>

### `null` is not the same as `Pre-legal`

`null` means no engagement has been created for this case at all — for example a lead still collecting quotes, a case pending contract signing, or one not yet assigned to a partner. It can also reflect a data-consistency gap. Treat `null` as its own distinct branch in your integration; never default it to `Pre-legal`.

<a id="phase-can-move-backwards--this-is-not-an-error"></a>

## Phase can move backwards — this is not an error

Phase advancement is not strictly one-directional. Two distinct, legitimate situations both move phase backwards:

1.  **Manual correction.** An admin can correct a case's phase in either direction (for example, `Legal` back to `Pre-legal` if a legal process is abandoned).
2.  **Partner hand-off.** When a case's collection partner changes, the new engagement always starts fresh at `Pre-legal` for the new partner — regardless of the phase the previous partner's engagement had reached.

Don't render phase as a strictly monotonic progress bar, and don't treat a backward move as a bug in your integration.

<a id="phase-persists-after-case-closure"></a>

## Phase persists after case closure

`currentEngagementPhase` reflects the case's **last-known** engagement phase. It is not cleared or reset when a case closes — a case closed while at `Legal` continues to report `Legal` afterward, independent of `lifecycle`/`closeCode`.

<a id="api-response-fields"></a>

## API Response Fields

| Field | Type | Nullable | Returned by |
| --- | --- | --- | --- |
| `currentEngagementPhase` | string | Yes | Customer API, Referral Partner API, Collection Partner API |

See the generated [API reference](https://docs.debitura.com/api.md) for the literal schema on each host.

<a id="integration-pattern"></a>

## Integration Pattern

```text
1. Read currentEngagementPhase as one of four independent branches: Pre-legal, Legal, Enforcement, null
2. Don't assume forward-only movement — handle a phase moving backwards as a normal update, not an error
3. Don't derive case status (lifecycle) from phase, or phase from status — they're orthogonal
4. Phase is not cleared when a case closes — don't discard it once lifecycle reaches Closed
```

There is no dedicated webhook event for phase changes today. `case.updated` fires on lifecycle changes but does not cover phase-only transitions. Poll `GET /cases/{id}` if you need to detect a phase change directly. The Customer and Collection Partner APIs also return the phase from `GET /cases/{id}/timeline`; the Referral Partner API does not expose that timeline endpoint.