AR Lenses and AR Filters

Lens and Fiter AR experiences are a powerful and memorable way to connect with consumers on a massive scale using augmented reality.

AR Lens and AR Filter Implementation Details

Lens package creation

Snap offers AR Lenses and AR Filters
AR Lenses appear in the pre-capture carousel, before Snapchatters take a photo or video using the Camera.
AR Filters appear in the post-capture carousel, this ad placement occurs after Snapchatters take a photo or video using the Camera.
AR Lenses and AR Filters are bespoke to Snap and can be created either via Lens Web Builder or Lens Studio, a free desktop software package.
After the advertiser has created an AR Lens or AR Filter they can export the resulting Lens package into the Lens folder of their Snapchat Business Organization

Creative and Campaign set up

Once the Lens package is in the Lens Folder it can be used to set up a Creative, which can be used in a Campaign with a target audience and a cost-per-impression bid.
When a user opens the Lens carousel (for AR Lenses) or the Post Capture Carousel (for AR Filters), Snapchat will run a second price auction containing all the Lenses targeting that user.
The Lens that wins the auction will be inserted into the Lens section of the carousel.
If the Lens is swiped on/over by the user, then the advertiser will be billed for the impression. An advertiser will only be billed once per Lens carousel session: while a user can swipe back and forth over the Lens during the session, the advertiser will only be billed for the first swipe in the session.
If a user either posts the Lens to their story or sends the Lens in a Direct Snap, then the advertiser will not be charged for any of the resulting views.

Create a Campaign

This endpoint will create a campaign within a specified ad account, note Ad Squads with the type LENS cannot be mixed with other types of Ad Squads (Snap Ads, Audience filters etc).

HTTP Request

POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/campaigns

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Example - Creating a Campaign

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
   -d '{"campaigns": [{"name": "Lens Campaign", "ad_account_id": "3b0fbace-04b4-4f04-a425-33b5e0af1dab", "status": "ACTIVE", "start_time": "2016-08-11T22:00:00.000Z"}]}' \
   "https://adsapi.snapchat.com/v1/adaccounts/3b0fbace-04b4-4f04-a425-33b5e0af1dab/campaigns"

{
  "request_status": "success",
  "request_id": "57b002ad00ff07e1f50fd2267f0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
  "campaigns": [
    {
      "sub_request_status": "success",
      "campaign": {
        "id": "5b48880f-bf65-495c-9810-2f4763add4cb",
        "updated_at": "2020-02-04T05:33:33.876Z",
        "created_at": "2020-02-04T05:33:33.876Z",
        "name": "Lens Campaign",
        "ad_account_id": "3b0fbace-04b4-4f04-a425-33b5e0af1dab",
        "status": "ACTIVE",
        "start_time": "2020-02-01T22:00:00.000Z"
      }
    }
  ]
}

Create a Lens Ad Squad

This creates an Ad Squad within a Campaign, note Ad Squads of the type LENS cannot contain other types of Ads (Snap Ads, Story Ads etc).

Attribute	Description	Required	Possible Values
campaign_id	Campaign ID	R
name	Ad Squad name	R
billing_event	Billing Event	R	IMPRESSION
bid_micro	Max Bid (micro-currency)	R
auto_bid	Allow Snapchat to automatically set the bid to recommended amount	O (One of auto_bid, target_bid or bid_micro must be set)	true/false.
target_bid	Allows Snapchat to adjust the bid aiming to keep your average CPA at or below the amount set by the ad set end date	O (One of auto_bid, target_bid or bid_micro must be set)	true/false.
pixel_id	Pixel to be associated with the Ad Squad	O
start_time	Start time	R
end_time	End time	R
optimization_goal	Optimization Goal, depends on the Lens Ad type as per Optimization goal per Ad type	R	APP_INSTALLS, IMPRESSIONS, USES, SWIPES, PIXEL_ADD_TO_CART, PIXEL_PAGE_VIEW, PIXEL_PURCHASE, PIXEL_SIGNUP
placement_v2.config	Placement	R	AUTOMATIC, CUSTOM
placement_v2.platforms	Placement	R	SNAPCHAT
placement_v2.snapchat_positions	Placement	R	CAMERA, POST_CAPTURE_CAROUSEL
status	Ad Squad status	R	ACTIVE, PAUSED
type	Ad Squad Type	R	LENS
targeting	Targeting spec	R	Any valid targeting options

HTTP Request

POST https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads

Parameters

Parameter	Default	Description
campaign_id		Campaign ID

Example 1 - Setting up an Ad Squad with automatic placement

This Ad Squad will serve the Lens in all valid Lens Placements as determined by the Lens Package Metadata.

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{"adsquads": [{"name": "Lens adsquad","status": "ACTIVE","campaign_id": "5b48880f-bf65-495c-9810-2f4763add4cb","type": "LENS","placement_v2": {"config": "AUTOMATIC"},"billing_event": "IMPRESSION","bid_micro": "200000000","daily_budget_micro": "2000000000","start_time": "2020-08-15T12:16:17.444-07:00","end_time": "2020-08-19T12:16:17.444-07:00","optimization_goal": "IMPRESSIONS","targeting": {"regulated_content": "false","demographics": [{"min_age": "21","max_age": "24"}],"geos": [{"country_code": "us"}]}}]}' \
  https://adsapi.snapchat.com/v1/campaigns/5b48880f-bf65-495c-9810-2f4763add4cb/adsquads

{
  "request_status": "SUCCESS",
  "request_id": "5e3c0a3d00ff077b3836beabb80001737e616473617069736300016275696c642d62343864336664332d312d3332332d3000010151",
  "adsquads": [
    {
      "sub_request_status": "SUCCESS",
      "adsquad": {
        "id": "caff7533-52e1-4412-9ef2-18232dbcd1ba",
        "updated_at": "2020-02-06T12:44:45.818Z",
        "created_at": "2020-02-06T12:44:45.818Z",
        "name": "Lens adsquad",
        "status": "ACTIVE",
        "campaign_id": "5b48880f-bf65-495c-9810-2f4763add4cb",
        "type": "LENS",
        "targeting": {
          "regulated_content": false,
          "demographics": [
            {
              "min_age": "21",
              "max_age": "24"
            }
          ],
          "geos": [
            {
              "country_code": "us"
            }
          ]
        },
        "targeting_reach_status": "VALID",
        "placement_v2": {
          "config": "AUTOMATIC"
        },
        "billing_event": "IMPRESSION",
        "bid_micro": 200000000,
        "auto_bid": false,
        "target_bid": false,
        "daily_budget_micro": 2000000000,
        "start_time": "2020-08-15T19:16:17.444Z",
        "end_time": "2020-08-19T19:16:17.444Z",
        "optimization_goal": "IMPRESSIONS",
        "delivery_constraint": "DAILY_BUDGET",
        "pacing_type": "STANDARD"
      }
    }
  ]
}

Example 2 - Setting up an Ad Squad with AR Lens (pre-capture) placement

This Ad Squad creation assumes the Lens Package metadata lens_applicable_types lists PRE_CAPTURE.

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{"adsquads": [{"name": "Lens adsquad","status": "ACTIVE","campaign_id": "5b48880f-bf65-495c-9810-2f4763add4cb","type": "LENS","placement_v2": {"config": "CUSTOM","platforms": ["SNAPCHAT"],"snapchat_positions": ["CAMERA"]},"billing_event": "IMPRESSION","bid_micro": "200000000","daily_budget_micro": "2000000000","start_time": "2021-08-15T12:16:17.444-07:00","end_time": "2021-08-19T12:16:17.444-07:00","optimization_goal": "IMPRESSIONS","targeting": {"regulated_content": "false","demographics": [{"min_age": "21","max_age": "24"}],"geos": [{"country_code": "us"}]}}]}' \
  https://adsapi.snapchat.com/v1/campaigns/5b48880f-bf65-495c-9810-2f4763add4cb/adsquads

{
  "request_status": "SUCCESS",
  "request_id": "5e3c0a3d00ff077b3836beabb80001737e616473617069736300016275696c642d62343864336664332d312d3332332d3000010151",
  "adsquads": [
    {
      "sub_request_status": "SUCCESS",
      "adsquad": {
        "id": "6cff7533-52e1-4412-9ef2-18232dbcd1ba",
        "updated_at": "2021-02-06T12:44:45.818Z",
        "created_at": "2021-02-06T12:44:45.818Z",
        "name": "Lens adsquad",
        "status": "ACTIVE",
        "campaign_id": "5b48880f-bf65-495c-9810-2f4763add4cb",
        "type": "LENS",
        "targeting": {
          "regulated_content": false,
          "demographics": [
            {
              "min_age": "21",
              "max_age": "24"
            }
          ],
          "geos": [
            {
              "country_code": "us"
            }
          ]
        },
        "targeting_reach_status": "VALID",
        "placement_v2": {
          "config": "CUSTOM",
          "platforms": ["SNAPCHAT"],
          "snapchat_positions": ["CAMERA"]
        },
        "billing_event": "IMPRESSION",
        "bid_micro": 200000000,
        "auto_bid": false,
        "target_bid": false,
        "daily_budget_micro": 2000000000,
        "start_time": "2021-08-15T19:16:17.444Z",
        "end_time": "2021-08-19T19:16:17.444Z",
        "optimization_goal": "IMPRESSIONS",
        "delivery_constraint": "DAILY_BUDGET",
        "pacing_type": "STANDARD"
      }
    }
  ]
}

Example 3 - Setting up an Ad Squad with AR Filter (post-capture) placement

This Ad Squad creation assumes the Lens Package metadata lens_applicable_types lists POST_CAPTURE.

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{"adsquads": [{"name": "AR Filter adsquad","status": "ACTIVE","campaign_id": "7a48880f-bf65-495c-9810-2f4763add4ca","type": "LENS","placement_v2": {"config": "CUSTOM","platforms": ["SNAPCHAT"],"snapchat_positions": ["POST_CAPTURE_CAROUSEL"]},"billing_event": "IMPRESSION","bid_micro": "200000000","daily_budget_micro": "2000000000","start_time": "2021-08-15T12:16:17.444-07:00","end_time": "2021-08-19T12:16:17.444-07:00","optimization_goal": "IMPRESSIONS","targeting": {"regulated_content": "false","demographics": [{"min_age": "21","max_age": "24"}],"geos": [{"country_code": "us"}]}}]}' \
  https://adsapi.snapchat.com/v1/campaigns/7a48880f-bf65-495c-9810-2f4763add4ca/adsquads

{
  "request_status": "SUCCESS",
  "request_id": "5e3c0a3d00ff077b3836beabb80001737e616473617069736300016275696c642d62343864336664332d312d3332332d3000010151",
  "adsquads": [
    {
      "sub_request_status": "SUCCESS",
      "adsquad": {
        "id": "5acc7533-52e1-4412-9ef2-18232dbcd1ba",
        "updated_at": "2021-03-06T12:44:45.818Z",
        "created_at": "2021-03-06T12:44:45.818Z",
        "name": "AR Filter adsquad",
        "status": "ACTIVE",
        "campaign_id": "7a48880f-bf65-495c-9810-2f4763add4ca",
        "type": "LENS",
        "targeting": {
          "regulated_content": false,
          "demographics": [
            {
              "min_age": "21",
              "max_age": "24"
            }
          ],
          "geos": [
            {
              "country_code": "us"
            }
          ]
        },
        "targeting_reach_status": "VALID",
        "placement_v2": {
          "config": "CUSTOM",
          "platforms": ["SNAPCHAT"],
          "snapchat_positions": ["POST_CAPTURE_CAROUSEL"]
        },
        "billing_event": "IMPRESSION",
        "bid_micro": 200000000,
        "auto_bid": false,
        "target_bid": false,
        "daily_budget_micro": 2000000000,
        "start_time": "2021-08-15T19:16:17.444Z",
        "end_time": "2021-08-19T19:16:17.444Z",
        "optimization_goal": "IMPRESSIONS",
        "delivery_constraint": "DAILY_BUDGET",
        "pacing_type": "STANDARD"
      }
    }
  ]
}

Lens Media

Unlike other Creatives, the Media file for a Lens Creative is not uploaded via the API, it's instead created in Snapchat Lens Studio or Lens Web Builder and then transferred to the Ad Account via the Lens folder in Business Manager.

Lens Package Attributes (lens_package_metadata)

These attributes are unique to the Media type LENS_PACKAGE.

Attribute	Description	Required	Possible Values
lens_applicable_types	Array listing the available placements for the lens_package Media	READ-ONLY	["POST_CAPTURE","CALLING_CAROUSEL","PRE_CAPTURE"]
lens_icon_media_id	Media name	READ-ONLY
default_camera	Default camera state when lens opens	READ-ONLY	BOTH, FACE, WORLD
perception_model	Metadata for lens media created by Lens Studio	READ-ONLY

Lens Placement - Ad Squad placement_v2

lens_package_metadata.lens_applicable_types	placement_v2.snapchat_positions	Description
PRE_CAPTURE	CAMERA	Lens is shown in Pre-capture Carousel
POST_CAPTURE	POST_CAPTURE_CAROUSEL	Lens is shown in Post-capture Carousel
CALLING_CAROUSEL	-	Lens is eligible for placement in the Calling arousel when using the AUTOMATIC configuration `"placement_v2": {"config": "AUTOMATIC"}`

Lens Preview Media

Lens preview media is sometimes available for LENS_PACKAGE media via the Lens Preview endpoint, not all Lens Media will have preview files available.

Attributes

Attribute	Description
icon_url	The URL where the Lens icon can be accessed
preview_video_url	The URL where a video capture of the Lens can be accessed
preview_image_url	The URL where a preview image of the Lens can be accessed
description	Description of the Lens as defined by it's creator

HTTP Request

GET https://adsapi.snapchat.com/v1/media/{media_id}/lens_preview

Parameters

Parameter	Default	Description
media_id		Media ID

Example - Fetching Lens Preview files

curl  "https://adsapi.snapchat.com/v1/media/cf721025-a249-4a2a-963a-8eaa55aa1831/lens_preview"

{
  "icon_url": "https://lens-storage.storage.googleapis.com/png/2f66687edc434256a80774c38715eed7",
  "preview_video_url": "https://community-lens.storage.googleapis.com/preview-media/final/e8b0340c-d305-4c76-8fcb-1d32a2b377ba.mp4",
  "preview_image_url": "https://community-lens.storage.googleapis.com/preview-media/final_poster/e8b0340c-d305-4c76-8fcb-1d32a2b377ba.jpg",
  "description": "Banana Spinning Lens",
  "request_status": "SUCCESS",
  "request_id": "a6239534-3f7f-456b-9d61-89308dd5902a"
}

Create the Creative - Lens

When a Lens is created in Snapchat Lens Studio, both the Media and the Creative will automatically be set up. You can however re-use the Lens media if you wish to set up a new Creative.

Attributes

Attribute	Description	Required	Possible Values
ad_account_id	Ad Account ID	R
name	Creative name	R
top_snap_media_id	Media ID of type LENS_PACKAGE	R
type	Creative Type	R	LENS, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_WEB_VIEW
ad_product	Ad product	R	LENS
brand_name	Brand Name	R (required but not displayed)	25 characters max
headline	Headline	R (required but not displayed)	34 characters max

curl -X POST  \
  -d '{"creatives": [{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1","name" : "Honey Badger Lens","type": "LENS","top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01","ad_product": "LENS","headline": "Try the Honey Badger Lens","brand_name": "Honey Badger"}]}' \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f1/creatives

{
  "request_status": "SUCCESS",
  "request_id": "5e3c5e7a00ff07ac2c051bd68e0001737e616473617069736300016275696c642d62343864336664332d312d3332332d3000010118",
  "creatives": [
    {
      "sub_request_status": "SUCCESS",
      "creative": {
        "id": "0091127a-1c58-4b0b-981d-d419d65cc87c",
        "updated_at": "2020-02-06T18:44:12.044Z",
        "created_at": "2020-02-06T18:44:12.044Z",
        "name": "Honey Badger Lens",
        "ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
        "type": "LENS",
        "packaging_status": "SUCCESS",
        "review_status": "PENDING_REVIEW",
        "shareable": true,
        "headline": "Try the Honey Badger Lens",
        "brand_name": "Honey Badger",
        "render_type": "STATIC",
        "top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01",
        "top_snap_crop_position": "MIDDLE",
        "ad_product": "LENS"
      }
    }
  ]
}

This creates a new Creative of the type LENS where the attribute top_snap_media_id is of the type LENS_PACKAGE.

HTTP Request

POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Create the Creative - Lens with App Install Attachment

When a Lens is created in Snapchat Lens Studio or Lens Web Builder, both the Media and the Creative will automatically be set up, you can however re-use the Lens media if you wish to set up a new Creative.

Attributes

Attribute	Description	Required	Possible Values
ad_account_id	Ad Account ID	R
name	Creative name	R
top_snap_media_id	Media ID of type LENS_PACKAGE	R
type	Creative Type	R	LENS_APP_INSTALL
ad_product	Ad product	R	LENS
brand_name	Brand Name	R (required but not displayed)	25 characters max
headline	Headline	R (required but not displayed)	34 characters max
call_to_action	Call to Action	R	Please refer to the Creative type to CTA mapping table

Additional Attributes

The following attributes should be added to the basic creative under the property app_install_properties.

Attribute	Description	Required	Possible Values
app_name	App name	R
ios_app_id	iOS App ID	R
android_app_url	Google Play Store ID	R	(eg "com.x.y")
icon_media_id	Icon Media ID	R
product_page_id	Custom product page ID from iOS App Store.	O	45812c9b-c296-43d3-c6a0-c5a02f74bf6e

curl -X POST  \
  -d '{"creatives": [{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1","name" : "Honey Badger Lens with App Install Attachment","type": "LENS_APP_INSTALL","top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01","ad_product": "LENS","headline": "Try the Honey Badger Lens","brand_name": "Honey Badger","call_to_action": "INSTALL_NOW","app_install_properties": {"app_name": "Bitmoji - Your Personal Emoji","ios_app_id": "868077558","android_app_url": "com.bitstrips.imoji","icon_media_id": "73b5deb6-5b2c-43b4-b60d-983bc344a4a2"}}]}' \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f1/creatives

{
  "request_status": "SUCCESS",
  "request_id": "5e42e3c700ff04d097d68c02810001737e616473617069736300016275696c642d63343664356339642d312d3332352d300001011a",
  "creatives": [
    {
      "sub_request_status": "SUCCESS",
      "creative": {
        "id": "1deb9eda-83bb-419d-a86c-67e2a7025385",
        "updated_at": "2020-02-11T17:26:32.402Z",
        "created_at": "2020-02-11T17:26:32.402Z",
        "name": "Honey Badger Lens with App Install Attachment",
        "ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
        "type": "LENS_APP_INSTALL",
        "packaging_status": "SUCCESS",
        "review_status": "PENDING_REVIEW",
        "shareable": true,
        "headline": "Try the Honey Badger Lens",
        "brand_name": "Honey Badger",
        "call_to_action": "INSTALL_NOW",
        "render_type": "STATIC",
        "top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01",
        "top_snap_crop_position": "MIDDLE",
        "app_install_properties": {
          "app_name": "Bitmoji - Your Personal Emoji",
          "ios_app_id": "868077558",
          "android_app_url": "com.bitstrips.imoji",
          "icon_media_id": "73b5deb6-5b2c-43b4-b60d-983bc344a4a2"
        },
        "ad_product": "LENS"
      }
    }
  ]
}

This creates a new Creative of the type LENS_APP_INSTALL where the attribute top_snap_media_id is of the type LENS_PACKAGE, and where the app_install_properties specify the attributes for the App Install Attachment.

HTTP Request

POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Create Lens with Deep Link Attachment

Attributes

Attribute	Description	Required	Possible Values
ad_account_id	Ad Account ID	R
name	Creative name	R
top_snap_media_id	Media ID of type LENS_PACKAGE	R
type	Creative Type	R	LENS_DEEP_LINK
ad_product	Ad product	R	LENS
brand_name	Brand Name	R (required but not displayed)	25 characters max
headline	Headline	R (required but not displayed)	34 characters max
call_to_action	Call to Action	R	Please refer to the Creative type to CTA mapping table

Additional Attributes

The following attributes should be added to the basic creative under the property deep_link_properties.

| Attribute | Description | Required | | --------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | ------------------------------- | | deep_link_uri | Deep Link URL | R | | app_name | App name | R | | ios_app_id | iOS App ID | Optional but one of ios_app_id or android_app_url is required | | android_app_url | Google Play Store ID | Optional but one of ios_app_id or android_app_url is required | | icon_media_id | Icon Media ID | R | | fallback_type | Type of fallback to be used when user doesn't have the app | O | APP_INSTALL (default), WEB_SITE | | web_view_fallback_url | Fallback web url to be used | O | | product_page_id | Custom Product Page ID on iOS App Store | O |

curl -X POST  \
  -d '{"creatives": [{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1","name" : "A new Lens with Deep Link Attachment","type": "LENS_DEEP_LINK","top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01","ad_product": "LENS","headline": "Try the Honey Badger Lens","brand_name": "Honey Badger","call_to_action": "TRY","deep_link_properties": {"deep_link_uri": "bitmoji://home","app_name": "Bitmoji - Your Personal Emoji","ios_app_id": "868077558","android_app_url": "com.bitstrips.imoji","icon_media_id": "73b5deb6-5b2c-43b4-b60d-983bc344a4a2","fallback_type": "APP_INSTALL"}}]}' \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f1/creatives

{
  "request_status": "SUCCESS",
  "request_id": "5e42ff007200ff071b3da02f5e6c0001737e616473617069736300016275696c642d63343664356339642d312d3332352d3000010110",
  "creatives": [
    {
      "sub_request_status": "SUCCESS",
      "creative": {
        "id": "d1b888eb-8998-42e3-9e73-45b5b5e8938d",
        "updated_at": "2020-02-11T19:24:35.553Z",
        "created_at": "2020-02-11T19:24:35.553Z",
        "name": "A new Lens with Deep Link Attachment",
        "ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
        "type": "LENS_DEEP_LINK",
        "packaging_status": "SUCCESS",
        "review_status": "PENDING_REVIEW",
        "shareable": true,
        "headline": "Try the Honey Badger Lens",
        "brand_name": "Honey Badger",
        "call_to_action": "TRY",
        "render_type": "STATIC",
        "top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01",
        "top_snap_crop_position": "MIDDLE",
        "deep_link_properties": {
          "deep_link_uri": "bitmoji://home",
          "app_name": "Bitmoji - Your Personal Emoji",
          "ios_app_id": "868077558",
          "android_app_url": "com.bitstrips.imoji",
          "icon_media_id": "73b5deb6-5b2c-43b4-b60d-983bc344a4a2",
          "fallback_type": "APP_INSTALL"
        },
        "ad_product": "LENS"
      }
    }
  ]
}

This creates a new Creative of the type LENS_APP_INSTALL where the attribute top_snap_media_id is of the type LENS_PACKAGE, and where the deep_link_properties specify the attributes for the Deep link Attachment.

HTTP Request

POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Create Lens with Web View Attachment

Attributes

Attribute	Description	Required	Possible Values
ad_account_id	Ad Account ID	R
name	Creative name	R
top_snap_media_id	Media ID of type LENS_PACKAGE	R
type	Creative Type	R	LENS_WEB_VIEW
ad_product	Ad product	R	LENS
brand_name	Brand Name	R (required but not displayed)	25 characters max
headline	Headline	R (required but not displayed)	34 characters max
call_to_action	Call to Action	R	Please refer to the Creative type to CTA mapping table

Additional Attributes

The following attributes should be added to the basic creative under the property web_view_properties.

Attribute	Description	Required	Possible Values
url	Web view URL	R
allow_snap_javascript_sdk	Allow Snapchat Javascript SDK to autofill form fields	O	true/false
block_preload	Block Snapchat from preloading the web page	O	true/false

curl -X POST  \
  -d '{"creatives": [{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1","name" : "A new Lens with Web View Attachment","type": "LENS_WEB_VIEW","top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01","ad_product": "LENS","headline": "Try the Honey Badger Lens","brand_name": "Honey Badger","call_to_action": "GET_NOW","web_view_properties": {"url": "http://www.example.com","allow_snap_javascript_sdk": "false","block_preload": "true"}}]}' \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f1/creatives

{
  "request_status": "SUCCESS",
  "request_id": "5e43d97400ff00ffe6fb1765c4350001737e616473617069736300016275696c642d63343664356339642d312d3332352d3000010119",
  "creatives": [
    {
      "sub_request_status": "SUCCESS",
      "creative": {
        "id": "b8f8dfb3-7738-4765-bd8e-ff312a34740d",
        "updated_at": "2020-02-12T10:54:45.363Z",
        "created_at": "2020-02-12T10:54:45.363Z",
        "name": "A new Lens with Web View Attachment",
        "ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
        "type": "LENS_WEB_VIEW",
        "packaging_status": "SUCCESS",
        "review_status": "PENDING_REVIEW",
        "shareable": true,
        "headline": "Try the Honey Badger Lens",
        "brand_name": "Honey Badger",
        "call_to_action": "GET_NOW",
        "render_type": "STATIC",
        "top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01",
        "top_snap_crop_position": "MIDDLE",
        "web_view_properties": {
          "url": "http://www.example.com",
          "allow_snap_javascript_sdk": false,
          "use_immersive_mode": false,
          "deep_link_urls": [],
          "block_preload": true
        },
        "ad_product": "LENS"
      }
    }
  ]
}

This creates a new Creative of the type LENS_WEB_VIEW where the attribute top_snap_media_id is of the type LENS_PACKAGE, and where the web_view_properties specify the attributes for the Web View Attachment.

HTTP Request

POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Create the Ad

This endpoint creates an Ad within an Ad Squad, note that the type attribute should match the Creative type of the Lens.

Attributes

Attribute	Description	Required	Possible Values
ad_squad_id	Ad Squad ID	R
creative_id	Creative ID	R
name	Ad name	R
type	Ad type	R	LENS, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_REMOTE_WEBPAGE
review_status	Ad Review Status	READ ONLY	PENDING, APPROVED, REJECTED
review_status_reason	List of Ad Review Rejection Reasons	READ ONLY	if rejected, list of reasons
status	Ad status	R	ACTIVE, PAUSED

Ad Type <-> Creative Type Mapping

Ad Type	Allowed Creative Lens Type
LENS	LENS
LENS_REMOTE_WEBPAGE	LENS_WEB_VIEW
LENS_APP_INSTALL	LENS_APP_INSTALL
LENS_DEEP_LINK	LENS_DEEP_LINK

curl -X POST \
  -d '{"ads":[{"ad_squad_id": "caff7533-52e1-4412-9ef2-18232dbcd1ba", "creative_id":"0091127a-1c58-4b0b-981d-d419d65cc87c", "name": "Honey Badger Ad - Lens", "type": "LENS", "status": "ACTIVE"}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adsquads/caff7533-52e1-4412-9ef2-18232dbcd1ba/ads

{
  "request_status": "SUCCESS",
  "request_id": "5e41982700ff0e64c8b9dcef490001737e616473617069736300016275696c642d66646632303364612d312d3332342d310001012a",
  "ads": [
    {
      "sub_request_status": "SUCCESS",
      "ad": {
        "id": "1ab494d4-73e8-4986-8517-c2d313e63f6e",
        "updated_at": "2020-02-10T17:51:38.097Z",
        "created_at": "2020-02-10T17:51:38.097Z",
        "name": "Honey Badger Ad - Lens",
        "ad_squad_id": "caff7533-52e1-4412-9ef2-18232dbcd1ba",
        "creative_id": "0091127a-1c58-4b0b-981d-d419d65cc87c",
        "status": "ACTIVE",
        "type": "LENS"
      }
    }
  ]
}

This creates a new Ad of the type LENS.

HTTP Request

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

Parameters

Parameter	Default	Description
ad_squad_id		Ad Squad ID

Reporting

Lens Metrics

Field	Description	Availability
paid_impressions	The total number of times your ad was served to a Snapchatter. Tracked when the ad fully renders on a device for the first time during a Snapchatter's viewing session	Real Time
earned_impressions	The number of times your ad was viewed after being shared by a Snapchatter via Chat or Stories	Within 24 hours
total_impressions	The total number of impressions (Paid and Earned)	Within 24 hours
shares	The number of times your Lens ad was shared via Chat or Stories	Real Time
saves	The number of times your Lens ad was saved to Memories	Real Time
play_time_millis	The total amount of time in where Snapchatters interacted with your Lens in the camera (milliseconds)	Real Time
spend	The total spend delivered in microcurrency	Real Time
uniques	The number of unique paid impressions	Within 24 hours, LIFETIME only
total_reach	The number of unique Snapchatters who viewed your Lens ad, either by receiving a Paid or Earned Impression.	Within 24 hours, LIFETIME only

Stats are available at the Ad, Ad Squad and Campaign levels and are supported for all granularities: HOUR, DAY, TOTAL and LIFETIME. For lenses with attachments you can also request swipes and attachment specific metrics.

curl "https://adsapi.snapchat.com/v1/adsquads/21136912-6d1a-44ea-a171-8ac29cf4d75d/stats?granularity=LIFETIME&fields=spend,paid_impressions,earned_impressions,shares,saves,play_time_millis,total_impressions,total_reach,uniques"
  -H "Authorization: Bearer meowmeowmeow"

{
  "request_status": "SUCCESS",
  "request_id": "5e448f8200ff0a3c430fd301390001737e616473617069736300016275696c642d63343664356339642d312d3332352d300001011c",
  "lifetime_stats": [
    {
      "sub_request_status": "SUCCESS",
      "lifetime_stat": {
        "id": "21136912-6d1a-44ea-a171-8ac29cf4d75d",
        "type": "AD_SQUAD",
        "granularity": "LIFETIME",
        "stats": {
          "uniques": 298861,
          "spend": 7027120158,
          "total_reach": 315925,
          "total_impressions": 979631,
          "earned_impressions": 29190,
          "paid_impressions": 950441,
          "shares": 7351,
          "saves": 1784,
          "play_time_millis": 6354875748
        },
        "start_time": "2016-09-26T08:00:00.000+01:00",
        "end_time": "2020-02-12T17:00:00.000Z",
        "finalized_data_end_time": "2020-02-12T17:00:00.000Z"
      }
    }
  ]
}

HTTP Request

GET https://adsapi.snapchat.com/v1/adsquads/{adsquad-id}/stats

Parameters

Parameter	Description
adsquad-id	Lens Ad squad ID

Was this page helpful?

Yes

AR Lens and AR Filter Implementation Details​

Lens package creation​

Creative and Campaign set up​

Create a Campaign​

HTTP Request​

Parameters​

Example - Creating a Campaign​

Create a Lens Ad Squad​

HTTP Request​

Parameters​

Example 1 - Setting up an Ad Squad with automatic placement​

Example 2 - Setting up an Ad Squad with AR Lens (pre-capture) placement​

Example 3 - Setting up an Ad Squad with AR Filter (post-capture) placement​

Lens Media​

Lens Package Attributes (lens_package_metadata)​

Lens Placement - Ad Squad placement_v2​

Lens Preview Media​

Attributes​

HTTP Request​

Parameters​

Example - Fetching Lens Preview files​

Create the Creative - Lens​

Attributes​

HTTP Request​

Parameters​

Create the Creative - Lens with App Install Attachment​

Attributes​

HTTP Request​

Parameters​

Create Lens with Deep Link Attachment​

Attributes​

Additional Attributes​

HTTP Request​

Parameters​

Create Lens with Web View Attachment​

Attributes​

Additional Attributes​

HTTP Request​

Parameters​

Create the Ad​

Attributes​

Ad Type <-> Creative Type Mapping​

HTTP Request​

Parameters​

Reporting​

Lens Metrics​

HTTP Request​

Parameters​

AR Lens and AR Filter Implementation Details

Lens package creation

Creative and Campaign set up

Create a Campaign

HTTP Request

Parameters

Example - Creating a Campaign

Create a Lens Ad Squad

HTTP Request

Parameters

Example 1 - Setting up an Ad Squad with automatic placement

Example 2 - Setting up an Ad Squad with AR Lens (pre-capture) placement

Example 3 - Setting up an Ad Squad with AR Filter (post-capture) placement

Lens Media

Lens Package Attributes (lens_package_metadata)

Lens Placement - Ad Squad placement_v2

Lens Preview Media

Attributes

HTTP Request

Parameters

Example - Fetching Lens Preview files

Create the Creative - Lens

Attributes

HTTP Request

Parameters

Create the Creative - Lens with App Install Attachment

Attributes

HTTP Request

Parameters

Create Lens with Deep Link Attachment

Attributes

Additional Attributes

HTTP Request

Parameters

Create Lens with Web View Attachment

Attributes

Additional Attributes

HTTP Request

Parameters

Create the Ad

Attributes

Ad Type <-> Creative Type Mapping

HTTP Request

Parameters

Reporting

Lens Metrics

HTTP Request

Parameters