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

# Bring your own Twilio number

> Use a phone number you already own in your own Twilio account for live call routing.

If you already own numbers in Twilio and would like to keep them in your own account, you can
connect that Twilio account and use your existing phone number.

Note that you can also port a number from another Twilio account to ours, for example to migrate
an existing call route from PagerDuty or Opsgenie.

<Info>
  Calls on your own number run entirely in your Twilio account. Twilio bills you directly for owning the number,
  receiving calls to it, and placing calls to your responders.
</Info>

## Before you start

You need a Twilio account containing at least one voice-capable number, and permission to manage
call routes in incident.io.

We strongly recommend putting the numbers you want on-call to answer in a dedicated **subaccount**.
The credentials you give us are the whole account's credentials, so a subaccount is what limits
what we can reach. A subaccount's auth token cannot touch the parent account or its other numbers.

## Step 1: Create a subaccount and move your numbers into it

Create the subaccount in the Twilio console, under **Account management**.

Moving an existing number into it is an API operation, and the console doesn't expose it. Run this
with your **parent** account credentials, because the subaccount has no rights over a number it
doesn't own yet:

```bash theme={null}
curl -X POST \
  "https://api.twilio.com/2010-04-01/Accounts/$PARENT_ACCOUNT_SID/IncomingPhoneNumbers/$PHONE_NUMBER_SID.json" \
  --data-urlencode "AccountSid=$SUBACCOUNT_SID" \
  -u "$PARENT_ACCOUNT_SID:$PARENT_AUTH_TOKEN"
```

`$PHONE_NUMBER_SID` is the number's SID, which starts with `PN`. Transfers only work between
accounts under the same parent, and the destination subaccount must be active.

The number keeps its existing webhook configuration through the transfer. We overwrite the voice
webhook when you attach it to a call route, so there's nothing to clean up first.

## Step 2: Copy the credentials

Switch to the subaccount in the console and copy two values from the **Account Info** panel on its
dashboard:

* **Account SID**, starting with `AC`
* **Auth Token**

<Warning>
  Use the Auth Token, not an API Key. Twilio signs the webhooks it sends us with the account's auth token, so it's the
  only credential that can prove an incoming call really came from Twilio.
</Warning>

## Step 3: Add the connection in incident.io

Go to **Settings → Call routes**, select **Request number**, then open the **Bring your own
number** tab. Select **Add Twilio connection** and enter the account SID, auth token, and the
region your Twilio account lives in.

We check the credentials as you save, so a mistake surfaces immediately rather than on the first
call. Once saved, the connection is available to every call route in your organization.

## Step 4: Create a call route on your number

On the **Bring your own number** tab, choose the Twilio connection, then pick one of its numbers.

Because the number already exists, a call route on your own number skips number purchase and
regulatory setup entirely. It activates as soon as you select the number, and we point that
number's voice URL and status callback at incident.io.

## What we do with your credentials

We use them to read the account, list its phone numbers, point the numbers you choose at our
webhooks, and read the calls and recordings belonging to those routes.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failed, auth token is not valid for account AC...">
    Twilio error 20003. Most often the credential is the wrong type: an API Key SID and secret
    rather than the account's auth token. Take the Auth Token from the Account Info panel instead.

    It also appears when the auth token belongs to a different account than the SID you entered, for
    example a parent account's token paired with a subaccount's SID. Each account, including each
    subaccount, has its own auth token, and the pair has to match.

    Finally, check the region. A Twilio auth token is only valid in the region it was created in, so
    a token made in `us1` will not authenticate against `ie1` or `au1`.
  </Accordion>

  <Accordion title="I can't choose an incident.io on-call number to call responders from">
    That option isn't available on a route using your own number, because we can't bridge calls
    between two accounts. Responders are called from this route's phone number instead.
  </Accordion>

  <Accordion title="Some of my numbers aren't in the list">
    We only offer voice-capable numbers. Numbers already backing another call route are shown
    but can't be selected twice.
  </Accordion>

  <Accordion title="I want to remove a connection">
    Delete the call routes using it first. We block removing a connection that still has routes
    attached, because those routes would stop paging anyone.
  </Accordion>

  <Accordion title="What happens to my number if I delete the call route?">
    We remove the incident.io webhooks from the number and leave it in your account. We never
    release a number we don't own, including when an organization is archived.

    To move it back to the parent account, or into a different subaccount, run the same transfer
    call as in [Step 1](#step-1-create-a-subaccount-and-move-your-numbers-into-it) with the
    destination account's SID.
  </Accordion>

  <Accordion title="Can I use my main account rather than a subaccount?">
    Yes. The credentials for a main account can reach its subaccounts and every number in them,
    which is why we recommend a dedicated subaccount instead.
  </Accordion>
</AccordionGroup>