> ## 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": "lead_disconnected",
    "transferInitiatedAt": "2026-09-14T18:49:11Z",
    "transferWaitDurationSeconds": 30,
    "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.transferInitiatedAt` | string \| undefined | When Apten began the transfer attempt and the lead began waiting. Included when transfer timing is available. |
| `data.transferWaitDurationSeconds` | number \| undefined | Seconds from transfer initiation until Apten recorded the terminal failure, rounded to the nearest whole second. Included when transfer timing is available. |
| `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 webhook event was emitted. |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.