Twilio API responses

Learn how to work with Twilio API responses, including how to set response formats, handle errors, and navigate paginated results.

Response formats

In your API requests, you can specify the format of the response you want to receive by adding an extension to the URI.

The Twilio 2010 APIs (api.twilio.com/2010-04-01) return responses in XML by default, but you can also request JSON, CSV, or HTML formats. The Twilio Product APIs (<PRODUCT>.twilio.com/v<VERSION>) only support responses in JSON.

Format	Extension	MIME type	2010 API	Product API
XML	`.xml`	`application/xml`	✓ (Default)
JSON	`.json`	`application/json`	✓	✓
CSV	`.csv`	`text/csv`	✓
HTML	`.html`	`text/html`	✓

Note: HTML responses are useful if you want to pass the data directly to a web browser. To use HTML responses, you need to include the full URIs with the appropriate subdomain (for example, api.twilio.com) in your request.

Response examples

The following examples show how to receive responses in different formats.

XMLJSONCSVHTML

GET /2010-04-01/Accounts/<ACCOUNT_SID>/Messages/<MESSAGE_SID>

1<TwilioResponse>
2    <SMSMessage>
3        <Sid>SM1f0e8ae6ade43cb3c0ce4525424e404f</Sid>
4        <DateCreated>Fri, 13 Aug 2010 01:16:24 +0000</DateCreated>
5        <DateUpdated>Fri, 13 Aug 2010 01:16:24 +0000</DateUpdated>
6        <DateSent/>
7        <AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
8        <To>+13455431221</To>
9        <From>+15104564545</From>
10        <Body>A Test Message</Body>
11        <Status>queued</Status>
12        <Flags>
13            <Flag>outbound</Flag>
14        </Flags>
15        <ApiVersion>2010-04-01</ApiVersion>
16        <Price/>
17        <Uri>
18            /2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SM1f0e8ae6ade43cb3c0ce4525424e404f
19        </Uri>
20    </SMSMessage>
21</TwilioResponse>

GET /2010-04-01/Accounts/<ACCOUNT_SID>/Messages/<MESSAGE_SID>.json

1{
2    "sid": "SM1f0e8ae6ade43cb3c0ce4525424e404f",
3    "date_created": "Fri, 13 Aug 2010 01:16:24 +0000",
4    "date_updated": "Fri, 13 Aug 2010 01:16:24 +0000",
5    "date_sent": null,
6    "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
7    "to": "+15305431221",
8    "from": "+15104564545",
9    "body": "A Test Message",
10    "status": "queued",
11    "flags":["outbound"],
12    "api_version": "2010-04-01",
13    "price": null,
14    "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SM1f0e8ae6ade43cb3c0ce4525424e404f.json"
15}

GET /2010-04-01/Accounts/<ACCOUNT_SID>/Messages/<MESSAGE_SID>.csv

1Sid,DateCreated,DateUpdated,DateSent,AccountSid,To,From,Body,Status,Flags,ApiVersion,Price,Uri
2SM1f0e8ae6ade43cb3c0ce4525424e404f,"Fri, 13 Aug 2010 01:16:24 +0000","Fri, 13 Aug 2010 01:16:24 +0000",,ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX,+15305431221,+15104564545,"A Test Message",queued,"[outbound]","2010-04-01",,"/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SM1f0e8ae6ade43cb3c0ce4525424e404f.json"

GET /2010-04-01/Accounts/<ACCOUNT_SID>/Messages/<MESSAGE_SID>.html

1<html>
2<head><title>200</title></head>
3<body class="twilio-response">
4  <div class="message">
5    <h1>Message</h1>
6    <dl>
7      <dt>sid</dt>
8      <dd>SM1f0e8ae6ade43cb3c0ce4525424e404f</dd>
9      <dt>date-created</dt>
10      <dd>Fri, 13 Aug 2010 01:16:24 +0000</dd>
11      <dt>date-updated</dt>
12      <dd>Fri, 13 Aug 2010 01:16:24 +0000</dd>
13      <dt>date-sent</dt>
14      <dd></dd>
15      <dt>account-sid</dt>
16      <dd>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</dd>
17      <dt>to</dt>
18      <dd>+15305431221</dd>
19      <dt>from</dt>
20      <dd>+15104564545</dd>
21      <dt>body</dt>
22      <dd>A Test Message</dd>
23      <dt>status</dt>
24      <dd>queued</dd>
25      <dt>flags</dt>
26      <dd>[outbound]</dd>
27      <dt>api-version</dt>
28      <dd>2010-04-01</dd>
29      <dt>price</dt>
30      <dd></dd>
31      <dt>uri</dt>
32      <dd><a href="/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SM1f0e8ae6ade43cb3c0ce4525424e404f.json">/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SM1f0e8ae6ade43cb3c0ce4525424e404f.json</a></dd>
33    </dl>
34  </div>
35</body>
36</html>

Status codes

When you make a request to a Twilio API, it returns an HTTP status code to indicate the result of your request.

Status code	Description
`200 OK`	Twilio successfully processed the request. The response body contains the requested resource.
`201 Created`	(For `POST` requests only) Twilio successfully created a new resource. The response body contains the new resource.
`202 Accepted`	Twilio accepted the request for processing but hasn't completed it yet.
`204 OK`	(For `DELETE` requests only) Twilio successfully deleted the resource.
`302 Found`	Twilio redirected the request. You can retrieve the resource at the URI in the `Location` header.
`304 Not modified`	The resource hasn't changed. Your client's cached version of the representation is still current.
`401 Unauthorized`	The credentials you provided are missing or invalid.
`404 Not found`	Twilio can't find the requested resource.
`405 Not allowed`	The HTTP method you used isn't allowed for this resource. For example, you're trying to `DELETE` a resource that can't be deleted.
`429 Too many requests`	You have reached Twilio's API concurrency limit.
`500 Server error`	Twilio encountered an internal error.
`503 Service unavailable`	Twilio's service is temporarily unavailable. Try again later.

Exceptions

When a request is unsuccessful, Twilio returns an exception with the following information:

Property	Description
`status`	The HTTP status code for the exception.
`message`	A detailed description of the exception.
`code`	(If present) A Twilio-specific error code to help you identify the problem.
`more_info`	(If present) A URL to Twilio's documentation for the error code.

Note: For XML responses, the exception is wrapped in a <TwilioResponse> element. For JSON responses, the exception is returned as a JSON object.

404 Not Found

The following is an example of a 404 Not Found error when a requested resource doesn't exist:

Requested resource not found

1<TwilioResponse>
2  <RestException>
3    <Status>404</Status>
4    <Message>The requested resource was not found</Message>
5  </RestException>
6</TwilioResponse>

400 Bad Request

The following is an example of a 400 Bad Request error when a required parameter is missing in the request. The 400 response includes the code and more_info properties to help you understand the error and how to fix it.

Bad request

1<TwilioResponse>
2  <RestException>
3    <Status>400</Status>
4    <Message>No to number is specified</Message>
5    <Code>21201</Code>
6    <MoreInfo>http://www.twilio.com/docs/errors/21201</MoreInfo>
7  </RestException>
8</TwilioResponse>

Hypermedia references

To align with the Hypermedia As The Engine Of Application State (HATEOAS) principle, the Twilio API responses include URIs to the resources and their related resources. Using the URIs, you can navigate the API and discover related resources.

For List resources, the response includes URIs for pagination. Learn more about Pagination.
For Instance resources with subresources, the response includes URIs for those subresources in the subresource_uris property.

Hypermedia in Instance Resources

1<TwilioResponse>
2  <Call>
3    <Sid>CAe1644a7eed5088b159577c5802d8be38</Sid>
4    <DateCreated>Tue, 10 Aug 2010 08:02:17 +0000</DateCreated>
5    <DateUpdated>Tue, 10 Aug 2010 08:02:47 +0000</DateUpdated>
6    <ParentCallSid/>
7    <AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
8    <To>+14153855708</To>
9    <From>+14158141819</From>
10    <PhoneNumberSid></PhoneNumberSid>
11    <Status>completed</Status>
12    <StartTime>Tue, 10 Aug 2010 08:02:31 +0000</StartTime>
13    <EndTime>Tue, 10 Aug 2010 08:02:47 +0000</EndTime>
14    <Duration>16</Duration>
15    <Price>-0.03000</Price>
16    <Flags>
17      <Flag>outbound-api</Flag>
18    </Flags>
19    <ApiVersion>2008-08-01</ApiVersion>
20    <ForwardedFrom/>
21    <CallerName/>
22    <Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAe1644a7eed5088b159577c5802d8be38</Uri>
23    <SubresourceUris>
24      <Notifications>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAe1644a7eed5088b159577c5802d8be38/Notifications</Notifications>
25      <Recordings>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAe1644a7eed5088b159577c5802d8be38/Recordings</Recordings>
26    </SubresourceUris>
27  </Call>
28</TwilioResponse>

Pagination

Twilio's API supports pagination for resources that return multiple items. When you request a list of resources, Twilio returns partial results in a single page and includes information to help you navigate through the pages of results.

Property	Description
`uri`	The URI of the current page.
`first_page_uri`	The URI for the first page of this list.
`next_page_uri`	The URI for the next page of this list.
`previous_page_uri`	The URI for the previous page of this list.
`page`	The current page number. Pages are zero-indexed, so the first page is 0.
`page_size`	The number of items included in each page of results. The default is `50`.

Pagination

1<TwilioResponse>
2  <Calls page="0" pagesize="50"
3    uri="/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls"
4    firstpageuri="/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls?Page=0&PageSize=50"
5    previouspageuri=""
6    nextpageuri="/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls?Page=1&PageSize=50&AfterSid=CA228399228abecca920de212121">
7    <Call>
8      <Sid>CA92d4405c9237c4ea04b56cbda88e128c</Sid>
9      <DateCreated>Fri, 13 Aug 2010 01:16:22 +0000</DateCreated>
10      <DateUpdated>Fri, 13 Aug 2010 01:16:22 +0000</DateUpdated>
11      <ParentCallSid/>
12      <AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
13      <To>+15305431221</To>
14      <From>+15104563443</From>
15      <PhoneNumberSid>PNe2d8e63b37f46f2adb16f228afdb9058</PhoneNumberSid>
16      <Status>queued</Status>
17      <StartTime/>
18      <EndTime/>
19      <Duration/>
20      <Price/>
21      <Flags>
22        <Flag>outbound-api</Flag>
23      </Flags>
24      <ApiVersion>2010-04-01</ApiVersion> <ForwardedFrom/> <CallerName/>
25      <Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CA92d4405c9237c4ea04b56cbda88e128c</Uri>
26      <SubresourceUris>
27        <Notifications>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CA92d4405c9237c4ea04b56cbda88e128c/Notifications</Notifications>
28        <Recordings>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CA92d4405c9237c4ea04b56cbda88e128c/Recordings</Recordings>
29      </SubresourceUris>
30    </Call>
31    ...
32  </Calls>
33</TwilioResponse>

Paging through API resources

(information)

Info

Twilio Helper Libraries automatically handle pagination. You don't need to explicitly request individual pages when using a Helper Library to retrieve lists of resources.

To retrieve multiple pages of API results, use the next_page_uri parameter provided in the response.
To control the number of items returned in each page, you can use the page_size parameter in your request. For example, GET /2010-04-01/Accounts/<ACCOUNT_SID>/Calls?PageSize=5 limits the number of items to five per page.

Data formats

Phone numbers

Twilio returns all phone numbers in E.164 format. For example, +14155554345. If Twilio can't normalize an incoming caller ID to E.164 format, it returns the raw caller ID string.

Dates and times

Twilio returns all dates and times in GMT using the RFC 2822 format. For example, Fri, 20 Aug 2010 01:13:42 +0000.