Get Started

REST API: Tips & Tricks

Vanity URLs

You can create a CNAME of our API URLS and serve up recording media from a hostname of your choosing! To do this, create a CNAME record with your DNS provider that points to api.twilio.com. Note, you shouldn't use SSL (https) URLs if you CNAME, as the certificate will not match.

Alternate Representations

CSV

Append a .csv to the end of REST URLs, and you'll get a Comma Separated Values (CSV) representation of the data, with a header row describing the columns. For example, if you requested the following Calls resource, the default representation is XML:

GET /2010-04-01/Accounts/AC30947.../Calls
<TwilioResponse>  
    <Calls page="0" numpages="1" pagesize="50" total="38" start="0" end="37">  
        <Call>  
            <Sid>CA42ed11f93dc08b952027ffbc406d0868</Sid>  
            <DateCreated>Sat, 07 Feb 2009 13:15:19 +0000</DateCreated>
            <DateUpdated>Sat, 07 Feb 2009 13:15:19 +0000</DateUpdated>
            <AccountSid>AC309475e5fede1b49e100272a8640f438</AccountSid>  
            <To>+14159633717</To>  
            <From>+14156767925</From>  
            <PhoneNumberSid>PN012345678901246789012345678900</PhoneNumberSid>  
            <Status>completed</Status>  
            <StartTime>Thu, 03 Apr 2008 04:36:33 +0000</StartTime>  
            <EndTime>Thu, 03 Apr 2008 04:36:47 +0000</EndTime>  
            <Duration>14</Duration>  
            <Price/>  
            <Flags>
                <Flag>inbound</Flag>
            </Flags>  
        </Call>  
        <Call>  
            <Sid>CA751e8fa0a0105cf26a0d7a9775fb4bfb</Sid>  
            <DateCreated>Sat, 07 Feb 2009 13:15:19 +0000</DateCreated>
            <DateUpdated>Sat, 07 Feb 2009 13:15:19 +0000</DateUpdated>
            <AccountSid>AC309475e5fede1b49e100272a8640f438</AccountSid>  
            <To>+12064287985</To>  
            <From>+14156767925</From>  
            <PhoneNumberSid>PNd59c2ba27ef482647db90476d1674</PhoneNumberSid>  
            <Status>completed</Status>  
            <StartTime>Thu, 03 Apr 2008 01:37:05 +0000</StartTime>  
            <EndTime>Thu, 03 Apr 2008 01:37:40 +0000</EndTime>  
            <Duration>35</Duration>  
            <Price/>  
            <Flags>
                <Flag>inbound</Flag>
            </Flags>  
        </Call>  
        ... 
    </Calls> 
</TwilioResponse>

Appending a .csv, you'd get a CSV representation of the same data with mime-type 'text/csv'. Each Call is a row in the table, and each XML element a column:

GET /2010-04-01/Accounts/AC30947.../Calls.csv

Would return:

Sid, DateCreated, DateUpdated, AccountSid, To, From, ...
CA42ed11f93dc08b952027ffbc406d0868,"Sat, 07 Feb 2009 13:15:19 +0000",
"Sat, 07 Feb 2009 13:15:19 +0000",AC309475e5fede1b49e100272a8640f438,
+14159633717,+14156767925,PN01234567890123456789012345678900,"completed","Thu, 
03 Apr 2008 04:36:33 +0000","Thu, 03 Apr 2008 04:36:47 +0000",14,,inbound,,

JSON

You can also request JSON responses by appending a .json to the end of any REST URL. The response mime-type is 'application/json'.

The 2010-04-01 API version returns a new format for JSON responses than previous REST API versions. This format includes paging information and a simplified structure for resources!

For example, to retrieve IncomingPhoneNumber records as JSON:

GET /2010-04-01/Accounts/AC33d49.../IncomingPhoneNumbers.json
{
    "incoming_phone_numbers":[
        {
            "sid":"PNd6b0e1e84f7b117332aed2fd2e5bbcab",
            "account_sid":"AC228ba7a5fe4238be081ea6f3c44186f3",
            "friendly_name":"My Phone Number",
            "phone_number":"+15104444444",
            "voice_url":"",
            "voice_method":"POST",
            "voice_fallback_url":"",
            "voice_fallback_method":"POST",
            "voice_caller_id_lookup":false,
            "date_created":"Thu, 29 Jul 2010 21:00:17 +0000","
            date_updated":"Mon, 09 Aug 2010 22:14:20 +0000",
            "sms_url":"http:\/\/www.google.com",
            "sms_method":"POST",
            "sms_fallback_url":"",
            "sms_fallback_method":"POST",
            "capabilities": {
                "voice":true,
                "sms":true
                },
            "status_callback":null,
            "status_callback_method":null,
            "api_version":"2008-08-01",
            "uri":"\/2010-04-01\/Accounts\/AC228ba7a5fe4238be081ea6f3c44186f3\/IncomingPhoneNumbers\/PNd6b0e1e84f7b117332aed2fd2e5bbcab.json"
        }
    ],
    "page":0,
    "num_pages":1,
    "page_size":50,
    "total":2,
    "start":0,
    "end":1,
    "uri":"\/2010-04-01\/Accounts\/AC228ba7a5fe4238be081ea6f3c44186f3\/IncomingPhoneNumbers.json",
    "first_page_uri":"\/2010-04-01\/Accounts\/AC228ba7a5fe4238be081ea6f3c44186f3\/IncomingPhoneNumbers.json?Page=0&PageSize=50",
    "previous_page_uri":null,
    "next_page_uri":null,
    "last_page_uri":"\/2010-04-01\/Accounts\/AC228ba7a5fe4238be081ea6f3c44186f3\/IncomingPhoneNumbers.json?Page=0&PageSize=50"
}

HTML

You can also get Twilio to return the same objects formatted as HTML by appending a .html to the end of any url. This may be useful if you intend to pass this data directly to a browser, as all URIs are rendered as links in the HTML document. This feature allows you to click around and explore the Twilio API all while in your browser.

For example, consider the following XML representation of an account:

GET /2010-04-01/Accounts/AC35542fc30a091bed0c1ed511e1d9935d
<TwilioResponse>
    <Account>
        <Sid>AC228ba7a5fe4238be081ea6f3c44186f3</Sid>
        <FriendlyName>folly@folly.com's Account</FriendlyName>
        <Status>Active</Status>
        <DateCreated>Tue, 27 Jul 2010 01:54:11 +0000</DateCreated>
        <DateUpdated>Thu, 29 Jul 2010 20:59:01 +0000</DateUpdated>
        <AuthToken>f9dd7f4177babe34369f719e1d76c0df</AuthToken>
        <Uri>/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3</Uri>
        <SubresourceUris>
            <AvailablePhoneNumbers>/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/AvailablePhoneNumbers.xml</AvailablePhoneNumbers>
            <Calls>/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/Calls.xml</Calls>
            ...
        </SubresourceUris>
    </Account>
</TwilioResponse>

The same resource, represented as HTML is shown below. Note the .html appended to the URI:

GET /2010-04-01/Accounts/AC35542fc30a091bed0c1ed511e1d9935d.html
<html>
<head><title>200</title></head>
<body class="twilio-response">
    <div class="account">
        <h1>Account</h1>
        <dl>
            <dt>sid</dt>
            <dd>AC228ba7a5fe4238be081ea6f3c44186f3</dd>
            <dt>friendly-name</dt>
            <dd>folly@folly.com's Account</dd>
            <dt>status</dt>
            <dd>Active</dd>
            <dt>date-created</dt>
            <dd>Tue, 27 Jul 2010 01:54:11 +0000</dd>
            <dt>date-updated</dt>
            <dd>Thu, 29 Jul 2010 20:59:01 +0000</dd>
            <dt>auth-token</dt>
            <dd>f9dd7f4177babe34369f719e1d76c0df</dd>
            <dt>uri</dt>
            <dd><a href="/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3.html">/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3.html</a></dd>
            <dt>subresource-uris</dt>
            <dd>
            <dl class="subresource-uris">
                <dt>available-phone-numbers</dt>
                <dd><a href="/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/AvailablePhoneNumbers.html">/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/AvailablePhoneNumbers.html</a></dd>
                <dt>calls</dt>
                <dd><a href="/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/Calls.html">/2010-04-01/Accounts/AC228ba7a5fe4238be081ea6f3c44186f3/Calls.html</a></dd>
                <dt>conferences</dt>
                ...
            </dl></dd>
        </dl>
    </div>
</body>
</html>