Twilio's REST APIs

Twilio’s APIs (Application Programming Interfaces) power its platform for communications. Behind these APIs is a software layer connecting and optimizing communications networks around the world to allow your users to call and message anyone, globally.

You can use the REST APIs to programmatically add capabilities like voice, video, and messaging to your applications.

What’s a REST API, anyway?

An API is an application programming interface - in short, it’s a set of rules that lets programs talk to each other, exposing data and functionality across the internet in a consistent format.

REST stands for Representational State Transfer. This is an architectural pattern that describes how distributed systems can expose a consistent interface. When people use the term ‘REST API,’ they are generally referring to an API accessed via HTTP protocol at a predefined set of URLs.

These URLs represent various resources - any information or content accessed at that location, which can be returned as JSON, HTML, audio files, or images.  Often, resources have one or more methods that can be performed on them over HTTP, like GET, POST, PUT and DELETE.

Twilio, for example, provides many separate REST APIs for sending text messages, making phone calls, looking up phone numbers, managing your accounts, and a whole lot more. In Twilio’s ecosystem, each product is its own API, but you will work with each of them in roughly the same way, whether over HTTP or using Twilio’s helper libraries for several different programming languages.

Working with Twilio’s APIs

Authenticate with HTTP

Twilio supports HTTP Basic authentication. This allows you to protect the URLs on your web server so that only you and Twilio can access them. In order to authenticate with HTTP, you may provide a username and password with the following URL format:

https://username:password@www.myserver.com/my_secure_document

For HTTP Basic authentication, you will use your Twilio account SID as your username and your auth token as your password:

curl -G https://api.twilio.com/2010-04-01/Accounts \
    -u '[YOUR ACCOUNT SID]:[YOUR AUTH TOKEN]'

You can find both your account SID and auth token in the Twilio Console after signing up for a free Twilio trial account.

Reveal Your Auth Token

Twilio will authenticate to your web server using the provided name and password and will remain logged in for the duration of the action.

You can learn more about how Twilio handles authentication in our security documentation.

Authenticate using the Twilio SDKs

At this time, Twilio offers six officially supported server-side libraries:

All of these helper libraries come with a Utilities class that facilitates request validation: you simply need to pass your account SID and auth token (found in the Twilio Console) to Twilio’s Client.

Please note: you should always use environment variables to keep your account sid and auth token secret before sharing any code or deploying to production. Check out our guidance for setting environment variables to learn more.

How Twilio’s API uses webhooks

Webhooks are user-defined HTTP callbacks triggered by an event in a web application. Twilio uses webhooks to asynchronously let your application know when events happen, like getting an incoming call or receiving an SMS message.

When the webhook event occurs, Twilio makes an HTTP request (usually POST or GET) to the URL you have configured for your webhook. Twilio’s request to your application includes details of the event like the body of an incoming message or the incoming phone number. Your application can then perform whatever logic is necessary, then reply to Twilio with a response containing the instructions you’d like Twilio to perform.

To handle a webhook when you use Twilio, you need to build a small web application that can accept HTTP requests. Check out our officially supported helper libraries to get up and running quickly.

Explore the APIs

Send an SMS with Twilio’s API

Twilio’s Programmable SMS API helps you send and receive SMS messages. You’ll need to sign up for a free Twilio account to get started.

Loading Code Samples...
Language
SDK Version:
  • 4.x
  • 5.x
Response Format:
  • json
SDK Version:
  • 6.x
  • 7.x
SDK Version:
  • 2.x
  • 3.x
SDK Version:
  • 4.x
  • 5.x
SDK Version:
  • 5.x
  • 6.x
SDK Version:
  • 4.x
  • 5.x
Format:
  • JSON
  • XML
// Twilio Credentials
const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';

// require the Twilio module and create a REST client
const client = require('twilio')(accountSid, authToken);

client.messages.create(
  {
    to: '+15558675310',
    from: '+15017122661',
    body: 'This is the ship that made the Kessel Run in fourteen parsecs?',
  },
  (err, message) => {
    console.log(message.sid);
  }
);
// Twilio Credentials
const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';

// require the Twilio module and create a REST client
const client = require('twilio')(accountSid, authToken);

client.messages
  .create({
    to: '+15558675310',
    from: '+15017122661',
    body: 'This is the ship that made the Kessel Run in fourteen parsecs?',
  })
  .then(message => console.log(message.sid));
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example
{
 static void Main(string[] args)
 {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "your_auth_token";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var message = twilio.SendMessage(
        "+15017122661", "+15558675310",
        "This is the ship that made the Kessel Run in fourteen parsecs?"
    );
    Console.WriteLine(message.Sid);
 }
}
<?php

// this line loads the library 
require('/path/to/twilio-php/Services/Twilio.php'); 
 
$account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; 
$auth_token = 'your_auth_token'; 
$client = new Services_Twilio($account_sid, $auth_token); 
 
$client->account->messages->create(array( 
    'To' => "+15558675310", 
    'From' => "+15017122661", 
    'Body' => "This is the ship that made the Kessel Run in fourteen parsecs?", 
));
require 'rubygems' # not necessary with ruby 1.9 but included for completeness
require 'twilio-ruby'

# put your own credentials here
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'

# set up a client to talk to the Twilio REST API
client = Twilio::REST::Client.new account_sid, auth_token

body = 'This is the ship that made the Kessel Run in fourteen parsecs?'
client.account.messages.create(from: '+15017122661',
                               to: '+15558675310',
                               body: body)
// Download the twilio-csharp library from twilio.com/docs/libraries/csharp
using System;
using Twilio;
using Twilio.Rest.Api.V2010.Account;
using Twilio.Types;

class Example
{
   static void Main(string[] args)
   {
        // Find your Account Sid and Auth Token at twilio.com/console
        const string accountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
        const string authToken = "your_auth_token";
        TwilioClient.Init(accountSid, authToken);

        var to = new PhoneNumber("+15017122661");
        var message = MessageResource.Create(
            to,
            from: new PhoneNumber("+15558675310"),
            body: "This is the ship that made the Kessel Run in fourteen parsecs?");

        Console.WriteLine(message.Sid);
   }
}
<?php
// Get the PHP helper library from https://twilio.com/docs/libraries/php
require_once '/path/to/vendor/autoload.php'; // Loads the library
use Twilio\Rest\Client;

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
$token = "your_auth_token";
$client = new Client($sid, $token);

$client->messages->create(
    '+15558675310',
    array(
        'from' => '+15017122661',
        'body' => "This is the ship that made the Kessel Run in fourteen parsecs?"
    )
);
from twilio.rest import TwilioRestClient

# put your own credentials here
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
AUTH_TOKEN = "your_auth_token"

client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)

client.messages.create(
    to="+15558675310",
    from_="+15017122661",
    body="This is the ship that made the Kessel Run in fourteen parsecs?",
)
require 'rubygems' # not necessary with ruby 1.9 but included for completeness
require 'twilio-ruby'

# put your own credentials here
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'

# set up a client to talk to the Twilio REST API
@client = Twilio::REST::Client.new(account_sid, auth_token)

@message = @client.messages.create(
  from: '+15017122661',
  to: '+15558675310',
  body: 'This is the ship that made the Kessel Run in fourteen parsecs?'
)

puts @message.status
// You may want to be more specific in your imports
import java.util.*;
import com.twilio.sdk.*;
import com.twilio.sdk.resource.factory.*;
import com.twilio.sdk.resource.instance.*;
import com.twilio.sdk.resource.list.*;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.NameValuePair;
import org.apache.http.message.BasicNameValuePair;

public class TwilioTest {
 // Find your Account Sid and Token at twilio.com/user/account
 public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
 public static final String AUTH_TOKEN = "your_auth_token";

 public static void main(String[]args) throws TwilioRestException {
  TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

   // Build the parameters
   List<NameValuePair> params = new ArrayList<NameValuePair>();
   params.add(new BasicNameValuePair("To", "+15558675310"));
   params.add(new BasicNameValuePair("From", "+15017122661"));
   params.add(new BasicNameValuePair("Body", "This is the ship that made the Kessel Run in fourteen parsecs?"));

   MessageFactory messageFactory = client.getAccount().getMessageFactory();
   Message message = messageFactory.create(params);
   System.out.println(message.getSid());
 }
}
from twilio.rest import Client

# put your own credentials here
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token = "your_auth_token"

client = Client(account_sid, auth_token)

client.messages.create(
    to="+15558675310",
    from_="+15017122661",
    body="This is the ship that made the Kessel Run in fourteen parsecs?"
)
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Message;
import com.twilio.type.PhoneNumber;

public class Example {
  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "your_auth_token";

  public static void main(String[] args) {
    Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

    Message message = Message.creator(new PhoneNumber("+15558675310"),
        new PhoneNumber("+15017122661"), "This is the ship that made the Kessel Run in fourteen parsecs?").create();

    System.out.println(message.getSid());
  }
}
curl -X POST 'https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json' \
--data-urlencode 'To=+15558675310'  \
--data-urlencode 'From=+15017122661'  \
--data-urlencode 'Body=This is the ship that made the Kessel Run in fourteen parsecs?'  \
-u ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token
{
  "sid": "MMc781610ec0b3400c9e0cab8e757da937",
  "date_created": "Mon, 19 Oct 2015 07:07:03 +0000",
  "date_updated": "Mon, 19 Oct 2015 07:07:03 +0000",
  "date_sent": null,
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "to": "+15558675310",
  "from": "+15017122661",
  "body": "This is the ship that made the Kessel Run in fourteen parsecs?",
  "status": "queued",
  "num_segments": "1",
  "num_media": "0",
  "direction": "outbound-api",
  "api_version": "2010-04-01",
  "price": null,
  "price_unit": "USD",
  "error_code": null,
  "error_message": null,
  "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc781610ec0b3400c9e0cab8e757da937.json",
}
<?xml version='1.0' encoding='UTF-8'?>
<TwilioResponse>
<Message>
  <Sid>MMc781610ec0b3400c9e0cab8e757da937</Sid>
  <DateCreated>Mon, 19 Oct 2015 07:09:09 +0000</DateCreated>
  <DateUpdated>Mon, 19 Oct 2015 07:09:09 +0000</DateUpdated>
  <DateSent/>
  <AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
  <To>+15558675310</To>
  <From>+15017122661</From>
  <Body>This is the ship that made the Kessel Run in fourteen parsecs?</Body>
  <Status>queued</Status>
  <NumSegments>1</NumSegments>
  <NumMedia>0</NumMedia>
  <Direction>outbound-api</Direction>
  <ApiVersion>2010-04-01</ApiVersion>
  <Price/>
  <PriceUnit>USD</PriceUnit>
  <ErrorCode/>
  <ErrorMessage/>
  <Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMf1150fe5baf04104a39c3f311a053e4e.xml</Uri>
  <SubresourceUris/>
</Message>
</TwilioResponse>
This code creates a new instance of the Message resource and sends an HTTP POST to the Messages resource URI.
Send a simple SMS using the Programmable SMS API

This code creates a new instance of the Message resource and sends an HTTP POST to the Messages resource URI.

For a complete step-by-step guide to sending and receiving messages with Twilio, check out our Quickstarts for Programmable SMS. Just select your server-side programming language of choice and dive in:

Explore Twilio’s other APIs

Twilio has a number of REST APIs that can help you build powerful communications into your applications, including Programmable Voice, Programmable Video, Wireless, and Authy for two-factor authentication and passwordless login.

We can’t wait to see what you build!

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 browsing the Twilio tag on Stack Overflow.

Loading Code Samples...
SDK Version:
  • 4.x
  • 5.x
Response Format:
  • json
SDK Version:
  • 6.x
  • 7.x
SDK Version:
  • 2.x
  • 3.x
SDK Version:
  • 4.x
  • 5.x
SDK Version:
  • 5.x
  • 6.x
SDK Version:
  • 4.x
  • 5.x
Format:
  • JSON
  • XML
// Twilio Credentials
const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';

// require the Twilio module and create a REST client
const client = require('twilio')(accountSid, authToken);

client.messages.create(
  {
    to: '+15558675310',
    from: '+15017122661',
    body: 'This is the ship that made the Kessel Run in fourteen parsecs?',
  },
  (err, message) => {
    console.log(message.sid);
  }
);
// Twilio Credentials
const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';

// require the Twilio module and create a REST client
const client = require('twilio')(accountSid, authToken);

client.messages
  .create({
    to: '+15558675310',
    from: '+15017122661',
    body: 'This is the ship that made the Kessel Run in fourteen parsecs?',
  })
  .then(message => console.log(message.sid));
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example
{
 static void Main(string[] args)
 {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "your_auth_token";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var message = twilio.SendMessage(
        "+15017122661", "+15558675310",
        "This is the ship that made the Kessel Run in fourteen parsecs?"
    );
    Console.WriteLine(message.Sid);
 }
}
<?php

// this line loads the library 
require('/path/to/twilio-php/Services/Twilio.php'); 
 
$account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; 
$auth_token = 'your_auth_token'; 
$client = new Services_Twilio($account_sid, $auth_token); 
 
$client->account->messages->create(array( 
    'To' => "+15558675310", 
    'From' => "+15017122661", 
    'Body' => "This is the ship that made the Kessel Run in fourteen parsecs?", 
));
require 'rubygems' # not necessary with ruby 1.9 but included for completeness
require 'twilio-ruby'

# put your own credentials here
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'

# set up a client to talk to the Twilio REST API
client = Twilio::REST::Client.new account_sid, auth_token

body = 'This is the ship that made the Kessel Run in fourteen parsecs?'
client.account.messages.create(from: '+15017122661',
                               to: '+15558675310',
                               body: body)
// Download the twilio-csharp library from twilio.com/docs/libraries/csharp
using System;
using Twilio;
using Twilio.Rest.Api.V2010.Account;
using Twilio.Types;

class Example
{
   static void Main(string[] args)
   {
        // Find your Account Sid and Auth Token at twilio.com/console
        const string accountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
        const string authToken = "your_auth_token";
        TwilioClient.Init(accountSid, authToken);

        var to = new PhoneNumber("+15017122661");
        var message = MessageResource.Create(
            to,
            from: new PhoneNumber("+15558675310"),
            body: "This is the ship that made the Kessel Run in fourteen parsecs?");

        Console.WriteLine(message.Sid);
   }
}
<?php
// Get the PHP helper library from https://twilio.com/docs/libraries/php
require_once '/path/to/vendor/autoload.php'; // Loads the library
use Twilio\Rest\Client;

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
$token = "your_auth_token";
$client = new Client($sid, $token);

$client->messages->create(
    '+15558675310',
    array(
        'from' => '+15017122661',
        'body' => "This is the ship that made the Kessel Run in fourteen parsecs?"
    )
);
from twilio.rest import TwilioRestClient

# put your own credentials here
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
AUTH_TOKEN = "your_auth_token"

client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)

client.messages.create(
    to="+15558675310",
    from_="+15017122661",
    body="This is the ship that made the Kessel Run in fourteen parsecs?",
)
require 'rubygems' # not necessary with ruby 1.9 but included for completeness
require 'twilio-ruby'

# put your own credentials here
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'

# set up a client to talk to the Twilio REST API
@client = Twilio::REST::Client.new(account_sid, auth_token)

@message = @client.messages.create(
  from: '+15017122661',
  to: '+15558675310',
  body: 'This is the ship that made the Kessel Run in fourteen parsecs?'
)

puts @message.status
// You may want to be more specific in your imports
import java.util.*;
import com.twilio.sdk.*;
import com.twilio.sdk.resource.factory.*;
import com.twilio.sdk.resource.instance.*;
import com.twilio.sdk.resource.list.*;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.NameValuePair;
import org.apache.http.message.BasicNameValuePair;

public class TwilioTest {
 // Find your Account Sid and Token at twilio.com/user/account
 public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
 public static final String AUTH_TOKEN = "your_auth_token";

 public static void main(String[]args) throws TwilioRestException {
  TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

   // Build the parameters
   List<NameValuePair> params = new ArrayList<NameValuePair>();
   params.add(new BasicNameValuePair("To", "+15558675310"));
   params.add(new BasicNameValuePair("From", "+15017122661"));
   params.add(new BasicNameValuePair("Body", "This is the ship that made the Kessel Run in fourteen parsecs?"));

   MessageFactory messageFactory = client.getAccount().getMessageFactory();
   Message message = messageFactory.create(params);
   System.out.println(message.getSid());
 }
}
from twilio.rest import Client

# put your own credentials here
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token = "your_auth_token"

client = Client(account_sid, auth_token)

client.messages.create(
    to="+15558675310",
    from_="+15017122661",
    body="This is the ship that made the Kessel Run in fourteen parsecs?"
)
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.Twilio;
import com.twilio.rest.api.v2010.account.Message;
import com.twilio.type.PhoneNumber;

public class Example {
  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "your_auth_token";

  public static void main(String[] args) {
    Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

    Message message = Message.creator(new PhoneNumber("+15558675310"),
        new PhoneNumber("+15017122661"), "This is the ship that made the Kessel Run in fourteen parsecs?").create();

    System.out.println(message.getSid());
  }
}
curl -X POST 'https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json' \
--data-urlencode 'To=+15558675310'  \
--data-urlencode 'From=+15017122661'  \
--data-urlencode 'Body=This is the ship that made the Kessel Run in fourteen parsecs?'  \
-u ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token
{
  "sid": "MMc781610ec0b3400c9e0cab8e757da937",
  "date_created": "Mon, 19 Oct 2015 07:07:03 +0000",
  "date_updated": "Mon, 19 Oct 2015 07:07:03 +0000",
  "date_sent": null,
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "to": "+15558675310",
  "from": "+15017122661",
  "body": "This is the ship that made the Kessel Run in fourteen parsecs?",
  "status": "queued",
  "num_segments": "1",
  "num_media": "0",
  "direction": "outbound-api",
  "api_version": "2010-04-01",
  "price": null,
  "price_unit": "USD",
  "error_code": null,
  "error_message": null,
  "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMc781610ec0b3400c9e0cab8e757da937.json",
}
<?xml version='1.0' encoding='UTF-8'?>
<TwilioResponse>
<Message>
  <Sid>MMc781610ec0b3400c9e0cab8e757da937</Sid>
  <DateCreated>Mon, 19 Oct 2015 07:09:09 +0000</DateCreated>
  <DateUpdated>Mon, 19 Oct 2015 07:09:09 +0000</DateUpdated>
  <DateSent/>
  <AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
  <To>+15558675310</To>
  <From>+15017122661</From>
  <Body>This is the ship that made the Kessel Run in fourteen parsecs?</Body>
  <Status>queued</Status>
  <NumSegments>1</NumSegments>
  <NumMedia>0</NumMedia>
  <Direction>outbound-api</Direction>
  <ApiVersion>2010-04-01</ApiVersion>
  <Price/>
  <PriceUnit>USD</PriceUnit>
  <ErrorCode/>
  <ErrorMessage/>
  <Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MMf1150fe5baf04104a39c3f311a053e4e.xml</Uri>
  <SubresourceUris/>
</Message>
</TwilioResponse>