Make an outbound phone call via REST API in a non-US Twilio Region

This guide will show you how to make an outbound Call using the Twilio REST API in a Region other than the default, United States (US1) Region.

The examples in this guide will use the Ireland (IE1) Region.

Please ensure that you understand the basic concepts involved in Making Calls and using Twilio Regions before reading this guide.

Step 1: Setup

Before proceeding, make sure that you have the following items handy:

Your Twilio Account SID, found on the Dashboard page of the Twilio Console
A Voice-capable Twilio phone number

See this guide for help finding and purchasing a Twilio phone number.

Next, you’ll need a Twilio API Key that is valid in the target Region.

Twilio API Keys are a Region-specific resource. In order to interact with the API in the IE1 Region, you need to use an API Key which exists in that Region (rather than an API Key you created in the default US1 Region, for example). Refer to the Twilio Regions overview for more information about the Region isolation model.

Follow these steps to create an API Key for the IE1 Region using the Twilio Console:

Log into the Twilio Console.
Click the Account menu in the upper right corner of the screen.
Click API keys, under the Keys & Credentials heading.
Select the “Ireland (IE1)” option from the Region menu.
Click the blue Create API key button.
Enter a friendly name for the key (example: “Regional Calls Quickstart”).
Leave Key type on the default option, “Standard”.
Click the blue Create API Key button.

Take note of the API Key’s SID and secret for use in the next step.

Step 2: Make a request to the Calls endpoint

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, you will 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:

The Twilio Product
The target Edge Location
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
studio.sydney.au1.twilio.com	Australia (AU1) Region
events.ashburn.us1.twilio.com	United States (US1) Region
messaging.dublin.ie1.twilio.com	Ireland (IE1) Region

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.

In this example, you’ll be making a POST request to the Call resource endpoint to create a Call. This endpoint is a part of Twilio’s core API product. You will select the dublin Edge Location, and the IE1 processing Region.

Thus, the FQDN you need to use is:

api.dublin.ie1.twilio.com

As we’ll discuss in Step 3 of this guide, you can use the Twilio helper libraries for making API requests to a target Region. Helper libraries accept an edge and region parameter, and automatically construct the appropriate FQDN for API requests.

Issue the API request with cURL

If you use a MacOS or Linux operating system, you can follow these instructions to issue the request using the cURL command line utility. Otherwise, please continue to read along, since this section contains important information.

First, set some environment variables containing data that will be referenced by the curl command you run later. This practice prevents us from needing to include sensitive data directly in shell commands, and has the added benefit of making our curl command copy/pasteable without needing to adjust any placeholder values.

Create a new file named .env, and add the following content, using your own Account SID, API Key SID, and API Key secret:

export ACCOUNT_SID=<your_account_sid_here>
export API_KEY_SID=<your_api_key_sid_here>
export API_KEY_SECRET=<your_api_key_secret_here>

Next, add E.164 formatted phone number values for the To and From number of the phone call that you want to make. Be sure to use a From number that is either a Twilio phone number you own, or a verified phone number associated with your Twilio account.

export TO_NUMBER=<your_to_number_here>
export FROM_NUMBER=<your_from_number_here>

Save the file, and run the source command in a terminal to set the file’s values as variables in your shell session:

source .env

Confirm that the variables are set by echoing one of them:

echo $TO_NUMBER

The shell should print the value of the To number that you set in the .env file.

Run the following command to issue the API request.

curl -X POST \
    -u $API_KEY_SID:$API_KEY_SECRET \
    https://api.dublin.ie1.twilio.com/2010-04-01/Accounts/$ACCOUNT_SID/Calls.json \
    --data-urlencode "To=$TO_NUMBER" \
    --data-urlencode "From=$FROM_NUMBER" \
    --data-urlencode "Twiml=<Response><Say>Ahoy from Ireland</Say></Response>"

The command should print a JSON representation of the new Call, and the destination phone should now be ringing.

Congratulations, you’ve successfully created a Call using a non-US1 Twilio Region!

Keep in mind that this Call will only exist in the Region where it was created -- IE1 in this case. In order to view the Call log in the Twilio Console, for example, you’ll need to access the IE1-specific Call Logs page. Refer to the Twilio Regions introduction for a refresher on Twilio's Region isolation model.

Step 3 (optional): Issue the API request with a server-side helper library

Real applications are unlikely to make API requests using cURL, and will instead be using an HTTP client appropriate for the application’s programming language. A common choice is to use one of Twilio’s language-specific server-side helper libraries.

These libraries make it easy to issue requests against a target Region, simply by setting a region attribute on a client instance.

For example, using one of the helper libraries, a request equivalent to the one sent using the curl command in the previous step could be sent using the following language-specific code:

const accountSid = process.env.ACCOUNT_SID;
const apiKeySid = process.env.API_KEY_SID;
const apiKeySecret = process.env.API_KEY_SECRET;

const toNumber = process.env.TO_NUMBER;
const fromNumber = process.env.FROM_NUMBER;

const client = require('twilio')(
    apiKeySid,
    apiKeySecret, {
        accountSid: accountSid,
        edge: 'dublin',
        region: 'ie1'
    });

client.calls
    .create({
        twiml: '<Response><Say>Ahoy from Ireland</Say></Response>',
        to: toNumber,
        from: fromNumber
    });

using Twilio;
using Twilio.Rest.Api.V2010.Account;

class Program
{
    static void Main(string[] args)
    {
        string accountSid = Environment.GetEnvironmentVariable("ACCOUNT_SID");
        string apiKeySid = Environment.GetEnvironmentVariable("API_KEY_SID");
        string apiKeySecret = Environment.GetEnvironmentVariable("API_KEY_SECRET");

        string toNumber = Environment.GetEnvironmentVariable("TO_NUMBER");
        string fromNumber = Environment.GetEnvironmentVariable("FROM_NUMBER");

        TwilioClient.Init(
            apiKeySid,
            apiKeySecret,
            accountSid=accountSid,
            edge="dublin",
            region="ie1"
        );

        var call = CallResource.Create(
            twiml: new Twilio.Types.Twiml("<Response><Say>Ahoy from Ireland</Say></Response>"),
            to: new Twilio.Types.PhoneNumber(toNumber),
            from: new Twilio.Types.PhoneNumber(fromNumber)
        );
    }
}

<?php

// Update the path below to your autoload.php,
// see https://getcomposer.org/doc/01-basic-usage.md
require_once '/path/to/vendor/autoload.php';

use Twilio\Rest\Client;

$account_sid = getenv("ACCOUNT_SID");
$api_key_sid = getenv("API_KEY_SID");
$api_key_secret = getenv("API_KEY_SECRET");

$to_number = getenv("TO_NUMBER");
$from_number = getenv("FROM_NUMBER");

$twilio = new Client(
    $api_key_sid,
    $api_key_secret,
    $account_sid,
    "ie1");

$twilio -> setEdge("dublin");

$call = $twilio->calls
               ->create($to_number,
                        $from_number,
                        [
                            "twiml" => "<Response><Say>Ahoy from Ireland</Say></Response>"
                        ]
               );

require "twilio-ruby"

account_sid = ENV["ACCOUNT_SID"]
api_key_sid = ENV["API_KEY_SID"]
api_key_secret = ENV["API_KEY_SECRET"]

to_number = ENV["TO_NUMBER"]
from_number = ENV["FROM_NUMBER"]

@client = Twilio::REST::Client.new(
    api_key_sid,
    api_key_secret,
    account_sid
)

@client.edge = "dublin"
@client.region = "ie1"

call = @client.calls.create(
    twiml: '<Response><Say>Ahoy from Ireland</Say></Response>',
    to: to_number,
    from: from_number
)

import os
from twilio.rest import Client


account_sid = os.environ['ACCOUNT_SID']
api_key_sid = os.environ['API_KEY_SID']
api_key_secret = os.environ['API_KEY_SECRET']

to_number = os.environ['TO_NUMBER']
from_number = os.environ['FROM_NUMBER']

client = Client(
    account_sid=account_sid,
    username=api_key_sid,
    password=api_key_secret,
    edge='dublin',
    region='ie1'
)

call = client.calls.create(
    twiml='<Response><Say>Ahoy from Ireland</Say></Response>',
    to=to_number,
    from_=from_number
)

import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Call;
import com.twilio.type.PhoneNumber;
import com.twilio.type.Twiml;

public class Example {

    public static final String ACCOUNT_SID = System.getenv("ACCOUNT_SID");
    public static final String API_KEY_SID = System.getenv("API_KEY_SID");
    public static final String API_KEY_SECRET = System.getenv("API_KEY_SECRET");

    public static final String TO_NUMBER = System.getenv("TO_NUMBER");
    public static final String FROM_NUMBER = System.getenv("FROM_NUMBER");

    public static void main(String[] args) {
        Twilio.init(API_KEY_SID, API_KEY_SECRET, ACCOUNT_SID);
        Twilio.setEdge("dublin");
        Twilio.setRegion("ie1");
        
        Call call = Call.creator(
                new com.twilio.type.PhoneNumber(TO_NUMBER),
                new com.twilio.type.PhoneNumber(FROM_NUMBER),
                new com.twilio.type.Twiml("<Response><Say>Ahoy from Ireland</Say></Response>"))
            .create();
    }
}

Next steps

Now that you know the basics of making Calls via a specific Twilio Region using the REST API, check out these other resources to learn more about building with Twilio Regions:

Route inbound calls to a non-US1 Twilio Region

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.