---
title: "Start a transfer"
method: POST
path: "/service_agents/transfers"
tags: ["Service Agent"]
---

# Start a transfer

`POST /service_agents/transfers`

## Request

- Base URL: `https://api.voipbin.net/v1.0`
- URL: `https://api.voipbin.net/v1.0/service_agents/transfers`
- Auth: none declared
- TypeScript: <https://skmtc.dev/voipbin/apis/voipbin-api/docs/service_agents/transfers/post.ts> (a function with typed inputs; its response is checked against the schema)

Transfers a call the calling agent owns to a colleague's extension, either blind or attended.
The call must be one the calling agent owns, be in progress and be in a conference (a bridged call). The transferee must be an extension of the calling agent's customer. Any other address type, or an extension that does not exist, is deleted or belongs to another customer, is rejected with 400.
Cancelling an attended transfer is not available through this API.

## Request body

- object
  - `transfer_type` 'attended' | 'blind', required
  - `transferer_call_id` string, uuid, required: The call ID returned from the `GET /service_agents/calls` response. It must be a call the calling agent owns.
  - `transferee_addresses` CallManagerParticipantAddress[], required: The colleague to transfer the call to. Exactly one address of type `extension`.
    - `type` 'extension', required: Type of address. Only `extension` is accepted.
    - `target` string, uuid, required: The extension ID of the colleague to reach. It is the `target` of the address of type `extension` returned from the `GET /service_agents/agents` response. The extension must belong to the calling agent's customer.

## Response `200`

The transfer details.

- TransferManagerTransfer
  - `id` string, uuid: The unique identifier of the transfer. Returned from the `POST /transfers` response.
  - `customer_id` string, uuid: The unique identifier of the customer who owns this transfer. Returned from the `GET /customers` response.
  - `type` 'attended' | 'blind'
  - `transferer_call_id` string, uuid: The unique identifier of the call initiating the transfer. Returned from the `GET /calls` response.
  - `transferee_addresses` CommonAddress[]: List of target addresses for the transfer.
    - `type` '' | 'agent' | 'conference' | 'email' | 'extension' | 'line' | 'sip' | 'tel' | 'web_session': Type of address.
    - `target` string: The address endpoint. Format depends on type: phone number for tel (e.g. +14155551234), UUID for agent/conference/extension, email for email, SIP URI for sip.
    - `target_name` string: Address's name.
    - `name` string: Optional label for this address.
    - `detail` string: Additional notes about this address.
  - `transferee_call_id` string, uuid: The unique identifier of the call being transferred. Returned from the `GET /calls` response.
  - `groupcall_id` string, uuid: The unique identifier of the groupcall created for the transfer. Returned from the `GET /groupcalls` response.
  - `confbridge_id` string, uuid: The unique identifier of the conference bridge used for attended transfer. Returned from the `GET /conferences` response.
  - `tm_create` string, date-time: Timestamp when created
  - `tm_update` string, date-time: Timestamp when updated
  - `tm_delete` string, date-time: Timestamp when deleted

## Other responses

- `400`: Invalid request (INVALID_ARGUMENT).
- `401`: Authentication required (UNAUTHENTICATED).
- `403`: Insufficient permission (PERMISSION_DENIED).
- `404`: Resource not found (NOT_FOUND).
- `409`: State conflict (ALREADY_EXISTS or FAILED_PRECONDITION).
- `500`: Internal error (INTERNAL).
- `503`: Upstream unavailable (UNAVAILABLE).

## Changes

- **2026-11-02** `390910abdc83`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/voipbin/apis/voipbin-api/changes/service_agents/transfers/post.md)

---

[API](https://skmtc.dev/voipbin/apis/voipbin-api.md) - [All operations](https://skmtc.dev/voipbin/apis/voipbin-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voipbin/apis/voipbin-api/revisions/ae049dcc6c89?raw)