REST API: Twilio Responses

Response Formats

Resource Representations

By default Twilio's REST API returns resource representations as XML within a root element of <TwilioResponse>. For example, the default representation of an account resource is:

GET /2008-08-01/Accounts/AC35542fc30a091bed0c1ed511e1d9935d HTTP/1.1

<TwilioResponse> 
    <Account> 
        <Sid>AC35542fc30a091bed0c1ed511e1d9935d</Sid> 
        <FriendlyName>Friendly Account 1</FriendlyName> 
        <Status>1</Status> 
        <StatusText>Inactive</StatusText> 
        <DateCreated>Tue, 01 Apr 2008 11:26:32 -0700</DateCreated> 
        <DateUpdated>Tue, 01 Apr 2008 11:26:32 -0700</DateUpdated> 
    </Account>
</TwilioResponse>

Twilio can also return JSON, CSV and other representation formats. See the Tips & Tricks section for more information.

Exceptions

Twilio returns exceptions as a <RestException> element within the root <TwilioResponse> element. The RestException contains up to four elements:

• Status: Corresponds to the HTTP status code returned.
• Message: A more verbose message regarding the error.
• Code: (Conditional) An error code that can be used to find specific help in the Twilio documentation.
• MoreInfo: (Conditional) The URL of Twilio's documentation for the error code.

If you receive a 400 response status (invalid request), then the <Code> and <MoreInfo> elements will be populated to help you debug your invalid request.

For example, a simple 404:

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

Another example; an invalid POST to the Calls resource that was missing the Called parameter:

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

List Resources

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

Paging Info

If lists are long, the API returns a single page of results. The XML response returns paging info in the list's element, including:

• page: which page you're currently viewing. Zero-indexed, so the first page is 0.
• numpages: How many pages of data are there in total
• pagesize: How many objects are on each page
• total: How many total objects are there in the result set
• start: The index of the first object on this page, out of the total result set size.
• end: The index of the last object on this page, out of the total result set size.

For example:

<TwilioResponse> 
    <Calls page="0" numpages="1" pagesize="50" total="38" start="0" end="37"> 
        <Call> 
            <Sid>CA42ed11f93dc08b952027ffbc406d0868</Sid> 
            <CallSegmentSid/> 
            <AccountSid>AC012345678901234567890123456789AF</AccountSid> 
            <Called>4159633717</Called> 
            <Caller>4156767925</Caller> 
            <PhoneNumberSid>PN01234567890123456789012345678900</PhoneNumberSid> 
            <Status>2</Status> 
            <StartTime>Thu, 03 Apr 2008 04:36:33 -0400</StartTime> 
            <EndTime>Thu, 03 Apr 2008 04:36:47 -0400</EndTime> 
            <Price/> 
            <Flags>1</Flags> 
        </Call> 
        ... 
    </Calls> 
</TwilioResponse>

You can control paging with query string parameters:

• num: How many objects to show on each page. Default is 50. The max is 1000
• page: Which page to view. Zero indexed, so the first page is 0. Default is 0.

For example:

GET /2008-08-01/Accounts/{MyAccountSid}/Calls?num=5&page=1 HTTP/1.1

This would limit the number of calls to 5 on each page, and would return results for the second page.

HTTP Status Codes

Twilio frequently return the following status codes:

• 200 OK: All is well, the request body is a representation of the requested resource.
• 201 CREATED: Your request resulted in a new resource being created. It's URL is given in the http Location header.
• 302 FOUND: A common redirect response, look for the new resource URI in the Location header.
• 304 NOT MODIFIED: Means that the client's cached version is still up to date.
• 400 BAD REQUEST: Something in the request was not valid, usually inputs to a POST or PUT. Check the RestException/Message string for more details.
• 401 UNAUTHORIZED: The supplied credentials, if any, are not sufficient to access the resource.
• 404 NOT FOUND: You know this one.
• 405 METHOD NOT ALLOWED: The HTTP method (GET, POST, PUT, DELETE) is not valid for the resource. For example, trying to DELETE your account. Bad idea.
• 500 SERVER ERROR: We screwed up. Sorry.