> ## 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 an Agent

> Create a reusable, named answer/bridge destination you can reference by id when connecting calls.

Creates a voice agent: a reusable, named destination you can reference by its `id` in the `connectTo` field on [place a call](/api-reference/voice/calls/place-call), answer a call, or dequeue, as well as the `to` field when dialing a monitor leg. Referencing an agent by id keeps its underlying number out of your request payloads. Every dial is compliance-screened regardless of whether the destination is a raw number or an agent.

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

## Body Parameters

<ParamField body="name" type="string" required>
  A human-readable label for the agent.
</ParamField>

<ParamField body="type" type="string" default="phone">
  The agent's destination type. Only `phone` is supported today.
</ParamField>

<ParamField body="number" type="string" required>
  The destination phone number in E.164 format (e.g. `+14155559876`). It is normalized to digits when stored.
</ParamField>

## Response Fields

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

  <Expandable title="Agent properties" defaultOpen>
    <ResponseField name="agent.id" type="string">The agent's unique identifier. Use this value in `connectTo`.</ResponseField>
    <ResponseField name="agent.name" type="string">The label you supplied.</ResponseField>
    <ResponseField name="agent.type" type="string">The destination type. Currently always `phone`.</ResponseField>
    <ResponseField name="agent.number" type="string">The normalized destination number.</ResponseField>
    <ResponseField name="agent.createdAt" type="string | null">ISO 8601 timestamp when the agent was created.</ResponseField>
  </Expandable>
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.tracklysms.com/api/v1/voice/agents \
    -H "X-Api-Key: trk_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Front Desk",
      "type": "phone",
      "number": "+14155559876"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "agent": {
      "id": "665f1e2a9c4b1a0012ab34cd",
      "name": "Front Desk",
      "type": "phone",
      "number": "14155559876",
      "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    | `agent_exists`       | An agent with the same name already exists on your account. |
| 422    | `missing_fields`     | A required field (`name` or `number`) is missing.           |