Skip to main content
To take real phone calls, your agent needs a phone number. This guide searches the carrier’s inventory, holds a number so it can’t be sniped, purchases it from your prepaid wallet, and points it at a published agent. All paths are relative to https://builder.flowyte.com/api/v1.
Authenticate with Authorization: Bearer flowyte_sk_…. Purchasing debits your prepaid wallet — top it up first if needed.

​
What you’ll use

ActionEndpointScope
Search inventoryGET /numbers/searchnumbers:read
Reserve (hold)POST /numbers/reservenumbers:write
PurchasePOST /numbers/purchasenumbers:write
Assign to an agentPOST /numbers/{id}/assignnumbers:write
Check walletGET /billing/walletbilling:read
1

Search available numbers

Filter by area code, city, state, capabilities, or a vanity pattern. bestEffort (default true) widens a too-narrow filter to nearby matches — set it false for strict last-four or vanity matching. Each result carries an e164 and a price.
curl "https://builder.flowyte.com/api/v1/numbers/search?areaCode=415&numberType=local&features=voice" \
  -H "Authorization: Bearer $FLOWYTE_API_KEY"
Pick an e164 from the results, e.g. +14155551234.
2

Reserve it

Hold the number (~30 minutes) so it can’t be purchased out from under you while you confirm. Reserving does not charge your wallet. Capture the returned reservation id.
curl -X POST https://builder.flowyte.com/api/v1/numbers/reserve \
  -H "Authorization: Bearer $FLOWYTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "e164": "+14155551234" }'
Reserving is optional but recommended for interactive flows. A 409 means the number can no longer be held — search again and pick another.
3

Purchase it

Purchase debits your prepaid wallet. Pass the reservationId from the previous step so the order can’t be sniped. A 402 means insufficient balance — top up with POST /billing/wallet/topup, then retry.
curl -X POST https://builder.flowyte.com/api/v1/numbers/purchase \
  -H "Authorization: Bearer $FLOWYTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "e164": "+14155551234", "reservationId": "'$RESERVATION_ID'" }'
The response is the purchased number. Capture data.id as NUMBER_ID.
Already own a number elsewhere? Use POST /numbers/import instead — it routes a number on your carrier account to this deployment with no wallet charge.
4

Assign it to an agent

Point the number at your agent. Inbound calls now route to the agent’s published version.
curl -X POST https://builder.flowyte.com/api/v1/numbers/$NUMBER_ID/assign \
  -H "Authorization: Bearer $FLOWYTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "'$AGENT_ID'" }'
5

Publish & call it

Calls serve the last published version of the agent — not your draft. If you haven’t published since your latest edits, publish now, then dial the number.
curl -X POST https://builder.flowyte.com/api/v1/agents/$AGENT_ID/publish \
  -H "Authorization: Bearer $FLOWYTE_API_KEY"
An assigned number routes to the agent’s published version. If the agent has never been published, callers reach nothing — publish before you dial.

​
Managing numbers later

To stop using a number without losing it, DELETE /numbers/{id}/assign moves it back to your pool (you keep owning and paying for it). DELETE /numbers/{id} permanently releases it to the carrier. SMS on a number requires per-organization 10DLC brand and campaign registration before sends are allowed.