Get Started

REST API: Twilio's Response

Response Formats

Twilio can respond to your requests with various formats. The most common are detailed below. For special cases and extra formats see the Tips & Tricks section.

XML

By default, Twilio's REST API returns XML, with a root element of <TwilioResponse>. For example, here is the default XML representation of a SMS message:

GET /2010-04-01/Accounts/AC228b9.../SMS/Messages/SM1f0e8ae6ade43cb3c0ce4525424e404f

<TwilioResponse>
    <SMSMessage>
        <Sid>SM1f0e8ae6ade43cb3c0ce4525424e404f</Sid>
        <DateCreated>Fri, 13 Aug 2010 01:16:24 +0000</DateCreated>
        <DateUpdated>Fri, 13 Aug 2010 01:16:24 +0000</DateUpdated>
        <DateSent/>
        <AccountSid>AC228b97a5fe4138be081eaff3c44180f3</AccountSid>
        <To>+13455431221</To>
        <From>+15104564545</From>
        <Body>A Test Message</Body>
        <Status>queued</Status>
        <Flags>
            <Flag>outbound</Flag>
        </Flags>
        <ApiVersion>2010-04-01</ApiVersion>
        <Price/>
        <Uri>
            /2010-04-01/Accounts/AC228b97a5fe4138be081eaff3c44180f3/SMS/Messages/SM1f0e8ae6ade43cb3c0ce4525424e404f
        </Uri>
    </SMSMessage>
</TwilioResponse>

JSON

Twilio also supports returning resource representations as JSON. Simply add the .json extension to any resource URI. Here is the above resource represented as JSON:

GET /2010-04-01/Accounts/AC228b9.../SMS/Messages/SM1f0e8ae6ade43cb3c0ce4525424e404f.json

{
    "sid": "SM1f0e8ae6ade43cb3c0ce4525424e404f",
    "date_created": "Fri, 13 Aug 2010 01:16:24 +0000",
    "date_updated": "Fri, 13 Aug 2010 01:16:24 +0000",
    "date_sent": null,
    "account_sid": "AC228b97a5fe4138be081eaff3c44180f3",
    "to": "+15305431221",
    "from": "+15104564545",
    "body": "A Test Message",
    "status": "queued",
    "flags":["outbound"],
    "api_version": "2010-04-01",
    "price": null,
    "uri": "\/2010-04-01\/Accounts\/AC228ba7a5fe4238be081ea6f3c44186f3\/SMS\/Messages\/SM1f0e8ae6ade43cb3c0ce4525424e404f.json"
}

Other

Twilio can also return CSV, HTML and other response types. See the Tips & Tricks section for more information.

Exceptions

Twilio returns exceptions in the HTTP response body when something goes wrong. In XML, these appear as a <RestException> element within the <TwilioResponse>. An exception has up to four properties:

Property Description
Status The HTTP status code for the exception.
Message A more descriptive message regarding the exception.
Code (Conditional) An error code to find help for the exception.
MoreInfo (Conditional) The URL of Twilio's documentation for the error code.

If you receive an exception with status code 400 (invalid request), the 'Code' and 'MoreInfo' properties are useful for debugging what went wrong.

Examples

Example 1

Here is a simple 404:

  • <TwilioResponse> 
    <RestException> 
        <Status>404</Status> 
        <Message>The requested resource was not found</Message> 
    </RestException> 
</TwilioResponse>
Example 2

An invalid POST to the Calls resource without a 'To' parameter would return:

  • <TwilioResponse> 
    <RestException> 
        <Status>400</Status> 
        <Message>No to number is specified</Message> 
        <Code>21201</Code>
        <MoreInfo>http://www.twilio.com/docs/errors/21201</MoreInfo>
    </RestException> 
</TwilioResponse>

Hypermedia References

One of the core principles of REST is "Hypermedia As The Engine Of Application State." Basically this means that every resource representation obtained from a REST API request must include URIs that identify that resource and the resources related to it. Hence the Twilio REST API returns representations that include various URIs to help you navigate the API.

Every representation contains a self-referencing URI (i.e. the URI used to retrieve it). For example, when you GET an OutgoingCallerId instance resource, its URI is one of the properties returned:

  • <TwilioResponse>
    <OutgoingCallerId>
        <Sid>PNe905d7e6b410746a0fb08c57e5a186f3</Sid>
        <AccountSid>AC228ba7a5fe4238be081ea6f3c44186f3</AccountSid>
        <FriendlyName>(510) 555-5555</FriendlyName>
        <PhoneNumber>+15105555555</PhoneNumber>
        <DateCreated>Tue, 27 Jul 2010 20:21:11 +0000</DateCreated>
        <DateUpdated>Tue, 27 Jul 2010 20:21:11 +0000</DateUpdated>
        <Uri>/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/OutgoingCallerIds/PNe905d7e6b410746a0fb08c57e5a186f3</Uri>
    </OutgoingCallerId>
</TwilioResponse>

Hypermedia in List Resources

There is extra hypermedia reference information related to the paging information included in list resource representations. Details are in the Paging Information section below.

Hypermedia in Instance Resources

If an instance resource has subresources, its representation will include the URIs for those resources within a subresource URIs property. For example, notice the subresources returned when GETting a Call instance resource:

  • <TwilioResponse>
    <Call>
        <Sid>CAe1644a7eed5088b159577c5802d8be38</Sid>
        <DateCreated>Tue, 10 Aug 2010 08:02:17 +0000</DateCreated>
        <DateUpdated>Tue, 10 Aug 2010 08:02:47 +0000</DateUpdated>
        <ParentCallSid/>
        <AccountSid>AC5ea872f6da5a21de157d80997a64bd33</AccountSid>
        <To>+14153855708</To>
        <From>+14158141819</From>
        <PhoneNumberSid></PhoneNumberSid>
        <Status>completed</Status>
        <StartTime>Tue, 10 Aug 2010 08:02:31 +0000</StartTime>
        <EndTime>Tue, 10 Aug 2010 08:02:47 +0000</EndTime>
        <Duration>16</Duration>
        <Price>-0.03000</Price>
        <Flags>
            <Flag>outbound-api</Flag>
        </Flags>
        <ApiVersion>2008-08-01</ApiVersion>
        <ForwardedFrom/>
        <CallerName/>
        <Uri>/2010-04-01/Accounts/AC5ea872f6da5a21de157d80997a64bd33/Calls/CAe1644a7eed5088b159577c5802d8be38</Uri>
        <SubresourceUris>
            <Notifications>/2010-04-01/Accounts/AC5ea872f6da5a21de157d80997a64bd33/Calls/CAe1644a7eed5088b159577c5802d8be38/Notifications</Notifications>
            <Recordings>/2010-04-01/Accounts/AC5ea872f6da5a21de157d80997a64bd33/Calls/CAe1644a7eed5088b159577c5802d8be38/Recordings</Recordings>
        </SubresourceUris>
    </Call>
</TwilioResponse>

List Resources

Some resources are lists of other resources. For example, the Calls list resource returns a list of calls. There are several important things to know about using and manipulating these lists.

Paging Information

If lists are long, the API returns partial results in a single "page". The representation includes the following paging information:

Property Description
page The current page number. Zero-indexed, so the first page is 0.
numpages The total number of pages.
pagesize How many items are in each page
total The total number of items in the list.
start The position in the overall list of the first item in this page.
end The position in the overall list of the last item in this page.

In addition to this information, the API returns URIs to the next, previous, first and last pages of the returned list, making navigating paged results a breeze:

Parameter Description
uri The URI of the current page.
firstpageuri The URI for the first page of this list.
nextpageuri The URI for the next page of this list.
previouspageuri The URI for the previous page of this list.
lastpageuri The URI for the last page of this list.

For example:

  • <TwilioResponse> 
    <Calls page="0" numpages="3" pagesize="50" total="147" start="0" end="49"
    uri="/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/Calls"
    firstpageuri="/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/Calls?Page=0&PageSize=50"
    previouspageuri=""
    nextpageuri="/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/Calls?Page=1&PageSize=50&AfterSid=CA228399228abecca920de212121"
    lastpageuri="/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/Calls?Page=2&PageSize=50">
        <Call> 
            <Sid>CA92d4405c9237c4ea04b56cbda88e128c</Sid> 
            <DateCreated>Fri, 13 Aug 2010 01:16:22 +0000</DateCreated>
            <DateUpdated>Fri, 13 Aug 2010 01:16:22 +0000</DateUpdated> 
            <ParentCallSid/>
            <AccountSid>AC228ba7a5fe4238be081ea6f3c44186f3</AccountSid>
            <To>+15305431221</To> 
            <From>+15104563443</From>
            <PhoneNumberSid>PNe2d8e63b37f46f2adb16f228afdb9058</PhoneNumberSid>
            <Status>queued</Status> 
            <StartTime/> 
            <EndTime/>
            <Duration/>
            <Price/>
            <Flags> 
                <Flag>outbound-api</Flag>
            </Flags>
            <ApiVersion>2010-04-01</ApiVersion> <ForwardedFrom/> <CallerName/>
            <Uri>/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/Calls/CA92d4405c9237c4ea04b56cbda88e128c</Uri>
            <SubresourceUris>
                <Notifications>/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/Calls/CA92d4405c9237c4ea04b56cbda88e128c/Notifications</Notifications>
                <Recordings>/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/Calls/CA92d4405c9237c4ea04b56cbda88e128c/Recordings</Recordings>
            </SubresourceUris>
        </Call>
        ...
    </Calls>
</TwilioResponse>

Paging Through API Resources

When fetching multiple pages of API results, use the provided nextpageuri parameter to retrieve the next page of results. All of the Twilio Helper Libraries use the nextpageuri to page through resources.

The Page parameter has been deprecated and may be removed in a future version of the API. The Page parameter is slower than the nextpageuri, and if new resources are created while paging with the Page parameter, consecutive pages may contain duplicate data.

You can control the size of pages with the PageSize parameter:

Parameter Description
PageSize How many resources to return in each list page. The default is 50, and the maximum is 1000.

For example, to limit the number of calls returned to five per page:

GET /2010-04-01/Accounts/{AccountSid}/Calls?PageSize=5

Data Formats

Phone Numbers

All phone numbers in requests from Twilio are in E.164 format if possible. For example, (415) 555-4345 would come through as '+14155554345'. However, there are occasionally cases where Twilio cannot normalize an incoming caller ID to E.164. In these situations Twilio will report the raw caller ID string.

Dates & Times

All dates and times in requests from Twilio are GMT in RFC 2822 format. For example, 6:13 PM PDT on August 19th, 2010 would be 'Fri, 20 Aug 2010 01:13:42 +0000'