Response Formats

When you make a request to TelAPI it will always return a response regarding the resources you have requested, created, or modified. These responses can be in a few different formats: XML, JSON, or CSV.

XML Response

XML is the default format when returning responses from TelAPI. All responses are wrapped by the <TelapiResponse> element. An example of a request to view a call resource with an XML response returned is below.

Request

Response

<TelapiResponse>
    
         <Call>
            <Sid>{CallSid}</Sid>
            <DateCreated>Tue, 24 Jul 2012 14:56:32 +0000</DateCreated>
            <DateUpdated>Tue, 24 Jul 2012 14:56:35 +0000</DateUpdated>
            <ParentCallSid></ParentCallSid>
            <AccountSid>{AccountSid}</AccountSid>
            <To>+14245555526</To>
            <From>+17325551300</From>
            <PhoneNumberSid>{PhoneNumberSid}</PhoneNumberSid>
            <Status>completed</Status>
            <StartTime>Tue, 24 Jul 2012 14:56:32 +0000</StartTime>
            <EndTime>Tue, 24 Jul 2012 14:56:35 +0000</EndTime>
            <Duration>3</Duration>
            <Price>0.010000</Price>
            <Direction>outbound-api</Direction>
            <AnsweredBy>None</AnsweredBy>
            <ApiVersion>v1</ApiVersion>
            <ForwardedFrom></ForwardedFrom>
            <CallerIdBlocked>False</CallerIdBlocked>
            <Uri>/v1/Accounts/{AccountSid}/Calls/{CallSid}</Uri>
            <SubresourceUris>
                <Notifications>/v1/Accounts/{AccountSid}/Calls/{CallSid}/Notifications</Notifications>
                <Recordings>/v1/Accounts/{AccountSid}/Calls/{CallSid}/Recordings</Recordings>
            </SubresourceUris>
        </Call>

</TelapiResponse>

JSON Response

The second optional response format is JSON. To enable a JSON response, simply apply .json to the end of the request URL. Elements within a JSON response are lowercase and separated by an underscore. An example of a request to view a call resource with a JSON response returned is below.

Request

Response

{
    "sid": "{CallSid}",
    "date_created": "Tue, 24 Jul 2012 14:56:32 +0000",
    "date_updated": "Tue, 24 Jul 2012 14:56:35 +0000",
    "parent_call_sid": "",
    "account_sid": "{AccountSid}",
    "to": "+14245555526",
    "from": "+17325551300",
    "phone_number_sid": "{phone_number_sid}",
    "status": "completed",
    "start_time": "Tue, 24 Jul 2012 14:56:32 +0000",
    "end_time": "Tue, 24 Jul 2012 14:56:35 +0000",
    "duration": "3",
    "price": "0.010000",
    "direction": "outbound-api",
    "answered_by": "None",
    "api_version": "v1",
    "forwarded_from": "",
    "p_asserted_identity": "",
    "sip_privacy": "",
    "privacy_hide_number": "False",
    "uri": "/v1/Accounts/{AccountSid}/Calls/{CallSid}.json",
    "subresource_uris": {
        "notifications": "/v1/Accounts/{AccountSid}/Calls/{CallSid}/Notifications.json",
        "recordings": "/v1/Accounts/{AccountSid}/Calls/{CallSid}/Recordings.json"
    }
}

CSV Response

.csv can be appended at the end of your request URL to receive a CSV (Comma Seperated Value) response. Data in a CSV format can be useful for easily displaying that information in spreadsheets. An example of a request to view a call list resource with a CSV response returned is below.

Response

sid,date_created,date_updated,parent_call_sid,account_sid,to,from,phone_number_sid,status,start_time,end_time,duration,price,direction,answered_by,api_version,forwarded_from,sip_privacy,privacy_hide_number,uri,notifications,recordings
CA6f59d1b165fc49778cb5c7d338f36292,"Mon, 13 Aug 2012 20:48:00 +0000","Mon, 13 Aug 2012 20:48:12 +0000",,{AccountSid},+14355553967,+17325551300,DIfbab1d298fcf4c8c9e1e6778e8dd8cf0,completed,"Mon, 13 Aug 2012 20:48:00 +0000","Mon, 13 Aug 2012 20:48:12 +0000",12,0.045000,inbound,None,v1,,,False,"/v1/Accounts/{AccountSid}/Calls/CA6f59d1b165fc49778cb5c7d338f36292.csv","/v1/Accounts/{AccountSid}/Calls/CA6f59d1b165fc49778cb5c7d338f36292/Notifications.csv","/v1/Accounts/{AccountSid}/Calls/CA6f59d1b165fc49778cb5c7d338f36292/Recordings.csv"
CA8dc61f5ddd5445f59b63dc8479b0a452,"Mon, 13 Aug 2012 20:47:02 +0000","Mon, 13 Aug 2012 20:47:06 +0000",,{AccountSid},+14355553967,+17325551300,DIfbab1d298fcf4c8c9e1e6778e8dd8cf0,completed,"Mon, 13 Aug 2012 20:47:02 +0000","Mon, 13 Aug 2012 20:47:06 +0000",4,0.045000,inbound,None,v1,,,False,"/v1/Accounts/{AccountSid}/Calls/CA8dc61f5ddd5445f59b63dc8479b0a452.csv","/v1/Accounts/{AccountSid}/Calls/CA8dc61f5ddd5445f59b63dc8479b0a452/Notifications.csv","/v1/Accounts/{AccountSid}/Calls/CA8dc61f5ddd5445f59b63dc8479b0a452/Recordings.csv"
CAae334f29aa2e4566bb8ed06dfd1de1cf,"Mon, 13 Aug 2012 20:46:46 +0000","Mon, 13 Aug 2012 20:46:54 +0000",,{AccountSid},+14355553967,+17325551300,DIfbab1d298fcf4c8c9e1e6778e8dd8cf0,completed,"Mon, 13 Aug 2012 20:46:46 +0000","Mon, 13 Aug 2012 20:46:54 +0000",8,0.045000,inbound,None,v1,,,False,"/v1/Accounts/{AccountSid}/Calls/CAae334f29aa2e4566bb8ed06dfd1de1cf.csv","/v1/Accounts/{AccountSid}/Calls/CAae334f29aa2e4566bb8ed06dfd1de1cf/Notifications.csv","/v1/Accounts/{AccountSid}/Calls/CAae334f29aa2e4566bb8ed06dfd1de1cf/Recordings.csv"
CA4f5b0620ed18436eac22e3d5e73fd818,"Mon, 13 Aug 2012 20:46:20 +0000","Mon, 13 Aug 2012 20:46:28 +0000",,{AccountSid},+14355553967,+17325551300,DIfbab1d298fcf4c8c9e1e6778e8dd8cf0,completed,"Mon, 13 Aug 2012 20:46:20 +0000","Mon, 13 Aug 2012 20:46:28 +0000",8,0.045000,inbound,None,v1,,,False,"/v1/Accounts/{AccountSid}/Calls/CA4f5b0620ed18436eac22e3d5e73fd818.csv","/v1/Accounts/{AccountSid}/Calls/CA4f5b0620ed18436eac22e3d5e73fd818/Notifications.csv","/v1/Accounts/{AccountSid}/Calls/CA4f5b0620ed18436eac22e3d5e73fd818/Recordings.csv"
CA519ae7fa2e05473597ccf3c92acab451,"Mon, 13 Aug 2012 20:45:55 +0000","Mon, 13 Aug 2012 20:46:04 +0000",,{AccountSid},+14355553967,+17325551300,DIfbab1d298fcf4c8c9e1e6778e8dd8cf0,completed,"Mon, 13 Aug 2012 20:45:55 +0000","Mon, 13 Aug 2012 20:46:04 +0000",9,0.045000,inbound,None,v1,,,False,"/v1/Accounts/{AccountSid}/Calls/CA519ae7fa2e05473597ccf3c92acab451.csv","/v1/Accounts/{AccountSid}/Calls/CA519ae7fa2e05473597ccf3c92acab451/Notifications.csv","/v1/Accounts/{AccountSid}/Calls/CA519ae7fa2e05473597ccf3c92acab451/Recordings.csv"

REST Exceptions

When something goes wrong during a request, TelAPI responds with an HTTP status code, a message describing what went wrong, and, if it can, an error code and link to more information regarding the error. Here are examples of an exception response returned by TelAPI when a request is made with invalid credentials.

<TelapiResponse>
    <RestException> 
        <Status>403</Status> 
        <Message>Invalid credentials supplied</Message>        
        <Code>10004</Code>
        <MoreInfo>http://www.telapi.com/docs/api/rest/overview/errors/10004</MoreInfo>   
    </RestException>
</TelapiResponse>        

{
	"status": 403,
	"message": "Invalid credentials supplied",
	"code": 10004,
	"more_info": "http://www.telapi.com/docs/api/rest/overview/errors/10004"
}        

Response Paging Properties

Requests to TelAPI asking for lists will sometimes receive very large responses. To help with navigating through this data, TelAPI breaks larger responses up into pages and provides paging information in each response.

The properties Page and PageSize can be used as CamelCased parameters during requests to designate that a particular page or pagesize should be returned. An example of the response returned when using these optional parameters is below.

Request

Response

<TelapiResponse>
    
      <Calls page="5" numpages="727" pagesize="2" total="1454" start="10" end="11" 
            uri="/v1/Accounts/{AccountSid}/Calls" 
            firstpageuri="/v1/Accounts/{AccountSid}/Calls?Page=0&PageSize=2" 
            previouspageuri="/v1/Accounts/{AccountSid}/Calls?Page=4&PageSize=2" 
            nextpageuri="/v1/Accounts/{AccountSid}/Calls?Page=6&PageSize=2" 
            lastpageuri="/v1/Accounts/{AccountSid}/Calls?Page=726&PageSize=2">

            <Call>
                <Sid>{CallSid}</Sid>
                <DateCreated>Fri, 27 Jul 2012 15:46:05 +0000</DateCreated>
                <DateUpdated>Fri, 27 Jul 2012 15:46:24 +0000</DateUpdated>
                <ParentCallSid></ParentCallSid>
                <AccountSid>{AccountSid}</AccountSid>
                <To>+14245555526</To>
                <From>+17325551300</From>
                <PhoneNumberSid>{PhoneNumberSid}</PhoneNumberSid>
                <Status>completed</Status>
                <StartTime>Fri, 27 Jul 2012 15:46:05 +0000</StartTime>
                <EndTime>Fri, 27 Jul 2012 15:46:24 +0000</EndTime>
                <Duration>19</Duration>
                <Price>0.010000</Price>
                <Direction>inbound</Direction>
                <AnsweredBy>None</AnsweredBy>
                <ApiVersion>v1</ApiVersion>
                <ForwardedFrom></ForwardedFrom>
                
                
                <CallerIdBlocked>False</CallerIdBlocked>
                <Uri>/v1/Accounts/{AccountSid}/Calls/{CallSid}</Uri>
                <SubresourceUris>
                    <Notifications>/v1/Accounts/{AccountSid}/Calls/{CallSid}/Notifications</Notifications>
                    <Recordings>/v1/Accounts/{AccountSid}/Calls/{CallSid}/Recordings</Recordings>
                </SubresourceUris>
            </Call>


            <Call>
                <Sid>{CallSid}</Sid>
                <DateCreated>Fri, 27 Jul 2012 14:54:26 +0000</DateCreated>
                <DateUpdated>Fri, 27 Jul 2012 14:54:51 +0000</DateUpdated>
                <ParentCallSid></ParentCallSid>
                <AccountSid>{AccountSid}</AccountSid>
                <To>+17325554321</To>
                <From>+17325554980</From>
                <PhoneNumberSid></PhoneNumberSid>
                <Status>completed</Status>
                <StartTime>Fri, 27 Jul 2012 14:54:26 +0000</StartTime>
                <EndTime>Fri, 27 Jul 2012 14:54:51 +0000</EndTime>
                <Duration>25</Duration>
                <Price>0.066000</Price>
                <Direction>outbound-api</Direction>
                <AnsweredBy>None</AnsweredBy>
                <ApiVersion>v1</ApiVersion>
                <ForwardedFrom></ForwardedFrom>
                
                
                <CallerIdBlocked>False</CallerIdBlocked>
                <Uri>/v1/Accounts/{AccountSid}/Calls/{CallSid}</Uri>
                <SubresourceUris>
                    <Notifications>/v1/Accounts/{AccountSid}/Calls/{CallSid}/Notifications</Notifications>
                    <Recordings>/v1/Accounts/{AccountSid}/Calls/{CallSid}/Recordings</Recordings>
                </SubresourceUris>
            </Call>

      </Calls>

</TelapiResponse>        

{
	"page": 5,
	"num_pages": 727,
	"page_size": 2,
	"total": 1454,
	"start": 10,
	"end": 11,
	"uri": "/v1/Accounts/{AccountSid}/Calls.json",
	"first_page_uri": "/v1/Accounts/{AccountSid}/Calls.json?Page=0&PageSize=2",
	"previous_page_uri": "/v1/Accounts/{AccountSid}/Calls.json?Page=4&PageSize=2",
	"next_page_uri": "/v1/Accounts/{AccountSid}/Calls.json?Page=6&PageSize=2",
	"last_page_uri": "/v1/Accounts/{AccountSid}/Calls.json?Page=726&PageSize=2",
	"calls": [
    
    {
    "sid": "{CallSid}",
    "date_created": "Fri, 27 Jul 2012 15:46:05 +0000",
    "date_updated": "Fri, 27 Jul 2012 15:46:24 +0000",
    "parent_call_sid": "",
    "account_sid": "{AccountSid}",
    "to": "+14245555526",
    "from": "+17325551300",
    "phone_number_sid": "{phone_number_sid}",
    "status": "completed",
    "start_time": "Fri, 27 Jul 2012 15:46:05 +0000",
    "end_time": "Fri, 27 Jul 2012 15:46:24 +0000",
    "duration": "19",
    "price": "0.010000",
    "direction": "inbound",
    "answered_by": "None",
    "api_version": "v1",
    "forwarded_from": "",
    "p_asserted_identity": "",
    "sip_privacy": "",
    "privacy_hide_number": "False",
    "uri": "/v1/Accounts/{AccountSid}/Calls/{CallSid}.json",
    "subresource_uris": {
        "notifications": "/v1/Accounts/{AccountSid}/Calls/{CallSid}/Notifications.json",
        "recordings": "/v1/Accounts/{AccountSid}/Calls/{CallSid}/Recordings.json"
        }
    }

	
    , 
    {
    "sid": "{CallSid}",
    "date_created": "Fri, 27 Jul 2012 14:54:26 +0000",
    "date_updated": "Fri, 27 Jul 2012 14:54:51 +0000",
    "parent_call_sid": "",
    "account_sid": "{AccountSid}",
    "to": "+17325554321",
    "from": "+17325554980",
    "phone_number_sid": "",
    "status": "completed",
    "start_time": "Fri, 27 Jul 2012 14:54:26 +0000",
    "end_time": "Fri, 27 Jul 2012 14:54:51 +0000",
    "duration": "25",
    "price": "0.066000",
    "direction": "outbound-api",
    "answered_by": "None",
    "api_version": "v1",
    "forwarded_from": "",
    "p_asserted_identity": "",
    "sip_privacy": "None",
    "privacy_hide_number": "False",
    "uri": "/v1/Accounts/{AccountSid}/Calls/{CallSid}.json",
    "subresource_uris": {
        "notifications": "/v1/Accounts/{AccountSid}/Calls/{CallSid}/Notifications.json",
        "recordings": "/v1/Accounts/{AccountSid}/Calls/{CallSid}/Recordings.json"
        }
    }

	]
}