curl -X POST https://api.tracklysms.com/api/v1/voice/queues/665f1e2a9c4b1a0012ab34cd/dequeue \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Idempotency-Key: 8f2c1a9e-4b7d-4c3a-9e21-3f0a1b2c3d4e" \
-H "Content-Type: application/json" \
-d '{
"connectTo": "665f1e2a9c4b1a0012ab34ef",
"record": true
}'
{
"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"
}
}
Voice Calls (v1)
Dequeue a Call
Claim the oldest waiting caller in a queue (FIFO) and bridge it to an agent.
POST
/
v1
/
voice
/
queues
/
{queueId}
/
dequeue
curl -X POST https://api.tracklysms.com/api/v1/voice/queues/665f1e2a9c4b1a0012ab34cd/dequeue \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Idempotency-Key: 8f2c1a9e-4b7d-4c3a-9e21-3f0a1b2c3d4e" \
-H "Content-Type: application/json" \
-d '{
"connectTo": "665f1e2a9c4b1a0012ab34ef",
"record": true
}'
{
"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"
}
}
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.
Trackly-managed queues require a nonblank Idempotency-Key of at most 128 characters. Repeating the same request with the same key stays bound to the selected caller; changing the resolved destination or record with that key returns 409 idempotency_conflict. Reuse the key only to retry an uncertain response for the same attempt. Use a new key for a new dequeue attempt after the caller returns to the queue; FIFO may select that same caller again. Hosted queues do not have this replay contract. After an uncertain hosted response, inspect the queue and active calls before retrying.
Requires the voice_calls.write scope and the Voice Calls product entitlement.
Headers
string
Required for Trackly-managed queues; nonblank and at most 128 characters. Retain the same key for an exact retry.
Path Parameters
string
required
The id of the queue to claim a caller from.
Body Parameters
string
required
The bridge target for the claimed caller. Accepts either the
id of a voice 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.boolean
default:false
Request recording only for the newly dialed agent bridge leg; the caller’s
record / recordingState is unchanged. Individual leg recording ends when it joins the conference, so this does not record the complete bridged conversation. See call recording.Response Fields
object
The claimed caller.
Hide Call properties
Hide Call properties
string
The call’s unique identifier.
string
inbound for a queued caller.string
Lifecycle state. A dequeued caller transitions to
dequeuing. See Call states.string
primary, bridge, or monitor.string
The caller’s number.
string
The number the caller dialed.
string | null
Always
null on the returned caller — the resolved agent target lives on the bridge leg, referenced by bridgedCallId.string | null
The queue this call was parked in.
string | null
The provider conference id once a bridge or monitor leg is attached.
string | null
For a bridge/monitor leg, the primary call it belongs to.
string | null
For a primary call, the currently bridged agent leg.
string | null
MONITOR or ADVISOR for a monitor leg.boolean
Whether recording was requested.
string | null
requested, started, stopped, ready, failed, or deleted.array
Provider file ids for completed recordings.
object
Metadata attached to the call.
string | null
A machine-readable reason when the call failed.
string | null
ISO 8601 timestamp when the call was placed.
string | null
ISO 8601 timestamp when the call was answered.
string | null
ISO 8601 timestamp when the call ended.
string | null
ISO 8601 timestamp when the record was created.
Examples
curl -X POST https://api.tracklysms.com/api/v1/voice/queues/665f1e2a9c4b1a0012ab34cd/dequeue \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Idempotency-Key: 8f2c1a9e-4b7d-4c3a-9e21-3f0a1b2c3d4e" \
-H "Content-Type: application/json" \
-d '{
"connectTo": "665f1e2a9c4b1a0012ab34ef",
"record": true
}'
{
"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"
}
}
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. |
| 409 | idempotency_conflict | The key was already used with another resolved destination or recording choice. |
| 409 | queue_call_unavailable | The caller bound to this key is no longer available. |
| 409 | call_control_limit | A Trackly-managed caller has no room for another dequeue reservation. Inspect that call before attempting another claim. |
| 409 | queue_changed | A hosted queue changed during the claim. Inspect the queue and active calls before retrying. |
| 422 | invalid_number | connectTo is not a valid E.164 number. |
| 422 | idempotency_key_required | A Trackly-managed queue requires a nonblank key of at most 128 characters. |
| 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 | media_error | The managed media result is uncertain; retry the same request with the same key. |
| 502 | provider_error | The upstream telephony provider rejected the request. |