> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowyte.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Numbers

> Own a phone number and point it at an agent — search, reserve, purchase, assign.

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Assign">
    `POST /numbers/{id}/assign` points the number at an agent (sets its default agent). Inbound
    calls now reach that agent.
  </Step>
</Steps>

<Note>
  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.
</Note>

## 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                         |

<Warning>
  `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.
</Warning>

## 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` |

<CodeGroup>
  ```bash curl theme={null}
  # 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"}'
  ```

  ```js Node theme={null}
  // 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" }),
  });
  ```
</CodeGroup>

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

The agent must be [published](/concepts/agents) to answer live calls on its assigned number.