Skip to main content
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.
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.

​
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:
$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
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.

​
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

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.
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.
We only offer voice-capable numbers. Numbers already backing another call route are shown but can’t be selected twice.
Delete the call routes using it first. We block removing a connection that still has routes attached, because those routes would stop paging anyone.
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 with the destination account’s SID.
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.