Get Started with Our API

Our /calls service will be available soon! Read about call features and functions below but please don't try them out just yet.

Please note that this getting-started tutorial relies on call features that are still in development. To try features that are already available, please see our API Reference Guide and API Tutorials.

Get started with our API

If you need to get started quickly with our API, you are in the right place!

This guide shows you how to configure your API Developer account using settings in our Telephony Toolkit. It also shows you how to make and receive a basic phone call using the API.

The API is a programming interface that lets you make and receive phone calls from your web or mobile applications, controling them in real time. Using simple HTTP requests you can dial one or more phone numbers and interact with the people you’ve called.

Note that our API also supports SMS and lets you offer your end users real-time account management, allowing them to manage their menus, queues, routing options and other resources as needed. These topics are covered in detail in our API Services Reference Guide and in our Tutorials.

In This Topic:

Defining Settings for Your Application

Before you can use our API, you will need to define settings for your app in your API Developer account. These include setting URLs for your application’s main and backup servers, as well as choosing the API key and password that you will use when making API requests. If you don’t have an account yet, sign up for one, and then follow the steps below.

  1. Log into your API Developer account.
  2. Under the API menu, click Add an Application.

Add Application page

  1. Complete the fields on the Add Application page:
    • API Application Name: Enter a name that will help you identify your application easily. Choose something that you will recognize when you go to route phone calls and SMS messages to your app later.
    • Main URL: (Optional) Set this field if you want to receive HTTP events from the API server during asynchronous API calls. Enter the URL of the primary webserver for your application.
    • Fallback URL: (Optional) You can also configure a fallback (backup) server to receive HTTP events if your primary webserver cannot be reached or is not responding. Enter the URL for your fallback server in this field.
    • API Key: This automatically generated key is used to identify your application when you make API requests. Make a note of your API key and keep it in a safe place.
    • API Password: Your API password is used to secure requests from your application to the API server. Choose a secure password or let generate one for you. Make a note of your API password and keep it in a safe place.
    • Format and Version: Use the default settings for the Format (JSON) and Version (1) fields.
    • Status: Choose the development stage that best describes the application you are configuring: Development, Beta or Live. This setting enables you to test applications at different stages of development concurrently.
  1. Click Save Changes.

The API server can now validate and accept your API requests.

Making a Phone Call from Your App

The API lets you make and control phone calls from your application using simple script-based commands. Create a script file to make a phone call as follows.

  1. Using a text editor, create a file called call.txt with the following content. Replace <to number> and <from number> with the phone numbers that you want to use.

   "commands": [
           "dial": {
               "to": "<to_number>",
               "from": "<from_number>"
           "say": {
               "text": "Hello world"
           "hangup": {}
  1. Save the script file in a location where you can easily include it in your API request.

Making the Call Request

Next, make your API call request. In the example below, we will use cURL, which is available for Unix, Windows and OSX. You can also use a variety of other tools (see HTTP Formatting).

 curl -u <api key>:<api password> -basic -d @call.txt

Use the API key and API password you created when configuring your application in your API Developer account. See Defining Settings for Your Application above.

When you make the request, the API server will call the number that you identified and play the “hello world” message that you defined in your script. When the message is complete, the API server should respond to your request with an HTTP 200 OK code.

If the phone number doesn’t ring or the API server responds with an error code, try the following:

  • If you received authentication errors or an HTTP 401 code, check the API key and password that you used.
  • If you received bad-request errors or an HTTP 400 code, check the syntax of the call script.

Making a Call by Placing Call Details in the URL

If you are not using a programming language that allows you to specify the method or HTTP headers in your call, you will need to use your HTTP request to make the call as follows:

  1. Make a POST request to:
  2. Use basic authentication.
  3. Use your API Key as the basic authentication username.
  4. Use your API Password as the basic authentication password.
  5. Send the script (call.txt) as the request’s body.

Congratulations on making your first request through the API!

Directing an Incoming Call to Your App

Next, we’ll use the API to manage an incoming call. Your API Developer account can be configured to direct incoming calls to your application and tell your app what to do with the call.

When our network receives a phone call for your application, the API server will send an HTTP request to your webserver asking for instructions. For this reason, you’ll need an application webserver that is connected to the Internet to receive phone calls. The webserver will host a script that receives and processes your incoming calls. For more information, see Setting Up Your Webserver.

In this example, we will use PHP instead of cURL.

Create the Script

  1. Create a text file called incoming.php that contains the following:

$body = @file_get_contents('php://input');
$obj  = json_decode($body);

$from = $obj->{'from'};

$script = <<<EOT
    "commands": [
            "say": {
                "text": "You are calling from $from"
            "hangup": {}

$uuid = $obj->{'uuid'};
$ch = curl_init("$uuid");
curl_setopt($ch, CURLOPT_PUT, true)
curl_setopt($ch, CURLOPT_POSTFIELDS, $script);
# Need to check return code

  1. Save the script file to your webserver’s directory, so that it can be reached at the Main and Backup URL you defined when configuring your application.

Your script is now ready to receive and process incoming calls.

Configure the URL in Your App

If you haven’t already done so, you will need to set the URL to which phone calls should be directed:

  1. Log into your account.
  2. Under the API menu, click Manage Applications.
  3. Click the application for which you want to set a URL.
  4. In the Main URL field, enter the URL for your primary webserver for your app in this format:
  5. If you have a backup webserver, enter that URL in the Backup URL field.
  6. Click Save Changes.

Configure Your Account to Route Calls to Your App

Now you need to instruct the API server to route incoming calls to your application:

Manage Numbers page

  1. Log into your account.
  2. Under the Configure menu, click Manage Numbers.
  3. On the Manage Numbers page, click Edit for the phone number you want to route.
  4. On the Edit Number page, click the Number Action button, and select the following options:
    • Incoming call type: Select All Calls.
    • How calls should be handled: Select Application, and then select the name of your application from the drop-down list.
  5. Click Save Rule Settings.

From this point on, incoming calls to the phone number that you selected will be answered by the script you created.

Place a Test Call

To place a test call, dial the number that you selected from any phone. As defined in the script, you will hear a message reading the number from which you are calling. If you don’t hear the message or the call hangs up unexpectedly, make sure that your script is executing without errors.

Congratulations! You’ve just used the API to direct a call to your application.

Learn More: