Guides

Phone numbers

Search available numbers, purchase one for your tenant, configure failover, and release numbers you no longer need.

Phone numbers are how callers reach your assistants. The flow is: search the provider inventory for available numbers, purchase one into your tenant, link it to an assistant, and optionally set a failover number for outages.

Method	Path	Purpose
GET	`/phone-numbers/available`	Search numbers available for purchase
POST	`/phone-numbers`	Purchase a number
GET	`/phone-numbers`	List numbers you own
GET	`/phone-numbers/{id}`	Get one of your numbers
PATCH	`/phone-numbers/{id}`	Update name / failover number
DELETE	`/phone-numbers/{id}`	Release a number

Search available numbers#

GET /phone-numbers/available returns numbers from the provider inventory that are not yet owned by anyone — use GET /phone-numbers for numbers you already own.

Query param	Type	Required	Description
`country`	string	Yes	Country code, e.g. `US`, `AU`, `NZ`, `CA`, `GB`, `CH`. Note: `IT` (Italy) may not be available for searches yet.
`locality`	string	No	City or region, e.g. `Melbourne`, `Sydney`, `Perth`
`areaCode`	string	No	Area code the number should start with (e.g. `438` for `+1438...`)

bash

curl "https://core-api.heysadie.ai/phone-numbers/available?country=AU&locality=Sydney" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Purchase a number#

POST /phone-numbers — the number must be one returned by the availability search.

Field	Type	Required	Description
`phoneNumber`	string	Yes	The number to purchase, from the available list
`name`	string	Yes	Friendly label (e.g. "Main line", "Reservations")
`failoverNumber`	string	No	E.164 failover destination (see below)

bash

curl -X POST https://core-api.heysadie.ai/phone-numbers \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+61255501234",
    "name": "Reservations line",
    "failoverNumber": "+61255509876"
  }'

Once purchased, the number belongs to your account and can be assigned to an assistant — set phoneNumberId on the assistant via POST /assistants or PATCH /assistants/{id} (see Assistants).

Restricted countries

Some countries are served from a pre-purchased pool only. If a number in such a country isn't in the pool, the purchase fails with a 400 (PREPURCHASED_REQUIRED); a pool number already assigned to another tenant fails with PREPURCHASED_ASSIGNED.

List and inspect your numbers#

GET /phone-numbers supports limit, offset, and search query params; GET /phone-numbers/{id} returns a single number you own.

Terminal

curl "https://core-api.heysadie.ai/phone-numbers?limit=25" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Configure failover#

The failover number is where calls are forwarded when the assistant fails or needs to escalate. It can be set in two places:

On the phone number — failoverNumber at purchase, or later via PATCH /phone-numbers/{id}. Must be a plain E.164 number (e.g. +15551234567); invalid formats are rejected.
On the assistant — the assistant's own failoverNumber + failoverMode fields (see Assistants). When updating an assistant, the failover number may include an extension after a comma — e.g. +15551234567,101 — and only the part before the comma is validated as E.164.

Terminal

curl -X PATCH https://core-api.heysadie.ai/phone-numbers/PHONE_NUMBER_ID \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Reservations line", "failoverNumber": "+61255509876" }'

Both name and failoverNumber are optional on PATCH — only provided fields are updated.

TODO — verify

Extension support (+15551234567,101) is confirmed in the validation for assistant failover-number updates. The phone-number endpoints (POST /phone-numbers, PATCH /phone-numbers/{id}) validate failoverNumber as strict E.164 with no extension handling in the current code — verify whether comma extensions are intended to be accepted there before documenting them for these routes.

Release a number#

DELETE /phone-numbers/{id} releases the number and stops billing for it.

What happens:

Ownership is validated — the number must belong to your tenant.
The number is unlinked from any associated assistant.
The number is released back to the provider inventory — billing stops immediately on success.
The record is marked deleted in your account.

Terminal

curl -X DELETE https://core-api.heysadie.ai/phone-numbers/PHONE_NUMBER_ID \
  -H "Authorization: ApiKey YOUR_API_KEY"

The response confirms the release: { "status": "released", "phoneNumberId": "...", "phoneNumber": "..." }.

Releases are permanent

Once released, the number becomes available for other customers to purchase. If the provider-side release fails, the record is still marked deleted in your account and manual cleanup on the provider side may be required.

Next steps#

Assistants — link the number with phoneNumberId and enable SMS on it.
Calls — see the calls arriving on your numbers.

PreviousTask groups NextCalls