This is the developer reference document for the insights API endpoints. The insights endpoints provide call detail records (CDR) and are limited to calls during the previous 6 months.
Base URL
https://api.cytracom.net/v1.0
API Endpoints for Data Services
| VERB | URL PATH | ABOUT |
| GET | /insights/{linked_id} | Call Detail Record Info |
| POST | /insights/search | List Selected Call Detail Records |
| POST | /insights/scroll | Continued List of Selected Call Detail Records |
Call Detail Record (CDR) Info
/insights/{linked_id}
When a request is made to retrieve one CDR, the following is required:
| Variable | Description | Mandatory |
| linked_id | The identifier of a specific call. | Yes |
The JSON response provides the data and the status code corresponding to the request made. The data returned is the CDR composed of the following attributes:
| Attribute | Description |
| uuid | Identifier of the origination leg of the call |
| toll_free | Indicates if the call to a toll free destination |
| started_on_ts | Time call began denoted as epoch timestamp in milliseconds (UTC) |
| started_on |
Time call began denoted in ISO 8601 format with timezone (yyyy-mm-ddThh:mm:ss.ffffff+|-hh:mm) |
| sent_to_ftp_on | Log of the date and time when call recording sent to customer's FTP site |
| paths_in_use | Number of call paths used for call |
| other_linked_ids | List of other calls |
| original_caller_id * | Caller ID of phone number making the call |
| origin_state | State code where the caller is located |
| on_network | Indicates if the call completion required trunking |
| monitored | Indicates if call recording is active for call |
| recording_url | Path and filename of call recording for monitored calls |
| linked_id | Identifier for the call |
| legs | Details for each call leg |
| started_on_ts | Time call leg began denoted as epoch timestamp in milliseconds (UTC) |
| started_on | Time call leg began denoted in ISO 8601 format with timezone (yyyy-mm-ddThh:mm:ss.ffffff+|-hh:mm) |
| source * | Endpoint initiating the leg |
| monitored | Indicates if call recording active for leg |
| index | Identifier for leg |
| duration | Length of the call leg in seconds |
| destination | Endpoint to receive to call |
| conference | Indicates if leg is part of conference call |
| caller_id * | Caller id of the source of the leg |
| bridged | Indicates the leg was connected |
| caller / callee | Details for each endpoint of the leg |
| type | Descriptive type of the endpoint such as external, extension, mailbox, etc |
| number * | Phone number or extension |
| name * | Name associated with number |
| call_route_id | Identifier of the dialplan route utilized |
| interstate | Indicates if the call destination is out-of-state |
| international | Indicates if the outbound call was international |
| duration | Length of the call in seconds |
| directory_assistance | Indicates if the outbound call was directory assistance |
| direction | Call direction where inbound is coming from external; outbound is going to external; internal is within the system |
| dialed_number * | Phone number dialed by person making call |
| destination_state | The state code of the country where the call |
| delete_at | Date of expiration for CDR data retention |
| customer_id | Identifier of the customer account |
| customer_code | Identifying code used by PBX for the account |
| call_flow | List of the leg endpoints |
| answered | Indicates if the call was answered |
Note * - These fields are searched when using the general_search.
Example cURL Request:
curl --request GET \
--user token:<<YOUR-TOKEN>> \
--url https://api.cytracom.net/v1.0/insights/1548719160851.275619
Example JSON Response:
{
"data": {
"call_detail": {
"uuid": "49ab7581-a17f-43ee-9cfb-85f8c4b3c39e",
"toll_free": false,
"started_on_ts": 1548719160826,
"started_on": "2019-01-28T17:46:00.826282-06:00",
"sent_to_ftp_on": null,
"paths_in_use": 1,
"other_linked_ids": [],
"original_caller_id": "\"Josh Wader\" <sip501_baaaaac>",
"origin_state": "TX",
"on_network": false,
"monitored": false,
"recording_url": null,
"linked_id": "1548719160851.275619",
"legs": [
{
"started_on_ts": 1548719160846,
"started_on": "2019-01-28T17:46:00.846272-06:00",
"source": "sip501_baaaaac",
"monitored": false,
"index": 1,
"duration": 5,
"destination": "*501",
"conference": false,
"caller_id": "\"Josh Wader\" <sip501_baaaaac>",
"caller": {
"type": "extension",
"number": "501",
"name": "Steve Jobs",
"call_route_id": 95069
},
"callee": {
"type": "mailbox",
"number": "501",
"name": "Ext 501",
"call_route_id": 95066
},
"bridged": false
}
],
"interstate": null,
"international": false,
"duration": 5,
"directory_assistance": false,
"direction": "internal",
"dialed_number": "*501",
"destination_state": "NA",
"delete_at": null,
"customer_id": 6,
"customer_code": "baaaaac",
"call_flow": [],
"answered": false
}
},
"code": 200
}
List Selected Call Detail Records
/insights/search
Searching for CDRs can be accomplished by two request methods; using a date range, or using a call identifier (linked_id) as a starting point. Both methods allow for additional criteria to be used to filter the search results.
When a large number of CDRs are retrieved, the size parameter controls the number of records retrieved. A scroll ID will be returned to allow a request for the next set of data of the search using only the scroll ID (scroll_id). Options for size and scroll expires may be used.
The values generated for the linked_id field are sequential according to the time calls begin. This allows retrieval of calls made since the last CDR was retrieved by a customer application.
When the request is made to list CDRs, the following fields are supported in the search query:
| Field | Value Type | Mandatory | Description |
| query | Yes | Includes fields for query | |
| date_range | Yes, if not using linked_id method | Includes date range fields corresponding to the CDR started_on date. Range must not exceed 90 days. | |
| start | String | Yes, if using date range | The beginning of the range, inclusive. It may be ISO 8601 format or epoch timestamp in milliseconds. |
| end | String | Yes, if using date range | The beginning of the range, inclusive. It may be ISO 8601 format or epoch timestamp in milliseconds. |
| since_linked_id | String | Yes, if not using date range method | The linked_id of a call just prior to the calls desired. |
| call_route_ids | List | No | Filter selected CDRs by the matching call_route_id. |
| general_search | String | No | Filter selected CDRs by using a single string (no spaces) contained in phone numbers or names. (See Note * above for fields searched) |
| options | No | Includes fields for optional parameters. | |
| size | Integer | No |
Pagination of results can be done by using size. The size parameter allows you to configure the maximum amount of records to be returned. It defaults to 0 and the maximum is 100. Setting as 0 will result in a response with the total number, but no data. |
| scroll | String | No | Scroll indicator value of true or false can be used to indicate if the iterative scroll process is needed. The scrolling will be available for only 1 minute before it expires. With each iteration, a new scroll_id is returned when there is more data to scroll otherwise returns an empty string. |
cURL Request Example using Date Range:
curl --request POST \
--url https://api.cytracom.net/v1.0/insights/search \
--user token:<<YOUR-TOKEN>> \
--header 'content-type: application/json' \
--data '{"query":{"date_range":{"start": "2018-07-27T00:00:00.000-0600","end": "2018-09-25T23:59:59.000-0600"},"general_search": "Cytracom"},"options":{"size": 4,"scroll": "true"}}'
Data Query Example JSON using Date Range:
{
"query": {
"date_range": {
"start": "2018-07-27T00:00:00.000-0600",
"end": "2018-09-25T23:59:59.000-0600"
},
"general_search": "Cytracom"
},
"options": {
"size": 4,
"scroll": "true"
}
}
cURL Request Example using Since Linked ID:
curl --request POST \
--url https://api.cytracom.net/v1.0/insights/search \
--user token:<<YOUR-TOKEN>> \
--header 'content-type: application/json' \
--data '{"query":{"since_linked_id": "1533671862.78830"},"options":{"size": 4}}'
Data Query Example JSON using Since Linked ID:
{
"query": {
"since_linked_id": "1533671862.78830"
},
"options": {
"size": 4
}
}
Continued List Selected Call Detail Records
/insights/scroll
When a large number of CDRs are retrieved, the size parameter controls the number of records retrieved. A scroll ID will be returned with each response to allow a request for the next set of data of the search using only the scroll ID (scroll_id). Options for size and scroll expires may be used.
Scroll requests should be made using each new scroll ID until no data is returned. Scroll IDs are valid for 1 minute and then expire.
When the request is made to scroll the CDR lising, the following fields are supported in the scroll:
| Field | Value Type | Mandatory | Description |
| scroll_id | String | Yes | The identifier used to retrieve the next set of data for the search. |
| scroll_expires | String | No | Scroll can be used to retrieve large amount of data, in much the same way as you would use a cursor on a traditional database. The scroll_expires field is used to keep the search content alive by defining how long the search content will be kept alive in minutes. The value ranges from "1m" to "5m" with "1m" being the default value and "5m" being the maximum. scroll_id is returned when there is more data to scroll otherwise returns an empty string |
cURL Request Example:
curl --request POST \
--url https://api.cytracom.net/v1.0/insights/scroll \
--user token:<<YOUR-TOKEN>> \
--header 'content-type: application/json' \
--data '{"scroll_id": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAAAE5iFnZTaU12UDVDUndDb0xnTmRZQmRkckEAAAAAAABOYxZ2U2lNdlA1Q1J3Q29MZ05kWUJkZHJBAAAAAAAATmUWdlNpTXZQNUNSd0NvTGdOZFlCZGRyQQAAAAAAAE5kFnZTaU12UDVDUndDb0xnTmRZQmRkckEAAAAAAABOZhZ2U2lNdlA1Q1J3Q29MZ05kWUJkZHJB",
"scroll_expires": "2m"}'
JSON Response Example:
{
"data": {
"total": 5,
"search": {
"scroll_id": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAAAFCDFnZTaU12UDVDUndDb0xnTmRZQmRkckEAAAAAAABQhBZ2U2lNdlA1Q1J3Q29MZ05kWUJkZHJBAAAAAAAAUIUWdlNpTXZQNUNSd0NvTGdOZFlCZGRyQQAAAAAAAFCHFnZTaU12UDVDUndDb0xnTmRZQmRkckEAAAAAAABQhhZ2U2lNdlA1Q1J3Q29MZ05kWUJkZHJB",
"records": [
{
"uuid":"901ff6d5-2b36-4803-8b04-a4d9564d4d22",
"toll_free": false,
"started_on_ts": 1533671847000,
"started_on": "2018-08-07T14:57:27.000-05:00",
"paths_in_use": 1,
"original_caller_id": "\"CYTRACOM LLC \" <+12144492821>",
"origin_state": "TX",
"on_network": false,
"monitored": false,
"recording_url": null,
"linked_id": "1533671847.78821",
"legs": [
{
"unique_id": "1533671847.78821",
"started_on_ts": 1533671847000,
"started_on": "2018-08-07T14:57:27.000-05:00",
"source": "2144492821",
"monitored": false,
"index": 1,
"duration": 84,
"destination": "203",
"conference": false,
"caller_id": "\"CYTRACOM LLC \" <2144492821>",
"caller": {
"origin": true,
"number": "2144492821",
"name": "CYTRACOM LLC "
},
"callee": {
"type": "extension",
"origin": false,
"number": "203",
"name": "Fred Flintstone",
"device": "sip203_baaaaab",
"call_route_id": 121967
},
"bridged": true
}
],
"interstate": false,
"international": false,
"duration": 84,
"directory_assistance": false,
"direction": "inbound",
"dialed_number": "4694409076",
"destination_state": "TX",
"customer_id": 4,
"customer_code": "baaaaab",
"call_flow": "extension(121967)",
"answered": true
},
{
"uuid":"901ff6d5-2b36-4803-8b04-a4d9564d4d22",
"toll_free": false,
"started_on_ts": 1533671942000,
"started_on": "2018-08-07T14:59:02.000-05:00",
"paths_in_use": 1,
"original_caller_id": "\"CYTRACOM LLC \" <+12144492821>",
"origin_state": "TX",
"on_network": false,
"monitored": false,
"recording_url": null,
"linked_id": "1533671942.78873",
"legs": [
{
"unique_id": "1533671942.78873",
"started_on_ts": 1533671942000,
"started_on": "2018-08-07T14:59:02.000-05:00",
"source": "2144492821",
"monitored": false,
"index": 1,
"duration": 28,
"destination": "203",
"conference": false,
"caller_id": "\"CYTRACOM LLC \" <2144492821>",
"caller": {
"origin": true,
"number": "2144492821",
"name": "CYTRACOM LLC "
},
"callee": {
"type": "extension",
"origin": false,
"number": "203",
"name": "Fred Flintstone",
"device": "sip203_baaaaab",
"call_route_id": 121967
},
"bridged": true
}
],
"interstate": false,
"international": false,
"duration": 28,
"directory_assistance": false,
"direction": "inbound",
"dialed_number": "4694409076",
"destination_state": "TX",
"customer_id": 4,
"customer_code": "baaaaab",
"call_flow": "extension(121967)",
"answered": true
},
{
"uuid":"901ff6d5-2b36-4803-8b04-a4d9564d4d22",
"toll_free": false,
"started_on_ts": 1533826950000,
"started_on": "2018-08-09T10:02:30.000-05:00",
"paths_in_use": 1,
"original_caller_id": "\"CYTRACOM LLC \" <+12144492821>",
"origin_state": "TX",
"on_network": false,
"monitored": false,
"recording_url": null,
"linked_id": "1533826950.104545",
"legs": [
{
"unique_id": "1533826950.104545",
"started_on_ts": 1533826950000,
"started_on": "2018-08-09T10:02:30.000-05:00",
"source": "2144492821",
"monitored": false,
"index": 1,
"duration": 25,
"destination": "203",
"conference": false,
"caller_id": "\"CYTRACOM LLC \" <2144492821>",
"caller": {
"origin": true,
"number": "2144492821",
"name": "CYTRACOM LLC "
},
"callee": {
"type": "extension",
"origin": false,
"number": "203",
"name": "Fred Flintstone",
"device": "sip203_baaaaab",
"call_route_id": 121967
},
"bridged": false
},
{
"unique_id": "1533826950.104545",
"started_on_ts": 1533826950000,
"started_on": "2018-08-09T10:02:56.000-05:00",
"source": "2144492821",
"monitored": false,
"recording_url": null,
"index": 2,
"duration": 20,
"destination": "u",
"conference": false,
"caller_id": "\"CYTRACOM LLC \" <2144492821>",
"caller": {
"origin": true,
"number": "2144492821",
"name": "CYTRACOM LLC "
},
"callee": {
"type": "mailbox",
"origin": false,
"number": "203",
"name": "Fred Flintstone",
"call_route_id": 121964
},
"bridged": true
}
],
"interstate": false,
"international": false,
"duration": 45,
"directory_assistance": false,
"direction": "inbound",
"dialed_number": "4694409076",
"destination_state": "TX",
"customer_id": 4,
"customer_code": "baaaaab",
"call_flow": "extension(121967)->mailbox(121964)",
"answered": false
},
{
"uuid":"901ff6d5-2b36-4803-8b04-a4d9564d4d22",
"toll_free": false,
"started_on_ts": 1533827342000,
"started_on": "2018-08-09T10:09:02.000-05:00",
"paths_in_use": 1,
"original_caller_id": "\"CYTRACOM LLC \" <+12144492821>",
"origin_state": "TX",
"on_network": false,
"monitored": false,
"recording_url": null,
"linked_id": "1533827342.104653",
"legs": [
{
"unique_id": "1533827342.104653",
"started_on_ts": 1533827342000,
"started_on": "2018-08-09T10:09:02.000-05:00",
"source": "2144492821",
"monitored": false,
"index": 1,
"duration": 25,
"destination": "203",
"conference": false,
"caller_id": "\"CYTRACOM LLC \" <2144492821>",
"caller": {
"origin": true,
"number": "2144492821",
"name": "CYTRACOM LLC "
},
"callee": {
"type": "extension",
"origin": false,
"number": "203",
"name": "Fred Flintstone",
"device": "sip203_baaaaab",
"call_route_id": 121967
},
"bridged": false
},
{
"unique_id": "1533827342.104653",
"started_on_ts": 1533827342000,
"started_on": "2018-08-09T10:09:27.000-05:00",
"source": "2144492821",
"monitored": false,
"recording_url": null,
"index": 2,
"duration": 18,
"destination": "u",
"conference": false,
"caller_id": "\"CYTRACOM LLC \" <2144492821>",
"caller": {
"origin": true,
"number": "2144492821",
"name": "CYTRACOM LLC "
},
"callee": {
"type": "mailbox",
"origin": false,
"number": "203",
"name": "Fred Flintstone",
"call_route_id": 121964
},
"bridged": true
}
],
"interstate": false,
"international": false,
"duration": 43,
"directory_assistance": false,
"direction": "inbound",
"dialed_number": "4694409076",
"destination_state": "TX",
"customer_id": 4,
"customer_code": "baaaaab",
"call_flow": "extension(121967)->mailbox(121964)",
"answered": false
}
]
}
},
"code": 200
}
To view the next article, click:
