Retrieving Phone Call Details

Retrieve All Calls

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

GET https://edgeapi.marchex.io/marketingedge/v5/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 and associated keyword spotting results where available

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

curl -H "x-organization-token: {authorization_token}" \
		 -H "subscription-key: {subscription_key}" \
     -X GET \
     "https://edgeapi.marchex.io/marketingedge/v5/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",
                "redaction": false,
                "voice_link": "https://webservice.telmetrics.com/filedownload.ashx/DE6634BC-4C0D-47DD-BA02-AA76E235CB05/1977086405.mp3",
                "dispositions": {
                    "lead": {
                        "status": true
                    },
                    "voicemail": {
                        "status": false
                    },
                    "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.marchex.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",
            "rescue": {
        				"opportunity": "Negative",
        				"result": "Customer Say They Will Call Back",
        				"lastUpdate": "2020-08-26T16:43:15.737"
    				}
        }
    ],
    "paging": {
        "pageNumber": 1,
        "pageSize": 10000,
        "total": 4636
    }
}
{
    "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",
                "call_record_redaction": false,
                "voice_link": "https://webservice.telmetrics.com/filedownload.ashx/DE6634BC-4C0D-47DD-BA02-AA76E235CB05/1977086405.mp3",
            "transcript": " Agent: Local kitchen upgrades How can I help you Caller: Hi Yeah my name is Judy Smith and I am calling to talk about a kitchen upgrade that I would like to get an estimate on. Agent: Ok great how did you hear about it Caller: I actually found out on Google and clicked on it. Agent: oh Ok and what appealed to you out I'm just curious Caller: It was actually the pictures on your Web site I loved the minimalist approach to kitchen remodelling So that's why I chose you guys. Agent: Ok. Yep Ok super and what kind of space are we talking about how big is the room and what is in there currently Caller: Well it's a it's a full kitchen and the house was built in 1970 so it's a little bit boxed in. And it's more of a galley shape it's like a nano is 10 by 30. Agent: Ok All right so he will see you tomorrow I will text you his phone number if I could to the number that you just call from just so you have his contact information tomorrow he'll likely call you about half an hour before just to let you know he's on his way Caller: sure excellent Agent: Ok well thanks for calling and yeah we look forward to working with you take care thanks Judy I know. Caller: Well thank you so much yes. Likewise thank you bye bye. ",
                "dispositions": {
                    "lead": {
                        "status": true
                    },
                    "voicemail": {
                        "status": false
                    },
                    "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.marchex.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://edgeapi.marchex.io/marketingedge/v5/api/groups/{group_id}/calls

Sample request:
https://edgeapi.marchex.io/marketingedge/v5/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://edgeapi.marchex.io/marketingedge/v5/api/numbers/{number_id}/calls

Sample Request:
https://edgeapi.marchex.io/marketingedge/v5/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://edgeapi.marchex.io/marketingedge/v5/api/numberpools/{number_pool_id}/calls

Sample Request:
https://edgeapi.marchex.io/marketingedge/v5/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 (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 -> call_record_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 Campaign 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 Campaign 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 Campaign 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
rescue -> opportunityIdentifies the call as a Positive, Negative or Neutral rescue opportunity
rescue -> resultDescription of the call results giving details on the contents of the call
rescue -> lastUpdateTimestamp of the last update made to the rescue status of the call.