Retrieving Phone Call Details

Retrieve All Calls

Details of calls made to your Tracking Numbers can be retrieved using the Calls Resource.

GET https://api.telmetrics.com/v3/api/calls

When submitting a request, the following URL parameters may be passed:

ParameterDescription
startdateutc=2001-01-01T00:00Filter option to return calls with a start date/time greater than the specified value. Please note that the date passed will be treated as a UTC value. This field is required.
enddateutc=2001-01-01T00:00Filter option to return calls with a start date/time less than the specified value. Please note that the date passed will be treated as a UTC value. This field is required
pageSize=1000How many records to return in the result set. For additional information on paging result sets, please reference our documentation on Paging.
pageNumber=1Will return the corresponding page from the result set. For additional information on paging result sets, please reference our documentation on Paging.
includeTranscription=trueWill return transcriptions where available

Submit a request similar to the following to retrieve a set of Call Detail Records:

curl -H "x-organization-token: {authorization_token}" \
     -X GET \
     "https://api.telmetrics.com/v3/api/calls?pagesize=10000&startdateutc=2018-01-01T00:00&enddateutc=2018-01-02T00:00

If successful, the following response will be returned:

{
    "results": [
        {
            "id": 1926683604,
            "call_type_id": 1,
            "call_type": "Standard",
            "number_id": 8498568,
            "group_id": 11435857,
            "caller_identity": 237277497,
            "organization_id": 4455,
            "answer_status_id": 1,
            "answer_status": "answered",
            "ring_duration": 2,
            "call_duration": 34,
            "registered_DNC": false,
            "tracking_number": "8003147859",
            "caller_number": "6283335467",
            "termination_number": "9052198255",
            "caller_details": {
                "name": "John Estrada",
                "address": "21 Merced Road",
                "city": "SAN FRANCISCO",
                "state": "CA",
                "zip_code": "94105",
                "country": "US",
                "latitude": 37.7844,
                "longitude": -122.3947
            },
            "conversation_analytics": {
                "call_record_file": "22ff5305-ba0e-4b80-97ca-bde9299f06b6",
                "pci_redaction": false,
                "voice_link": "https://webservice.telmetrics.com/filedownload.ashx/DE6634BC-4C0D-47DD-BA02-AA76E235CB05/1977086405.mp3",
                "dispositions": {
                    "lead": {
                        "status": true
                    },
                    "voicemail": {
                        "status": true
                    },
                    "current_customer": {
                        "status": false
                    },
                    "employment_inquiry": {
                        "status": false
                    }
                }
            },
            "attribution_details": {
                "rule_description": "Google Paid -  Local Numbers San Jose",
                "session_id": 7959788,
                "session_identifier": "8b72d00b-f160-4acc-88fa-8a1423f30879",
                "utm_campaign": "backtoschool",
                "utm_term": "pencils",
                "utm_source": "google",
                "utm_medium": "search",
                "utm_content": "banner1",
                "landing_page_url": "https://abccompany.net?utm_campaign=backtoschool&utm_term=pencil&utm_medium=search&utm_content=banner1",
                "referrer_url": "google.com",
                "multisession_flag": true,
                "page_tracks": {
                    "page_track": [
                        {
                            "session_id": "7959788",
                            "page_url": "http://www.test.com/tests/sessions",
                            "timestamp": "2017-12-08T08:53:27.000"
                        },
                        {
                            "session_id": "7959788",
                            "page_url": "http://www.test.com/tests/forms",
                            "timestamp": "2017-12-08T08:53:39.000"
                        }
                    ]
                },
                "events": {
                    "event": {
                        "event_type": "form_submission",
                        "session_id": "7959788",
                        "page_url": "http://tm.telmetrics.com/form1a.htm",
                        "event_data": {
                            "salutation": "Mr.",
                            "name": "John Smith",
                            "email": "[email protected]",
                            "message": "What are your hours today"
                        },
                        "timestamp": "2017-12-08T08:54:12.000"
                    }
                },
            },
            "routing_keypress": "1",
            "start_time": "2017-12-08T08:55:31.000",
            "answer_time": "2017-12-08T08:55:39.000",
            "end_time": "2017-12-08T08:56:13.000",
            "start_time_utc": "2017-12-08T15:55:31.363Z",
            "answer_time_utc": "2017-12-08T15:55:38.717Z",
            "end_time_utc": "2017-12-08T15:56:12.597Z",
            "status": "complete"
        }
    ],
    "paging": {
        "pageNumber": 1,
        "pageSize": 10000,
        "total": 4636
    }
}

Retrieve Calls for a Group

Calls may be retrieved for an individual Groups via the following endpoint:

GET https://api.telmetrics.com/v3/api/v3/api/groups/{group_id}/calls

Sample request:
https://api.telmetrics.com/v3/api/v3/api/groups/{group_id}/calls?startdateutc=2018-10-01T00:00&enddateutc=2019-01-02T00:00&includeTranscription=true&pagesize=1000

Retrieve Calls for a Tracking Number

Calls may be retrieved for an individual Tracking Number via the following endpoint:

GET https://api.telmetrics.com/v3/api/numbers/{number_id}/calls

Sample Request:
https://api.telmetrics.com/v3/api/numbers/{number_id}/calls?startdateutc=2018-10-01T00:00&enddateutc=2019-01-02T00:00&pagesize=1000

Retrieve Calls for a Number Pool

Calls may be retrieved for an individual Number Pool via the following endpoint:
GET https://api.telmetrics.com/v3/api/numberpools/{number_pool_id}/calls

Sample Request:
https://api.telmetrics.com/v3/api/numberpools/{number_pool_id}/calls?startdateutc=2018-10-01T00:00&enddateutc=2019-01-02T00:00&pagesize=1000

Field Definitions

The following fields may be returned by a requests to retrieve calls

FieldDescription
idUnique ID of the phone call
number_idTracking number the call is associated with
group_idGroup the call is associated with
caller_identityUnique identity value for the caller
organization_idglobal organization identifier of the call
answer_statusAnswer status of the phone call. Possible values:
- Answered
- Busy
- Missed
- Pending (All other answer statuses such as StopCall)
ring_durationDuration in seconds for how long a phonecall was ringing before being answered
call_durationDuration in seconds of how long the phone calls lasted
registered_DNCFlag indicating if the caller is on the Do Not Call list
tracking_numberTracking Number that was called
caller_numberPhone Number of the caller
termination_numberPhone Number that the call was forwarded
caller_details -> caller_typeDefines the type of phone number the call came from. Possible values: residential, business, cellular
caller_details -> nameName of the caller
caller_details -> addressStreet address of the caller
caller_details -> cityCity of the caller
caller_details -> stateState/Province of the caller
caller_details -> zip_codeZIP Code/Postal Code of the caller
caller_details -> countryTwo letter country code of the caller
caller_details -> lattitudeLatitude of the caller as defined by their Area Code (NPA) and Exchange (NXX)
caller_details -> longitudeLongitude of the caller as defined by their Area Code (NPA) and Exchange (NXX)
attribution_details -> session_idUnique session id created when a website visitor arrives at a page with DNI
attribution_details -> utm_campaignutm_campaign parameter captured when a user arrives at a site where DNI occurs
attribution_details -> utm_termutm_term parameter captured when a user arrives at a site where DNI occurs
attribution_details -> utm_sourceutm_source parameter captured when a user arrives at a site where DNI occurs
attribution_details -> utm_mediumutm_medium parameter captured when a user arrives at a site where DNI occurs
attribution_details -> utm_contentutm_content parameter captured when a user arrives at a site where DNI occurs
attribution_details -> landing_page_urlURL of the landing page that a website user arrives on
attribution_details -> referrer_urlURL of the referrer responsible for bringing a user to a webpage with DNI enabled
attribution_details -> multisession_flaga true/false that indicates whether more than 1 website visitor has seen the same Tracking Number within the match period configured for a Number Pool
conversation_analytics -> call_record_fileUnique of the Call Recording file
conversation_analytics -> pci_redactionTrue/False flag if redaction was performed on the call recording
conversation_analytics -> voice_linkURL to the call recording
conversation_analytics -> dispostionsAn array of call scoring dispositions that were applied to the call
conversation_analytics -> dispostions -> {disposition_name} -> statusTrue/False flag indicating whether the call was scored to match the disposition
conversation_analytics -> dispostions -> {disposition_name} -> confidence_scoreA confidence score reflecting how certain the machine learning algorithm is that the disposition is correct
routing_keypressIf Key Press routing was enabled for the number, this field will contain the value entered by the consumer
start_timeTime the call was initiated relative to the time zone of the Group the Tracking Number is associated with. This time is used when calculating usage for billing purposes.
answer_timeTime the call answered relative to the time zone of the Group the Tracking Number is associated with. This time is used when calculating usage for billing purposes.
end_timeTime the call ended relative to the time zone of the Group the Tracking Number is associated with. This time is used when calculating usage for billing purposes.
start_time_utcTime the call was initiated in UTC
answer_time_utcTime the call was answered in UTC
end_time_utcTime the call ended in UTC
statusCurrent status of the call. Possible values: Processing, Complete