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, REMINDER
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
REMINDERREMINDER

Create an 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.

Example - 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"
      }
    }
  ]
}

Update an 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

Example - 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"
      }
    }
  ]
}

Get all Ads under an Ad Squad​

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
limit50-1000Parameter for pagination, sets the number of Ads returned per page
sortupdated_at-desc, created_at-descoptional parameter, sorts the resulting Ads in descending order, either by when the Ads were last updated or by when they were created.

Example - Get all Ads under an Ad Squad​

curl "https://adsapi.snapchat.com/v1/adsquads/ae838988-238b-4e47-ba5d-b6ceb523ce43/ads?sort=updated_at-desc&limit=10" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "a6f034eb-137d-45c4-afc7-d1e505acdc63",
  "paging": {},
  "ads": [
    {
      "sub_request_status": "SUCCESS",
      "ad": {
        "id": "719ca339-79d4-49b5-86fa-165decfa1d08",
        "updated_at": "2025-10-06T23:23:07.358Z",
        "created_at": "2025-10-06T10:26:25.771Z",
        "name": "Domino Preview test",
        "ad_squad_id": "ae838988-238b-4e47-ba5d-b6ceb523ce43",
        "creative_id": "df69d82c-6006-4fa2-af9a-396ce27ada0e",
        "status": "ACTIVE",
        "type": "REMOTE_WEBPAGE",
        "render_type": "DYNAMIC",
        "review_status": "APPROVED",
        "delivery_status": ["INVALID_EFFECTIVE_INVALID"]
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "ad": {
        "id": "2a6a6f97-7d92-406e-ba11-cd246c5e254b",
        "updated_at": "2025-10-06T11:48:55.103Z",
        "created_at": "2025-10-06T11:26:27.554Z",
        "name": "Partly Dynamic Collection Ad",
        "ad_squad_id": "ae838988-238b-4e47-ba5d-b6ceb523ce43",
        "creative_id": "f0ed1565-062a-4643-89b2-2cc3441b7fbd",
        "status": "ACTIVE",
        "type": "COLLECTION",
        "render_type": "DYNAMIC",
        "review_status": "APPROVED",
        "delivery_status": ["INVALID_EFFECTIVE_INVALID"]
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "ad": {
        "id": "2c5494cb-c87b-43f2-a416-893d493a58b1",
        "updated_at": "2025-10-06T10:34:10.909Z",
        "created_at": "2025-10-06T10:25:52.455Z",
        "name": "Domino Preview test",
        "ad_squad_id": "ae838988-238b-4e47-ba5d-b6ceb523ce43",
        "creative_id": "80311974-14d3-4306-aa84-3233dcc9c588",
        "status": "ACTIVE",
        "type": "COLLECTION",
        "render_type": "DYNAMIC",
        "review_status": "REJECTED",
        "review_status_reasons": [
          "Your Brand Name does not reflect the Paying Advertiser. Paying Advertiser examples include your Organization Name, Product Name, Parent Company, Artist Name or Co-Branded Partnerships. Please update your Brand Name to be reflective of the content you are advertising, resubmit for review, and our team will take another look."
        ],
        "delivery_status": [
          "INVALID_NOT_APPROVED_REVIEW_STATUS",
          "INVALID_EFFECTIVE_INVALID"
        ]
      }
    }
  ]
}

Get all Ads under a Campaign​

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
limit50-1000Parameter for pagination, sets the number of Ads returned per page
sortupdated_at-desc, created_at-descoptional parameter, sorts the resulting Ads in descending order, either by when the Ads were last updated or by when they were created.

Example - Get all Ads under a Campaign​

This request gets 20 Ad Squads per result page sorted in descending order of the creation date.

curl "https://adsapi.snapchat.com/v1/campaigns/77b217e4-7a2c-455b-9fd6-02a55c924177/ads?sort=created_at-desc&limit=20" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "b63bc373-c9d3-4025-a754-4924c5b7eac7",
  "paging": {},
  "ads": [
    {
      "sub_request_status": "SUCCESS",
      "ad": {
        "id": "bdde66d3-fe79-4862-a5db-1f052bef98d4",
        "updated_at": "2025-05-21T16:15:17.118Z",
        "created_at": "2025-05-21T16:13:32.338Z",
        "name": "Tuxedo Cat - Story Ad without PREVIEW creative",
        "ad_squad_id": "c4cb4ba0-a352-4257-b5ff-c26456d834ef",
        "creative_id": "3a8e2b42-ae77-4c64-99bc-85c747120b3b",
        "status": "ACTIVE",
        "type": "STORY",
        "render_type": "STATIC",
        "review_status": "APPROVED",
        "delivery_status": [
          "INVALID_NOT_APPROVED_REVIEW_STATUS",
          "INVALID_EFFECTIVE_INVALID"
        ]
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "ad": {
        "id": "ee8ebf82-06b8-4944-bd6d-a187afd39754",
        "updated_at": "2025-05-21T10:57:50.683Z",
        "created_at": "2025-05-21T10:04:54.621Z",
        "name": "Badgers - Story Ad with chat_properties",
        "ad_squad_id": "c4cb4ba0-a352-4257-b5ff-c26456d834ef",
        "creative_id": "e99442b4-9626-4069-9d39-e483fc11a221",
        "status": "ACTIVE",
        "type": "STORY",
        "render_type": "STATIC",
        "review_status": "REJECTED",
        "review_status_reasons": [
          "Your ad is in violation of Snap policy. Please see our Advertising Policies, Community Guidelines, Snap Ad Specifications and Creative Guidelines for more information."
        ],
        "delivery_status": [
          "INVALID_NOT_APPROVED_REVIEW_STATUS",
          "INVALID_EFFECTIVE_INVALID"
        ]
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "ad": {
        "id": "0b653b96-a43b-40b4-b55e-21ac4d277c9e",
        "updated_at": "2025-01-31T13:58:03.030Z",
        "created_at": "2025-01-31T13:25:53.608Z",
        "name": "Boxer - Sponsored Snap - No Response",
        "ad_squad_id": "17993c19-2745-42da-b830-37a68314a71e",
        "creative_id": "fbcfe23b-99ba-4281-a139-49308538481c",
        "status": "ACTIVE",
        "type": "REMOTE_WEBPAGE",
        "render_type": "STATIC",
        "review_status": "APPROVED",
        "delivery_status": ["INVALID_EFFECTIVE_INVALID"]
      }
    }
  ]
}

Get all Ads under an Ad Account​

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
limit50-1000Parameter for pagination, sets the number of Ads returned per page
sortupdated_at-desc, created_at-descoptional parameter, sorts the resulting Ads in descending order, either by when they were last updated or by when they were created, this parameter can be combined with limit, but cannot be combined with read_deleted_entities

Example - Get all Ads under an Ad Account​

This request returns 10 results per page sorted by when the Ads were last updated in descending order.

curl "https://adsapi.snapchat.com/v1/adaccounts/82825ba6-7559-4000-9663-bace8adff5f2/ads?sort=updated_at-desc&limit=10" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "b7677337-da1a-43ef-b3b7-309b0d08443d",
    "paging": {
        "next_link": "https://adsapi.snapchat.com/v1/adaccounts/82825ba6-7559-4000-9663-bace8adff5f2/ads?cursor=QWRzLzAyY2YzYWQ4LTY0MTQtNGQ4Mi1hMDBiLTNkZmI0MTllNjAxYg&limit=10&sort=updated_at-desc"
    },
    "ads": [
        {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "719ca339-79d4-49b5-86fa-165decfa1d08",
                "updated_at": "2025-10-06T23:23:07.358Z",
                "created_at": "2025-10-06T10:26:25.771Z",
                "name": "Collection Ad - Webview",
                "ad_squad_id": "ae838988-238b-4e47-ba5d-b6ceb523ce43",
                "creative_id": "df69d82c-6006-4fa2-af9a-396ce27ada0e",
                "status": "ACTIVE",
                "type": "REMOTE_WEBPAGE",
                "render_type": "DYNAMIC",
                "review_status": "APPROVED",
                "delivery_status": [
                    "INVALID_EFFECTIVE_INVALID"
                ]
            }
        },
        ...
        {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "2a6a6f97-7d92-406e-ba11-cd246c5e254b",
                "updated_at": "2025-10-06T11:48:55.103Z",
                "created_at": "2025-10-06T11:26:27.554Z",
                "name": "Partly Dynamic Collection Ad",
                "ad_squad_id": "ae838988-238b-4e47-ba5d-b6ceb523ce43",
                "creative_id": "f0ed1565-062a-4643-89b2-2cc3441b7fbd",
                "status": "ACTIVE",
                "type": "COLLECTION",
                "render_type": "DYNAMIC",
                "review_status": "APPROVED",
                "delivery_status": [
                    "INVALID_EFFECTIVE_INVALID"
                ]
            }
        }
    ]
}

Get a specific 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

Example - 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"
      }
    }
  ]
}

Delete an Ad​

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

Example - 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": []
}

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
secure-cert.imrworldwide.com
pixel.adsafeprotected.com
ad.doubleclick.net/ddm/trackclkClick tracker intended for third_party_on_swipe_tracking_urls
ad.doubleclick.net/ddm/trackimpImpression tracker intended for third_party_paid_impression_tracking_urls
ad.doubleclick.net/ddm/adShould not be used in the Third-party tracking attributes
ad.doubleclick.net/ddm/clkNot allowed in the Third-party tracking attributes, but can be placed in the URL attribute of a Webview Creative
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