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

# Dequeue a Call

> Claim the oldest waiting caller in a queue (FIFO) and bridge it to an agent.

Claims the oldest waiting caller in the queue (FIFO) and bridges it to the supplied agent or number. The returned call is the caller, now transitioning to the `dequeuing` state.

Requires the `voice_calls.write` scope and the **Voice Calls** product entitlement.

## Path Parameters

<ParamField path="queueId" type="string" required>
  The id of the queue to claim a caller from.
</ParamField>

## Body Parameters

<ParamField body="connectTo" type="string" required>
  The bridge target for the claimed caller. Accepts either the `id` of a [voice agent](/api-reference/voice/agents/create-agent) or an E.164 number. The resolved destination is screened against your account's compliance suppression (DNC, opt-out, quiet hours) before dialing; if it is blocked, the caller is returned to the queue and the request fails with a `403`.
</ParamField>

<ParamField body="record" type="boolean" default={false}>
  Whether to record the call. This applies only to the newly dialed **agent bridge leg** and never changes the caller's own `record` / `recordingState`. The returned caller reflects whatever recording state it already had — `record: false` / `recordingState: null` unless recording was previously started on that caller, for example via [Start Recording](/api-reference/voice/calls/start-recording) while queued, or by answering the call with `record: true`. Recording may require consent — see [call recording](/api-reference/voice/overview#call-recording).
</ParamField>

## Response Fields

<ResponseField name="call" type="object">
  The claimed caller.

  <Expandable title="Call properties" defaultOpen>
    <ResponseField name="call.id" type="string">The call's unique identifier.</ResponseField>
    <ResponseField name="call.direction" type="string">`inbound` for a queued caller.</ResponseField>
    <ResponseField name="call.state" type="string">Lifecycle state. A dequeued caller transitions to `dequeuing`. See [Call states](/api-reference/voice/overview#call-states).</ResponseField>
    <ResponseField name="call.legKind" type="string">`primary`, `bridge`, or `monitor`.</ResponseField>
    <ResponseField name="call.from" type="string">The caller's number.</ResponseField>
    <ResponseField name="call.to" type="string">The number the caller dialed.</ResponseField>
    <ResponseField name="call.connectTo" type="string | null">Always `null` on the returned caller — the resolved agent target lives on the bridge leg, referenced by `bridgedCallId`.</ResponseField>
    <ResponseField name="call.queueId" type="string | null">The queue this call was parked in.</ResponseField>
    <ResponseField name="call.conferenceId" type="string | null">The provider conference id once a bridge or monitor leg is attached.</ResponseField>
    <ResponseField name="call.parentCallId" type="string | null">For a bridge/monitor leg, the primary call it belongs to.</ResponseField>
    <ResponseField name="call.bridgedCallId" type="string | null">For a primary call, the currently bridged agent leg.</ResponseField>
    <ResponseField name="call.monitorRole" type="string | null">`MONITOR` or `ADVISOR` for a monitor leg.</ResponseField>
    <ResponseField name="call.record" type="boolean">Whether recording was requested.</ResponseField>
    <ResponseField name="call.recordingState" type="string | null">`requested`, `started`, `stopped`, `ready`, `failed`, or `deleted`.</ResponseField>
    <ResponseField name="call.recordingFileIds" type="array">Provider file ids for completed recordings.</ResponseField>
    <ResponseField name="call.customData" type="object">Metadata attached to the call.</ResponseField>
    <ResponseField name="call.error" type="string | null">A machine-readable reason when the call failed.</ResponseField>
    <ResponseField name="call.startedAt" type="string | null">ISO 8601 timestamp when the call was placed.</ResponseField>
    <ResponseField name="call.answeredAt" type="string | null">ISO 8601 timestamp when the call was answered.</ResponseField>
    <ResponseField name="call.endedAt" type="string | null">ISO 8601 timestamp when the call ended.</ResponseField>
    <ResponseField name="call.createdAt" type="string | null">ISO 8601 timestamp when the record was created.</ResponseField>
  </Expandable>
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.tracklysms.com/api/v1/voice/queues/665f1e2a9c4b1a0012ab34cd/dequeue \
    -H "X-Api-Key: trk_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "connectTo": "665f1e2a9c4b1a0012ab34ef",
      "record": true
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "call": {
      "id": "665f1e2a9c4b1a0012ab34d0",
      "direction": "inbound",
      "state": "dequeuing",
      "legKind": "primary",
      "from": "+14155551234",
      "to": "+18005551234",
      "connectTo": null,
      "queueId": "665f1e2a9c4b1a0012ab34cd",
      "conferenceId": "665f1e2a9c4b1a0012ab34e1",
      "parentCallId": null,
      "bridgedCallId": "665f1e2a9c4b1a0012ab34e2",
      "monitorRole": null,
      "record": false,
      "recordingState": null,
      "recordingFileIds": [],
      "customData": {},
      "error": null,
      "startedAt": "2026-08-21T18:00:00.000000Z",
      "answeredAt": "2026-08-21T18:00:12.000000Z",
      "endedAt": null,
      "createdAt": "2026-08-21T18:00:00.000000Z"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Status | Code                                                                                           | Meaning                                                               |
| ------ | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| 403    | `voice_not_entitled`                                                                           | Voice calling is not enabled for your account.                        |
| 404    | `queue_not_found`                                                                              | No queue with this id exists in your account.                         |
| 404    | `queue_empty`                                                                                  | No callers are currently waiting in this queue.                       |
| 404    | `agent_not_found`                                                                              | `connectTo` is an agent id that does not exist.                       |
| 422    | `invalid_number`                                                                               | `connectTo` is not a valid E.164 number.                              |
| 403    | `compliance_dnc` / `compliance_opted_out` / `compliance_suppressed` / `compliance_quiet_hours` | The resolved `connectTo` destination is blocked by a compliance rule. |
| 429    | `concurrency_limit`                                                                            | Your account has too many concurrent calls in progress.               |
| 502    | `provider_error`                                                                               | The upstream telephony provider rejected the request.                 |