/
Call Detail Reporting API v2

CityGrid Advertising APIs

Call Detail Reporting API v2

Introduction

You are not looking at the most recent version of the Call Detail Reporting API, see here for the updated version

 

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.

Contents

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:

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 Call Detail Reporting API v2

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
Error rendering macro 'code': Invalid value specified for parameter 'lang'
 
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

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

 
api.citygrid.com/advertising/performance/v2/places/daily?placeId=1234&period=Last14Dayz 
code,message,field 
PARAMETER_INVALID,The parameter, period, was invalid. Valid options are billing1, billing2, billing3, last14Days, last30Days, last7Days, lastBusinessWeek, lastMonth, lastWeek, thisMonth, yesterday.,period 

Related content