Skip to main content

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

AttributeDescriptionRequiredPossible Values
ad_squad_idAd Squad IDR
creative_idCreative IDR
nameAd nameRmax length: 375 characters
paying_advertiser_nameName of the paying advertiser/political entityOThis value is inherited from the Ad Account entity and is immutable
review_statusAd Review StatusREAD ONLYPENDING, APPROVED, REJECTED
review_status_reasonsList of Ad Review Rejection ReasonsREAD ONLYif rejected, list of reasons
statusAd statusRACTIVE, PAUSED
typeAd typeRSNAP_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_statusDelivery statusRead-onlySee Delivery status
deletedIndicates whether the entity has been deleted or not, only shown when using the parameter read_deleted_entitiesRead-onlytrue

Ad Type <-> Creative Type Mapping

Ad TypeAllowed Creative Type
APP_INSTALLAPP_INSTALL
SNAP_ADSNAP_AD (aka top snap only)
REMOTE_WEBPAGEWEB_VIEW
DEEP_LINKDEEP_LINK
STORYCOMPOSITE
AD_TO_LENSAD_TO_LENS
AD_TO_CALLAD_TO_CALL
AD_TO_MESSAGEAD_TO_MESSAGE
LENSLENS
LENS_REMOTE_WEBPAGELENS_WEB_VIEW
LENS_APP_INSTALLLENS_APP_INSTALL
LENS_DEEP_LINKLENS_DEEP_LINK
COLLECTIONCOLLECTION
LEAD_GENERATIONLEAD_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

ParameterDefaultDescription
ad_squad_idAd 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

AttributeDescriptionRequiredPossible Values
nameAd nameR
statusAd statusRACTIVE, PAUSED
on_swipe_tracking_urlsThird-party swipe-up tagsO
third_party_tracking_urlsThird-party impression tagsO

HTTP Request

PUT https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads

Parameters

ParameterDefaultDescription
ad_squad_idAd 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

ParameterDefaultDescription
ad_squad_idAd 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

ParameterDefaultDescription
campaign_idCampaign 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

ParameterDefaultDescription
ad_account_idAd Account ID
read_deleted_entitiestrueoptional 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

ParameterDefaultDescription
ad_idAd ID
read_deleted_entitiestrueoptional 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

ParameterDescription
IDThe 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

AttributeDescriptionRequired
third_party_on_swipe_tracking_urlsThird-party swipe tags, executed on swipe of attachmentO
third_party_paid_impression_tracking_urlsThird-party impression tags, executed on ad impressionO
on_swipe_tracking_urlsDEPRECATED, Use attribute third_party_on_swipe_tracking_urls-
third_party_tracking_urlsDEPRECATED, Use attribute third_party_paid_impression_tracking_urls-

Approved Third Party Tracking URL domains

URLDescription
secure-gl.imrworldwide.com
ad.doubleclick.net
pixel.adsafeprotected.com
sn.moatads.comDEPRECATED, 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 .TIMESTAMP. and not [timestamp]

URL Macros

There are several dynamic placeholder macros that can be used within the URL that are replaced on-the-fly:

MacroDescription
.SERVER_ORG_ID.Organization ID
.SERVER_AD_ACCOUNT_ID.Ad Account ID
.SERVER_CAMPAIGN_ID.Campaign ID
.SERVER_AD_SQUAD_ID.Ad Squad ID
.SERVER_CREATIVE_ID.Creative ID
.SERVER_AD_ID.Ad ID
.SERVER_MOAT_PRODUCT_TYPE.Ad Product Type
.TIMESTAMP.Timestamp
Was this page helpful?
Yes
No

AI-Powered Search