Call Detail Reporting API

Introduction

The CityGrid Call Detail Reporting API is part of the Advertising API suite and generates a list of phone calls tracked by the metered phone line for a particular place within an ad group. Report information is available in both JSON or CSV.

Call Detail Report Endpoint

The Call Detail Report endpoint returns a list of phone calls made through the metered phone line. The operation is invoked via HTTPS GET or POST to:

api.citygrid.com/advertising/performance/v2/adgroup/calldetail

Request Parameters

Parameter	Description	Required	Type	Default	Example
`adGroupId`	The AdGroup IDs for lookup, comma-separated.	Yes	Long	N/A	123 4352,8473,242
`period`	Date range for the report (case sensitive). Cannot be used with startDate and endDate.	No	yesterday last7Days last14Days last30Days lastWeek lastBusinessWeek thisMonth lastMonth billing1 billing2 billing3	yesterday	last7Days
`startDate`	Start date (inclusive) for the report date range to query.	Yes if endDate is used.	Date (formatted as MM-DD-YYYY)	N/A	11-17-2012
`endDate`	End date (inclusive) for the report date range to query.	Yes if startDate is used.	Date (formatted as MM-DD-YYYY)	N/A	11-17-2012

billing1 refers to the most recent billing cycle, billing2 to the billing cycle just before billing1, and billing3 to the billing cycle just preceding billing2.

Request Header Values

Header	Description	Required	Valid Values
`Content-Type`	Media type of the request body, if any	Only if POST	`application/json` `application/xml`
`Accept`	Requested format for the response	Yes	`application/json` `application/json` `application/csv`
`authToken`	Authentication Token from the Authentication API	Yes	Valid token
`developerToken`	The token received during registration	Yes	Valid token

Request Examples

Example 1: Request the call details from the last 14 days for the campaign listing designated by adGroupId 626642 (JSON format, HTTPS GET)

 
curl -X GET \ 
-H 'Accept:application/json' \ 
-H 'authToken:mytoken' \ 
'https://api.citygrid.com/advertising/performance/v2/adgroup/calldetail?adGroupId=626642&period=last14Days'

Example 2: Request the call details from the last billing cycle for ad groups, 1, 7987, and 98003 (CSV format, HTTPS POST)

 
curl -X POST \ 
-H 'Accept:application/csv' \ 
-H 'Content-Type:application/json' \ 
-H 'authToken:mytoken' \ 
-d '{"adGroupId":"1,626642,617502", "period":"billing3"}' \ 
'https://api.citygrid.com/advertising/performance/v2/adgroup/calldetail'

Example 3: Request the call details for 11-01-2012 (inclusive) to 11-15-2012 (inclusive).

 
curl -X GET \ 
-H 'Accept:application/json' \ 
-H 'authToken:mytoken' \ 
'https://api.citygrid.com/advertising/performance/v2/adgroup/calldetail?adGroupId=626642&startDate=11-01-2012&endDate=11-15-2012'

Response Properties

Property	Type	Description
`adGroupId`	Long	Ad Group ID
`audioUrl`	String	URL to access call recording if one is available
`callCompletionCode`	{Normal, Busy, Missed}	How the call was completed.
`callDetails`	List	Top-level element for results
`callId`	String	Unique ID for the call
`callerPhone`	String	The caller's phone number
`displayPhone`	String	The CityGrid metered line
`duration`	Integer	The length of the call in seconds
`providerPhone`	String	The "ring to" phone number for the merchant
`response`	Response Metadata	(See complete response descriptions)
`startTime`	String	The start date and time of the call in ISO 8601 format with the offset given in hours (no minutes and seconds). Examples: 2012-03-09T18:58:21-08 2012-03-12T11:12:55-07
`totalNumEntries`	Integer	Total number of results

Response Examples

JSON Success Response

{
  "totalNumEntries": "3",
  "callDetails": [
    {
      "adGroupId": "29674552",
      "callId": "8A40430580BB45408F3F3EA43F588EAC",
      "startTime": "2012-12-24T12:51:11-08",
      "duration": "34",
      "providerPhone": "3239541020",
      "displayPhone": "3236173630",
      "callerPhone": "3107488768",
      "audioUrl": "https:\/\/webservice.telmetrics.com\/filedownload.ashx\/68a-781d-4603-aeca-5434b7ab\/1505943738.mp3",
      "callCompletionCode": "Normal",
      "response": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      }
    },
    {
      "adGroupId": "29674552",
      "callId": "A4267F8244584B4DAB3C9D7C973ED92F",
      "startTime": "2012-12-29T08:21:51-08",
      "duration": "49",
      "providerPhone": "3239541020",
      "displayPhone": "3236173630",
      "callerPhone": "8184428282",
      "audioUrl": "https:\/\/webservice.telmetrics.com\/filedownload.ashx\/fec-2dc7-4e2f-a011-ef7ef34bd5c8\/1506444753.mp3",
      "callCompletionCode": "Normal",
      "response": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      }
    },
    {
      "adGroupId": "1",
      "callId": "",
      "startTime": "",
      "duration": "",
      "providerPhone": "",
      "callerPhone": "",
      "dislayPhone": "",
      "audioUrl": "",
      "callCompletionCode": "",
      "response": {
        "code": "DATA_NOT_FOUND",
        "message": "There is no data for This adGroupId.",
        "field": ""
      }
    }
  ],
  "response": {
    "code": "SUCCESS",
    "message": "Success",
    "field": ""
  }
}

CSV Success Response

 
adGroupId,callId,startTime,providerPhone,displayPhone,callerPhone,duration,audioUrl,code,message,callCompletionCode
29674552,8A40430580BB45408F3F3EA43F588EAC,2012-12-24T12:51:11-08,3239541020,3236173630,3107488768,34,https://webservice.telmetrics.com/filedownload.ashx/616a6a8a-781d-4603-aeca-51b72624b7ab/1505943738.mp3,SUCCESS,Success,Normal
29674552,A4267F8244584B4DAB3C9D7C973ED92F,2012-12-29T08:21:51-08,3239541020,3236173630,8184428282,49,https://webservice.telmetrics.com/filedownload.ashx/fe3f066c-2dc7-4e2f-a011-ef7eee3bd5c8/1506444753.mp3,SUCCESS,Success,Normal
9,,,,,,,,DATA_NOT_FOUND,There is no data for this adGroupId.,

JSON Error Response

A request for the following (note "Last14Dayz" instead of the required "last14Days")

 
{
  "totalNumEntries": "",
  "callDetails": [
    
  ],
  "response": {
    "code": "PARAMETER_INVALID",
    "message": "The parameter, period, was invalid. Valid options are billing1, billing2, billing3, last14Days, last30Days, last7Days, lastBusinessWeek, lastMonth, lastWeek, thisMonth, yesterday.",
    "field": "period"
  }
}

CSV Error Response