Menu

Expand
Rate this page:

Using the Twilio REST API in a non-US Region

This guide will show you how to manage resources in your target Twilio Region with Twilio’s REST API. By the end of the guide, you’ll learn:

  • How to select a target Region for API requests
  • How to authenticate requests using Region-specific credentials
  • How to interact with various Region-specific resources using the API
  • Selecting a target Region using Twilio helper libraries

Note that this guide uses examples that utilize the cURL command-line utility for making API requests, rather than one of Twilio’s language-specific helper libraries. This choice is intended to highlight the principles of Twilio’s REST API by avoiding the use of higher level abstractions that tend to obscure some of these details.

Select a target Region for your API requests

The Twilio REST API operates on a per-Region basis. When making requests to the API, it’s up to you to select which Region will handle the request. Whichever Region you choose will be the Region that processes and stores data related to the request.

If you don’t specify a target Region for a request, the request will be handled in the default US1 Region.

To specify a target Region for a request, include the name of the target Region in the request’s hostname, also known as the fully qualified domain name (FQDN).

The Twilio API’s FQDN format

The FQDN format follows a convention that encodes three pieces of information in the hostname:

  1. The Twilio Product
  2. The target Edge Location
  3. The target Region

The format of an FQDN is:

{product}.{edge-location}.{region}.twilio.com

Some example FQDNs targeting API products in different Regions (through various Edge Locations) include:

FQDN

Target Region

api.sydney.au1.twilio.com

Australia (AU1) Region

voice.ashburn.us1.twilio.com

United States (US1) Region

insights.dublin.ie1.twilio.com

Ireland (IE1) Region (not yet available)

Note: Legacy FQDNs which do not include the Edge Location and Region (e.g. video.twilio.com) are implicitly routed to the US1 Region through the ashburn Edge Location.

Twilio server-side helper libraries

When making requests using any of Twilio’s server-side helper libraries, you don’t need to worry about constructing an FQDN. Instead, provide the client constructor with an edge and region parameter, and the client will construct the FQDN accordingly.

When specifying a region parameter for a helper library client, be sure to also specify the edge parameter. For backward compatibility purposes, specifying a region without specifying an edge will result in requests being routed to US1.

Region-specific authentication credentials

In order to provide Region-specific access control, Twilio manages your accounts’ API credentials on a per-Region basis. This means that you’ll need to use different Auth Tokens and API Keys based on which Region you are sending API requests to. Refer to the Twilio Regions overview for more information about the Region isolation model.

You can manage API Keys for a Region using the REST API with your account’s Auth Token for that Region. Find your Auth Token for a given Region by navigating to the API Keys page in the Twilio Console and selecting a target Region from the menu in the upper-right corner of the page.

Here’s an example using the REST API to create a standard API key in the AU1 Region using cURL (assuming you’ve set ACCOUNT_SID and AUTH_TOKEN environment variables appropriately):

curl -u $ACCOUNT_SID:$AUTH_TOKEN \
    https://api.sydney.au1.twilio.com/2010-04-01/Accounts/$ACCOUNT_SID/Keys.json \
    --data "FriendlyName=SampleAU1ApiKey"

Note that because your Auth Token confers account-level access, usage of the Auth Token as API credentials should be limited to cases where the Auth Token is required (i.e. managing Account settings and API Keys). See this blog post for more information around best practices regarding Auth Token and API Keys usage.

Other Region-specific resources

Most Twilio resources can be managed via REST API in a target Region using standard API Keys which exist in the Region.

For example, to list your account’s TwiML Applications in the AU1 region using cURL (again with the appropriate environment variables present in your shell):

curl -u $API_KEY_SID:$API_KEY_SECRET \
  https://api.sydney.au1.twilio.com/2010-04-01/Accounts/$ACCOUNT_SID/Applications.json

Note that some API Endpoints are not yet available in Regions outside of US1.

For example, using the REST API to manage Push Credentials used by our Notification service is currently only supported in US1.

Next steps

To learn more about building with Twilio’s Global infrastructure, check out these other resources:

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