Phone numbers
Search live inventory, buy a number in one call, bind it to an inbox and an agent, and release it when you no longer need it.
Every call needs a from — a number your account owns. You search live inventory, buy a number in one call, and it becomes the caller id your agent dials from and the line that answers incoming calls into your inbox.
| Operation | Method & path | Scope |
|---|---|---|
| Search inventory | GET /v1/phone/numbers/available | phone:read |
| List your numbers | GET /v1/phone/numbers | phone:read |
| Buy | POST /v1/phone/numbers | phone:write |
| Get one | GET /v1/phone/numbers/{id} | phone:read |
| Configure | PATCH /v1/phone/numbers/{id} | phone:write |
| Release | DELETE /v1/phone/numbers/{id} | phone:write |
Search available numbers
Filter by country (ISO 3166-1 alpha-2, default US), areaCode, a contains digit sequence, and type (local, toll_free, national, mobile). limit is 1–100 and defaults to 10.
capabilities lists what the carrier supports on the number (voice, sms); Dairo uses it for calls. monthlyCostUsd and setupCostUsd are the recurring and one-time cost of owning it.
A result with purchasable: false and a masked number like +16313------ is real inventory your account can't buy yet: additional identity verification is required before those numbers unlock. It isn't an error and it isn't hidden from you — pick a purchasable: true number instead.
Buy a number
Pass the exact E.164 number from a search result. You get back a phone_number record; when the country requires no paperwork it arrives with status: "active", immediately usable as a caller id. Buying a number you already own returns 409, and so does a number that is no longer available.
With an active number in hand, use it as the from on Making calls.
Regulated countries: pending is not an error
Some countries regulate who may hold a local number. Germany, for example, requires proof of a local address before a number activates. Buying a number there succeeds, but the order settles at status: "pending" with a requirements object listing exactly which documents are outstanding:
The purchase is reserved for you. Poll GET /v1/phone/numbers/{id} to watch the status: once the listed requirements are met, the number turns active. A number's status is one of active, pending, or released — only an active number can be a call's from.
Configure a number
Two bindings turn a bare number into part of your fleet — set either, both, or clear them with an explicit null:
inboxId— every call the number answers lands in that inbox's mailbox as a message, next to your email and other channels.agentId— attribute the number to one of your agents, so its calls carry clear provenance.
The same call configures the agent that answers when someone dials the number — inboundInstructions, inboundGreeting, inboundVoice, and inboundLanguage; Inbound calls covers them. You can replace the number's metadata there too — a JSON object of at most 8 KiB (null clears it); the request must carry at least one field. Binding an inbox or agent you don't own is rejected. List everything you own with GET /v1/phone/numbers — add includeReleased=true to include released numbers, which stay on your account for the audit trail.
Release a number
Releasing returns the number to the public pool — anyone can buy it afterwards, and whoever does receives the calls meant for you. Because that is irreversible, the API refuses to release without an explicit confirm: true in the body (400 without it), and releasing an already-released number returns 409. A successful release returns the number's final record with status: "released" and releasedAt set.
Release is irreversible. A released number stops receiving calls for you, monthly charges end, and the number returns to the pool for anyone to claim. If a number is printed on letterheads or saved in customers' contacts, keep it.