Buy a number & go live

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

Action	Endpoint	Scope
Search inventory	`GET /numbers/search`	`numbers:read`
Reserve (hold)	`POST /numbers/reserve`	`numbers:write`
Purchase	`POST /numbers/purchase`	`numbers:write`
Assign to an agent	`POST /numbers/{id}/assign`	`numbers:write`
Check wallet	`GET /billing/wallet`	`billing:read`

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"

const params = new URLSearchParams({ areaCode: "415", numberType: "local", features: "voice" });
const res = await fetch(`https://builder.flowyte.com/api/v1/numbers/search?${params}`, {
  headers: { Authorization: `Bearer ${process.env.FLOWYTE_API_KEY}` },
});
const { data: numbers } = await res.json();

import os, requests
r = requests.get(
    "https://builder.flowyte.com/api/v1/numbers/search",
    headers={"Authorization": f"Bearer {os.environ['FLOWYTE_API_KEY']}"},
    params={"areaCode": "415", "numberType": "local", "features": "voice"},
)
numbers = r.json()["data"]

Pick an e164 from the results, e.g. +14155551234.

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.

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.

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'" }'

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.

Get started

Concepts

Channels

Integrations

Guides

Trust & Security

Buy a number & go live

What you’ll use

Managing numbers later

​What you’ll use

​Managing numbers later

What you’ll use

Managing numbers later