This guide will illustrate how to use Twilio's REST API to control which Twilio Region handles incoming calls to your phone numbers.
To get the most out of this guide, please ensure you are familiar with the concepts described in the Inbound Processing Region overview.
The examples in this guide will target the Ireland (IE1) Region. To see the available Regions, visit the Region and Product Availability reference.
Your phone number's webhook configuration is Region-specific and may vary between different Regions. Before making any changes to your phone number's call routing, it's a good idea to double-check the number's configuration in the specific Region that you plan to set the number's routing to.
To manage a phone number's configuration via Twilio Console, follow the instructions under the phone number section of our guide to managing Region-specific resources in the Console.
To inspect a phone number's configuration via the API, make a request to fetch the IncomingPhoneNumber resource in the target Region. Make sure that the request's FQDN targets the desired Region, and remember that the default FQDN of api.twilio.com defaults to the US1 Region.
For example, to check a phone number's configuration in the IE1 Region, you might make the following request using cURL or another HTTP client:
curl -u $API_KEY_SID:$API_KEY_SECRET \ https://api.dublin.ie1.twilio.com/2010-04-01/Accounts/$ACCOUNT_SID/IncomingPhoneNumbers/$PHONE_NUMBER.json
Alternatively, you can issue these requests using a Twilio helper library or the Twilio CLI. See the guide to using the REST API with Twilio Regions for more information.
If the phone number's configuration in the target Region is not correct, use the REST API or the Console to adjust the number's configuration in the target Region before proceeding.
To check the Region that your number is routed to, make a GET request to the Inbound Processing Region API.
curl -u $API_KEY_SID:$API_KEY_SECRET \ https://routes.dublin.ie1.twilio.com/v2/PhoneNumbers/+16505551212
Look for the
voice_region key in the response. This will indicate which Region your number's inbound voice calls will be routed to for processing.
If the response to this request is a 404, it indicates that this number does not yet have an explicitly set routing configuration, and will route inbound calls to the default United States (US1) Region.
This occurs only when a phone number has been provisioned via the
/IncomingPhoneNumbers REST API resource. Phone numbers provisioned via the Twilio Console will automatically be configured with an explicit routing configuration.
To set the Region that your number is routed to, make a POST request to the Inbound Processing Region API.
In this example, the request sets the Region for inbound calls to IE1:
curl -u $API_KEY_SID:$API_KEY_SECRET \ https://routes.dublin.ie1.twilio.com/v2/PhoneNumbers/+16505551212 \ -d VoiceRegion=us1
Warning: changing a phone number’s incoming call routing Region can lead to call handling errors in certain cases. Be sure to test call routing in the target Region in a pre-production environment before changing routing in production.
To demonstrate that calls to your phone number are being handled in the appropriate Region after a routing change, perform the following steps:
- Place a call to your phone number from any phone.
- Visit the phone number’s Call Logs in the target Region.
- Verify that you find a new Call Log that corresponds with your sample call from step 1.
- Visit the phone number’s Call Logs in a different, non-Active Region.
- Verify that you do not find a Call Log that corresponds with your sample call.
To manage routing for these resources types using the Inbound Processing Region API, adjust the request URL paths illustrated above as follows:
- Replace the word
SipDomain, depending on which resource type you are managing.
- Replace the phone number in the path with the Trunk or Domain's full URI.
It may take up to five minutes for a routing change to take effect.