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

# Import a Twilio number

> Add a phone number you own in Twilio by its Account SID and Auth Token, and choose the assistants that answer it and dial from it.

Adds a number from your own Twilio account, using the account's credentials to place and receive its calls.

<Note>
  For a new number, [SIP trunking](/api-reference/phone-numbers/connect-sip) is the path to choose: it works with Twilio through Elastic SIP Trunking, and only a SIP-trunk number has an [inbound call webhook](/guides/inbound-call-webhook).
</Note>

This request stores the number and does not contact Twilio. Inbound calls reach Verbeo only after you point the number at it — call [`POST /phone-number/{id}/twilio-webhook`](/api-reference/phone-numbers/twilio-webhook) once the import has succeeded.

## Body

<ParamField body="phone_number" type="string" required>
  The number in E.164 format — a `+`, the country code, the number: `+14155550123`. Spaces, dashes and brackets are accepted and removed.
</ParamField>

<ParamField body="twilio_sid" type="string" required>
  Your Twilio **Account SID**: `AC` followed by 32 hexadecimal characters.
</ParamField>

<ParamField body="twilio_auth_token" type="string" required>
  Your Twilio **Auth Token**, exactly as the Twilio console shows it. Up to 128 characters, no spaces. Write-only: no endpoint returns it.
</ParamField>

<ParamField body="nickname" type="string">
  Your label for the number, up to 100 characters.
</ParamField>

<ParamField body="inbound_agent_id" type="string">
  UUID of the assistant that answers calls to this number.
</ParamField>

<ParamField body="outbound_agent_id" type="string">
  UUID of the assistant that places calls from this number when a call names none.
</ParamField>

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.verbeo.ai/v1/phone-number/twilio" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "phone_number": "+14155550123",
      "twilio_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "twilio_auth_token": "your_twilio_auth_token",
      "nickname": "Main line",
      "inbound_agent_id": "550e8400-e29b-41d4-a716-446655440000"
    }'
  ```

  ```javascript Node.js theme={null}
  const headers = {
    Authorization: `Bearer ${process.env.VERBEO_API_KEY}`,
    "Content-Type": "application/json",
  };

  const res = await fetch("https://api.verbeo.ai/v1/phone-number/twilio", {
    method: "POST",
    headers,
    body: JSON.stringify({
      phone_number: "+14155550123",
      twilio_sid: process.env.TWILIO_ACCOUNT_SID,
      twilio_auth_token: process.env.TWILIO_AUTH_TOKEN,
      nickname: "Main line",
      inbound_agent_id: "550e8400-e29b-41d4-a716-446655440000",
    }),
  });
  const { data: number } = await res.json();

  // Then point the number's calls at Verbeo.
  await fetch(`https://api.verbeo.ai/v1/phone-number/${number.id}/twilio-webhook`, {
    method: "POST",
    headers,
  });
  ```

  ```python Python theme={null}
  import os, requests

  headers = {"Authorization": f"Bearer {os.environ['VERBEO_API_KEY']}"}

  number = requests.post(
      "https://api.verbeo.ai/v1/phone-number/twilio",
      headers=headers,
      json={
          "phone_number": "+14155550123",
          "twilio_sid": os.environ["TWILIO_ACCOUNT_SID"],
          "twilio_auth_token": os.environ["TWILIO_AUTH_TOKEN"],
          "nickname": "Main line",
          "inbound_agent_id": "550e8400-e29b-41d4-a716-446655440000",
      },
  ).json()["data"]

  # Then point the number's calls at Verbeo.
  requests.post(
      f"https://api.verbeo.ai/v1/phone-number/{number['id']}/twilio-webhook",
      headers=headers,
  )
  ```
</CodeGroup>

## Response

`201 Created` with [the phone number object](/api-reference/phone-numbers/overview#the-phone-number-object). `provider` is `twilio`, and the Auth Token is not in it.

```json theme={null}
{
  "success": true,
  "data": {
    "id": "7d9f3b52-4c1e-4a8e-9b1a-2f6c0d4e8a11",
    "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
    "phone_number": "+14155550123",
    "nickname": "Main line",
    "provider": "twilio",
    "is_active": true,
    "max_cps": 1,
    "inbound_agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "outbound_agent_id": null,
    "inbound_webhook_url": null,
    "created_at": "2026-01-15T10:30:00.123456+00:00",
    "updated_at": "2026-01-15T10:30:00.123456+00:00",
    "inbound_agent_name": "Customer Support",
    "outbound_agent_name": null
  }
}
```

## Errors

| Code | Status | When |
| - | - | - |
| `VALIDATION_FAILED` | 422 | A missing or malformed field — the message names it, e.g. `twilio_sid: must be a Twilio Account SID: AC followed by 32 hex characters`. Also an assistant id that is not an assistant of your workspace. |
| `CONFLICT` | 409 | The number is already connected to Verbeo, in your workspace or another. |

<Note>
  The credentials are not checked against Twilio here. Wrong ones are reported when you [configure the webhook](/api-reference/phone-numbers/twilio-webhook), and when the number first places a call.
</Note>


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