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

# Buy a number & go live

> Search available numbers, reserve one, purchase it from your wallet, assign it to an agent, and route real calls.

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

<Note>
  Authenticate with `Authorization: Bearer flowyte_sk_…`. Purchasing **debits your prepaid wallet** — top it up first if needed.
</Note>

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

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

    <CodeGroup>
      ```bash curl theme={null}
      curl "https://builder.flowyte.com/api/v1/numbers/search?areaCode=415&numberType=local&features=voice" \
        -H "Authorization: Bearer $FLOWYTE_API_KEY"
      ```

      ```ts Node theme={null}
      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();
      ```

      ```python Python theme={null}
      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"]
      ```
    </CodeGroup>

    Pick an `e164` from the results, e.g. `+14155551234`.
  </Step>

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

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

    <Tip>
      Reserving is optional but recommended for interactive flows. A `409` means the number can no
      longer be held — search again and pick another.
    </Tip>
  </Step>

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

    ```bash theme={null}
    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`.

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="Assign it to an agent">
    Point the number at your agent. Inbound calls now route to the agent's **published** version.

    ```bash theme={null}
    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'" }'
    ```
  </Step>

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

    ```bash theme={null}
    curl -X POST https://builder.flowyte.com/api/v1/agents/$AGENT_ID/publish \
      -H "Authorization: Bearer $FLOWYTE_API_KEY"
    ```
  </Step>
</Steps>

<Warning>
  An assigned number routes to the agent's published version. If the agent has never been
  published, callers reach nothing — publish before you dial.
</Warning>

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