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

Make an HTTP Request to Twilio


There are a lot of ways you can make an HTTP request to the Twilio API. You can make a raw HTTP request in your code (for example, using a module like got in NodeJS(link takes you to an external page)) or by using a tool like Postman(link takes you to an external page). You might find it easier to use the Twilio Helper Library or SDK for your preferred programming language - even if that's $bash, and you need to use the Twilio CLI.


Credentials

credentials page anchor

All requests to Twilio's REST API need to be authenticated. Twilio supports two forms of authentication, both using HTTP basic auth(link takes you to an external page), which use the following username/password schemes:

Account SID and Auth Token

account-sid-and-auth-token page anchor

The account SID and auth token are the master keys to your account. They can be found on your Account Dashboard(link takes you to an external page) in the Twilio Console.

UsernamePassword
AccountSidAuthToken

API Keys are credentials you can create and revoke in the Console or using the API using your AccountSid and AuthToken. API Keys are typically safer to work within your Twilio projects. You can quickly delete them to revoke access if they become compromised and create a fresh API Key for different use cases - so, if you need to turn off a specific use case for some reason, you can just delete the API Key!

UsernamePassword
API Key SIDAPI Key Secret

The examples below will demonstrate how to use both username/password schemes with cURL, Twilio's SDKs, and the Twilio CLI.


Twilio mostly uses the GET, POST, and DELETE HTTP methods on various resources. Here's how all of these methods might be used for one of Twilio's most common resources: the SMS Message Resource.

Creating or Updating Resources with the POST Method

creating-or-updating-resources-with-the-post-method page anchor

You can create or update a resource using the HTTP POST method on a resource URI. All you need to provide is the description of what it is that you want to make! The Twilio helper libraries are useful for making these requests simpler, but you can see the parameters for any post request in the documentation for a resource. Here's a POST request that will create and send an SMS using the Twilio API.

POST a New Message via SMS

post-a-new-message-via-sms page anchor

Using Account SID and Auth Token for Authentication

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 will be the body of the new message!',
_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 will be the body of the new message!",
_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": "+14155552345",
_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": "+14155552345",
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_24
}

Using API Key SID and Secret for Authentication

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

_16
// Download the helper library from https://www.twilio.com/docs/node/install
_16
// Find your Account SID at twilio.com/console
_16
// Provision API Keys at twilio.com/console/runtime/api-keys
_16
// and set the environment variables. See http://twil.io/secure
_16
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16
const apiKey = process.env.TWILIO_API_KEY;
_16
const apiSecret = process.env.TWILIO_API_SECRET;
_16
const client = require('twilio')(apiKey, apiSecret, { accountSid: accountSid });
_16
_16
client.messages
_16
.create({
_16
body: 'This will be the body of the new message!',
_16
from: '+15017122661',
_16
to: '+15558675310'
_16
})
_16
.then(message => console.log(message.sid));

Output

_24
{
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"api_version": "2010-04-01",
_24
"body": "This will be the body of the new message!",
_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": "+14155552345",
_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": "+14155552345",
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_24
}

Retrieving Resources with the GET Method

retrieving-resources-with-the-get-method page anchor

Congrats on sending a message! You can see in the output that you'll receive a Message SID that looks something like MM followed by a long string of letters and numbers. In the sample output, it's just a long string of X's. You can use that SID to retrieve information about the message using the GET method.

Using Account SID and Auth Token for Authentication

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

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.messages('MMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.fetch()
_10
.then(message => console.log(message.to));

Output

_25
{
_25
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25
"api_version": "2010-04-01",
_25
"body": "testing",
_25
"date_created": "Fri, 24 May 2019 17:18:27 +0000",
_25
"date_sent": "Fri, 24 May 2019 17:18:28 +0000",
_25
"date_updated": "Fri, 24 May 2019 17:18:28 +0000",
_25
"direction": "outbound-api",
_25
"error_code": 30007,
_25
"error_message": "Carrier violation",
_25
"from": "+12019235161",
_25
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25
"num_media": "0",
_25
"num_segments": "1",
_25
"price": "-0.00750",
_25
"price_unit": "USD",
_25
"sid": "MMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25
"status": "sent",
_25
"subresource_uris": {
_25
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Media.json",
_25
"feedback": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Feedback.json"
_25
},
_25
"to": "+18182008801",
_25
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMb7c0a2ce80504485a6f653a7110836f5.json"
_25
}

Using API Key SID and Secret for Authentication

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

_12
// Download the helper library from https://www.twilio.com/docs/node/install
_12
// Find your Account SID at twilio.com/console
_12
// Provision API Keys at twilio.com/console/runtime/api-keys
_12
// and set the environment variables. See http://twil.io/secure
_12
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_12
const apiKey = process.env.TWILIO_API_KEY;
_12
const apiSecret = process.env.TWILIO_API_SECRET;
_12
const client = require('twilio')(apiKey, apiSecret, { accountSid: accountSid });
_12
_12
client.messages('MMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_12
.fetch()
_12
.then(message => console.log(message.to));

Output

_25
{
_25
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25
"api_version": "2010-04-01",
_25
"body": "testing",
_25
"date_created": "Fri, 24 May 2019 17:18:27 +0000",
_25
"date_sent": "Fri, 24 May 2019 17:18:28 +0000",
_25
"date_updated": "Fri, 24 May 2019 17:18:28 +0000",
_25
"direction": "outbound-api",
_25
"error_code": 30007,
_25
"error_message": "Carrier violation",
_25
"from": "+12019235161",
_25
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25
"num_media": "0",
_25
"num_segments": "1",
_25
"price": "-0.00750",
_25
"price_unit": "USD",
_25
"sid": "MMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25
"status": "sent",
_25
"subresource_uris": {
_25
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Media.json",
_25
"feedback": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Feedback.json"
_25
},
_25
"to": "+18182008801",
_25
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMb7c0a2ce80504485a6f653a7110836f5.json"
_25
}

Deleting a Resource with the DELETE Method

deleting-a-resource-with-the-delete-method page anchor

Finally, there are times when you might want to delete the message. You can use the same Message SID to make an HTTP DELETE request. Note that not all Twilio REST API resources support DELETE.

Using Account SID and Auth Token for Authentication

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

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.messages('MMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX').remove();

Using API Key SID and Secret for Authentication

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

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID at twilio.com/console
_10
// Provision API Keys at twilio.com/console/runtime/api-keys
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const apiKey = process.env.TWILIO_API_KEY;
_10
const apiSecret = process.env.TWILIO_API_SECRET;
_10
const client = require('twilio')(apiKey, apiSecret, { accountSid: accountSid });
_10
_10
client.messages('MMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX').remove();

As you make these requests, you'll see responses indicating what's happening on the other side of the server. The following is a list of common status codes you'll see in response from the Twilio API, and what they mean.

Status CodeMeaningDescription
200OKThe request was successful and the response body contains the representation requested.
201CREATEDThe request was successful, we created a new resource and the response body contains the representation. This should only appear for POST requests.
202ACCEPTEDThe request has been accepted for processing, but the processing has not been completed.
204OKUsed with the DELETE method. The request was successful; the resource was deleted.
302FOUNDA common redirect response; you can GET the representation at the URI in the Location response header.
304NOT MODIFIEDYour client's cached version of the representation is still up to date.
401UNAUTHORIZEDThe supplied credentials, if any, are not sufficient to access the resource.
404NOT FOUNDThe request resource wasn't found.
405NOT ALLOWEDTypically means you can't DELETE the resource.
429TOO MANY REQUESTSYour application is sending too many requests too quickly, and you are reaching the concurrency limit(link takes you to an external page) of the Twilio API.
500SERVER ERRORWe couldn't return the representation due to an internal server error - this one is Twilio's fault!
503SERVICE UNAVAILABLEWe are temporarily unable to return the representation. Please wait for a bit and try again.

Rate this page: