Case Lifecycle

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

Business context: See Cases in Debitura for what each status means operationally.

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

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 for what each outcome means and when it applies.

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

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 or Referral Partner Webhooks 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:

GET /cases/{caseId}
XApiKey: YOUR_API_KEY

Integration Pattern

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.

When closeCode is Paid or Partially paid, cross-reference with payment.created events for reconciliation. See Payments and Reconciliation.