Ads
Ad is a light weight entity that contains all the information needed to display the ad. It also contains a third party measurement URL if needed.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_squad_id | Ad Squad ID | R | |
creative_id | Creative ID | R | |
name | Ad name | R | max length: 375 characters |
paying_advertiser_name | Name of the paying advertiser/political entity | O | This value is inherited from the Ad Account entity and is immutable |
review_status | Ad Review Status | READ ONLY | PENDING, APPROVED, REJECTED |
review_status_reasons | List of Ad Review Rejection Reasons | READ ONLY | if rejected, list of reasons |
status | Ad status | R | ACTIVE, PAUSED |
type | Ad type | R | SNAP_AD, APP_INSTALL, REMOTE_WEBPAGE, DEEP_LINK, STORY, AD_TO_LENS, AD_TO_CALL, AD_TO_MESSAGE, FILTER, LENS, LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK, COLLECTION, LEAD_GENERATION |
delivery_status | Delivery status | Read-only | See Delivery status |
deleted | Indicates whether the entity has been deleted or not, only shown when using the parameter read_deleted_entities | Read-only | true |
Ad Type <-> Creative Type Mapping
Ad Type | Allowed Creative Type |
---|---|
APP_INSTALL | APP_INSTALL |
SNAP_AD | SNAP_AD (aka top snap only) |
REMOTE_WEBPAGE | WEB_VIEW |
DEEP_LINK | DEEP_LINK |
STORY | COMPOSITE |
AD_TO_LENS | AD_TO_LENS |
AD_TO_CALL | AD_TO_CALL |
AD_TO_MESSAGE | AD_TO_MESSAGE |
LENS | LENS |
LENS_REMOTE_WEBPAGE | LENS_WEB_VIEW |
LENS_APP_INSTALL | LENS_APP_INSTALL |
LENS_DEEP_LINK | LENS_DEEP_LINK |
COLLECTION | COLLECTION |
LEAD_GENERATION | LEAD_GENERATION |
Create an Ad
curl -X POST \
-d '{"ads":[{"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe", "creative_id":"c1e6e929-acec-466f-b023-852b8cacc18f", "name": "Ad One", "type": "SNAP_AD", "status": "PAUSED"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/ads
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b018c500ff0d22d3cefd730d0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010107",
"ads": [
{
"sub_request_status": "success",
"ad": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"updated_at": "2016-08-14T07:07:50.241Z",
"created_at": "2016-08-14T07:07:50.241Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "PAUSED",
"type": "SNAP_AD"
}
}
]
}
This endpoint creates an Ad within an Ad Squad.
HTTP Request
POST https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads
Parameters
Parameter | Default | Description |
---|---|---|
ad_squad_id | Ad Squad ID |
There are rate limits on creating ads with the same creative consecutively within a second. If the response is 429 and you are using same creative id to create ads, please consider using bulk requests.
Update an Ad
curl -X PUT \
-d '{"ads":[{"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4", "ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe", "creative_id":"c1e6e929-acec-466f-b023-852b8cacc18f", "name": "Ad One", "type": "SNAP_AD", "status": "ACTIVE"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/ads
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b01a6300ff0c09d23a7706470001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010108",
"ads": [
{
"sub_request_status": "success",
"ad": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"updated_at": "2016-08-14T07:14:45.174Z",
"created_at": "2016-08-14T07:07:50.241Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "ACTIVE",
"type": "SNAP_AD"
}
}
]
}
This endpoint updates an Ad.
Attributes that can be updated
Attribute | Description | Required | Possible Values |
---|---|---|---|
name | Ad name | R | |
status | Ad status | R | ACTIVE, PAUSED |
on_swipe_tracking_urls | Third-party swipe-up tags | O | |
third_party_tracking_urls | Third-party impression tags | O |
HTTP Request
PUT https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads
Parameters
Parameter | Default | Description |
---|---|---|
ad_squad_id | Ad Squad ID |
Get All Ads under an Ad Squad
curl "https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/ads" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b01b3400ff0608a82948df6b0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
"ads": [
{
"sub_request_status": "success",
"ad": {
"id": "2ded6d53-0805-4ff8-b984-54a7eb5c8918",
"updated_at": "2016-08-14T07:18:05.699Z",
"created_at": "2016-08-14T07:18:05.699Z",
"name": "Ad Two",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "PAUSED",
"type": "SNAP_AD"
}
},
{
"sub_request_status": "success",
"ad": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"updated_at": "2016-08-14T07:14:45.174Z",
"created_at": "2016-08-14T07:07:50.241Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "ACTIVE",
"type": "SNAP_AD"
}
}
]
}
This endpoint retrieves all ads within a specified ad squad.
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads
Parameters
Parameter | Default | Description |
---|---|---|
ad_squad_id | Ad Squad ID |
Get All Ads under a Campaign
curl "https://adsapi.snapchat.com/v1/campaigns/77b217e4-7a2c-455b-9fd6-02a55c924177/ads" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f8453bc00ff0d27cde61b08060001737e616473617069736300016275696c642d32626566663136392d312d3339322d3000010102",
"paging": {},
"ads": [
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "0bfdb79e-38cc-470f-8593-789b51b83c97",
"updated_at": "2018-09-12T18:11:00.831Z",
"created_at": "2018-09-12T18:02:25.767Z",
"name": "Fur Coat Shine",
"ad_squad_id": "7fc34710-1c46-417e-bfc6-c4d5696aac4f",
"creative_id": "7ef92e04-e99f-4e22-9496-5cc82b129c77",
"status": "ACTIVE",
"type": "APP_INSTALL",
"render_type": "STATIC",
"review_status": "APPROVED",
"approval_type": "FULL",
"delivery_status": ["VALID"]
}
},
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "54d00642-58bb-4db4-8a04-84ffd56258f7",
"updated_at": "2018-08-31T16:34:37.673Z",
"created_at": "2018-08-31T15:36:57.096Z",
"name": "Fur coat conditioner",
"ad_squad_id": "71ca9842-4628-4660-9ba3-3be2e7d15778",
"creative_id": "348e9545-5706-4ff6-8701-2971db6e0017",
"status": "ACTIVE",
"type": "APP_INSTALL",
"render_type": "STATIC",
"review_status": "APPROVED",
"approval_type": "FULL",
"delivery_status": ["VALID"]
}
},
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "d1e3c618-b4a0-46ec-8982-b3b357c35507",
"updated_at": "2018-08-31T15:48:52.200Z",
"created_at": "2018-08-31T13:43:41.986Z",
"name": "Claw polish",
"ad_squad_id": "71ca9842-4628-4660-9ba3-3be2e7d15778",
"creative_id": "e261479b-4f2b-443f-8fde-583816fb0167",
"status": "ACTIVE",
"type": "APP_INSTALL",
"render_type": "STATIC",
"review_status": "APPROVED",
"approval_type": "FULL",
"delivery_status": ["VALID"]
}
}
]
}
This endpoint retrieves all Ads under a specified Campaign.
HTTP Request
GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/ads
Parameters
Parameter | Default | Description |
---|---|---|
campaign_id | Campaign ID |
Get All Ads under an Ad Account
curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/ads" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b01b3400ff0608a82948df6b0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
"ads": [
{
"sub_request_status": "success",
"ad": {
"id": "2ded6d53-0805-4ff8-b984-54a7eb5c8918",
"updated_at": "2016-08-14T07:18:05.699Z",
"created_at": "2016-08-14T07:18:05.699Z",
"name": "Ad Two",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "PAUSED",
"type": "SNAP_AD"
}
},
{
"sub_request_status": "success",
"ad": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"updated_at": "2016-08-14T07:14:45.174Z",
"created_at": "2016-08-14T07:07:50.241Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "ACTIVE",
"type": "SNAP_AD"
}
}
]
}
This endpoint retrieves all Ads under a specified Ad account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/ads
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID | |
read_deleted_entities | true | optional parameter, this param will return the deleted attribute on deleted Ad entities |
Get a Specific Ad
curl "https://adsapi.snapchat.com/v1/ads/e8d6217f-32ab-400f-9e54-39a86a7963e4"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b01adc00ff0a5290ad9d42c00001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010103",
"ads": [
{
"sub_request_status": "success",
"ad": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"updated_at": "2016-08-14T07:14:45.174Z",
"created_at": "2016-08-14T07:07:50.241Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "ACTIVE",
"type": "SNAP_AD"
}
}
]
}
This endpoint retrieves a specific ad.
HTTP Request
GET https://adsapi.snapchat.com/v1/ads/{ad_id}
URL Parameters
Parameter | Default | Description |
---|---|---|
ad_id | Ad ID | |
read_deleted_entities | true | optional parameter, this param will return the deleted attribute on deleted Ad entities |
Delete an Ad
curl -X DELETE "https://adsapi.snapchat.com/v1/ads/2ded6d53-0805-4ff8-b984-54a7eb5c8918" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b01b6200ff05d100ff30ca9b1d0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010101",
"ads": []
}
This endpoint deletes a specific ad.
HTTP Request
DELETE https://adsapi.snapchat.com/v1/ads/{ad_id}
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the ad to delete |
Third-Party Tracking Tags
On the 1st of January 2020 we will be sunsetting the fields on_swipe_tracking_urls
and third_party_tracking_urls
.
From the 1st of January 2020 it won't be possible to update an Ad entity without removing the third-party tracking from the deprecated fields. This tracking can instead be implemented within the two fields third_party_on_swipe_tracking_urls
and third_party_paid_impression_tracking_urls
.
If you are trafficking third-party tags to the fields on_swipe_tracking_urls
and/or third_party_tracking_urls
you should amend your app as soon as possible and make use of the corresponding fields third_party_on_swipe_tracking_urls
and third_party_paid_impression_tracking_urls
.
Additionally MOAT tracking at Ad level will also be sunset on the 1st of January 2020, for any Ads where you wish to implement MOAT tracking you should instead activate the MOAT tracking at AdSquad level, using the new measurement_provider_names
attribute. Activation at AdSquad level will apply MOAT tracking to all Ad entities within the AdSquad.
Snap currently allows third-party tags from DCM, MDAR and Integral Ad Science (IAS).
MOAT tracking should be implemented at AdSquad level tracking activation via the measurement_provider_names
attribute.
curl -X PUT \
-d '{"ads":[{"id": "ebb64f61-0e12-4f3c-a55c-71a9a6d1ea63", "ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe", "creative_id":"c1e6e929-acec-466f-b023-852b8cacc18f", "name": "Ad One", "type": "SNAP_AD", "status": "ACTIVE", "third_party_paid_impression_tracking_urls": ["https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.222222222;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"],"third_party_on_swipe_tracking_urls": ["https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.333333333;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"]}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/ads
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "58bb7c5000ff06616e9fa0e86e0001737e616473617069736300016275696c642d33333562626234342d312d35302d330001013d",
"ads": [
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "ebb64f61-0e12-4f3c-a55c-71a9a6d1ea63",
"updated_at": "2017-03-18T00:16:17.690Z",
"created_at": "2017-03-18T00:16:17.690Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"third_party_paid_impression_tracking_urls": [
{
"trackingUrlMetadata": null,
"expandedTrackingUrl": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.222222222;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?",
"tracking_url": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.222222222;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"
}
],
"third_party_on_swipe_tracking_urls": [
{
"trackingUrlMetadata": null,
"expandedTrackingUrl": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.33333333;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?",
"tracking_url": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.33333333;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"
}
],
"status": "PAUSED",
"type": "SNAP_AD",
"review_status": "APPROVED"
}
}
]
}
Additional Ad Attributes
Attribute | Description | Required |
---|---|---|
third_party_on_swipe_tracking_urls | Third-party swipe tags, executed on swipe of attachment | O |
third_party_paid_impression_tracking_urls | Third-party impression tags, executed on ad impression | O |
DEPRECATED, Use attribute third_party_on_swipe_tracking_urls | - | |
DEPRECATED, Use attribute third_party_paid_impression_tracking_urls | - |
Approved Third Party Tracking URL domains
URL | Description |
---|---|
secure-gl.imrworldwide.com | |
ad.doubleclick.net | |
pixel.adsafeprotected.com | |
DEPRECATED, Use AdSquad level tracking activation |
How to get tags
-
DCM and IAS: Refer to your DCM/IAS Account Manager to request tags or generate them using the campaign management tools.
-
mDAR: Clients should request their Snapchat Account Manager to provide a tag.
Notes
- Ensure all tags are secure and use https
- Choose standard type 1x1 pixel and not Javascript or iframe
- Make sure cachebusting parameter is
.and not [timestamp]TIMESTAMP.
URL Macros
There are several dynamic placeholder macros that can be used within the URL that are replaced on-the-fly:
Macro | Description |
---|---|
Organization ID | |
Ad Account ID | |
Campaign ID | |
Ad Squad ID | |
Creative ID | |
Ad ID | |
Ad Product Type | |
Timestamp |