Skip to main content
POST
/
v1
/
agents
Create an agent
curl --request POST \
  --url https://api.callingbox.io/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Appointment reminders",
  "persona": "<string>",
  "instructions": "<string>",
  "voice": "<string>",
  "language": "<string>",
  "returns": {},
  "tools": [
    {}
  ],
  "webhook_url": "<string>",
  "voicemail_action": "hangup",
  "number_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "primary_number_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "org_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "user_id": "<string>",
  "name": "Appointment reminders",
  "persona": "<string>",
  "instructions": "<string>",
  "voice": "<string>",
  "language": "<string>",
  "returns": {
    "confirmed": "boolean",
    "reschedule_to": "string"
  },
  "tools": [
    {}
  ],
  "webhook_url": "<string>",
  "voicemail_action": "hangup",
  "primary_number_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "archived_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "numbers": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "e164": "+15551234567",
      "friendly_name": "<string>",
      "country_code": "US",
      "number_type": "local",
      "status": "active",
      "monthly_cost_cents": 100,
      "purchased_at": "2023-11-07T05:31:56Z",
      "inbound_agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "outbound_agent_ids": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    }
  ]
}

Authorizations

​
Authorization
string
header
default:sk_live_your_api_key
required

API key starting with sk_

Body

application/json
​
name
string
required
Example:

"Appointment reminders"

​
type
enum<string>
required

Inbound agents answer incoming calls on their attached numbers. Outbound agents are dispatched via POST /v1/calls and use their attached numbers as caller ID.

Available options:
inbound,
outbound
​
persona
string

Optional. Omit for the canonical default persona.

​
instructions
string

Default task. Per-call instructions on outbound replace this wholly.

​
voice
string
​
language
string
​
returns
object
​
tools
object[]
​
webhook_url
string
​
voicemail_action
enum<string>
default:hangup
Available options:
hangup,
leave_message
​
number_ids
string<uuid>[]

Phone numbers to attach on creation. The first id becomes the primary if primary_number_id is not set.

​
primary_number_id
string<uuid>

Must be included in number_ids when provided.

Response

Agent created

Reusable call-behavior primitive. Calls dispatched against this agent inherit persona, instructions, voice, language, returns, tools, webhook_url, and voicemail_action.

​
id
string<uuid>
​
org_id
string<uuid>
​
user_id
string
​
name
string

Human-readable label.

Example:

"Appointment reminders"

​
type
enum<string>

Inbound agents answer incoming calls on their attached numbers. Outbound agents are dispatched via POST /v1/calls and use their attached numbers as caller ID.

Available options:
inbound,
outbound
​
persona
string | null

Identity/policy for the agent. Null falls back to the canonical default persona at call-render time.

​
instructions
string | null

Default task for calls handled by this agent. Outbound calls can replace this per call via the instructions field on POST /v1/calls.

​
voice
string
​
language
string | null

BCP-47 language code.

​
returns
object

Schema for structured data extraction.

Example:
{
  "confirmed": "boolean",
  "reschedule_to": "string"
}
​
tools
object[] | null

In-call tools the agent may invoke.

​
webhook_url
string | null

Default webhook URL for calls handled by this agent.

​
voicemail_action
enum<string>
default:hangup
Available options:
hangup,
leave_message
​
primary_number_id
string<uuid> | null

Default caller ID for outbound calls (also indicates the "owning" number for inbound agents).

​
archived_at
string<date-time> | null
​
created_at
string<date-time>
​
updated_at
string<date-time>
​
numbers
object[]

Full set of phone numbers attached to this agent. Present on detail and mutation responses.