# AI agents

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

[AI agents in the API reference](https://vocatech.com/developers/reference/ai-agents)