Menu

Expand
Rate this page:

Set a phone number's inbound processing Region using the REST API

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.

Review your phone number's webhook configuration in the target Region

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.

Check which Region your phone number is currently routed to

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.

Set which Region your phone number is currently routed to

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.

Verify the incoming call routing Region

To demonstrate that calls to your phone number are being handled in the appropriate Region after a routing change, perform the following steps:

  1. Place a call to your phone number from any phone.
  2. Visit the phone number’s Call Logs in the target Region.
  3. Verify that you find a new Call Log that corresponds with your sample call from step 1.
  4. Visit the phone number’s Call Logs in a different, non-Active Region.
  5. Verify that you do not find a Call Log that corresponds with your sample call.

Routing calls to an Elastic SIP Trunk or Twilio SIP Domain

Twilio routes inbound calls to your Twilio-powered SIP Trunks and SIP Domains using the same system as for phone numbers.

To manage routing for these resources types using the Inbound Processing Region API, adjust the request URL paths illustrated above as follows:

  1. Replace the word PhoneNumbers with Trunk or SipDomain, depending on which resource type you are managing.
  2. 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.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

        
        
        

        Thank you for your feedback!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more