Skip to main content
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

1

Search

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

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

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

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…CallResult
Keep owning it, just free it from the agentDELETE /numbers/{id}/assignMoves to your pool (status: available); reassign any time
Stop owning and paying for itDELETE /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

ActionEndpointScope
List owned numbersGET /numbersnumbers:read
Search available numbersGET /numbers/searchnumbers:read
Re-check one number’s priceGET /numbers/available/{e164}numbers:read
Reserve a holdPOST /numbers/reservenumbers:write
Release a holdDELETE /numbers/reserve/{id}numbers:write
PurchasePOST /numbers/purchasenumbers:write
Import an owned numberPOST /numbers/importnumbers:write
Assign to an agentPOST /numbers/{id}/assignnumbers:write
Unassign (keep, move to pool)DELETE /numbers/{id}/assignnumbers:write
Release to carrierDELETE /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"}'
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.