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:
| Parameter | Description |
|---|---|
| startdateutc=2001-01-01T00:00 | Filter 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:00 | Filter 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=1000 | How many records to return in the result set. For additional information on paging result sets, please reference our documentation on Paging. |
| pageNumber=1 | Will return the corresponding page from the result set. For additional information on paging result sets, please reference our documentation on Paging. |
| includeTranscription=true | Will 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
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
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
Field Definitions
The following fields may be returned by a requests to retrieve calls
| Field | Description |
|---|---|
| id | Unique ID of the phone call |
| number_id | Tracking number the call is associated with |
| group_id | Group the call is associated with |
| caller_identity | Unique identity value for the caller |
| organization_id | global organization identifier of the call |
| answer_status | Answer status of the phone call. Possible values: - Answered - Busy - Missed - Pending (Other answer statuses such as StopCall) |
| ring_duration | Duration in seconds for how long a phonecall was ringing before being answered |
| call_duration | Duration in seconds of how long the phone calls lasted |
| registered_DNC | Flag indicating if the caller is on the Do Not Call list |
| tracking_number | Tracking Number that was called |
| caller_number | Phone Number of the caller |
| termination_number | Phone Number that the call was forwarded |
| caller_details -> caller_type | Defines the type of phone number the call came from. Possible values: residential, business, cellular |
| caller_details -> name | Name of the caller |
| caller_details -> address | Street address of the caller |
| caller_details -> city | City of the caller |
| caller_details -> state | State/Province of the caller |
| caller_details -> zip_code | ZIP Code/Postal Code of the caller |
| caller_details -> country | Two letter country code of the caller |
| caller_details -> lattitude | Latitude of the caller as defined by their Area Code (NPA) and Exchange (NXX) |
| caller_details -> longitude | Longitude of the caller as defined by their Area Code (NPA) and Exchange (NXX) |
| attribution_details -> session_id | Unique session id created when a website visitor arrives at a page with DNI |
| attribution_details -> utm_campaign | utm_campaign parameter captured when a user arrives at a site where DNI occurs |
| attribution_details -> utm_term | utm_term parameter captured when a user arrives at a site where DNI occurs |
| attribution_details -> utm_source | utm_source parameter captured when a user arrives at a site where DNI occurs |
| attribution_details -> utm_medium | utm_medium parameter captured when a user arrives at a site where DNI occurs |
| attribution_details -> utm_content | utm_content parameter captured when a user arrives at a site where DNI occurs |
| attribution_details -> landing_page_url | URL of the landing page that a website user arrives on |
| attribution_details -> referrer_url | URL of the referrer responsible for bringing a user to a webpage with DNI enabled |
| attribution_details -> multisession_flag | a 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_file | Unique of the Call Recording file |
| conversation_analytics -> call_record_redaction | True/False flag if redaction was performed on the call recording |
| conversation_analytics -> voice_link | URL to the call recording |
| conversation_analytics -> dispostions | An array of call scoring dispositions that were applied to the call |
| conversation_analytics -> dispostions -> {disposition_name} -> status | True/False flag indicating whether the call was scored to match the disposition |
| conversation_analytics -> dispostions -> {disposition_name} -> confidence_score | A confidence score reflecting how certain the machine learning algorithm is that the disposition is correct |
| routing_keypress | If Key Press routing was enabled for the number, this field will contain the value entered by the consumer |
| start_time | Time 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_time | Time 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_time | Time 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_utc | Time the call was initiated in UTC |
| answer_time_utc | Time the call was answered in UTC |
| end_time_utc | Time the call ended in UTC |
| status | Current status of the call. Possible values: Processing, Complete |
| rescue -> opportunity | Identifies the call as a Positive, Negative or Neutral rescue opportunity |
| rescue -> result | Description of the call results giving details on the contents of the call |
| rescue -> lastUpdate | Timestamp of the last update made to the rescue status of the call. |
Updated over 1 year ago