Entity Snapshot
Overview
The Entity Snapshot API provides functionality to retrieve the campaign structure of all the ad campaigns for a given advertiser.
Usage:
- To create file-based snapshot for all the campaign entities for an advertiser
- To retrieve entity by providing snapshot ID and advertiser ID for an advertiser
Details about ‘Request Header' and 'Authorization’ are available in the Authorization Guide
Create Entity Snapshot
Description: Create file-based snapshot for all the campaign entities for an advertiser.
End Point: api/v1/snapshot/entity
HTTP Method: POST
Body Parameters
Parameter | Description | Type | Required | Possible Values |
---|---|---|---|---|
advertiserId | The ID of the advertiser | Integer | Y | Unique numeric identifier |
entityStatus | The status of the entity Note: The default status is “enabled”. Disabled entities won’t be part of the snapshot unless you request “disabled” and/or “all” |
String | Y | Enable, Disable and All |
entityTypes | The type of entity for which the snapshot should be generated. | StringArray | Y | campaign, adGroup, keyword, adItem, bidMultiplier ,placement: If you select this value, the entity snapshot will return which placements have been included or excluded for a given keyword campaign. |
format | Choose the format type for snapshot | String | N | Types of Formats: GZIP, ZIP Note: GZIP allows decompression while file is being transferred over the network, hence it is a faster and simpler way to download the reports. You will receive snapshot in zip format if no specific format is selected |
Note: There is no limit on number of snapshot requests for an advertiser.
Sample Requests for Create Entity Snapshot
Sample Request 1
Sample Request 2
Sample Request 3
Sample Responses for Create Entity Snapshot
Response
Element | Description | Type |
---|---|---|
code | The response code can have following values: success, failure | String |
details | Details of the error if value of response code is failure | String |
snapshotId | ID of the snapshot | String |
jobStatus | It is an indicator to confirm status of snapshot generation. The possible values of jobStatus are: Pending, Processing, Done, Failed, Expired | String |
Sample Response 1
[
{
"code": "success",
"snapshotId": "1",
"details": "https://advertising.samsclub.com/file/1 ",
" jobStatus ": "done"
}
]
Sample Response 2
[
{
"code": "success",
"snapshotId": "2",
"details": "https://advertising.samsclub.com/file/2",
"jobStatus": "done"
}
]
Sample Response 3
[
{
"code": "success",
"snapshotId": "3",
"details": "https://advertising.samsclub.com/file/3",
" jobStatus ": "done"
}
]
Status Code | Description | Possible Error Messages |
---|---|---|
400 | Bad request |
|
403 | Forbidden |
|
429 | Too Many Requests | <Exception Message> |
500 | Internal Server Error | There was an error processing the request |
Retrieve Entity Snapshots
Description: Retrieve entity by providing snapshot id and advertiser id for an advertiser
End Point: /api/v1/snapshot
HTTP Method: GET
Note:
- The output is generated in a “ZIP/GZIP” file depending upon format chosen
- The file type in ZIP file will be JSON
Query Parameters
Parameter | Description | Type | Required | Possible Values |
---|---|---|---|---|
advertiserId | The ID of the advertiser for whom the ad group(s) should be returned | Integer | Y | Unique numeric identifier |
snapshotId | ID of the snapshot | Integer | Y | Unique String identifier for each snapshot report request. |
Sample Request
Response
Element | Description | Type |
---|---|---|
snapshotId | ID of the snapshot | String |
jobStatus | It is an indicator to confirm status of snapshot generation. The possible values of jobStatus are: Pending, Processing, Done, Failed, Expired | String |
details | Details of the error if value of response code is failure | String |
code | The response code can have following values: Success, Failure | String |
Note: TTL
(Time to Live) for files generated is one day
Sample Response 1
[
{
"code": "success",
"snapshotId": "1",
"details": "https://advertising.samsclub.com/file/1 ",
" jobStatus ": "done"
}
]
The snapshot file is in JSON format that includes response for each entity type. You can request multiple entity types in one request; however, the response would be captured in one ZIP/GZIP file as requested. It will have single JSON file returning response for all entities.
Example of the content of snapshot with id “1”. The file format is “json”
{
"campaigns": [
{
"name": "camp1",
"campaignType": "sponsoredProducts",
"targetingType": "auto",
"status": "enabled",
"budgetType": "both",
"startDate": "2019-03-15",
"endDate": "2019-04-15",
"totalBudget": 1000,
"dailyBudget": 100,
"rollover": true,
"advertiserId": 600001,
"campaignId": 200001
},
{
"name": "camp2",
"campaignType": "sponsoredProducts",
"targetingType": "auto",
"status": "enabled",
"budgetType": "both",
"startDate": "2019-04-15",
"endDate": "2019-05-15",
"totalBudget": 1000,
"dailyBudget": 100,
"rollover": true,
"advertiserId": 600001,
"campaignId": 219032
}
],
"adGroups": [
{
"adGroupId": 15718,
"name": "AG_FOR_CAMPAIGN_14758",
"status": "enabled",
"campaignId": 100002
},
{
"adGroupId": 10625,
"name": "01_ABB_A6019",
"status": "enabled",
"campaignId": 106063
}
]
}
Sample Response 2
[
{
"code": "success",
"snapshotId": "2",
"details": "https://advertising.samsclub.com/file/2",
"jobStatus": "done"
}
]
Example of the content of snapshot with id “2”. The file format is “json”:
{
"placementBidMultipliers": [
{
"campaignId": 170621,
"placementType": "Buy-Box",
"multiplier": 0
},
{
"campaignId": 170621,
"placementType": "Search In-grid",
"multiplier": 0
}
],
"platformBidMultipliers": [
{
"campaignId": 17062,
"platformType": "Desktop",
"multiplier": 0
},
{
"campaignId": 17062,
"platformType": "App",
"multiplier": 0
}
],
"adItem": [
{
"campaignId": 106061,
"adGroupId": 106250,
"itemId": "46492243",
"adItemId": 52196,
"bid": 2,
"status": "enabled",
"itemImageUrl": "https://scene7.samsclub.com/is/image/samsclub/0004200094484_A?$DT_PDP_BB$",
"itemPageUrl": "https://www.samsclub.com/p/quilted-northern-ultra-soft-strong-toilet-paper-32-rolls-271-sheets/prod23132701",
"name": "TV Console"
}
]
}
Sample Response 3
[
{
"code": "success",
"snapshotId": "3",
"details": "https://advertising.samsclub.com/file/3",
" jobStatus ": "done"
}
]
Example of the content of snapshot with id “3”. The file format is “json”:
{
"campaigns": {
"name": "camp3",
"campaignType": "sponsoredProducts",
"targetingType": "auto",
"status": "enabled",
"budgetType": "both",
"startDate": "2019-02-01",
"endDate": "2019-03-01",
"totalBudget": 899999,
"dailyBudget": 100,
"rollover": true,
"advertiserId": 600003,
"campaignId": 183000
},
"adGroups": {
"adGroupId": 157181,
"name": "AG_FOR_CAMPAIGN_14758",
"status": "enabled",
"campaignId": 147581
},
"keywords": {
"campaignId": 170910,
"adGroupId": 181590,
"keywordId": 36511789533,
"state": "enabled",
"keywordText": "pedialyte",
"keywordCategory": null,
"status": "awaiting_approval",
"matchType": "exact",
"bid": 2
},
"adItem": {
"campaignId": 106061,
"adGroupId": 106250,
"itemId": "46492243",
"adItemId": 52196,
"bid": 2,
"status": "enabled",
"itemImageUrl": "https://scene7.samsclub.com/is/image/samsclub/0004200094484_A?$DT_PDP_BB$",
"itemPageUrl": "https://www.samsclub.com/p/quilted-northern-ultra-soft-strong-toilet-paper-32-rolls-271-sheets/prod23132701",
"name": "TV Console"
},
"placementBidMultipliers": {
"campaignId": 170621,
"placementType": "Buy-Box",
"multiplier": 0
},
"platformBidMultipliers": {
"campaignId": 17062,
"platformType": "Desktop",
"multiplier": 0
}
}
Sample Response 4
[
{
"code": "success",
"snapshotId": "4",
"details": "https://advertising.samsclub.com/file/4",
" jobStatus ": "done"
}
]
Example of the content of snapshot with id “4”. The file format is “json”:
{
"campaigns": {
"name": "camp3",
"campaignType": "sponsoredProducts",
"targetingType": "auto",
"status": "enabled",
"budgetType": "both",
"startDate": "2019-02-01",
"endDate": "2019-03-01",
"totalBudget": 899999,
"dailyBudget": 100,
"rollover": true,
"advertiserId": 600003,
"campaignId": 183000
},
"adGroups": {
"adGroupId": 157181,
"name": "AG_FOR_CAMPAIGN_14758",
"status": "enabled",
"campaignId": 147581
},
"keywords": {
"campaignId": 170910,
"adGroupId": 181590,
"keywordId": 36511789533,
"state": "enabled",
"keywordText": "pedialyte",
"keywordCategory": null,
"status": "awaiting_approval",
"matchType": "exact",
"bid": 2
},
"adItem": {
"campaignId": 106061,
"adGroupId": 106250,
"itemId": "46492243",
"adItemId": 52196,
"bid": 2,
"status": "enabled",
"itemImageUrl": "https://scene7.samsclub.com/is/image/samsclub/0004200094484_A?$DT_PDP_BB$",
"itemPageUrl": "https://www.samsclub.com/p/quilted-northern-ultra-soft-strong-toilet-paper-32-rolls-271-sheets/prod23132701",
"name": "TV Console"
},
"placementBidMultipliers": {
"campaignId": 170621,
"placementType": "Buy-Box",
"multiplier": 0
},
"platformBidMultipliers": {
"campaignId": 17062,
"platformType": "Desktop",
"multiplier": 0
},
"campaignPlacements": {
"campaignId": 600002,
"placements": {
"placement": "Search Carousel",
"status": "included"
}
}
}
Sample Response 5
[
{
"code": "success",
"snapshotId": "5",
"details": "https://advertising.samsclub.com/file/5",
" jobStatus ": "done"
}
]
Example of the content of snapshot with id “5”. The file format is “json”:
Note: If a campaign has two Sponsored Brand profiles, the response will have 2 different Sponsored Brand profile IDs associated with the same campaign ID and ad group ID with the Sponsored Brand profile’s respective status
{
"sbaProfiles": [
{
"searchAmpName": "text1",
"headLineText": "text2",
"sbaProfileId": 600000,
"logoUrl": "logo URL",
"clickUrl": "https://www.samsclub.com",
"reviewStatus": "pending",
"reviewReason": null,
"adGroupId": 600001,
"campaignId": 200001,
"status": "enabled"
}
],
"categories": [
{
"adGroupId": 100001,
"campaignId": 100002,
"id": 100003,
"categoryId": "4908_439045_1010345",
"state": "enabled",
"bid": 5.23
}
]
}
Sample Response 6
[
{
"code": "success",
"snapshotId": "6",
"details" : "https://advertising.samsclub.com/file/6",
"jobStatus": "done"
}
]
Example of the content of snapshot with id “6”. The file format is “json”:
{
"campaigns":[
{
"name": "Video Campaign",
"campaignType": "video",
"targetingType": "manual",
"status": "Proposal",
"budgetType": "both",
"startDate": "%currentDate%",
"endDate": "%currentDatePlus1Month%",
"totalBudget": 10000.0,
"dailyBudget": 2000.0,
"rollover": true,
"advertiserId": 600001,
"campaignId": 600007,
"channel": "Walmart.com"
}
],
"adGroups":[
{
"adGroupId":600008,
"name":"Ad Group Video",
"status":"Enabled",
"campaignId":600007
}
],
"keywords":[
{
"campaignId":600006,
"adGroupId":600007,
"keywordId":600007,
"state":"enabled",
"keywordText":"sv keyword 2 normalized",
"keywordCategory":null,
"status":"pending",
"matchType":"exact",
"bid":5.85
},
{
"campaignId":600005,
"adGroupId":600006,
"keywordId":600008,
"state":"enabled",
"keywordText":"sv keyword 1 normalized",
"keywordCategory":null,
"status":"pending",
"matchType":"exact",
"bid":5.85
}
],
"adItem":[
{
"campaignId":600001,
"adGroupId":600001,
"itemId":"562728956",
"adItemId":600003,
"bid":3.0,
"status":"enabled",
"itemImageUrl":"https://scene7.samsclub.com/is/image/samsclub/0004200094484_A?$DT_PDP_BB$",
"name":"TV",
"itemPageUrl":"https://www.samsclub.com/p/quilted-northern-ultra-soft-strong-toilet-paper-32-rolls-271-sheets/prod23132701",
"reviewReason": null,
"reviewStatus": "approved"
},
{
"campaignId":600002,
"adGroupId":600003,
"itemId":"45769024",
"adItemId":600004,
"bid":1.5,
"status":"enabled",
"itemImageUrl":"https://scene7.samsclub.com/is/image/samsclub/0004200094484_A?$DT_PDP_BB$",
"name":"TV Stand",
"itemPageUrl":"https://www.samsclub.com/p/quilted-northern-ultra-soft-strong-toilet-paper-32-rolls-271-sheets/prod23132701",
"reviewReason": null,
"reviewStatus": "approved"
}
],
"adGroupMedias": [
{
"campaignId": 600007,
"adGroupId": 600008,
"adGroupMediaId": 600003,
"mediaId": 600001,
"reviewStatus": "pending",
"reviewReason": null,
"status": "enabled"
}
]
}