By area
AI agents
Written beside the API’s code, and read from it every hour.
| Method | Path | What it does |
|---|---|---|
| GET | /v1/agents | Your AI agents: id, name, extension, active, outgoing_calls, provisioned |
| POST | /v1/agents/{id}/calls | Have one agent place one call |
| Field | Meaning |
|---|---|
to | Required. A 10-digit number, or an extension of 2 to 6 digits. |
purpose | Why the agent is calling, in a few words, up to 200 characters. subject also works. |
instructions | What to do on the call, up to 2,000 characters. Send purpose, instructions or both. |
person_name | Who to ask for, up to 80 characters. |
reference | Your id for the matter: letters, digits, . _ : and -, up to 80. It comes back with the outcome. |
kind | notice (default), a short message with a question, or callback, the office returning their call. |
job | The name of one of the agent's jobs to start with, such as a reschedule job. |
allow_quiet_hours | true to call outside the agent's calling hours. |
Send an Idempotency-Key header, your own id for the request, up to 80 characters: a repeat of it within a day answers the same call (202, the same call_sid) instead of placing a second one. Without the header, the same agent, number and reference within two minutes is treated as the same request. An agent places at most 50 calls a day; past that the request is refused with 422 until the next day.
404: no agent with that id on your account. 422: the call cannot be placed, and the message says why (a missing field, a refused number, the agent or its outgoing calls switched off, its line not ready yet, outside its calling hours, or the day's calls used up). 502: the agent platform did not answer, and the call may have been placed: check for the placed-call tag (your reference in the agent's message) before you retry, or retry with the same Idempotency-Key and get the same call. 503: outgoing calls are not available right now.