API reference

Numbers API

A number is addressed by its owning agent: number.id == agent.id. Guide: Phone numbers.

Endpoint	Purpose
`GET /api/twilio/numbers/available?area_code=NNN`	Search purchasable numbers
`GET /api/v1/numbers`	List your numbers
`POST /api/v1/numbers`	Provision (creates minimal agent if no `agent_id`)
`GET /api/v1/numbers/{id}`	Get one
`PATCH /api/v1/numbers/{id}`	`nickname`, `inbound_instruction`
`DELETE /api/v1/numbers/{id}`	Release at Twilio + detach
`POST /api/twilio/numbers/purchase`	Attach an exact number to an agent

POST /api/v1/numbers

Body: area_code or phone_number; optional agent_id, nickname, inbound_instruction. Voice/SMS/status webhooks are configured during purchase. Failures roll back a just-created minimal agent. Caps: 5 purchases/hour.

Errors worth handling

409 — number already assigned to another agent. 404 — no numbers available in that area code. 502 — carrier-side failure; pick another number and retry.

← Agents Calls →