> For a complete page index, fetch https://docs.synthflow.ai/llms.txt. For full documentation content, fetch https://docs.synthflow.ai/llms-full.txt. # Transfer outcome states > Reference for the call transfer outcome states and failed_reason values returned by the Synthflow API and the post-call webhook. Every [call transfer](/call-transfers) reports how it ended. Use these values to track how often transfers connect, drive fallback logic, and debug individual calls. * **[Outcome states](#outcome-states)** say whether the transfer connected, and if not, what got in the way. * **[Transfer modes](#transfer-mode-reactions)** decide what happens next: warm transfers can recover, while a cold transfer ends the call. * **[Failure reasons](#failure-reasons)** name the specific cause, such as a busy line, an IVR menu, or a wrong number. ## Where the values appear The outcome is saved on the transfer action of each call: * **[Get a call](/api-reference/platform-api/calls/get-phone-call) and [List calls](/api-reference/platform-api/calls/list-calls)** return it in `executed_actions`, keyed by action name, as `return_value.status` and `return_value.failed_reason`. * **The [post-call webhook](/webhooks#webhook-response-example)** sends the same `executed_actions` object. * **[Call logs](/logs#call-logs)** show each call's transfer attempts and whether they succeeded, and the [SIP ladder](/sip-call-ladder#warm-transfers) shows the signaling of each warm transfer attempt. * **The [action execution timeline](/webhooks#action-execution-timeline)** records a `failed_reason` for every failed attempt, so a transfer that retried shows the cause of each try. Its `status` field is `started`, `success`, or `failed` rather than an outcome state. ```json { "executed_actions": { "action_transfer_call": { "name": "action_transfer_call", "action_type": "transfer_call_action_type", "return_value": { "status": "transfer-failed-connection-error", "failed_reason": "number_not_found" } } } } ``` ## Outcome states \[#outcome-states] | Outcome state | `failed_reason` | What happened | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `transfer-success` | none | A live human answered and the caller was bridged to them. | | `transfer-configuration-error` | `unresolved_variable`, or `invalid_dtmf` | The transfer was not dialed, or its extension could not be sent. The [phone number](/call-transfers#variables) or [extension](/call-transfers#advanced-settings) was still a `` or `{variable}`, or the extension digits were not valid DTMF. | | `transfer-failed-connection-error` | `transfer_outside_availability`, a [carrier or SIP reason](#carrier-and-sip-rejections), or `transfer_failed` | No transfer leg was established. Either the caller asked for a transfer outside the [Human Availability](/call-transfers#human-availability) window, or the carrier rejected the transfer. | | `transfer-failed-timeout` | `transfer_failed`, `human_detection_timeout` | The destination rang until the [Timeout](/call-transfers#advanced-settings) expired, or it answered but [Human Detection](/call-transfers#human-detection) did not confirm a live human in time. | | `transfer-failed-ivr` | `ivr_detected` | Human Detection identified an auto-attendant or IVR menu rather than a person. | | `transfer-failed-voicemail` | `voicemail_detected` | Human Detection identified a voicemail greeting. | | `transfer-failed-destination-busy` | `destination_busy` | The destination line was busy. | | `transfer-failed-transfer-target-hangup` | `transfer_target_hangup` | The destination answered, then hung up before the caller was bridged. | | `transfer-cancelled` | `caller_hung_up` | The caller hung up before the transfer completed, for example while waiting on [background music](/call-transfers#background-music). | | `transfer-screening-rejected` | `screening_rejected` | The destination declined the call during [call screening](/call-transfers#call-screening). | ## How each transfer mode reacts \[#transfer-mode-reactions] Some outcome states depend on features that only warm transfers support, so a cold transfer never produces them. | Outcome state | Cold transfer | Warm transfer | | ---------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `transfer-configuration-error` | Agent speaks the failure message and the call continues. Nothing was dialed. | Agent speaks the failure message and the call continues. Nothing was dialed, or the extension was refused after the destination answered. | | `transfer-failed-connection-error` | Call ends | Agent is informed and can try an alternate destination | | `transfer-failed-timeout` | Call ends | Agent can retry or continue the conversation | | `transfer-failed-ivr` | Not produced, requires [human detection](/call-transfers#human-detection) | Agent resumes the conversation and can try an alternate destination | | `transfer-failed-voicemail` | Not produced, requires [human detection](/call-transfers#human-detection) | Agent resumes the conversation and can try an alternate destination | | `transfer-failed-destination-busy` | Call ends | Agent resumes the conversation and can retry | | `transfer-failed-transfer-target-hangup` | Not produced, the destination is never briefed on a cold transfer | Agent resumes the conversation and can retry | | `transfer-cancelled` | Call ends | Agent resumes the conversation with the caller | | `transfer-screening-rejected` | Not produced, [call screening](/call-transfers#call-screening) requires a warm transfer | Agent resumes the conversation and can attempt a fallback | > **Warning** > > **Cold transfers cannot recover once the destination has been dialed.** If reliability is critical, use warm transfers so the agent can fall back on a failed outcome, for example apologize, take a message, try an alternate destination, or schedule a callback. A phone number or extension that is still an unresolved variable fails before dialing, in both modes, and the call continues. ## Failure reasons \[#failure-reasons] Reach for the failure reason when the outcome state on its own is not specific enough, for example to tell an unanswered ring apart from a wrong number. The reasons below are grouped by what caused the failure. ### Human detection \[#human-detection-reasons] These reasons are only set when [Human Detection](/call-transfers#human-detection) is enabled on a warm transfer. | `failed_reason` | Outcome state | Meaning | | ------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `human_detection_timeout` | `transfer-failed-timeout` | The recipient answered, but no live human was confirmed before the **Human Detection Timeout** expired, and the answering party was not classified as an IVR or voicemail. | | `ivr_detected` | `transfer-failed-ivr` | The answering party was classified as an IVR or auto-attendant. | | `voicemail_detected` | `transfer-failed-voicemail` | The answering party was classified as a voicemail greeting. | ### Busy lines, hang-ups, and declines \[#busy-hangups-and-declines] | `failed_reason` | Outcome state | Meaning | | ------------------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `destination_busy` | `transfer-failed-destination-busy` | The destination was busy: SIP `486 Busy Here`, SIP `600 Busy Everywhere`, or a `USER_BUSY` cause before the call was answered. | | `transfer_target_hangup` | `transfer-failed-transfer-target-hangup` | The recipient answered, then hung up before the caller was bridged: during human detection, during the whisper message or summary, or during a [pause](/call-transfers#stage-messages-and-timing). | | `caller_hung_up` | `transfer-cancelled` | The caller hung up while the transfer was still in progress. | | `screening_rejected` | `transfer-screening-rejected` | The recipient declined the call during [call screening](/call-transfers#call-screening). | ### Carrier and SIP rejections \[#carrier-and-sip-rejections] The carrier returned a SIP error before the transfer leg connected. All of these report the outcome state `transfer-failed-connection-error`. | `failed_reason` | SIP response | Meaning | | ----------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `number_not_found` | `404 Not Found`, `604 Does Not Exist Anywhere` | The destination number could not be routed. | | `number_incomplete` | `484 Address Incomplete` | The destination number was incomplete. | | `destination_unavailable` | `480 Temporarily Unavailable` | The destination was temporarily unavailable. Distinct from a [Timeout](/call-transfers#advanced-settings) that expires while the phone is still ringing. | | `rejected_by_destination` | `603 Decline` | The destination declined the transfer. | | `transfer_blocked_by_carrier` | `403 Forbidden` | The carrier refused the transfer. | | `carrier_unavailable` | `503 Service Unavailable` | The carrier or downstream network was unavailable. | | `routing_loop` | `483 Too Many Hops` | The transfer was rejected because it would loop. | | `media_negotiation_failed` | `415 Unsupported Media Type`, `488 Not Acceptable Here` | The two sides could not agree on media, such as audio codecs. | | `transfer_method_unsupported` | `405 Method Not Allowed`, `501 Not Implemented` | The destination does not allow or implement the transfer method. | ### Availability and fallback \[#availability-and-fallback] | `failed_reason` | Outcome state | Meaning | | ------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `transfer_outside_availability` | `transfer-failed-connection-error`, or a legacy `error` on older transfer paths | The transfer was blocked by the [Human Availability](/call-transfers#human-availability) schedule, so no attempt was placed. | | `unresolved_variable` | `transfer-configuration-error` | The phone number or extension was still a `` or `{variable}` after the call's variables were applied, so the transfer was not dialed. | | `invalid_dtmf` | `transfer-configuration-error` | The extension was sent after the destination answered, and it was not valid DTMF. | | `transfer_failed` | Any failure state | Fallback for every failure without a more specific cause, including a destination that rang until the Timeout expired. | ## Timestamps \[#transfer-timestamps] A transfer records up to two timestamps, both in ISO 8601 UTC. The gap between them is how long the caller waited between asking for a person and reaching one. | Field | What it marks | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `transfer_timestamp` | The moment the transfer action started. | | `human_connected_at` | Warm transfers only. The point where the person who answered is in the conversation: with [human detection](/call-transfers#human-detection) on, their first words after the whisper message ends and the two legs are joined; with it off, the moment the whisper message finishes. It stays `null` on a transfer that never completed, and is never filled in afterwards. | Both appear on the transfer action in the same places as the outcome state. ## Legacy values \[#legacy-values] Some values changed as transfer reporting became more specific. If your reporting or automation groups transfers by outcome state or failure reason, add the current values so these calls are not counted as generic failures. | Value | What changed | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `transfer-configuration-error` | An unresolved `` or `{variable}` in the phone number or extension used to be dialed or sent as DTMF, then reported as `transfer-failed-connection-error`. | | `transfer-failed-ivr`, `transfer-failed-voicemail`, `transfer-failed-destination-busy` | Previously reported as `transfer-failed-connection-error` or `transfer-failed-timeout`. | | `transfer-failed-transferee-hangup` | Renamed to `transfer-failed-transfer-target-hangup`. | | Carrier and SIP reasons | Previously reported with the `failed_reason` `transfer_failed`. | | `error` | Generic status that older transfer paths may still report instead of an outcome state. | ## FAQ #### The SIP call ladder shows a successful REFER. Why did the transfer fail? A `202 Accepted` on the REFER only means the other side accepted the request to transfer. The transfer leg can still fail afterwards, and the carrier reports that in a follow-up NOTIFY, for example a `503` that is reported as `carrier_unavailable`. The outcome state and `failed_reason` reflect that final result, so trust them over the REFER in the [SIP call ladder](/sip-call-ladder). #### Why did the transfer fail before anyone was dialed? The phone number or extension was still a `` or `{variable}`. That is `transfer-configuration-error` with `failed_reason` `unresolved_variable`. Map the [input variable](/call-transfers#variables) to a value the call actually has. It is not a carrier failure. #### Why does my failed transfer only say transfer_failed? `transfer_failed` is the fallback when no more specific cause is known. On `transfer-failed-timeout` it means the destination rang until the [Timeout](/call-transfers#advanced-settings) expired. On `transfer-failed-connection-error` it means the carrier did not return one of the [SIP errors](#carrier-and-sip-rejections) Synthflow recognizes. #### Does a successful transfer have a failed_reason? No. `transfer-success` carries no `failed_reason`. The field is only set on failure states. #### Why does a transfer in the action execution timeline show failed instead of an outcome state? The [action execution timeline](/webhooks#action-execution-timeline) reports one entry per attempt with a simple `started`, `success`, or `failed` status. The `failed_reason` on each failed attempt uses the same values as this page, and the final outcome state is on the transfer action in `executed_actions`. #### Can new failure reasons appear? Yes. Synthflow adds reasons as it detects more specific causes. Treat an unrecognized `failed_reason` as a generic failure for its outcome state so your integration keeps working when a new value ships.