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

# Case Lifecycle

Reference for case lifecycle states and close codes returned by the API.

**Business context:** See [Cases in Debitura](https://support.debitura.com/en/articles/13638770-cases-in-debitura-what-they-are-and-how-they-move-through-the-lifecycle) for what each status means operationally.

<a id="lifecycle-states"></a>

## Lifecycle States

The `lifecycle` field indicates where a case is in the collection process.

| API Value | Description |
| --- | --- |
| `Pending contract signing` | Awaiting creditor contract signature. Returned when `allowPendingContracts: true` and SDCA or PoA contracts are unsigned. See [Creating a Case](https://docs.debitura.com/clients/integration-guides/create-a-case.md) for handling. |
| `Pending Verification Internal` | Internal review before partner assignment |
| `Pending Verification` | Partner reviewing case details |
| `More Info Required` | Additional information needed from creditor |
| `Collecting Quotes` | Legal escalation requested, awaiting partner quotes |
| `Pending Quote Selection` | Partner has submitted a quote, awaiting selection |
| `Active` | Case is being actively collected |
| `Paused` | Collection temporarily suspended |
| `Closed` | Case resolved (check `closeCode` for outcome) |
| `Merged` | Case was consolidated into another case (loser in a case merge). Read-only — no further collection actions are possible. |

<a id="close-codes"></a>

## Close Codes

The `closeCode` field indicates why a case was closed. Only present when `lifecycle` is `Closed`; `Merged` cases do not carry a `closeCode`.

| API Value | Category | Settable via `POST /cases/{id}/close`? |
| --- | --- | --- |
| `Paid` | Success | ✅ |
| `Partially paid` | Success | ✅ |
| `Case never started` | Rejected | ❌ System/internal only |
| `Invalid Case Data` | Rejected | ❌ System/internal only |
| `Debtor Insolvent/Bankrupt` | Uncollectable | ✅ |
| `Debtor Untraceable` | Uncollectable | ✅ |
| `Disputed – Legal Action Declined by Client` | Client decision | ✅ |
| `Withdrawn by Client` | Client decision | ✅ |
| `Pre-Legal Exhausted – No Payment` | Collection exhausted | ✅ |
| `Statute of Limitations Expired` | Collection exhausted | ✅ |
| `Settlement Rejected by Client` | Client decision | ✅ |
| `Unresponsive Client` | Client decision | ✅ |
| `Uneconomical to Pursue` | Collection exhausted | ✅ |
| `No Quotes Received` | System | ❌ System-assigned |
| `Quotes Expired – Not Accepted` | System | ❌ System-assigned |
| `Other` | Other | ✅ |

Only the 12 codes marked ✅ may be submitted as the `closeCode` on `POST /cases/{id}/close` — the endpoint validates the value against this exact allowlist and returns `400` for any other value, including the codes marked ❌ above, numeric representations, and unrecognized strings. Codes marked ❌ are assigned automatically by internal system or lifecycle flows and can appear in `closeCode` on a case you read back, but can never be set through this endpoint.

**Business context:** See [Case Close Codes](https://support.debitura.com/en/articles/13886994-case-close-codes-what-each-outcome-code-means-and-when-to-use-it) for what each outcome means and when it applies.

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

## API Response Fields

| Field | Type | Description |
| --- | --- | --- |
| `lifecycle` | string | Current lifecycle state |
| `closeCode` | string | Outcome reason (only when `lifecycle` is `Closed`; null for `Merged` and all other states) |
| `dateFinished` | datetime | When case was closed |
| `dateCollectionStarted` | datetime | When collection began |

<a id="tracking-changes"></a>

## Tracking Changes

Subscribe to webhook events to receive real-time lifecycle updates:

| Event | Trigger |
| --- | --- |
| `case.created` | Case first created — may be in `Pending contract signing` if SDCA not yet signed at creation time |
| `case.updated` | Lifecycle state changed |
| `case.closed` | Case reached `Closed` status |

See [Client Webhooks](https://docs.debitura.com/clients/integration-guides/webhooks.md) or [Referral Partner Webhooks](https://docs.debitura.com/referral-partners/integration-guides/webhooks.md) for event payloads and setup.

Transitions to `Merged` do not currently fire `case.updated` or `case.closed`. Poll the case endpoint if you need to detect merge transitions.

Alternatively, poll the case endpoint:

```http
GET /cases/{caseId}
XApiKey: YOUR_API_KEY
```

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

## Integration Pattern

```text
1. Receive case.updated or case.closed webhook
2. Validate signature (see webhook security)
3. Update status in your database
4. For closures, store closeCode for reporting
```

Use the event `id` field for [idempotent processing](https://docs.debitura.com/developer-concepts/idempotency.md#webhook-consumption).

When `closeCode` is `Paid` or `Partially paid`, cross-reference with `payment.created` events for reconciliation. See [Payments and Reconciliation](https://docs.debitura.com/clients/integration-guides/payments-and-reconciliation.md).