Numbers

A number is a phone line your organization owns. Inbound calls to it ring the agent you assign. You can buy a new number from the carrier, or import one you already own, then route it to any agent — all over the API.

The lifecycle

GET /numbers/search browses purchasable inventory. Filter by areaCode, locality, administrativeArea (state), numberType (local or toll_free), required features (voice, sms, …), or a vanity contains / endsWith. bestEffort (default true) widens a too-narrow filter; set it false for strict last-four or vanity matching.

Reserve (optional)

POST /numbers/reserve holds a number (about 30 minutes) so it can’t be taken while you confirm. This does not charge your wallet. Pass the returned reservation id to purchase.

Purchase

POST /numbers/purchase buys the number and debits your prepaid wallet. Include the reservationId from the hold so the order can’t be sniped. Returns the owned number.

Assign

POST /numbers/{id}/assign points the number at an agent (sets its default agent). Inbound calls now reach that agent.

Already own a number elsewhere? POST /numbers/import brings a number you hold on your carrier account into Flowyte with no wallet charge — and can assign it to an agent in the same call.

Releasing vs unassigning

Detaching a number has two very different outcomes:

You want to…	Call	Result
Keep owning it, just free it from the agent	`DELETE /numbers/{id}/assign`	Moves to your pool (`status: available`); reassign any time
Stop owning and paying for it	`DELETE /numbers/{id}`	Permanently released to the carrier

DELETE /numbers/{id} is irreversible — the number goes back to the carrier and may be gone for good. To park a number without losing it, unassign it instead.

Vendor-neutral provider field

Each number carries a provider field. It is an opaque, vendor-neutral label for the carrier behind the line — treat it as an identifier, not a brand to depend on. Cost is reported as monthlyCost (and setupCost on available numbers).

In the API

Action	Endpoint	Scope
List owned numbers	`GET /numbers`	`numbers:read`
Search available numbers	`GET /numbers/search`	`numbers:read`
Re-check one number’s price	`GET /numbers/available/{e164}`	`numbers:read`
Reserve a hold	`POST /numbers/reserve`	`numbers:write`
Release a hold	`DELETE /numbers/reserve/{id}`	`numbers:write`
Purchase	`POST /numbers/purchase`	`numbers:write`
Import an owned number	`POST /numbers/import`	`numbers:write`
Assign to an agent	`POST /numbers/{id}/assign`	`numbers:write`
Unassign (keep, move to pool)	`DELETE /numbers/{id}/assign`	`numbers:write`
Release to carrier	`DELETE /numbers/{id}`	`numbers:write`

# 1. Find a local number in area code 415
curl "https://builder.flowyte.com/api/v1/numbers/search?areaCode=415&numberType=local" \
  -H "Authorization: Bearer flowyte_sk_..."

# 2. Purchase it (debits the wallet)
curl https://builder.flowyte.com/api/v1/numbers/purchase \
  -H "Authorization: Bearer flowyte_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"e164":"+14155550100"}'

// Assign an owned number to an agent
await fetch("https://builder.flowyte.com/api/v1/numbers/NUMBER_ID/assign", {
  method: "POST",
  headers: {
    Authorization: "Bearer flowyte_sk_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ agentId: "AGENT_ID" }),
});

A purchase needs funds in your prepaid wallet — an empty balance returns 402. A number that was taken between search and purchase returns 409.

The agent must be published to answer live calls on its assigned number.

Get started

Concepts

Channels

Integrations

Guides

Trust & Security

The lifecycle

Releasing vs unassigning

Vendor-neutral provider field

In the API

​The lifecycle

​Releasing vs unassigning

​Vendor-neutral provider field

​In the API

The lifecycle

Releasing vs unassigning

Vendor-neutral provider field

In the API