Call Detail Reporting API

Introduction

This is documentation for the v3 endpoint, if you are looking for the previous v2 version see here

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 lines for a particular campaign

Call Detail Report Endpoint

The Call Detail Report endpoint returns a paginated list of phone calls. The operation is invoked via HTTPS GET to:

api.citygrid.com/advertising/performance/v3/campaign/calldetail

Request Parameters

Parameter	Description	Required	Type	Default	Example
`campaignId`	The Campaign ID for lookup	Yes	Long	N/A	2605
`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	01-15-2018
`endDate`	End date (inclusive) for the report date range to query.	Yes if startDate is used.	Date (formatted as MM-DD-YYYY)	N/A	02-15-2018
startIndex	Page number of results to return (zero-based)	No	Integer	0	2
`numberResults`	Number of results per page	No	Integer	100	50

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
`Accept`	Requested format for the response	Yes	`application/json`
`authToken`	Authentication Token from the Call Detail Reporting API	Yes	Valid token

Request Examples

Example 1: Request the call details from the last 14 days for the campaign 2605

 curl -X GET \
  'https://api.citygrid.com/advertising/performance/v3/campaign/calldetail?campaignId=2605&period=last14Days' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'authToken: <authToken>'

Example 2: Request the call details for 01-15-2018 (inclusive) to 02-15-2018 (inclusive).

curl -X GET \
  'https://api.citygrid.com/advertising/performance/v3/campaign/calldetail?campaignId=2605&startDate=01-15-2018&endDate=02-15-2018' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'authToken: <authToken>'

Response Properties

Property	Type	Description
`totalNumEntries`	Integer	Total number of results
`callDetails`	List	Top-level element for results
placeId	Long	ID of the Place that received the call
`callId`	String	Unique ID for the call
`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
`duration`	Integer	The length of the call in seconds
`providerPhone`	String	The "ring to" phone number for the merchant
`displayPhone`	String	The CityGrid metered line
`callerPhone`	String	The caller's phone number
`audioUrl`	String	URL to access call recording if one is available
`callCompletionCode`	{Normal, Busy, Missed}	How the call was completed.
isBillable	{0, 1}	Whether or not the call is billable
`response`	Response Metadata	(See complete response descriptions)

Response Examples

JSON Success Response

{
    "totalNumEntries": "15",
    "callDetails": [
        {
            "placeId": "6179535",
            "callId": "BBA6A32302E545479D7431F38117008D",
            "startTime": "2018-02-28T06:16:47-08",
            "duration": "124",
            "providerPhone": "8884794220",
            "displayPhone": "8884050654",
            "callerPhone": "6103131000",
            "audioUrl": "",
            "callCompletionCode": "Normal",
            "isBillable": "0"
        },
        {
            "placeId": "6179535",
            "callId": "662AD90AEDFF4C29A5668D116483E25F",
            "startTime": "2018-02-28T06:19:06-08",
            "duration": "31",
            "providerPhone": "8884794220",
            "displayPhone": "8884050654",
            "callerPhone": "6103131000",
            "audioUrl": "",
            "callCompletionCode": "Normal",
            "isBillable": "0"
        },
        {
            "placeId": "6179535",
            "callId": "A0680D9205DC4A79827B52D11F25337A",
            "startTime": "2018-02-28T12:32:15-08",
            "duration": "163",
            "providerPhone": "8884794220",
            "displayPhone": "8884465673",
            "callerPhone": "9198521618",
            "audioUrl": "",
            "callCompletionCode": "Normal",
            "isBillable": "0"
        },
        {
            "placeId": "6179535",
            "callId": "65A012693FA647B5839F4FCEA24B8CC5",
            "startTime": "2018-03-01T09:51:39-08",
            "duration": "61",
            "providerPhone": "9198325463",
            "displayPhone": "8559735251",
            "callerPhone": "9198289945",
            "audioUrl": "",
            "callCompletionCode": "Normal",
            "isBillable": "0"
        },
        {
            "placeId": "6179535",
            "callId": "4F3E6056ACF34E16A777DE3789941E04",
            "startTime": "2018-03-02T04:00:35-08",
            "duration": "12",
            "providerPhone": "8884794220",
            "displayPhone": "8884465673",
            "callerPhone": "6629314557",
            "audioUrl": "",
            "callCompletionCode": "Normal",
            "isBillable": "0"
        }
    ],
    "response": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
    }
}

JSON Error Response

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

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