Campaign API

Introduction

The CityGrid Campaign API is part of the Advertising API suite and enables developers to write applications to manage campaigns. A campaign holds one or more ad groups together with a budget and serving date range. The API provides two endpoints: campaign/get and campaign/mutate.

Campaign Get Endpoint

The campaign/get endpoint retrieves information about one or more selected campaigns. The operation is invoked via HTTPS GET to:

api.citygrid.com/advertising/campaign/v2/get

Request Parameters

Parameter	Description	Required	Type	Default	Example
`campaignId`	Comma-separated list of campaign IDs. If specified, other filter parameters will be ignored.	No	Long	—	1,2,3,4,5
`externalId`	Comma-separated list of external IDs of the campaign. If specified without `campaignId`, other filter parameters will be ignored.	No	Long	—	6,7,8,9,10
`campaignStatus`	Case-sensitive list of statuses for filtering	No	{ACTIVE, CANCELLED, PENDING, SUSPENDED}	—	ACTIVE
`startDate`	Restricts campaigns to those starting on or after this date. This date refers to the date the creator of the campaign indicated that the campaign should start, not necessarily the date the campaign actually started.	No	String	—	20100131
`endDate`	Restricts campaigns to those ending on or before this date. If the field is omitted, campaigns for all end dates are returned.	No	String	—	20100131
`ordering`	Field(s) to sort by	No	{name, date}	—	name
`sortAsc`	Used with `ordering` to determine ascending or descending sort	No	{true, false}	—	false
`startIndex`	Page number of results to return (zero-based)	No	Integer	0	5
`numberResults`	Number of results per page	No	Integer	10	25

If campaignId appears, then all other parameters will be ignored.

If externalId appears and campaignId does not appear, then all other parameters will be ignored.

Request Headers

Header	Description	Required	Valid Values
`Accept`	Requested format for the response	Yes	`application/json` `application/xml`
`authToken`	Authentication Token from the Authentication API	Yes	Valid token
`developerToken`	The token received during registration	Yes	Valid token

Request Examples

Example 1: Get campaigns 1, 54, 766, and 5678

curl -X GET \
    -H 'Accept:application/json' \
    -H 'authToken:mytoken' \
    -H 'developerToken:myDevToken' \
    'https://api.citygrid.com/advertising/campaign/v2/get?campaignId=1,54,766,5678'

Example 2: Get all campaigns in a date range for the current user's account, 8 campaigns per page, ordered ascending by name

curl -X GET \
    -H 'Accept:application/json' \
    -H 'authToken:mytoken' \
    -H 'developerToken:myDevToken' \
    'https://api.citygrid.com/advertising/campaign/v2/get?startDate=20100324&endDate=20110720&ordering=name&sortAsc=true&numberResults=8'

Example 3: Get campaigns with external ids 1 and 2

curl -X GET \
    -H 'Accept:application/json' \
    -H 'authToken:mytoken' \
    -H 'developerToken:myDevToken' \
    'https://api.citygrid.com/advertising/campaign/v2/get?externalId=1,2'

Example 4: Get all active campaigns for the current user's account

curl -X GET \
    -H 'Accept:application/json' \
    -H 'authToken:mytoken' \
    -H 'developerToken:myDevToken' \
    'https://api.citygrid.com/advertising/campaign/v2/get?campaignStatus=ACTIVE'

Response Properties

Property	Type	Description
`response`	Response Metadata	(See complete response descriptions)
`totalNumEntries`	Integer	Total number of campaigns in the response
`totalBudget`	Double	Total monthly budget for the campaigns listed
`totalDailyBudget`	Double	Total daily budget for the campaigns listed
`campaigns`	Campaign List	The campaigns returned from the search
`id`	String	The campaign ID
`name`	String	Arbitrary campaign name, not shown in the ads
`servingStatus`	{ACTIVE, CANCELLED, PENDING, SUSPENDED}	Status of the campaign in the system
`startDate`	Datestring	Date that the creator of the campaign indicated the campaign should begin, YYYYMMDD format
`endDate`	Datestring	Date that the campaign ends if any, YYYYMMDD format
cancelDate	Datestring	Date when campaign should no longer be in distribution. cancelDate is set to following day in YYYYMMDD format when REMOVE operation is called. It is empty when it is not on cancelled or pending cancellation state
`budgetAmount`	Double	Current budget for campaign, in U.S. Dollars
`period`	{DAILY, MONTHLY}	Period over which to spend the budget
`externalId`	Long	External ID of the campaign
affiliateId	Integer	Affiliate ID of the campaign

Response Examples

Example 1: A XML success response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<results>
  <totalNumEntries>4</totalNumEntries>
  <totalBudget>30</totalBudget>
  <totalDailyBudget>94</totalDailyBudget>
  <campaigns>
    <campaign>
      <affiliateId></affiliateId>
	  <budgetAmount>90</budgetAmount>
      <endDate>20170520</endDate>
      <cancelDate></cancelDate>
      <externalId/>
      <id>3167472</id>
      <name>myFallCampaign</name>
      <period>DAILY</period>
      <response>
        <code>SUCCESS</code>
        <field/>
        <message>Success</message>
      </response>
      <servingStatus>PENDING</servingStatus>
      <startDate>20120920</startDate>
    </campaign>
    <campaign>
      <affiliateId>8</affiliateId>
      <budgetAmount>20</budgetAmount>
      <endDate>20170520</endDate>
      <cancelDate></cancelDate>
      <externalId/>
      <id>3167502</id>
      <name>myFallCampaign</name>
      <period>MONTHLY</period>
      <response>
        <code>SUCCESS</code>
        <field/>
        <message>Success</message>
      </response>
      <servingStatus>PENDING</servingStatus>
      <startDate>20120920</startDate>
    </campaign>
    <campaign>
      <affiliateId></affiliateId>
      <budgetAmount>10</budgetAmount>
      <endDate>20170520</endDate>
      <cancelDate></cancelDate>
      <externalId/>
      <id>3167492</id>
      <name>myFallCampaign</name>
      <period>MONTHLY</period>
      <response>
        <code>SUCCESS</code>
        <field/>
        <message>Success</message>
      </response>
      <servingStatus>PENDING</servingStatus>
      <startDate>20120920</startDate>
    </campaign>
    <campaign>
      <affiliateId></affiliateId>
      <budgetAmount>4</budgetAmount>
      <endDate>20170520</endDate>
      <cancelDate></cancelDate>
      <externalId/>
      <id>3167482</id>
      <name>myFallCampaign</name>
      <period>DAILY</period>
      <response>
        <code>SUCCESS</code>
        <field/>
        <message>Success</message>
      </response>
      <servingStatus>PENDING</servingStatus>
      <startDate>20120920</startDate>
    </campaign>
  </campaigns>
</results>

Example 2: A JSON success response

{
    "totalNumEntries": 4,
    "totalBudget": 30,
    "totalDailyBudget": 94,
    "campaigns": [
        {
            "response": {
                "code": "SUCCESS",
                "message": "Success",
                "field": ""
            },
            "id": "3167472",
            "externalId": "",
            "startDate": "20120920",
            "endDate": "20170520",
            "cancelDate": "",
            "name": "myFallCampaign",
            "servingStatus": "PENDING",
            "period": "DAILY",
            "budgetAmount": "90"
            "affiliateId": ""
        },
        {
            "response": {
                "code": "SUCCESS",
                "message": "Success",
                "field": ""
            },
            "id": "3167502",
            "externalId": "",
            "startDate": "20120920",
            "endDate": "20170520",
            "cancelDate": "",
            "name": "myFallCampaign",
            "servingStatus": "PENDING",
            "period": "MONTHLY",
            "budgetAmount": "20"
            "affiliateId": "8"
        },
        {
            "response": {
                "code": "SUCCESS",
                "message": "Success",
                "field": ""
            },
            "id": "3167492",
            "externalId": "",
            "startDate": "20120920",
            "endDate": "20170520",
            "cancelDate": "",
            "name": "myFallCampaign",
            "servingStatus": "PENDING",
            "period": "MONTHLY",
            "budgetAmount": "10"
            "affiliateId": ""
        },
        {
            "response": {
                "code": "SUCCESS",
                "message": "Success",
                "field": ""
            },
            "id": "3167482",
            "externalId": "",
            "startDate": "20120920",
            "endDate": "20170520",
            "cancelDate": "20130119",
            "name": "myFallCampaign",
            "servingStatus": "PENDING",
            "period": "DAILY",
            "budgetAmount": "4"
            "affiliateId": ""
        }
    ]
}

Campaign Mutate Endpoint

The campaign/mutate endpoint uses five operators to provide the following operations on campaigns:

The ADD operator creates a campaign.
The SET operator updates campaign properties.
The PAUSE operator pauses a campaign
The UNPAUSE operator re-activates a campaign
The REMOVE operator cancels a campaign.

These operations are invoked via HTTPS POST to:

api.citygrid.com/advertising/campaign/v2/mutate

Input data such as request parameters are subject to field size limits.

Request Parameters

Every campaign mutate request requires the following two parameters:

Property	Type	Description	Required
`operator`	{ADD, REMOVE, SET, PAUSE, UNPAUSE}	Type of operation to perform (case sensitive). See the section below for information regarding the PAUSE and UNPAUSE operations	Yes
`operand`	Campaign	The campaign to operate on	Yes

The properties of a Campaign request operand are:

Property	Type	Description	Required	Limits
`name`	String	Name of the campaign	If operator is ADD	100 chars
`id`	Long	ID of the campaign	If operator is SET, REMOVE, PAUSE or UNPAUSE (unless `externalId` is set)	10 digits
`externalId`	Long	External ID of the campaign	If operator is SET, REMOVE, PAUSE or UNPAUSE (unless `id` is set)	10 digits
`servingStatus`	String	Status of the campaign	No	9 chars
`budget`	Budget	Budget object for this request	No- See details below	11 digits total, 4 decimals
`product`	String	Type of the product of the campaign, default is PERFORMANCE	No
affiliateId	Integer	The ID of the affiliate of the campaign. For SET if affiliateId is an empty string the current value will be removed.	No	4 digits
startDate	Datestring	Indicates when the campaign should start, In YYYYMMDD format. This date refers to the date that the creator of the campaign indicated that the campaign should start, not necessarily the date the campaign actually started. For the ADD and SET operations, this date cannot be before the current date. For the SET operation, this date cannot be before the creation date of the campaign.	No (default is current date)
`endDate`	Datestring	Indicates when the campaign should end, in YYYYMMDD format	No (default is to run indefinitely)	1000 chars
`reason`	String	The reason for the cancellation	If operator is REMOVE
`statusReason`	Integer	The ID of the status reason associated with campaign deactivation	No

Budget

The Campaign operand may or may not include a budget object. If you wish to set budget at the AdGroup level do not include the budget object in your Campaign API requests. You may create a campaign budget at the time the campaign is created (ADD operation) or you may add it later using the campaign SET operation. Once the budget is added at the Campaign level, it cannot be configured at the AdGroup level and vice versa. properties of a budget object in a request are as follows:

Property	Type	Description	Required	Notes
`amount`	Double	Amount of budget in U.S. Dollars	Yes
`period`	{Daily, Monthly}	Period over which to spend the budget	No	If this property is not supplied, the budget period defaults to monthly

Notes

A campaign will not become active until budget is added either at the Campaign level or the AdGroup level (the AdGroup API is used to configure budget at the AdGroup level).

Once an external ID is used to create campaign, that external ID cannot be reassigned to another campaign.

The campaignId and externalId properties cannot be submitted together for a mutate operation.

The period can not switched from monthly to daily or from daily to monthly once it is set.

Request Headers

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

Request Examples

Example 1: Create a campaign with a $3000 budget ending on 2017-05-20

{
  "mutateOperationListResource":[
    {
      "operator":"ADD",
      "operand":{
        "mopId":"202602",
        "name":"myFallCampaign",
        "endDate":"20170520",
        "product":"PERFORMANCE",
        "affiliateId":"11",
        "budget":{
          "amount":"100.0",
          "period":"Monthly"
        }
      }
    }
  ]
}

Example 2: Update campaigns 3168332 and remove campaign 3981

{
  "mutateOperationListResource":[
    {
      "operator":"SET",
      "operand":{
        "id":"3168332",
        "budget":{
          "period":"MONTHLY",
          "amount":"50.0"
        }
      }
    },
    {
      "operator":"REMOVE",
      "operand":{
        "id":"3981",
        "reason":"The campaign period expired"
      }
    }
  ]
}

Example 3: Update campaign 3168332, remove campaign 3981 (XML)

<mutateOperationListResource>
  <mutateOperation>
    <operator>SET</operator>
    <operand>
      <id>3168332</id>
      <budget>
        <period>MONTHLY</period>
        <amount>50.0</amount>
      </budget>
    </operand>
  </mutateOperation>
  <mutateOperation>
    <operator>REMOVE</operator>
    <operand>
      <id>3981</id>
      <reason>The campaign period expired</reason>
    </operand>
  </mutateOperation>
</mutateOperationListResource>

Response Properties

Property	Type	Description
`response`	Response Metadata	(See complete response descriptions)
`campaigns`	Campaign list	List of campaigns
`id`	Long	The Campaign ID
`externalId`	Long	External ID of the campaign
`name`	String	The Campaign name
`servingStatus`	{ACTIVE, CANCELLED, PENDING, SUSPENDED}	Status of the campaign
`startDate`	Datestring	Date that the creator of the campaign indicated the campaign should begin, YYYYMMDD format
`endDate`	Datestring	Date when the campaign ends, if any, YYYYMMDD format
cancelDate	Datestring	cancelDate will be set to following day in YYYYMMDD format when REMOVE operation is called. Remain empty otherwise.
`budgetAmount`	Double	Current budget amount in U.S. Dollars
`period`	{DAILY, MONTHLY}	Period over which to spend the budget
affiliateId	Integer	The affiliate ID of the campaign

Response Examples

Example 1: An XML success response

<results>
  <campaigns>
    <campaign>
      <budgetAmount>100</budgetAmount>
      <endDate>20170520</endDate>
      <cancelDate></cancelDate>
      <externalId />
      <id>3173712</id>
      <name>myFallCampaign</name>
      <period>MONTHLY</period>
      <response>
        <code>SUCCESS</code>
        <field />
        <message>Success</message>
      </response>
      <servingStatus>PENDING</servingStatus>
      <startDate>20120924</startDate>
      <affiliateId>11</affiliateId>
    </campaign>
  </campaigns>
</results>

Example 2: A JSON success response to an ADD request

{
  "campaigns": [
    {
      "response": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      },
      "id": "3173702",
      "externalId": "",
      "startDate": "20120924",
      "endDate": "20170520",
      "cancelDate":"",
      "name": "myFallCampaign",
      "servingStatus": "PENDING",
      "period": "MONTHLY",
      "budgetAmount": "100",
      "affiliateId": ""
    }
  ]
}

Example 3: A JSON success response to a SET request

{
  "campaigns": [
    {
      "response": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      },
      "id": "3174222",
      "externalId": "",
      "startDate": "20170630",
      "cancelDate":"",
      "endDate": "",
      "name": "discover NewZealand",
      "servingStatus": "PENDING",
      "period": "MONTHLY",
      "budgetAmount": "100",
      "affiliateId": "7"
    }
  ]
}

Example 4: A JSON success response to a REMOVE request

{
  "campaigns": [
    {
      "response": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      },
      "id": "3174242",
      "externalId": "",
      "startDate": "20170630",
      "endDate": "",
      "cancelDate":"20130209",
      "name": "discover NewZealand",
      "servingStatus": "PENDING",
      "period": "DAILY",
      "budgetAmount": "100",
      "affiliateId": ""
    }
  ]
}

Example 5: A JSON response for a duplicate ADD request

{
  "campaigns": [
    {
      "response": {
        "code": "ASSOCIATION_EXISTS",
        "message": "The campaign and external id association already exists.",
        "field": ""
      },
      "id": "",
      "externalId": "",
      "startDate": "",
      "endDate": "",
      "cancelDate":"",
      "name": "",
      "servingStatus": "",
      "period": "",
      "budgetAmount": "",
      "affiliateId": ""
    }
  ]
}

Example 6: A JSON response for a date change request on an active campaign

{
  "campaigns":[
    {
      "name":"",
      "id":3111,
      "response":{
        "field":"",
        "message":"The start date cannot be modified because the campaign is in an active state",
        "code":"ENTITY_NOT_MODIFIED"
      },
      "externalId":"",
      "endDate":"",
      "cancelDate":"",
      "startDate":"",
      "servingStatus":"",
      "budgetAmount":"",
      "period":"",
      "affiliateId": ""
    }
  ]
}

Example 7: A JSON response for a request to move the end date before the start date

{
  "campaigns":[
    {
      "name":"",
      "id":3531,
      "response":{
      "field":"",
        "message":"The end date cannot be before the start date",
        "code":"DATE_BEFORE_DATE"
      },
      "externalId":"",
      "endDate":"",
      "startDate":"",
      "cancelDate":"",
      "servingStatus":"",
      "budgetAmount":"",
      "period":"",
      "affiliateId": ""
    }
  ]
}

PAUSE and UNPAUSE Operations

The PAUSE and UNPAUSE operations allow a user to pause Ad/Budget distribution for all AdGroups within a campaign and subsequently reactivate (unpause) the Ads/Budget at a later time. When the PAUSE or UNPAUSE operations are indicated all other request parameters will be ignored as the only function of these operations is to change the campaign's servingStatus between ACTIVE and PAUSED. Note that the user can only PAUSE an ACTIVE campaign (i.e. cannot pause campaigns that are PENDING, CANCELED, etc) and can only UNPAUSE a PAUSED campaign.

Note that when a campaign is set to PAUSE or UNPAUSE, the status will take affect immediately.

Example 8: A JSON PAUSE Request

Example PAUSE Operation

{"mutateOperationListResource" :
[{
     "operator": "PAUSE",
     "operand": {"id":"2354642"}
}]}

Example 9: A JSON PAUSE Response

{
  "campaigns": [
    {
      "response": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      },
      "id": "2354642",
      "externalId": "",
      "startDate": "20130130",
      "endDate": "",
      "cancelDate": "",
      "name": "Tesco Campaign",
      "servingStatus": "PAUSED",
      "period": "MONTHLY",
      "budgetAmount": "123.45"
    }
  ]
}

Example 9: A JSON UNPAUSE Request

{"mutateOperationListResource" :
[{
    "operator": "UNPAUSE",
    "operand": {"id":"2354642"}
}]}

Example 10: A JSON UNPAUSE Response

{
  "campaigns": [
    {
      "response": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      },
      "id": "2354642",
      "externalId": "",
      "startDate": "20130130",
      "endDate": "",
      "cancelDate": "",
      "name": "Tesco Campaign",
      "servingStatus": "ACTIVE",
      "period": "MONTHLY",
      "budgetAmount": "123.45"
    }
  ]
}

Advertiser APIs V2

Campaign API

Introduction

Contents

Campaign Get Endpoint

Request Parameters

Request Headers

Request Examples

Example 1: Get campaigns 1, 54, 766, and 5678

Example 2: Get all campaigns in a date range for the current user's account, 8 campaigns per page, ordered ascending by name

Example 3: Get campaigns with external ids 1 and 2

Example 4: Get all active campaigns for the current user's account

Response Properties

Response Examples

Example 1: A XML success response

Example 2: A JSON success response

Campaign Mutate Endpoint

Request Parameters

Budget

Notes

Request Headers

Request Examples

Example 1: Create a campaign with a $3000 budget ending on 2017-05-20

Example 2: Update campaigns 3168332 and remove campaign 3981

Example 3: Update campaign 3168332, remove campaign 3981 (XML)

Response Properties

Response Examples

Example 1: An XML success response

Example 2: A JSON success response to an ADD request

Example 3: A JSON success response to a SET request

Example 4: A JSON success response to a REMOVE request

Example 5: A JSON response for a duplicate ADD request

Example 6: A JSON response for a date change request on an active campaign

Example 7: A JSON response for a request to move the end date before the start date

PAUSE and UNPAUSE Operations

Example 8: A JSON PAUSE Request

Example 9: A JSON PAUSE Response

Example 9: A JSON UNPAUSE Request

Example 10: A JSON UNPAUSE Response