List Ad Groups
URL: POST/api/v1/adGroups/list
Request Parameters
| Parameter | Parameter Description | Type | Required | Possible Values |
|---|---|---|---|---|
| advertiserId | ID of advertiser | integer | Y | Advertiser ID for which the ad group needs to be updated for delivery status |
| campaignId | ID of the campaign | integer | Y | Unique numeric identifier. |
| Filter[name] | A valid ad group name with which the desired ad group can be searched in the absence of ad group ID | array | N | Provide an ad group name to search the relevant ad group by name instead of ad group ID |
| Filter[status] | Filter based on the ad group status | string | N | Enum values: • draft • live • scheduled • paused • completed • archived |
| Filter[lastModifiedDate] | Provide a date to fetch only those ad groups which were modified on or after that date | string | N | Date format must follow ISO 8601 time zone format: • yyyy-MM-dd'T'HH:mm:ss.SSSXXX |
| Filter[adGroupId] | ID of the ad groups you wish to list details for. Note: if no adGroupId is specified, all ad groups in the campaign will be returned | array | N | Unique numeric identifier. Maximum list size is 25 entries. |
| startIndex | You can use this parameter in combination with count, to fetch specific number of ad groups from a list. This indicates the starting position of the list | integer | N | Integer value. Default = 0 Example: To return the first ten ad groups, set startIndex=0 and count=10 |
| count | Defines the total number of ad groups to be returned. You can use this parameter in combination with startIndex, to fetch specific number of ad groups from a list. | integer | N | Integer value. Default = 0 Max = 100 Min = 1 Example: To return the first ten adGroups, set startIndex=0 and count=10 |
Headers
| Header Name | Description | Required | Values |
|---|---|---|---|
| Authorization | The token will provide you the access to the API. It is same for all advertisers you access through the API. | Y | Please utilize the generated auth_token shared with you at the time of partner onboarding from the Getting Started Guide |
| Content-Type | application/json | Y | n/a |
| WM_CONSUMER.ID | We will provide you the consumer ID to access the API. It is same for all advertisers you access through the API. | Y | Please use the generated ConsumerId shared with you at the time of partner onboarding. Refer to the Getting Started Guide for more information |
| WM_SEC.AUTH_SIGNATURE | Auth signature as an API key. | Y | Use the signature generator code from Getting Started Guide to generate this value |
| WM_SEC.KEY_VERSION | We will provide you with the KEY VERSION to access the API. It is same for all advertisers you access through the API. | Y | 1 |
| WM_CONSUMER.intimestamp | Timestamp for which the auth signature is generated. Use Unix epoch format for the timestamp. | Y | Use the signature generator code from Getting Started Guide to generate this value |
Sample Request
curl -X POST \ 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/adGroups/list' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>'
--header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \ --header 'WM_CONSUMER.intimestamp: 1565309779' \ --data ' { "advertiserId": 1, "campaignId": 1, "Filter[name]": ["string"], "Filter[status]": "string", "Filter[lastModifiedDate]": "string", "Filter[adGroupId]": [1, 2], "startIndex": 0, "count": 10 } ' Response
| Field | Description | Data Type | Possible Values |
|---|---|---|---|
| totalResults | Number of ad groups returned matching the filter criteria | Integer | success, failure |
| response | Array of ad group objects. Each object within the response field corresponds to a different ad group. | Array | — |
Response Object Fields
Each object within the response field corresponds to a different ad group.
| Field | Description | Data Type | Possible Values |
|---|---|---|---|
| campaignId | ID of the campaign the ad group belongs to | Integer | — |
| adGroupId | Internal ID of the ad group | Integer | — |
| adGroupExtId | External ad server ID of the ad group | Integer | — |
| name | Name of the ad group | String | — |
| status | Status of the ad group | String | DRAFT, LIVE, SCHEDULED, PAUSED, COMPLETED, ARCHIVED |
| startDate | Ad group start date (ISO 8601 format) | Date | — |
| endDate | Ad group end date (ISO 8601 format); returns 9999-12-31T00:00:00-05:00 for indefinite run | Date | — |
| isInventoryAware | Opt in / opt out of inventory-aware delivery at the ad group level | Boolean | true, false |
| budgetType | Budget type | String | DAILY, TOTAL |
| deliverySpeed | Pacing strategy | String | FRONTLOADED, EVENLY |
| dailyBudget | Daily budget (if applicable) | Double | — |
| totalBudget | Total budget (if applicable) | Double | — |
| rateType | Pricing structure | String | CPM |
| frequencyCapDay | Daily frequency cap per user | Integer | — |
| frequencyCapWeek | Weekly frequency cap per user | Integer | — |
| frequencyCapMonth | Monthly frequency cap per user | Integer | — |
| baseBid | Starting bid | Double | — |
| maxBid | Maximum bid | Double | — |
| targeting | Targeting configuration for the ad group. Supports keywords, contextual, behavioral, or run-of-site (only one allowed), optionally combined with geo targeting | Object[] | — |
| creationDate | Ad group creation timestamp (ISO 8601 format) | Date | — |
| lastUpdatedDate | Last modified timestamp (ISO 8601 format) | Date | — |
| attributesSetOnAdGroupLevel | Indicates whether budget and schedule are set at the ad group level | Boolean | true, false |
| creativeRotationMode | Creative rotation strategy | String | OPTIMIZE_PERFORMANCE, ROTATE_EVENLY |
| mediaType | Media type of the ad group | String | BANNER, VIDEO |
Sample Response
{ "totalResults": 2, "response": [ { "campaignId": 1, "adGroupId": 1, "adGroupExtId": 1, "name": "string", "status": "string", "startDate": "string", "endDate": "string", "budgetType": "string", "deliverySpeed": "string", "dailyBudget": 0, "totalBudget": 0, "rateType": "string", "frequencyCapDay": 0, "frequencyCapWeek": 0, "frequencyCapMonth": 0, "baseBid": 0, "maxBid": 0, "targeting": { "and": [ { "behavioral": [ { "audienceType": "RETAIL", "attribute": "HISTORICAL", "id": 1, "name": "tropicana", "mappingType": "PRODUCT_CATEGORY" }, { "audienceType": "RETAIL", "attribute": "HISTORICAL", "id": 5, "name": "sprite", "mappingType": "PRODUCT_FAMILY" } ] }, { "geoTargets": [ { "id": 2, "name": "Alabama", "locationType": "STATE" }, { "id": 3, "name": "Alaska", "locationType": "STATE" }, { "id": 10, "name": "Abbeville", "locationType": "CITY" } ] } ] }, "creationDate": "string", "lastUpdatedDate": "string", "attributesSetOnAdGroupLevel": true, "creativeRotationMode": "string" }, { "campaignId": 1, "adGroupId": 2, "adGroupExtId": 2, "name": "string", "status": "string", "startDate": "string", "endDate": "string", "budgetType": "string", "deliverySpeed": "string", "dailyBudget": 0, "totalBudget": 0, "rateType": "string", "frequencyCapDay": 0, "frequencyCapWeek": 0, "frequencyCapMonth": 0, "baseBid": 0, "maxBid": 0, "targeting": { "and": [ { "behavioral": [ { "audienceType": "CATEGORY", "attribute": "HISTORICAL", "id": 1, "name": "tropicana", "mappingType": "PRODUCT_CATEGORY" }, { "audienceType": "CATEGORY", "attribute": "HISTORICAL", "id": 5, "name": "sprite", "mappingType": "PRODUCT_FAMILY" } ] }, { "geoTargets": [ { "zipCode": "35004" } ] } ] }, "creationDate": "string", "lastUpdatedDate": "string", "attributesSetOnAdGroupLevel": true, "creativeRotationMode": "string" } ]
} Updated 2 days ago