Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

How to Use Our 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.

(information)

Info

Twilio has a whole host of APIs, from SMS to Voice to Wireless. You can find Twilio's API reference documentation throughout our product documentation. You can browse the various APIs here, or jump straight to the API reference for Programmable SMS or Programmable Voice.


What is a REST API, anyway?

what-is-a-rest-api-anyway page anchor

API is short for 'Application Programming Interface' . An API is 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(link takes you to an external page)'. 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 using the 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. The action represented by the first and last of these is clear, but POST and PUT have specific meanings. How they are defined is confusing, but the general rule is: use POST to create resources, and PUT to update resources.

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 directly over HTTP or using Twilio's helper libraries for several different programming languages.


Working with Twilio's APIs

working-with-twilios-apis page anchor

Authenticate with HTTP

authenticate-with-http page anchor

Twilio supports HTTP Basic authentication(link takes you to an external page). 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:


_10
https://username:password@api.twilio.com/2010-04-01/your_desired_path

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


_10
curl -G https://api.twilio.com/2010-04-01/Accounts \
_10
-u '<YOUR_ACCOUNT_SID>:<YOUR_AUTH_TOKEN>'

You can find both your account SID and auth token in the Twilio Console(link takes you to an external page) after signing up for a free Twilio trial account(link takes you to an external page).

Reveal Your Auth Token.

If you want to use API keys to authenticate instead of your Twilio account SID and auth token, then use the API key as your username and your API key's Secret as your password:


_10
curl -G https://api.twilio.com/2010-04-01/Accounts \
_10
-u '<YOUR_API_KEY>:<YOUR_API_KEY_SECRET>'

The API key type has to be created as Main for the above command to access your accounts. Keys of type Standard can only be used on commands where you also provide the Account SID as part of the API. For example:


_10
curl -X GET 'https://api.twilio.com/2010-04-01/Accounts/\
_10
'<YOUR_ACCOUNT_SID>/Applications.json' \
_10
-u $'<YOUR_API_KEY>:<YOUR_API_KEY_SECRET>'

Twilio will authenticate to your web server using the provided username 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.

Expected Content Type for API Requests

expected-content-type-for-api-requests page anchor

Twilio's APIs expect the content type of API requests to be either application/x-www-form-urlencoded or multipart/form-data. It is important to note that although Twilio returns responses in JSON format, the API requests themselves should be formatted as either www-urlencoded or multiparty form data.

Please ensure that your API requests are formatted correctly using the appropriate content type to ensure successful communication with the Twilio APIs. Using the wrong content type may result in unexpected behavior or errors.

Authenticate using the Twilio SDKs

authenticate-using-the-twilio-sdks page anchor

At this time, Twilio offers officially supported server-side libraries in the following languages:

All of these helper libraries come with a Utilities class that facilitates request validation by passing your Account SID and Auth Token (found in the Console(link takes you to an external page)) to the library.

(error)

Danger

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(link takes you to an external page) to learn more.

How Twilio's APIs use webhooks

how-twilios-apis-use-webhooks page anchor

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

When the webhook event occurs, Twilio makes an HTTP request (usually POST or GET(link takes you to an external page)) 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.


Send an SMS with Twilio's API

send-an-sms-with-twilios-api page anchor

Twilio's Programmable SMS API helps you send and receive SMS messages. You'll need to sign up for a free Twilio account(link takes you to an external page) to get started.

Send a simple SMS using the Programmable SMS API

send-a-simple-sms-using-the-programmable-sms-api page anchor

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

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.messages
_14
.create({
_14
body: 'This is the ship that made the Kessel Run in fourteen parsecs?',
_14
from: '+15017122661',
_14
to: '+15558675310'
_14
})
_14
.then(message => console.log(message.sid));

Output

_24
{
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"api_version": "2010-04-01",
_24
"body": "This is the ship that made the Kessel Run in fourteen parsecs?",
_24
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"direction": "outbound-api",
_24
"error_code": null,
_24
"error_message": null,
_24
"from": "+15017122661",
_24
"num_media": "0",
_24
"num_segments": "1",
_24
"price": null,
_24
"price_unit": null,
_24
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"status": "queued",
_24
"subresource_uris": {
_24
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"
_24
},
_24
"to": "+15558675310",
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_24
}

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

explore-twilios-other-apis page anchor

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

We can't wait to see what you build!


Rate this page: