> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apten.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Call Transfer Failed

> Get notified when a transfer was started and did not connect the lead to an agent

The `call.transfer.failed` webhook event fires **once** after Apten starts dialing the human agent and the transfer does not connect. Subscribe to this event if you want to take different actions depending on *why* the handoff failed.

<Note>
  This is the terminal failure counterpart to [`call.transfer.connected`](/webhooks/call-transfer-connected). After a **warm** transfer starts, Apten emits exactly one of those two events. Cold transfers do not emit `call.transfer.connected`; a cold transfer that fails after the agent is dialed still emits this event.

  If the lead never answered a dedicated outbound transfer call, Apten did not dial an agent. That case stays on [`call.attempted`](/webhooks/call-attempted) with `isTransfer: true`. It does **not** emit `call.transfer.failed`.
</Note>

## Failure codes

| `failureCode`         | Meaning                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------- |
| `agent_not_connected` | We dialed the agent. They never joined (no answer, missed accept, or fallback also missed). |
| `lead_disconnected`   | The lead was on the line, then left before the agent was bridged.                           |

Treat unknown codes as a generic transfer failure so later codes do not break your handler.

## Payload

```json theme={null}
{
  "event": "call.transfer.failed",
  "data": {
    "leadId": "fc5859ea-1f9f-4871-946c-fd73e83f05f7",
    "firstName": "Jane",
    "lastName": "Doe",
    "externalLeadId": "003XX000004DHPY",
    "phone": "+13102919783",
    "profile": "Swim Parent",
    "callId": "ddd1cf74-e6d3-4b32-a6c4-76e81c5295ff",
    "transferType": "WARM",
    "transferTo": "+14153750579",
    "failureCode": "agent_not_connected",
    "isTransfer": true,
    "midCallTransfer": false
  },
  "timestamp": "2026-09-14T18:49:41Z"
}
```

## Properties

| Property                | Type    | Description                                                                                           |
| ----------------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `event`                 | string  | The webhook event type (`call.transfer.failed`).                                                      |
| `data.leadId`           | string  | The unique identifier for the lead.                                                                   |
| `data.firstName`        | string  | The first name of the lead.                                                                           |
| `data.lastName`         | string  | The last name of the lead.                                                                            |
| `data.externalLeadId`   | string  | The CRM lead ID (Salesforce, HubSpot, or Close CRM). Only included if the lead has a CRM association. |
| `data.phone`            | string  | The phone number of the lead.                                                                         |
| `data.profile`          | string  | The customer profile assigned to the lead.                                                            |
| `data.callId`           | string  | The unique identifier for the call.                                                                   |
| `data.transferType`     | string  | `WARM` or `COLD`.                                                                                     |
| `data.transferTo`       | string  | The number we tried to transfer to.                                                                   |
| `data.failureCode`      | string  | `agent_not_connected` or `lead_disconnected`.                                                         |
| `data.isTransfer`       | boolean | `true` if this was a dedicated transfer call.                                                         |
| `data.midCallTransfer`  | boolean | `true` if the transfer started during an AI conversation.                                             |
| `data.close_crm_leadId` | string  | The Close CRM lead ID. Only included if the lead is associated with Close CRM via integration.        |
| `timestamp`             | string  | The ISO 8601 timestamp when the transfer was marked failed.                                           |

The same outcome is on [`GET /calls/{callId}`](/api-reference/calls/get-call) as `transferStatus` and `transferFailureCode`. Use that to reconcile or backfill. Do not infer failure from a missing `call.transfer.connected`.