API - Call History/CDR Documentation
his API facilitates export of Call History/Call Detail Records (CDR) in either CSV or JSON format.
In order to access this API method, please ensure you have correctly set permissions for the relevant API Key. See Creating a new API Key
Base URI and Endpoint
Base URI: https://myapi.voipportal.com.au/
Endpoint: calls/list
Permissions Required
Call History/Get Call History
Example
The API example below is called via standard HTTP GET request, however all parameters can be posted or included in a JSON array.
https://myapi.voipportal.com.au/calls/list/?key=[key]&startTime=[start]&endTime=[end]
Supported Parameters
| Attribute | Supported Values | Required | Notes |
| key | The API key from My Account Portal | Yes | |
| startTime | Unix Timestamp RFC TimeDate |
Yes | Start time of period for which CDR's are required. Treated as >= |
| endTime | Unix Timestamp RFC TimeDate |
Yes | End time of period for which CDR's are required. Treated as < |
| outputFormat | json or csv | No | Default is json |
| chargesOnly | 0 1 |
No | Specifies if result set is to include calls which have not attracted a charge (0) or only return calls which have attracted a charge (1) |
| showHeadings | 0 1 |
No | Include header row in CSV output |
| connectedOnly | 0 1 |
No | List only connected calls in the result set |
| humanReadable | 0 1 |
No | Includes a Human Readable conversion of the duration |
| waitForActiveCalls | 0 1 |
No | This parameter will block the response if there is a call in progress that is yet to complete |
| limit | 1 to 10000 | No | Default 10000. Limits the results |
API Responses
Successful Response
A successful request to the API will result in a HTTP 200 response, and CDR data being returned in either a JSON object, or CSV format, dependent on the request type.
Successful Response - CSV
Should records be available for the request period and filters, a CSV file is returned comprising call records.
Should no records be available for the requested period and filters, an empty CSV file is returned.
Successful Response - JSON
A JSON array with status: 1 and an array of calls (with key "calls") is returned. If there are no calls, count is 0 and data is null.
An example of a result set containing a single call record is as follows:
{
"status":1
"request":"calls\/list",
"timezone":"Australia\/Brisbane",
"offset":"+10:00",
"starttime":"2022-08-27 00:00:00",
"endtime":"2022-08-27 23:59:59",
"count":1,
"calls":[{
"callid":722954181,
"recording":1,
"statid":271020361,
"datetime":"2022-08-27 10:43:32",
"unixtime":1661561012,
"direction":"IN",
"origin":"0731235300",
"destination":"1800121210\/PBX",
"rate":"",
"inboundrate":"1800 Incoming",
"status":"Connected.",
"duration":60,
"cost":"0.25"]}
}
If your access attempt is successful, but no records be available for the requested period and filters, a JSON object is returned as follows;
{
"status":1,
"request":"calls\/list",
"timezone":"Australia\/Brisbane",
"offset":"+10:00",
"starttime":"2022-08-27 00:00:00",
"endtime":"2022-08-27 23:59:59",
"count":0,
"calls":null
}
Successful Response - Result
For JSON The following parameters are returned
| Field | Description |
| timezone | Timezone in Country/City format |
| offset | Timezone offset in +/-hours:minutes |
| starttime | Parsed start time from input startTime |
| endtime | Parsed end time from input endTime |
| count | The total number of records returned |
| calls | An array of call detail records (described below) |
In the case of both JSON & CSV result sets, each CDR returns the following fields
| Field | Description |
| callid | Unique identifier for the call detail record |
| datetime | CDR Time (YYYY-MM-dd HH:MM:SS format) |
| unixtime | CDR Time (Unixtime format) |
| direction | Call direction (Inbound, Outbound) |
| origin | Originating party number (A Party) |
| destination | Terminating party number (B Party) |
| rate | Plaintext description of rate category, empty field for Inbound calls |
| inboundrate | Plaintext description of rate category, empty field for Outbound calls |
| status | Call completion status ( |
| duration | Call duration (seconds) |
| duration_hr | Call duration in friendly format (hh mm ss) |
| cost | Call charge ($.c) |
| recording | Whether or not a call recording exists for the call |
| statid | Unique identifier for related statistics in the PBX system (unused) |
Unsuccessful Response
An unsuccessful request to the API will result in a HTTP response other than a 200 OK, and json with status:0.
Examples of unsuccessful HTTP codes include 401 Unauthorised, 404 Invalid method, a 400 Bad Request/Incomplete request, or 403 Forbidden if the supplied key has insufficient permissions for the method or resource.
{
"status":0,
"request":"\/",
"error":"INVALID METHOD",
"reason":"A method must be supplied
"}
As further functionality becomes available, full permissions, functions, and API descriptions will be available in our upcoming developer portal.
For further assistance with any API CDR related queries, please reach out to Upstreamtech support.