> ## 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.

# Create a Queue

> Create a named hold queue that parks inbound callers on hold audio until an agent dequeues them.

Creates a named queue. A queue holds inbound callers on hold audio until an agent dequeues them and bridges the oldest waiting caller to an answerer.

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

## Body Parameters

<ParamField body="name" type="string" required>
  A human-readable name for the queue. Must be unique within your account.
</ParamField>

<ParamField body="holdAudioUrl" type="string" optional>
  A public `https` URL to the hold-audio file played to waiting callers. The URL's origin must be on the platform's configured hold-audio origin allowlist — a deployment-wide list, not per-account — or the request is rejected with `hold_audio_origin_not_allowed`. If no origins are configured at all, the request is rejected with `hold_audio_origin_not_configured`.
</ParamField>

<ParamField body="notifyUrl" type="string" optional>
  Your HTTPS webhook that receives queue events. See [Queue Webhooks](/api-reference/voice/webhooks).
</ParamField>

<ParamField body="notifySecret" type="string" optional>
  A secret used to HMAC-sign the webhook payload delivered to `notifyUrl`. Use a long, high-entropy random value — its strength is what protects your endpoint from forged events. See [Queue Webhooks](/api-reference/voice/webhooks).
</ParamField>

<ParamField body="isDefault" type="boolean" default={false}>
  Make this the account default queue for unrouted numbers.
</ParamField>

<ParamField body="autoAnswer" type="boolean" default={true}>
  Automatically answer inbound calls routed to this queue.
</ParamField>

## Response Fields

<ResponseField name="queue" type="object">
  The created queue.

  <Expandable title="Queue properties" defaultOpen>
    <ResponseField name="queue.id" type="string">The queue's unique identifier.</ResponseField>
    <ResponseField name="queue.name" type="string">The queue name.</ResponseField>
    <ResponseField name="queue.holdAudioUrl" type="string | null">The hold-audio URL played to waiting callers.</ResponseField>
    <ResponseField name="queue.notifyUrl" type="string | null">The webhook that receives queue events.</ResponseField>
    <ResponseField name="queue.numbers" type="array">The numbers this queue serves, in digits-only form (no leading `+`). Numbers are assigned during onboarding, not through this API, so a newly created queue returns `[]`. Request number routing from support.</ResponseField>
    <ResponseField name="queue.isDefault" type="boolean">Whether this is the account default queue for unrouted numbers.</ResponseField>
    <ResponseField name="queue.autoAnswer" type="boolean">Whether inbound calls routed here are answered automatically.</ResponseField>
    <ResponseField name="queue.createdAt" type="string | null">ISO 8601 timestamp when the queue was created.</ResponseField>
  </Expandable>
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.tracklysms.com/api/v1/voice/queues \
    -H "X-Api-Key: trk_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Support",
      "holdAudioUrl": "https://cdn.example.com/audio/hold.wav",
      "notifyUrl": "https://hooks.example.com/voice/queue",
      "notifySecret": "whsec_9f2c1a9e4b7d4c3a8e5b2f1d6c0a49387b1c2d3e4f5061728394a5b6c7d8e9f0",
      "isDefault": true,
      "autoAnswer": true
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "queue": {
      "id": "665f1e2a9c4b1a0012ab34cd",
      "name": "Support",
      "holdAudioUrl": "https://cdn.example.com/audio/hold.wav",
      "notifyUrl": "https://hooks.example.com/voice/queue",
      "numbers": [],
      "isDefault": true,
      "autoAnswer": true,
      "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.                                       |
| 409    | `queue_exists`                     | A queue with this name already exists in your account.                               |
| 422    | `invalid_hold_audio_url`           | `holdAudioUrl` is not a valid URL.                                                   |
| 422    | `invalid_notify_url`               | `notifyUrl` is not a valid URL.                                                      |
| 422    | `hold_audio_origin_not_allowed`    | The `holdAudioUrl` origin is not on the approved-origins allowlist.                  |
| 422    | `hold_audio_origin_not_configured` | No approved hold-audio origins are configured, so `holdAudioUrl` cannot be accepted. |