telmetricsV3

Marchex Marketing Edge API Developer Documentation

Welcome to the Marchex Marketing Edge developer hub. You'll find comprehensive guides and documentation to help you start working with our API as quickly as possible.

Get Started    

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 that 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 greater that 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/Unanswered/Busy
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

Updated 3 months ago

Retrieving Phone Call Details


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.