Interpreting calls that did not complete

Two API fields explain why a call request ends up without concrete outcomes: stop_reason on the scheduled request says why the request stopped calling, and reason_why_no_concrete_outcomes on each call attempt within the request gives you granular details on why. Read stop_reason first for the request-level answer, then drill into the call attempts.

The mental model

A scheduled request keeps calling until it acquires a concrete outcome about the appointment. When it does, the request finishes with workflow_status COMPLETE and an empty stop_reason. A non-empty stop_reason always answers one question: why did the calling stop without a concrete outcome?

A continuing call request is not always able to acquire concrete outcomes. On every call attempt that ends without one, the attempt carries reason_why_no_concrete_outcomes: the reason that attempt could not get any information. So the two fields work at different levels, where 1 request can have many call attempts:

• Request level (stop_reason): why the request stopped calling, or in the default case, that it completed with concrete outcomes and no reason is needed.

• Attempt level (reason_why_no_concrete_outcomes): why this individual call attempt produced no concrete outcome. When a request stops without outcomes, the attempt-level reasons are the evidence trail behind the request-level stop.

Multiple call attempts per call job

A call job runs up to three call attempts. The outcomes returned at the job level come from one of those attempts, chosen by rank.

Attempts without generated outcomes are skipped. The rest are ranked by contact result: positive contact first, then an attempt that left a voicemail, then negative contact, then any other outcome. Ties go to the higher attempt number.

Ranking decides which attempt is reported, not whether the request continues. A positive-contact attempt with an insignificant outcome still outranks a later negative-contact attempt.

A third attempt happens only when neither of the first two ended the request: negative contact, or positive contact with an insignificant outcome such as a rep hangup. Terminal cases, such as the patient not being found at the clinic or the wrong location being called, end the request with no further attempts.

Where to read these fields

Poll GET /scheduler/call-jobs/{call_job_id} or bulk-read with POST /scheduler/call-jobs/query. Request-level fields are on each entry in scheduled_requests; attempt-level fields are on each entry in call_attempts, included only when include_call_attempts is true. The submission response returns neither field. Field references for every endpoint are in the Call Jobs API, and reason_why_no_concrete_outcomes is also returned on call attempts from the scheduled request endpoints.

Reading stop_reason

stop_reason is a nullable string on each scheduled request. Empty by default: concrete outcomes mean the request completed and no reason is needed. Read it together with workflow_status, which tells you whether the request is finished or still moving. When the request stopped without concrete outcomes, the value falls into one of three groups.

The call learned something definite

These stop reasons come with workflow_status COMPLETE. The call did not confirm attendance, but it learned something definite, so the request is done and will not call again.

The call could not finish

These reasons mean the calling workflow itself could not carry the request to an answer. Each one pairs with the workflow_status shown here and could lead to either re-ENQUEUEDing the request or setting it to ERROR

Internal safety hatches

Three values exist so a request can never get stuck when it cannot progress. They are not call failures.

One more null case to know: requests that end as CANCELLED or DO_NOT_CALL_BACK also carry no stop reason.

Drilling into the attempts: reason_why_no_concrete_outcomes

reason_why_no_concrete_outcomes is a nullable string on each call attempt. It is null when the attempt produced a concrete outcome: a recognized attendance or confirmation status, a rescheduled appointment, or a corrected date. Otherwise it explains why no information was obtained, chosen in this order:

1. The reason the call could not proceed, extracted from the transcript (the values below).

2. voicemail_left, when a voicemail message was left.

3. negative_contact, when the outcome recorded negative contact, such as no answer.

4. The attempt's error_classification, when the call itself failed (the last eight values in the table below).

Values for the extracted reason

Does not complete the request; it keeps calling because sometimes this is a rep level refusal.

The last eight rows are the attempt's error_classification values. A classification describes the failure and does not by itself decide whether the request is retried; that is the retry disposition. Classification is code-based only: it comes from the provider's SIP status code or service-level code, a mapped SIP code takes precedence over a service-level mapping, and a failure that matches neither returns UNKNOWN.

Note: When the provider reports SIP 404 for that situation, the attempt is classified DESTINATION_NOT_FOUND. The service-side values (SERVICE_UNAVAILABLE, SERVICE_CAPACITY_EXCEEDED, PROVIDER_TIMEOUT) describe our calling infrastructure or provider capacity, not the destination number. A null classification means none has been saved; attempts recorded before the field existed are not backfilled.

How the two levels connect

When an extracted reason completes the request, that same value becomes the request's stop_reason under workflow_status COMPLETE. A callback is never triggered by a reason value; it comes from separate callback evidence in the transcript, and the workflow writes CALLBACK_REQUESTED when one is needed.