AdGroup API

Introduction

The CityGrid AdGroup API is part of the Advertising API suite and enables developers to manage ad groups within a campaign. An ad group contains a collection of ads for a particular place, together with category and geographical targeting information. The API allows you to get and set data about the group. To manipulate the ads and targeting information within an ad group, see the AdGroupAd API, the AdGroupCriterion API, and the AdGroupGeo API.

The AdGroup API provides two endpoints: adgroup/get and adgroup/mutate.

Contents

AdGroup Get Endpoint

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

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

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

Request Parameters

Parameter	Description	Required	Type	Default	Example
`adGroupIds`	Specified to retrieve ad groups by ID	Only if `campaignId` and `placeId` are both missing	Long list (Comma-delimited)	N/A	4556,45,3344
`externalPlaceId`	Specified to retrieve ad groups by place using the place's external ID	No	String	N/A	compexu3821
`placeId`	Specified to retrieve ad groups by place	Only if `campaignId` and `adGroupIds` are both missing	Long	N/A	442442
`campaignId`	Specified to retrieve ad groups in a campaign	Only if `placeId` and `adGroupIds` are both missing	Long	N/A	144534
`startIndex`	Page number of results to return (zero-based)	No	Integer	0	5
`numberResults`	Number of results per page	No	Integer	10	25

Request Header Values

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 you received at registration	Yes	Valid Token

Request Examples

Example 1: Request up to 3 ad groups for campaign 16631

curl -X GET \
    -H 'Accept:application/json' \
    -H 'authToken:mytoken' \
    -H 'developerToken:mydevtoken' \
    'https://api.citygrid.com/advertising/adgroup/v2/get?campaignId=16631&numberResults=3'

Example 2: Request ad groups 6, 11, and 155 in XML

curl -X GET \
    -H 'Accept:application/xml' \
    -H 'authToken:mytoken' \
    -H 'developerToken:mydevtoken' \
    'https://api.citygrid.com/advertising/adgroup/v2/get?adGroupIds=6,11,155'

Example 3: Request the default number of ad groups for external place aa-123

curl -X GET \
    -H 'Accept:application/json' \
    -H 'authToken:mytoken' \
    -H 'developerToken:mydevtoken' \
    'https://api.citygrid.com/advertising/adgroup/v2/get?campaignId=16631&externalPlaceId=aa-123'

Response Properties

Property	Type	Description
`response`	Response Metadata	(See complete response descriptions)
`totalNumEntries`	Integer	Number of ad groups returned
`adGroups`	AdGroup list	Container for multiple ad groups
`adGroup`	AdGroup	Details on a single ad group
`id`	Long	ID of the ad group
externalPlaceId	String	External ID of the place associated with the ad group
`placeId`	Long	ID of the place associated with the ad group
`campaignId`	Long	ID of the campaign that this ad group belongs to
`businessPhone`	String	Business ring-to number. This field is populated *only* when there is no metered phone line provisioned by CGM, but `displayPhone` and `businessPhone` information was previously supplied in the request.
`providerPhone`	String	The phone number that CGM provisioned a metered line for: either the existing metered line already provided by the advertising partner, or, if the advertising partner has not provisioned its own metered line, the business ring-to number. This field is populated *only* when a metered phone line is provisioned by CGM.
`displayPhone`	String	The displayPhone provided in the request or the metered line number if a line has been provisioned by CGM.
`meteredPhoneType`	{LOCAL, TOLLFREE}	Metered phone number type
`recordCalls`	{true, false}	Whether calls may be recorded.
`meteredLineStatus`	{0, 1, 2}	Status of the metered line: 0 = no or inactive metered line, 1 = has metered line, 2 = pending
`name <deprecated>`	String	Arbitrary name of the ad group
`status`	{Active, Inactive, Pending, Cancelled, Paused}	Status
`bids`	Bid list	List of bids
`ppe`	Double	PPE (Price per Event) of the action of the bid
`actionTargetName`	String	Action of the bid
`email`	String	Business email

Response Examples

Example 1: A JSON success response

{
  "totalNumEntries":1,
  "adGroups":[
    {
      "id":5482,
      "externalPlaceId":aa-123,
      "campaignId":1234,
      "businessPhone":"",
      "providerPhone":"(617)523-5959",
      "displayPhone":"(617)892-4337",
      "meteredPhoneType":"LOCAL",
      "recordCalls":"false",
      "meteredLineStatus":1,
      "email":"massiminosboston@gmail.com",
      "name":"",
      "status":"Active",
      "bids":[
        {
          "actionTargetName":"partner menu link",
          "ppe":0.55
        },
        {
          "actionTargetName":"partner reservation link",
          "ppe":0.55
        },
        {
          "actionTargetName":"send to phone (press send)",
          "ppe":0.55
        },
        {
          "actionTargetName":"customer menu link",
          "ppe":0.55
        },
        {
          "actionTargetName":"get directions",
          "ppe":0.55
        },
        {
          "actionTargetName":"featured sponsor ad views",
          "ppe":0.055
        },
        {
          "actionTargetName":"enhanced merchant profile",
          "ppe":0.55
        },
        {
          "actionTargetName":"virtual tour",
          "ppe":0.55
        },
        {
          "actionTargetName":"request quote",
          "ppe":0.55
        },
        {
          "actionTargetName":"profile api",
          "ppe":0.55
        }
      ],
      "response":{
        "field":"",
        "message":"Success",
        "code":"SUCCESS"
      },

    }
  ]
}

Example 2: An XML success response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<results>
  <totalNumEntries>1</totalNumEntries>
  <adgroups>
    <adGroup>
      <id>5482</id>
      <placeId>4726033</placeId>
      <campaignId>1234</campaignId>
      <businessPhone></businessPhone>
      <providerPhone>(617)523-5959</providerPhone>
      <displayPhone>(617)892-4337</displayPhone>
      <meteredPhoneType>LOCAL</meteredPhoneType>
      <recordCalls>false</recordCalls>
      <meteredLineStatus>1</meteredLineStatus>
      <email>massiminosboston@gmail.com</email>
      <name/>
      <status>Active</status>
      <bids>
        <bid>
          <actionTargetName>partner menu link</actionTargetName>
          <ppe>0.55</ppe>
        </bid>
        <bid>
          <actionTargetName>partner reservation link</actionTargetName>
          <ppe>0.55</ppe>
        </bid>
        <bid>
          <actionTargetName>print driving directions</actionTargetName>
          <ppe>0.55</ppe>
        </bid>
        <bid>
          <actionTargetName>map &amp; directions</actionTargetName>
          <ppe>0.55</ppe>
        </bid>
        <bid>
          <actionTargetName>consumer reviews views</actionTargetName>
          <ppe>0.55</ppe>
        </bid>
        <bid>
          <actionTargetName>recommend this business</actionTargetName>
          <ppe>0.55</ppe>
        </bid>
        <bid>
          <actionTargetName>save</actionTargetName>
          <ppe>0.55</ppe>
        </bid>
        <bid>
          <actionTargetName>print map</actionTargetName>
          <ppe>0.55</ppe>
        </bid>
        <bid>
          <actionTargetName>print offer</actionTargetName>
          <ppe>0.55</ppe>
        </bid>
        <bid>
          <actionTargetName>print profile</actionTargetName>
          <ppe>0.55</ppe>
        </bid>
        <bid>
          <actionTargetName>send to friend (email)</actionTargetName>
          <ppe>0.55</ppe>
        </bid>
        <bid>
          <actionTargetName>customer website link</actionTargetName>
          <ppe>0.55</ppe>
        </bid>
        <bid>
          <actionTargetName>email business form</actionTargetName>
          <ppe>0.55</ppe>
        </bid>
        <bid>
          <actionTargetName>trackable phone number</actionTargetName>
          <ppe>0.55</ppe>
        </bid>
      </bids>
      <response>
        <field/>
        <code>SUCCESS</code>
        <message>Success</message>
      </response>
    </adGroup>
  </adGroups>
</result>

Example 3: A response to a missing (misspelled) required parameter

A request with the parameter adGroupIds misspelled as ids will produce a result such as:

{
  "totalNumEntries":0,
  "adGroups":[
    {
      "id":"",
      "placeId":"",
      "campaignId":"",
      "businessPhone":"",
      "providerPhone":"",
      "displayPhone":"",
      "meteredPhoneType":"",
      "recordCalls":"",
      "meteredLineStatus":"",
      "email":"",
      "name":"",
      "status":"",
      "bids":[
      ],
      "response":{
        "field":"adGroupIds, campaignId or placeId",
        "message":"One of the parameters adGroupIds, campaignId or placeId is required",
        "code":"PARAMETER_REQUIRED"
      }
    }
  ]
}

Example 4: A response to a non-numeric ad group id

A request to api.citygrid.com/advertising/adgroup/v2/get?adGroupIds=234,4A produces a response such as:

<results>
  <totalNumEntries>0</totalNumEntries>
  <adGroups>
    <adGroup>
      <id></id>
      <placeId></placeId>
      <campaignId></campaignId>
      <businessPhone></businessPhone>
      <providerPhone></providerPhone>
      <displayPhone></displayPhone>
      <meteredPhoneType></meteredPhoneType>
      <recordCalls></recordCalls>
      <meteredLineStatus></meteredLineStatus>
      <email></email>
      <name></name>
      <status></status>
      <bids />
      <response>
        <code>PARAMETER_FORMAT</code>
        <field>adGroupIds</field>
        <message>The parameter adGroupIds is formatted incorrectly. Valid format is comma-delimited number list.</message>
      </response>
    </adGroup>
  </adGroups>
</results>

AdGroup Mutate Endpoint

The adgroup/mutateendpoint uses five operators to provide the following operations:

The ADD operator creates an ad group.
The SET operator updates ad group properties.
The PAUSE operator pauses an ad group
The UNPAUSE operator re-activates a paused ad group
The REMOVE operator cancels an ad group.

Please note that when the operation is REMOVE, the ad group is not physically removed from the system.

These operations are invoked via HTTPS POST to:

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

Request Parameters

Every adgroup/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`	Ad Group	The ad group to operate on	Yes

The properties of an ad group object in a request are:

Property	Description	Type	Required	Limit
`adGroupId`	The ID of the ad group	Long	If operator is SET or REMOVE	10 digits
`externalPlaceId`	External ID of the place	String	If operator is ADD	256 chars
`placeId`	ID of the Place	Long	If operator is ADD	10 digits
`campaignId`	ID of the campaign containing the ad group	Long	If operator is ADD	10 digits
`contractTermMonths`	The duration in months of the contract	Integer	No. 0 es a valid value for SET operator
`monthlyServiceFee`	The monthly fee associated with the ad group	Double	No. 0 is a valid value for SET operator
`bids`	Bid list	Bid	If operator is ADD	see below
`budget`	Budget object for this request	Budget	No- See details below	see below
businessPhone	The number to be displayed on place pages in the CityGrid network	String	No	see below
`displayPhone`	The number to be displayed on place pages in the CityGrid network	String	No	see below
`meteredPhoneType`	Metered phone number type	{LOCAL, TOLLFREE}	No
`recordCalls`	Whether call recording is set on the metered line	{0, 1}	No
`email`	The primary email for this business	String	No	60 chars
`assignMeteredLine`	How a metered line is provisioned. 0=Provision a metered line. 1=Do NOT provision a metered line.	{0, 1}	No. If not specified, a metered line will be provisioned (default = 0).

Bids

The properties of a bid object in an ad group in a request are:

Property	Description	Required	Type	Default	Example	Limit
ppe	The PPE (Price per Event) of the action of the bid	Yes	Double	N/A	1.30	7 digits for integer part, 4 decimals
actionTargetName	The action of the bid	Yes	String	N/A	listing_profile	40 chars

Advertisers should set up a bid amount for each of the following action targets:

consumer reviews views
customer website link
enhanced merchant profile
get directions
map & directions
partner menu link
partner reservation link
print map
print offer
print profile
send to friend (email)
send to phone (press send)
trackable phone number

For virtual places, the only available action target is:

customer website link

Budget

The AdGroup operand may or may not include a budget object. If you wish to set budget at the Campaign level do not include the budget object in your AdGroup API requests. You may create an AdGroup budget at the time the AdGroup is created (ADD operation) or you may add it later using the AdGroup SET operation. Once the budget is added at the AdGroup level, it cannot be configured at the Campaign level and vice versa. The 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	Max 7 digits for integer part, 4 decimals
period	Daily/ Monthly	Period over which to spend the budget	No	If this property is not supplied, the budget period is defaulted 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).

Entering an empty string into the businessPhone and displayPhone will remove the values from the ad group.

After removing businessPhone and displayPhone, the GET operation will return an empty string for meteredPhoneType and recordCalls, and 0 for meteredLineStatus. Furthermore, updates to meteredPhoneType and recordCalls will not be allowed unless businessPhone and displayPhone are added or are nonempty in the same request.

Removing only one of businessPhone or displayPhone field will produce an error with response code PARAMETER_ASSOCIATION_ACTION_NOT_PERFORMED.

If no businessPhone is present, the phone number associated with the place will be used as the business phone.

A budget provider customer can provision a line by specifying 0 in the assignMeteredLine field

Entering an empty string into the email field will remove the value from the ad group.

The following fields are considered non-removable, in that entering an empty string to any of these fields will produce an error with response code PARAMETER_INVALID:
- contractTermMonths
- monthlyServiceFee
- meteredPhoneType
- recordCalls
- assignMeteredLine

Entering an empty string into the bids field will produce an error with response code INVALID_REQUEST_BODY.
The following phone format are accepted:
- (312)456-7890
- 3214567890
- 312-456-7890
- +1 (215)456-7890

Entering an empty string into the ppe field will produce an error with response code PARAMETER_INVALID.
Entering an empty string into the budget.amount or budget.period results in a PARAMETER_INVALID error.

If the ad group's place is virtual, then adding or setting any of the following fields will produce an error with response code PARAMETER_NOT_SUPPORTED:
- businessPhone
- displayPhone
- meteredPhoneType
- recordCalls
- assignMeteredLine

When performing a SET operation:
- If no phone information is passed in the request, the line associated to the ad group (if any) remains untouched.
- If phone information is passed in the request, then:
  - For an ad group with no metered line associated: A new metered line is associated using the input parameters. The line is provisioned depending on the input parameters.
  - For an ad group with a line that has not been provisioned: The line is updated using both the input parameters and the data from the current line. If the businessPhone is not passed in, then the current ring-to number is used for the business phone. If the displayPhone is not passed in, then the current provisioned number used for the display phone.
  - For an ad group with a previously provisioned line:
    - If the current request is to not provision a line, then the current line is deleted, and a new line is associated to the ad group using the phone information from the request.
    - If the current request is to provision a line, then the current line is updated using the phone information from the request and the information from the current line. If the businessPhone parameter is not passed in, the place's phone number is used for the business phone. If the displayPhone parameter is not passed in, the current ring-to number is used for the display phone.

Request Header Values

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 the Authentication API	Yes	Valid token
`developerToken`	The token you received at registration	Yes	Valid Token

Request Examples

Example 1: Create a new ad group

{
  "mutateOperationListResource":[
    {
      "operator":"ADD",
      "operand":{
        "placeId":"123456",
        "externalPlaceId":"number123456",
        "campaignId":"1351",
        "contractTermMonths":"12",
        "monthlyServiceFee":"4000",
        "businessPhone":"(925)722-1234",
        "displayPhone":"(215)722-1759",
        "meteredPhoneType":"LOCAL",
        "recordCalls":"1",
        "assignMeteredLine":"1",
        "email":"valid.example@somewhere.com",
        "bids":[
          {
            "actionTargetName":"print profile",
            "ppe":"1.82"
          },
          {
            "actionTargetName":"customer menu link",
            "ppe":"0.42"
          },
          {
            "actionTargetName":"send to phone (press send)",
            "ppe":"0.12"
          }
        ]
      }
    }
  ]
}

Example 2: Update an ad group

{
  "mutateOperationListResource":[
    {
      "operator":"SET",
      "operand":{
        "adGroupId":"5482",
        "contractTermMonths":"12",
        "monthlyServiceFee":"4000",
        "businessPhone":"(925)722-1234",
        "displayPhone":"(215)722-1759",
        "meteredPhoneType":"LOCAL",
        "recordCalls":"1",
        "assignMeteredLine":"1",
        "email":"valid.example@somewhere.com",
        "bids":[
          {
            "actionTargetName":"print profile",
            "ppe":"1.82"
          },
          {
            "actionTargetName":"customer menu link",
            "ppe":"0.42"
          },
          {
            "actionTargetName":"send to phone (press send)",
            "ppe":"0.12"
          }
        ]
      }
    }
  ]
}

Response Properties

Property	Type	Description
`response`	Response Metadata	(See complete response descriptions)
`totalNumEntries`	Integer	Number of ad groups affected by mutate
`adGroups`	AdGroup list	ad group(s) affected by the mutate
`id`	Long	The id of the ad group
`placeId`	Long	The ID of the place this ad group is assigned to
`externalPlaceId`	String	External ID of the place this ad group is assigned to
`campaignId`	Long	The ID of the campaign this ad group is part of
`productId`	Long	The ID of the product associated to the ad group
`contractTermMonths`	Integer	The duration in months of the contract
`monthlyServiceFee`	Double	The monthly fee associated to the ad group in U.S. Dollars
`name`	String	The name of the ad group (currently blank)
`status`	{Active, Inactive, Pending, Cancelled, Paused}	The status of the ad group
`displayPhone`	String	same as request
`businessPhone`	String	same as request
providerPhone	String	The phone number that CGM provisioned a metered line for: either the existing metered line already provided by the advertising partner, or, if the advertising partner has not provisioned its own metered line, the business ring-to number. This field is populated *only* when a metered phone line is provisioned by CGM.
`recordCalls`	{0, 1}	same as request
`assignMeteredLine`	{0, 1}	same as request
`meteredLineType`	{LOCAL, TOLLFREE}	Metered line type, same as request
`meteredLineStatus`	{0, 1, 2}	metered line status 0=Inactive, 1=active, 2=pending
`email`	String	Business email
`bids`	Bid list	Bids applied to this ad group
`ppe`	Double	The PPE (Price per Event) of the action of the bid
`actionTargetName`	String	The action of the bid

Response Examples

Example 1: A JSON success response

{
  "adGroups":[
    {
      "id":"641",
      "placeId":"0",
      "campaignId":"1351",
      "productId":"125",
      "contractTermMonths":"12",
      "monthlyServiceFee":"0.0",
      "businessPhone":"(925)722-6839",
      "displayPhone":"",
      "meteredPhoneType":"LOCAL",
      "recordCalls":"false",
      "email":"valid.example@somewhere.com",
      "assignMeteredLine":"",
      "name":"",
      "status":"Active",
      "response":{
        "field":"",
        "message":"Success",
        "code":"SUCCESS"
      },
      "bids":[
        {
          "actionTargetName":"print profile",
          "ppe":"1.82"
        },
        {
          "actionTargetName":"customer menu link",
          "ppe":"0.42"
        },
        {
          "actionTargetName":"send to phone (press send)",
          "ppe":"0.12"
        }
      ]
    }
  ]
}

Example 2: An XML success response

<results>
  <adGroups>
    <adGroup>
      <id>645</id>
      <placeId>0</placeId>
      <campaignId>1351</campaignId>
      <productId>125</productId>
      <contractTermMonths>12</contractTermMonths>
      <monthlyServiceFee>0.0</monthlyServiceFee>
      <businessPhone>(925)722-6111</businessPhone>
      <displayPhone></displayPhone>
      <meteredPhoneType>LOCAL</meteredPhoneType>
      <recordCalls>false</recordCalls>
      <email>your.email@somedomain.com</email>
      <assignMeteredLine></assignMeteredLine>
      <bids>
        <bid>
          <actionTargetName>print profile</actionTargetName>
          <ppe>1.82</ppe>
        </bid>
        <bid>
          <actionTargetName>customer menu link</actionTargetName>
	  <ppe>0.42</ppe>
        </bid>
        <bid>
          <actionTargetName>send to phone (press send)</actionTargetName>
	  <ppe>0.12</ppe>
        </bid>
      </bids>
      <name></name>
      <status>Active</status>
      <response>
        <field/>
        <code>SUCCESS</code>
        <message>Success</message>
      </response>
    </adGroup>
  </adGroups>
</results>

Example 3: An XML error response (change request still pending)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<results>
  <adGroups>
    <adGroup>
      <id/>
      <placeId>123456</placeId>
      <campaignId>1351</campaignId>
      <productId/>
      <contractTermMonths>12</contractTermMonths>
      <monthlyServiceFee>4000</monthlyServiceFee>
      <businessPhone>(925)722-1234</businessPhone>
      <displayPhone>(215)722-1759</displayPhone>
      <meteredPhoneType>LOCAL</meteredPhoneType>
      <recordCalls>false</recordCalls>
      <email>valid.example@somewhere.com</email>
      <assignMeteredLine>1</assignMeteredLine>
      <bids>
        <bid>
          <actionTargetName>print profile</actionTargetName>
          <ppe>1.82</ppe>
        </bid>
        <bid>
          <actionTargetName>customer menu link</actionTargetName>
          <ppe>0.42</ppe>
        </bid>
        <bid>
          <actionTargetName>send to phone (press send)</actionTargetName>
          <ppe>0.12</ppe>
        </bid>
      </bids>
      <name/>
      <status/>
      <response>
        <field/>
        <code>ENTITY_STATE_INVALID</code>
        <message>The request could not be processed because a change request is still in pending.</message>
      </response>
    </adGroup>
  </adGroups>
</results>

Example 4: A JSON error response (change request still pending)

{
  "adGroups":[
    {
      "id":"",
      "placeId":"123456",
      "campaignId":"1351",
      "productId":"",
      "contractTermMonths":"12",
      "monthlyServiceFee":"",
      "businessPhone":"",
      "displayPhone":"(215)722-1759",
      "meteredPhoneType":"local",
      "recordCalls":"",
      "email":"valid.example@somewhere.com",
      "assignMeteredLine":"",
      "bids":[
        {
          "actionTargetName":"print profile",
          "ppe":"1.82"
        },
        {
          "actionTargetName":"customer menu link",
          "ppe":"0.42"
        },
        {
          "actionTargetName":"send to phone (press send)",
          "ppe":"0.12"
        }
      ],
      "name":"",
      "status":"",
      "response":{
        "field":"",
        "message":"The request could not be processed because a change request is still in pending.",
        "code":"ENTITY_STATE_INVALID"
      }
    }
  ]
}

Example 6: A JSON error response after trying to remove only the `displayPhone` field

{
  "adGroups":[
    {
      "id":"8482992",
      "placeId":"",
      "campaignId":"",
      "productId":"",
      "contractTermMonths":"",
      "monthlyServiceFee":"",
      "displayPhone":"",
      "businessPhone":"(215)722-1759",
      "meteredPhoneType":"",
      "recordCalls":"",
      "email":"",
      "assignMeteredLine":"1",
      "bids":[
      ],
      "name":"",
      "status":"",
      "responseStatus":{
        "code":"PARAMETER_ASSOCIATION_ACTION_NOT_PERFORMED",
        "message":"The parameter business phone has an association with display phone. All associated fields need to be updated/deleted also.",
        "field":"business phone"
      }
    }
  ]
}

PAUSE and UNPAUSE Operations

The PAUSE and UNPAUSE operations allow a user to pause Ad/Budget distribution for a specific AdGroup 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 ad group (i.e. cannot pause campaigns that are PENDING, CANCELED, etc) and can only UNPAUSE a PAUSED ad group.

Note that when an ad group is set to PAUSE or UNPAUSE, the status will take affect immediately.

Example 7: A JSON PAUSE Request

{"mutateOperationListResource": 
[{
      "operator": "PAUSE","operand": 
       {"adGroupId":"8167"}
}]}

Example 8: A JSON PAUSE response

{
  "adGroups": [
    {
      "id": "8167",
      "placeId": "40862360",
      "externalPlaceId": "40862360",
      "campaignId": "900",
      "productId": "6",
      "contractTermMonths": "0",
      "monthlyServiceFee": "9.95",
      "businessPhone": "",
      "providerPhone": "",
      "displayPhone": "",
      "meteredPhoneType": "",
      "recordCalls": "",
      "email": "",
      "assignMeteredLine": "",
      "meteredLineStatus": "",
      "bids": [
        {
          "actionTargetName": "enhanced merchant profile",
          "ppe": "1.75"
        }
      ],
      "name": "",
      "period": "",
      "budgetAmount": "",
      "status": "Paused",
      "cancelDate": "",
      "responseStatus": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      }
    }
  ]
}

Example 9: A JSON UNPAUSE Request

{"mutateOperationListResource": 
[{
      "operator": "UNPAUSE","operand": 
       {"adGroupId":"8167"}
}]}

Example 10: A JSON UNPAUSE Response

{
  "adGroups": [
    {
      "id": "8167",
      "placeId": "40862360",
      "externalPlaceId": "40862360",
      "campaignId": "900",
      "productId": "6",
      "contractTermMonths": "0",
      "monthlyServiceFee": "9.95",
      "businessPhone": "",
      "providerPhone": "",
      "displayPhone": "",
      "meteredPhoneType": "",
      "recordCalls": "",
      "email": "",
      "assignMeteredLine": "",
      "meteredLineStatus": "",
      "bids": [
        {
          "actionTargetName": "enhanced merchant profile",
          "ppe": "1.75"
        }
      ],
      "name": "",
      "period": "",
      "budgetAmount": "",
      "status": "Active",
      "cancelDate": "",
      "responseStatus": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      }
    }
  ]
}

AdGroup API

Introduction

AdGroup Get Endpoint

Request Parameters

Request Header Values

Request Examples

Example 1: Request up to 3 ad groups for campaign 16631

Example 2: Request ad groups 6, 11, and 155 in XML

Example 3: Request the default number of ad groups for external place aa-123

Response Properties

Response Examples

Example 1: A JSON success response

Example 2: An XML success response

Example 3: A response to a missing (misspelled) required parameter

Example 4: A response to a non-numeric ad group id

AdGroup Mutate Endpoint

Request Parameters

Budget

Request Header Values

Request Examples

Example 1: Create a new ad group

Example 2: Update an ad group

Response Properties

Response Examples

Example 1: A JSON success response

Example 2: An XML success response

Example 3: An XML error response (change request still pending)

Example 4: A JSON error response (change request still pending)

Example 6: A JSON error response after trying to remove only the displayPhone field

PAUSE and UNPAUSE Operations

Example 7: A JSON PAUSE Request

Example 8: A JSON PAUSE response

Example 9: A JSON UNPAUSE Request

Example 10: A JSON UNPAUSE Response

Example 6: A JSON error response after trying to remove only the `displayPhone` field