Call lifecycle and status values

A call can move through dialing, dialed, initiated, ringing, and answered before ending; canceled, dial_failed, compliance_blocked, configuration_error, and ended represent outcomes that require no normal forward transition.

Updated Jul 14, 2026v1Reviewed by engineering and product

Treat the stored status as the current state of the call and the ordered events array as its audit trail. Carrier events can arrive asynchronously, so consumers must tolerate repeated reads and should not assume that every intermediate state will be observed.

Call lifecycle from dialing to ended with blocked, failed, and canceled outcomes

Status reference

Status	Meaning	Terminal?
`dialing`	The request passed preflight and CallOnline is starting the dial operation.	No
`dialed`	The carrier accepted the dial request and returned call identifiers.	No
`initiated`	The carrier reported that the call was initiated.	No
`ringing`	The destination is being alerted.	No
`answered`	The destination answered and the connected call can proceed.	No
`ended`	The connected or attempted call has ended.	Yes
`canceled`	A cancel request ended the active CallOnline call.	Yes
`dial_failed`	The dial operation failed before a normal connected lifecycle.	Yes
`compliance_blocked`	Product preflight rejected the call before dialing.	Yes
`configuration_error`	Required calling or usage-tracking configuration was unavailable before dialing.	Yes

The normal path is not guaranteed to visit every non-terminal status. For example, a fast carrier update may make polling observe dialed and then answered without seeing initiated or ringing.

Status versus events

GET /v1/calls/{callId} returns:

{
  "call": {
    "id": "call_opaque_identifier",
    "status": "answered",
    "createdAt": "2026-07-14T14:30:00.000Z",
    "answeredAt": "2026-07-14T14:30:08.000Z",
    "endedAt": null,
    "errorCode": null,
    "errorMessage": null
  },
  "events": [
    { "eventType": "dial", "payload": {} },
    { "eventType": "dialed", "payload": {} },
    { "eventType": "call.answered", "payload": {} }
  ]
}

Use call.status for the current decision and preserve event IDs or delivery IDs for audit and deduplication. Event names can be carrier-oriented (call.answered) or product-oriented (dialed, configuration_error). Do not convert event strings into the call-status enum without an explicit mapping.

Cancellation behavior

Canceling an active call returns canceled. If the stored call is already ended, canceled, or compliance_blocked, the cancel endpoint returns the existing state with alreadyFinal: true. A missing call returns 404.

Recommended application mapping

Show dialing, dialed, initiated, and ringing as in progress.
Show answered as connected.
Show ended as finished.
Show canceled as stopped by request.
Send dial_failed, compliance_blocked, and configuration_error to an exception path that displays the supplied error or block details.

Do not label compliance_blocked as a transient carrier failure. It requires a policy or evidence correction, not an automatic retry.