API - Insights

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
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 minutes
   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,
"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 http://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_expires": "2m"}}'

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_expires": "2m"
}
}

cURL Request Example using Since Linked ID:

curl --request POST \
  --url http://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 http://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,
                    "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,
                    "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,
                    "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,
                            "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,
                    "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,
                            "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:

next-button__for_articles_.png

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request