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

# Phone Numbers

> Your agent can reserve a phone number to make calls and send text messages.

<Note>
  During the beta, reserving a phone number is free. Each account is limited to one number at a time. If you'd like a different number, delete your current one and purchase a new one.
</Note>

***

## How to reserve a number

There are two ways to reserve a number: via the Poku dashboard, or programmatically (either directly via the API or by asking your Poku agent).

### Option 1 — Dashboard

<Steps>
  <Step title="Log in to the Poku dashboard">
    Go to [dashboard.pokulabs.com](https://dashboard.pokulabs.com).
  </Step>

  <Step title="Open the Numbers tab">
    Navigate to the **Numbers** tab in the sidebar.
  </Step>

  <Step title="Purchase a number">
    Browse available numbers, find one you like, and hit **Reserve**.
  </Step>
</Steps>

Once the number appears in your purchased numbers list, your agent will automatically use it for all outbound calls and texts.

***

### Option 2 — Programmatically (API or agent)

You can reserve a number directly via the API, or by asking your agent to do it for you if it has the Poku Skill installed.

#### Step 1: Browse available numbers

Filter by country (`US` or `GB`) and area code, or omit any parameters you don't need:

```bash theme={null}
curl -G https://api.pokulabs.com/numbers/available \
  -H "Authorization: Bearer <your-poku-api-key>" \
  --data-urlencode "country=<US|GB>" \
  --data-urlencode "areaCode=<area code>"
```

An empty response means no numbers match — try broadening your search.

#### Step 2: Reserve your chosen number

Once you've identified the number you want, reserve it with a POST request:

```bash theme={null}
curl -X POST https://api.pokulabs.com/numbers/reserve \
  -H "Authorization: Bearer <your-poku-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "<selected number>"}'
```

On success, the number is immediately reserved to your account and ready for use.

#### Asking your agent

If you have the Poku Skill installed, you can also ask your agent in plain language, for example:

> "Reserve a phone number for me with a 916 area code."

The agent will browse available numbers, confirm your selection, and complete the reservation on your behalf.

***

## Verify your reserved number

You can confirm your reserved number is registered to your Poku account at any time with a GET request:

```bash theme={null}
curl -H "Authorization: Bearer <your-poku-api-key>" \
  https://api.pokulabs.com/numbers
```

A successful response returns your reserved number:

```json theme={null}
[
  {
    "id": "cab29b2d-a8be-43a6-82e1-7eb33b9fc844",
    "phoneNumber": "+14157046427",
    "createdAt": "2026-03-02T17:21:32.602Z",
    "updatedAt": "2026-03-02T17:21:32.602Z"
  }
]
```

An empty array (`[]`) means no number is currently reserved on your account.