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

# Phone Numbers

> Connect numbers in the Verbeo dashboard or through the API, assign them to agents for inbound calls, and use them as the caller ID for outbound calls.

Phone numbers in Verbeo are the bridge between the public telephone network and your AI agents. You connect numbers in the Verbeo dashboard or through the [Phone Numbers API](/api-reference/phone-numbers/overview), then assign them to agents so calls can flow in both directions. Every number you provision is yours to use for inbound call routing, outbound call initiation, or both.

## Provisioning a number

In the dashboard, phone number management happens in the **Phone Numbers** page. From there you can add new numbers, assign them to agents, and remove numbers you no longer need. Everything on that page can also be done through the [Phone Numbers API](/api-reference/phone-numbers/overview).

<Steps>
  <Step title="Open Phone Numbers">
    Navigate to **Phone Numbers** in the left sidebar of your Verbeo dashboard.
  </Step>

  <Step title="Add a number">
    Click **Add Number** and follow the prompts to provision a new phone number for your workspace.
  </Step>

  <Step title="Assign to an agent">
    Once provisioned, open the number's settings and assign it to the agent that should handle inbound calls to that number.
  </Step>
</Steps>

<Note>
  You can also initiate outbound calls directly from the Phone Numbers page using the **Make Call** button, without writing any code.
</Note>

## Inbound calls

When a caller dials one of your provisioned numbers, Verbeo routes the call to whichever agent is assigned to that number. The assigned agent picks up immediately and begins the conversation according to its system prompt and settings.

Each provisioned number is assigned one agent by default. To personalize the call — or to send different callers to different agents on the same number — set an [inbound call webhook](/guides/inbound-call-webhook) on the number. Verbeo calls your endpoint before the agent picks up, and your response supplies the dynamic variables for the agent's prompt and, optionally, a different agent to answer.

## Outbound calls

For outbound calls placed through the [Calls API](/api-reference/calls/create), `from_number` must be a phone number you have already connected to your Verbeo workspace. You cannot use an arbitrary number as the caller ID — it must belong to your workspace.

```json theme={null}
{
  "to_number": "+12025551234",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "from_number": "+19875554321"
}
```

If `from_number` is not a number of your workspace, the API returns a `422` error.

<Warning>
  The Calls API requires a **private** API key (prefix `vbr_`). Public keys (`vbr_pub_`) cannot be used to initiate calls.
</Warning>

## E.164 format

All phone numbers in Verbeo — whether you're provisioning them, assigning them as `from_number`, or setting a `staticDestination` for call transfers — must be in **E.164 format**.

E.164 is an international standard for phone number formatting:

* Starts with a `+` sign
* Followed by the country code (no leading zero)
* Followed by the subscriber number, with no spaces, dashes, or parentheses

<CodeGroup>
  ```text Valid E.164 examples theme={null}
  +12025551234      (US)
  +441234567890     (UK)
  +61412345678      (Australia)
  +4915123456789    (Germany)
  ```

  ```text Invalid formats theme={null}
  (202) 555-1234    (missing + and country code)
  +1 202 555 1234   (contains spaces)
  001-202-555-1234  (trunk prefix format)
  12025551234       (missing + prefix)
  ```
</CodeGroup>

<Tip>
  Most phone number libraries (like `libphonenumber`) can convert local formats to E.164 automatically. If you're building a workflow that accepts user-entered phone numbers, normalize them to E.164 before passing them to Verbeo.
</Tip>

## Inbound vs. outbound: summary

<CardGroup cols={2}>
  <Card title="Inbound" icon="phone-incoming">
    A caller dials your provisioned number. Verbeo routes the call to the assigned agent automatically. No API call required.
  </Card>

  <Card title="Outbound" icon="phone-outgoing">
    Your code calls the [Calls API](/api-reference/calls/create) with a `to_number`, a `from_number` and, optionally, an `agent_id`. The `from_number` must be one of your workspace's numbers.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.