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) or by using a tool like Postman. 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

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

Account SID and Auth Token

The account SID and auth token are the master keys to your account. They can be found on your Account Dashboard in the Twilio Console.

Username	Password
AccountSid	AuthToken

API Keys

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!

Username	Password
API Key SID	API Key Secret

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

HTTP Methods

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

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

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createMessage() {
11  const message = await client.messages.create({
12    body: "This will be the body of the new message!",
13    from: "+14155552344",
14    to: "+14155552345",
15  });
16
17  console.log(message.body);
18}
19
20createMessage();

Output

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "api_version": "2010-04-01",
4  "body": "This will be the body of the new message!",
5  "date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6  "date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7  "date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8  "direction": "outbound-api",
9  "error_code": null,
10  "error_message": null,
11  "from": "+14155552344",
12  "num_media": "0",
13  "num_segments": "1",
14  "price": null,
15  "price_unit": null,
16  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "status": "queued",
19  "subresource_uris": {
20    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21  },
22  "tags": {
23    "campaign_name": "Spring Sale 2022",
24    "message_type": "cart_abandoned"
25  },
26  "to": "+14155552345",
27  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
28}

POST a New Message via SMS

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7const accountSid = process.env.TWILIO_ACCOUNT_SID;
8const apiKey = process.env.TWILIO_API_KEY;
9const apiSecret = process.env.TWILIO_API_SECRET;
10const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
11
12async function createMessage() {
13  const message = await client.messages.create({
14    body: "This will be the body of the new message!",
15    from: "+14155552344",
16    to: "+14155552345",
17  });
18
19  console.log(message.body);
20}
21
22createMessage();

Output

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "api_version": "2010-04-01",
4  "body": "This will be the body of the new message!",
5  "date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6  "date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7  "date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8  "direction": "outbound-api",
9  "error_code": null,
10  "error_message": null,
11  "from": "+14155552344",
12  "num_media": "0",
13  "num_segments": "1",
14  "price": null,
15  "price_unit": null,
16  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "status": "queued",
19  "subresource_uris": {
20    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21  },
22  "tags": {
23    "campaign_name": "Spring Sale 2022",
24    "message_type": "cart_abandoned"
25  },
26  "to": "+14155552345",
27  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
28}

Retrieving Resources with the GET Method

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.

GET the sent SMS

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchMessage() {
11  const message = await client
12    .messages("SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .fetch();
14
15  console.log(message.body);
16}
17
18fetchMessage();

Output

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "api_version": "2010-04-01",
4  "body": "testing",
5  "date_created": "Fri, 24 May 2019 17:18:27 +0000",
6  "date_sent": "Fri, 24 May 2019 17:18:28 +0000",
7  "date_updated": "Fri, 24 May 2019 17:18:28 +0000",
8  "direction": "outbound-api",
9  "error_code": 30007,
10  "error_message": "Carrier violation",
11  "from": "+12019235161",
12  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "num_media": "0",
14  "num_segments": "1",
15  "price": "-0.00750",
16  "price_unit": "USD",
17  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "status": "sent",
19  "subresource_uris": {
20    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Media.json",
21    "feedback": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Feedback.json"
22  },
23  "tags": {
24    "campaign_name": "Spring Sale 2022",
25    "message_type": "cart_abandoned"
26  },
27  "to": "+18182008801",
28  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMb7c0a2ce80504485a6f653a7110836f5.json"
29}

GET the sent SMS

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7const accountSid = process.env.TWILIO_ACCOUNT_SID;
8const apiKey = process.env.TWILIO_API_KEY;
9const apiSecret = process.env.TWILIO_API_SECRET;
10const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
11
12async function fetchMessage() {
13  const message = await client
14    .messages("SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
15    .fetch();
16
17  console.log(message.body);
18}
19
20fetchMessage();

Output

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "api_version": "2010-04-01",
4  "body": "testing",
5  "date_created": "Fri, 24 May 2019 17:18:27 +0000",
6  "date_sent": "Fri, 24 May 2019 17:18:28 +0000",
7  "date_updated": "Fri, 24 May 2019 17:18:28 +0000",
8  "direction": "outbound-api",
9  "error_code": 30007,
10  "error_message": "Carrier violation",
11  "from": "+12019235161",
12  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13  "num_media": "0",
14  "num_segments": "1",
15  "price": "-0.00750",
16  "price_unit": "USD",
17  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "status": "sent",
19  "subresource_uris": {
20    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Media.json",
21    "feedback": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Feedback.json"
22  },
23  "tags": {
24    "campaign_name": "Spring Sale 2022",
25    "message_type": "cart_abandoned"
26  },
27  "to": "+18182008801",
28  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMb7c0a2ce80504485a6f653a7110836f5.json"
29}

Deleting a Resource with the DELETE Method

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.

DELETE the Message

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function deleteMessage() {
11  await client.messages("SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").remove();
12}
13
14deleteMessage();

DELETE the Message

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7const accountSid = process.env.TWILIO_ACCOUNT_SID;
8const apiKey = process.env.TWILIO_API_KEY;
9const apiSecret = process.env.TWILIO_API_SECRET;
10const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
11
12async function deleteMessage() {
13  await client.messages("SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa").remove();
14}
15
16deleteMessage();

Status Codes

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 Code	Meaning	Description
200	OK	The request was successful and the response body contains the representation requested.
201	CREATED	The request was successful, we created a new resource and the response body contains the representation. This should only appear for `POST` requests.
202	ACCEPTED	The request has been accepted for processing, but the processing has not been completed.
204	OK	Used with the `DELETE` method. The request was successful; the resource was deleted.
302	FOUND	A common redirect response; you can `GET` the representation at the URI in the Location response header.
304	NOT MODIFIED	Your client's cached version of the representation is still up to date.
401	UNAUTHORIZED	The supplied credentials, if any, are not sufficient to access the resource.
404	NOT FOUND	The request resource wasn't found.
405	NOT ALLOWED	Typically means you can't `DELETE` the resource.
429	TOO MANY REQUESTS	Your application is sending too many requests too quickly, and you are reaching the concurrency limit of the Twilio API.
500	SERVER ERROR	We couldn't return the representation due to an internal server error - this one is Twilio's fault!
503	SERVICE UNAVAILABLE	We are temporarily unable to return the representation. Please wait for a bit and try again.