Creatives
A Creative is the combination of one or more pieces of media. Creative is owned by an Ad Account and can be used by multiple Ads simultaneously.
See dedicated sections for examples on how to set up and launch FILTER and LENS creatives.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | max length: 32 characters |
call_to_action | Call to Action | O | Please refer to the Creative type to CTA mapping table |
favorite_display_mode | Allows users to favorite the Creative within the Snapchat App | O | SHOW, HIDE |
offer_disclaimer_id | The Offer Disclaimer ID to be associated with the creative | O | |
cta_color_display_mode | Defines the colour of the Call-to-action button, a prerequisite is that the Creative uses profile_properties with a profile_id , see the CTA Color Display Mode behaviour table for full description of the different modes | O | DEFAULT_COLOR , AUTO_COLOR_DETECTION |
headline | Headline (displayed under brand name) | R | max length: 34 characters |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | max length: 375 characters |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | SNAP_AD, APP_INSTALL, WEB_VIEW, DEEP_LINK, AD_TO_LENS, AD_TO_CALL, AD_TO_MESSAGE, PREVIEW, COMPOSITE, LENS, LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK, COLLECTION, LEAD_GENERATION |
forced_view_eligibility | Indicates whether Creative can be used as a Commercial | O | FULL_DURATION, SIX_SECONDS, NONE |
preview_creative_id | ID of the preview creative | R (For Story Ads) | |
ad_product | Type of Ad Product | Required only for R&F creatives | SNAP_AD (default), LENS, FILTER |
profile_properties | Contains the profile ID to be associated with the creative | R | { profile_id: 72cf5c50-8343-48d3-a0a7-3ed45b75faaa } |
** LENS type will be available soon with Reach and Frequency buying. Please check Reach and Frequency guide for more details.
Creative Types and attachments
Creative Types
Name | Creative type | Description |
---|---|---|
Snap Ad | SNAP_AD | A Snap Ad comprised of a Top Snap only, latest Video/Image specs |
Snap Ad with attachment | APP_INSTALL, WEB_VIEW, DEEP_LINK, AD_TO_LENS, AD_TO_CALL, AD_TO_MESSAGE | See below for list of all attachments |
Story Ad | COMPOSITE | Story Ad Creatives require a PREVIEW creative |
Collection Ad | COLLECTION | |
Lens | LENS, LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK | See section on Lens creatives for specs and references |
A basic Snap Ad is comprised of a top snap only. Snap Ads can be enhanced by using one of the following attachments:
Creative Type to Call To Actions Mapping
Creative type | Call To Actions |
---|---|
APP_INSTALL | BOOK_NOW, DONATE, DOWNLOAD, GET_NOW, INSTALL_NOW, ORDER_NOW, PLAY, SHOP_NOW, SIGN_UP, TRY, USE_APP, WATCH, VOTE, DIRECTIONS, PLAY_GAME |
LENS_APP_INSTALL | BOOK_NOW, DONATE, DOWNLOAD, GET_NOW, INSTALL_NOW, ORDER_NOW, PLAY, SHOP_NOW, SIGN_UP, TRY, USE_APP, WATCH, PLAY_GAME |
DEEP_LINK | DONATE, PLAY, SHOP_NOW, SIGN_UP, USE_APP, MORE, OPEN_APP, TRY, WATCH, VIEW_PROFILE, VOTE, DIRECTIONS, PRE_REGISTER, PLAY_GAME, DOWNLOAD |
LEAD_GENERATION | APPLY_NOW, MORE, BOOK_NOW, GET_NOW, SIGN_UP, TEST_DRIVE, REQUEST_APPOINTMENT, REQUEST_QUOTE, FREE_TRIAL, CLAIM_SAMPLE, GET_COUPON |
LENS_DEEP_LINK | DONATE, PLAY, SHOP_NOW, SIGN_UP, USE_APP, MORE, OPEN_APP, TRY, WATCH, VIEW_PROFILE, VOTE, DIRECTIONS, VIEW_MENU, PRE_REGISTER, PLAY_GAME |
WEB_VIEW | APPLY_NOW, MORE, ORDER_NOW, PLAY, READ, SHOP_NOW, SHOW, SIGN_UP, VIEW, SHOW, WATCH, DONATE, DOWNLOAD, APPLY_NOW, ORDER_NOW, RESPOND, BUY_TICKETS, SHOWTIMES, BOOK_NOW, GET_NOW, LISTEN, TRY, VOTE, VIEW_MENU, PRE_REGISTER, PLAY_GAME |
LENS_WEB_VIEW | APPLY_NOW, MORE, ORDER_NOW, PLAY, READ, SHOP_NOW, SHOW, SIGN_UP, VIEW, SHOW, WATCH, DONATE, DOWNLOAD, APPLY_NOW, ORDER_NOW, RESPOND, BUY_TICKETS, SHOWTIMES, BOOK_NOW, GET_NOW, LISTEN, TRY, VOTE, DIRECTIONS, VIEW_MENU, PRE_REGISTER, PLAY_GAME |
AD_TO_LENS | PLAY, TRY, SHOP_NOW, VOTE |
AD_TO_MESSAGE | MESSAGE_NOW, OPEN_APP |
AD_TO_CALL | CALL_NOW, OPEN_APP |
AD_TO_PLACE | SEE_PLACE, DIRECTIONS, VIEW_MENU |
CTA Color Display Mode behaviour
This table explains how the behaviour of the cta_color_display_mode attribute.
Scenario | Value | Behaviour |
---|---|---|
cta_color_display_mode set to default color | ”cta_color_display_mode”:”DEFAULT_COLOR” | CTA button uses white background and black text string |
cta_color_display_mode set to extract color | ”cta_color_display_mode”:”AUTO_COLOR_DETECTION” | CTA button uses color extracted from Profile logo |
cta_color_display_mode is left out on creation | - | CTA button uses color extracted from Profile logo |
Attachments
Name | Creative type | Description |
---|---|---|
Web View attachment | WEB_VIEW | Creative requires web_view_properties |
App Install attachment | APP_INSTALL | Creative requires app_install_properties |
Deep Link attachment | DEEP_LINK | Creative requires deep_link_properties |
Lens attachment | AD_TO_LENS | Creative requires ad_to_lens_properties |
Call attachment | AD_TO_CALL | Creative requires ad_to_call_properties |
Text attachment | AD_TO_MESSAGE | Creative requires ad_to_message_properties |
Lead Generation form | LEAD_GENERATION | Creative requires lead_generation_form_id |
Create a Snap Ad
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 32 characters max |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | SNAP_AD |
forced_view_eligibility | Indicates whether Creative can be used as a Commercial, see Commercials section for instructions on how to determine and set this value | O | FULL_DURATION, SIX_SECONDS, NONE |
curl -X POST \
-d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837", "name": "Creative Creative", "type": "SNAP_AD", "brand_name": "Maxiumum Brand", "headline": "Healthy Living", "shareable": true}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0136f00ff085e3d63d358a20001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010108",
"creatives": [
{
"sub_request_status": "success",
"creative": {
"id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"updated_at": "2016-08-14T06:45:04.300Z",
"created_at": "2016-08-14T06:45:04.300Z",
"name": "Creative Creative",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "SNAP_AD",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE"
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Snap Ad with App Install attachment
App Install attachments allow users to swipe up and download the advertised app.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 32 characters max |
call_to_action | Call to Action | O | Please refer to the Creative type to CTA mapping table |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | APP_INSTALL |
forced_view_eligibility | Indicates whether Creative can be used as a Commercial, see Commercials section for instructions on how to determine and set this value | O | FULL_DURATION, SIX_SECONDS, NONE |
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 | 30 characters max |
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. Only set when using a Custom Product Page | O | 45812c9b-c296-43d3-c6a0-c5a02f74bf6e |
Icon Media specifications
- Minimum 200 x 200 px, Maximum 2000 x 2000 px
- Must be PNG format
- The image should be square
- The image should not have any borders or padding
Mobile Measurement Partners - Setup Details
curl -X POST \
-d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837", "name": "Creative App Install", "type": "APP_INSTALL", "shareable": true, "call_to_action": "INSTALL_NOW", "app_install_properties": {"app_name": "Cool App Yo", "ios_app_id": "447188370", "android_app_url": "com.snapchat.android", "icon_media_id": "ab32d7e5-1f80-4e1a-a76b-3c543d2b28e4"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0163000ff05bee93989450c0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010107",
"creatives": [
{
"sub_request_status": "success",
"creative": {
"id": "1c7065c2-ad9f-41cc-b2c5-d48d9810439b",
"updated_at": "2016-08-14T06:56:48.631Z",
"created_at": "2016-08-14T06:56:48.631Z",
"name": "Creative App Install",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "APP_INSTALL",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"call_to_action": "INSTALL_NOW",
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE",
"app_install_properties": {
"app_name": "Cool App Yo",
"ios_app_id": "447188370",
"android_app_url": "com.snapchat.android",
"icon_media_id": "ab32d7e5-1f80-4e1a-a76b-3c543d2b28e4"
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Snap Ad with Web View attachment
Web View attachments allow users to swipe up to view a web page, you have the option of preloading the website as directed by the block_preload attribute
. You can see more details on preloading and recommendations for optimizations here.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 32 characters max |
call_to_action | Call to Action | O | Please refer to the Creative type to CTA mapping table |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | WEB_VIEW |
forced_view_eligibility | Indicates whether Creative can be used as a Commercial, see Commercials section for instructions on how to determine and set this value | O | FULL_DURATION, SIX_SECONDS, NONE |
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 | The following macros are supported: {{campaign.name}} {{campaign.id}} {{adSet.name}} {{adSet.id}} {{ad.id}} {{creative.name}} {{creative.headline}} {{site_source_name}} max length: 2048 characters |
block_preload | Block Snapchat from preloading the web page | O | true/false (default) |
curl -X POST \
-d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837", "name": "Creative WV", "type": "WEB_VIEW", "shareable": true, "call_to_action": "VIEW", "web_view_properties": {"url": "http://snapchat.com/ads"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0168400ff06efecfdcdc8da0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010c",
"creatives": [
{
"sub_request_status": "success",
"creative": {
"id": "67e4296c-486b-4bf3-877b-f34e8eeb173c",
"updated_at": "2016-08-14T06:58:12.768Z",
"created_at": "2016-08-14T06:58:12.768Z",
"name": "Creative WV",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "WEB_VIEW",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"call_to_action": "VIEW",
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE",
"web_view_properties": {
"url": "http://snapchat.com/ads"
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Snap Ad with Deep Link attachment
The Deep Link attachment allows users who have the app installed to be directed to the location defined in the deep_link_properties
, users who do not have the app installed will be directed to the App store to install the app.
If you have a web view with deep links there is no need to specify the deep links in a separate field on the Creative. The deep links inside the web view will be auto detected.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 32 characters max |
call_to_action | Call to Action | O | Please refer to the Creative type to CTA mapping table |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | DEEP_LINK |
Additional Attributes
The following attributes should be added to the basic creative under the property deep_link_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
deep_link_uri | Deep Link URL | R | |
app_name | App name | R | 30 characters max |
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 from iOS App Store. Only set when using a Custom Product Page | O |
Icon Media specifications
- Minimum 200 x 200 px, Maximum 2000 x 2000 px
- Must be PNG format
- The image should be square
- The image should not have any borders or padding
curl -X POST \
-d '{"creatives": [{"name": "Deep Link test","ad_account_id": "{{ad_account_id}}","type": "DEEP_LINK","shareable": true,"headline": "some headline","brand_name": "some brand name","top_snap_media_id": "{{media_id}}","top_snap_crop_position": "MIDDLE","call_to_action": "{{cta}}","deep_link_properties": {"deep_link_uri":"spotify://somelink","ios_app_id": "1234","android_app_url": "com.snapchat.android","app_name": "not hotdog app","icon_media_id": "{{app_icon_media_id}}"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0168400ff06efecfdcdc8da0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010c",
"creatives": [
{
"sub_request_status": "success",
"creative": {
"id": "67e4296c-486b-4bf3-877b-f34e8eeb173c",
"updated_at": "2016-08-14T06:58:12.768Z",
"created_at": "2016-08-14T06:58:12.768Z",
"name": "Deep Link test",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "DEEP_LINK",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"call_to_action": "VIEW",
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE",
"deep_link_properties": {
"deep_link_uri": "spotify://somelink",
"ios_app_id": "1234",
"android_app_url": "com.snapchat.android",
"app_name": "not hotdog app",
"icon_media_id": "{{app_icon_media_id}}"
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Snap Ad with Lens attachment
The lens attachment will open up an AR Lens upon swipe up
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 32 characters max |
call_to_action | Call to Action | O | Please refer to the Creative type to CTA mapping table |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | AD_TO_LENS |
forced_view_eligibility | Indicates whether Creative can be used as a Commercial, see Commercials section for instructions on how to determine and set this value | O | FULL_DURATION, SIX_SECONDS, NONE |
Additional Attributes
The following attributes should be added to the basic creative under the property ad_to_lens_properties.
Attribute | Description | Required |
---|---|---|
lens_media_id | The Media ID of the lens to be opened upon swipe up | R |
Lens 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 in question via Lens Studio.
curl -X POST \
-d '{"creatives": [{"name":"Swipe to Lens","ad_account_id":"0b5176e0-9d5e-467c-8275-c1b619bd87d1","type":"AD_TO_LENS","shareable":true,"headline":"Headline Headline","brand_name":"Best Brand","call_to_action":"TRY","top_snap_media_id":"77f0c0a5-3374-4196-ac71-eb9fce49a5f3","top_snap_crop_position":"MIDDLE","ad_product":"SNAP_AD","ad_to_lens_properties":{"lens_media_id":"708ba95f-74e4-4e95-b443-21ccd2091a96"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b52250700ff0c3438c927b7db0001737e616473617069736300016275696c642d31393039356634322d312d3138352d310001011b",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "0df4bc92-00c8-4a6d-af89-533def1e5750",
"updated_at": "2018-07-20T14:32:09.102Z",
"created_at": "2018-07-20T14:29:44.160Z",
"name": "Swipe to lens",
"ad_account_id": "0b5176e0-9d5e-467c-8275-c1b619bd87d1",
"type": "AD_TO_LENS",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Headline Healine",
"brand_name": "Best Brand",
"call_to_action": "TRY",
"top_snap_media_id": "77f0c0a5-3374-4196-ac71-eb9fce49a5f3",
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD",
"ad_to_lens_properties": {
"lens_media_id": "708ba95f-74e4-4e95-b443-21ccd2091a96"
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Swipe to Call/Text - Phone number verification
All Phone Numbers used in Swipe to Call/Text Creatives need to be Verified via Snap Ads Manager as we use 2 factor authentication. You can do this by using Snap Ads Manager to set up a first Swipe to Call/Text Creative in your account, this set up will include adding a phone number and verifying it, see this guide for more details on how to verify your phone number.
After successful verification of the phone number you will be able to retrieve a phone number ID for the number in question.
This type of Ad is currently only available in the United States, France, Qatar, Saudi Arabia, Egypt, Kuwait and the United Arab Emirates.
curl "https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/phone_numbers" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e6fb44400ff098283dd16a12e0001737e616473617069736300016275696c642d31636430373832652d312d3333342d300001010a",
"paging": {},
"phone_numbers": [
{
"sub_request_status": "SUCCESS",
"phone_number": {
"id": "d85758e1-4aac-435d-9660-de29e9b97548",
"updated_at": "2020-02-06T22:10:46.573Z",
"created_at": "2020-02-06T22:10:37.609Z",
"name": "Phone number - Pizza",
"country_code": "us",
"numerical_country_code": "1",
"phone_number": "1111333444",
"verification_status": "VERIFIED"
}
},
{
"sub_request_status": "SUCCESS",
"phone_number": {
"id": "dab10be9-6147-4ef4-9ad5-328f39777625",
"updated_at": "2020-02-06T22:07:40.452Z",
"created_at": "2020-02-06T22:07:26.553Z",
"name": "Phone number - Chicken",
"country_code": "us",
"numerical_country_code": "1",
"phone_number": "1111222333",
"verification_status": "VERIFIED"
}
}
]
}
This endpoint retrieves all verified phone numbers for an Ad Account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/phone_numbers
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Snap ad with Swipe to Call attachment
Call attachments allow users to swipe up to initiate a call.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 32 characters max |
call_to_action | Call to Action | O | Please refer to the Creative type to CTA mapping table |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | AD_TO_CALL |
Additional Attributes
The following attributes should be added to the basic creative under the property ad_to_call_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
phone_number_id | ID of the phone number to be used | R |
curl -X POST \
-d '{"creatives": [{"ad_account_id": "497979f0-ed17-4971-8288-054883f1cbca","name" : "A new AD_TO_CALL Creative","type": "AD_TO_CALL","top_snap_media_id": "2fbaa906-d2d2-423d-b8e3-9535f1281998","ad_product": "SNAP_AD","headline": "Order your meal now","brand_name": "Honey Foods","call_to_action": "OPEN_APP","ad_to_call_properties": {"phone_number_id": "715b6ee0-357c-41d2-9246-feb09c199fc9"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e6fb51900ff040ef4db1db40b0001737e616473617069736300016275696c642d31636430373832652d312d3333342d300001010a",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "dbf052de-139c-4860-9f29-9dc4fa580620",
"updated_at": "2020-03-16T17:19:24.063Z",
"created_at": "2020-03-16T17:19:24.063Z",
"name": "A new AD_TO_CALL Creative",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2",
"type": "AD_TO_CALL",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Order your meal now",
"brand_name": "Honey Foods",
"call_to_action": "OPEN_APP",
"render_type": "STATIC",
"top_snap_media_id": "2fbaa906-d2d2-423d-b8e3-9535f1281998",
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD",
"ad_to_call_properties": {
"phone_number_id": "715b6ee0-357c-41d2-9246-feb09c199fc9",
"message": null
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Snap Ad with Swipe to Text attachment
Text attachments allow users to swipe up to initiate a text message.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 32 characters max |
call_to_action | Call to Action | O | Please refer to the Creative type to CTA mapping table |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | AD_TO_MESSAGE |
Additional Attributes
The following attributes should be added to the basic creative under the property ad_to_message_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
phone_number_id | ID of the phone number to be used | R | |
message | A pre-populated message for the user to send, max 160 characters | O |
curl -X PUT \
-d '{"creatives":[{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2","name" : "A new AD_TO_MESSAGE Creative","type": "AD_TO_MESSAGE","top_snap_media_id": "2fbaa906-d2d2-423d-b8e3-9535f1281998","ad_product": "SNAP_AD","headline": "Honey Dating","brand_name": "Dating for honey bears","call_to_action": "OPEN_APP","ad_to_message_properties": {"phone_number_id": "715b6ee0-357c-41d2-9246-feb09c199fc9","message": "Please send me details of Single Polar Bears"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e6fb51900ff040ef4db1db40b0001737e616473617069736300016275696c642d31636430373832652d312d3333342d300001010a",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "48c1a68d-782c-48af-8dba-ceef18d22a3c",
"updated_at": "2020-03-16T17:19:24.250Z",
"created_at": "2020-03-16T17:19:24.250Z",
"name": "A new AD_TO_MESSAGE Creative",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2",
"type": "AD_TO_MESSAGE",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Honey Dating",
"brand_name": "Dating for honey bears",
"call_to_action": "OPEN_APP",
"render_type": "STATIC",
"top_snap_media_id": "2fbaa906-d2d2-423d-b8e3-9535f1281998",
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD",
"ad_to_message_properties": {
"phone_number_id": "715b6ee0-357c-41d2-9246-feb09c199fc9",
"message": "Send me details of Single Polar Bears"
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Story Ad Creative
The Story Ad Creative comes in two different variants, the full variant includes a Preview Creative and a Composite Creative, this type of Story Ad can run in the Stories Tab and also in between User stories and Curated stories.
The second variant of the Story Ad Creative uses only a Composite Creative, this type of Story Ad Creative can only run between User stories and Curated stories.
The Preview Creative is used to display the thumbnail within the Stories tab of the app, the Composite Creative is used to define the individual Snap Ads that make up the story. When the Story Ad runs in between User stories and Curated stories the Preview Creative is not used.
Create the Preview Creative
Additional Attributes
The following attributes should be added to the basic creative under the property preview_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
preview_media_id | Image that is the preview for Story Ads | R | |
logo_media_id | Logo shown on the tile for Story Ads | O | |
preview_headline | Preview Headline shown on the tile for Story Ads | R | 55 Character limit, emoji unicode characters allowed |
Preview Image Specifications
- Resolution 3:5
- Minimum dimensions: 360 x 600 px
- Maximum file size: 2MB
- File Type: png
Logo Specifications
- Dimensions: 993 x 284 px
- Maximum file size: 2MB
- File Type: png
curl -X POST \
-d '{"creatives": [{"ad_account_id": "0cf0aace-39d4-4502-8656-8f42daa473c7", "name": "Story Ad Preview", "type": "PREVIEW", "preview_properties": {"preview_media_id": "00a76e9f-186c-4ed4-87d7-d58a7dd06749", "logo_media_id": "6d54643b-e6e1-4c50-ab9a-a1f05965bf33", "preview_headline": "test preview headline"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/0cf0aace-39d4-4502-8656-8f42daa473c7/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ae7ac0a00ff09a390a9b9b4d60001737e616473617069736300016275696c642d36393364326336352d312d3136322d3400010101",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "62537bbc-1a3a-4a40-b46f-43d181eac8ee",
"updated_at": "2018-04-30T23:51:40.466Z",
"created_at": "2018-04-30T23:51:40.466Z",
"name": "Story Ad Preview",
"ad_account_id": "0cf0aace-39d4-4502-8656-8f42daa473c7",
"type": "PREVIEW",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"top_snap_crop_position": "MIDDLE",
"preview_properties": {
"preview_media_id": "00a76e9f-186c-4ed4-87d7-d58a7dd06749",
"logo_media_id": "6d54643b-e6e1-4c50-ab9a-a1f05965bf33",
"preview_headline": "test preview headline"
}
}
}
]
}
Create the Composite Creative
Additional Attributes
The following attributes should be added to the basic creative under the property composite_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
creative_ids | List of creative ids that make up composite creative | R (For Story Ads) | Creative types SNAP_AD, APP_INSTALL, WEB_VIEW and DEEP_LINK are supported |
Composite creation guidelines
- Story Ad Creatives use 1-20 individual Creatives within a Composite creative
- The Creative types listed in
creative_ids
attribute can be mixed as long as they are of the supported type listed above - Creatives are shown to the user in the order listed at creation
- The order of the Creatives is immutable once created
- The shareable attribute on the composite overrides the shareable value of the individual creatives
curl -X POST \
-d '{"creatives": [{"ad_account_id": "0cf0aace-39d4-4502-8656-8f42daa473c7", "name": "First Composite Creative", "type": "COMPOSITE", "headline": "Test headline", "brand_name": "Test brand name",*", "shareable": true, "preview_creative_id": "62537bbc-1a3a-4a40-b46f-43d181eac8ee", "composite_properties": {"creative_ids": ["2cc52fce-855e-40aa-bb4b-016c2befd8ab", "f9a4b56c-ece0-4da4-bc9d-08c29ef941a2", "9c4b3882-addc-48d9-8503-22f7d03d6309"]}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ae7b4cb00ff05f9646ae5a400ff0001737e616473617069736300016275696c642d36393364326336352d312d3136322d3400010155",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "d3f4b7a5-e8dc-4e85-8d05-52094e3e3708",
"updated_at": "2018-05-01T00:28:59.816Z",
"created_at": "2018-05-01T00:28:59.816Z",
"name": "First Composite Creative",
"ad_account_id": "0cf0aace-39d4-4502-8656-8f42daa473c7",
"type": "COMPOSITE",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Test headline",
"brand_name": "Test brand name",
"top_snap_crop_position": "MIDDLE",
"composite_properties": {
"creative_ids": [
"2cc52fce-855e-40aa-bb4b-016c2befd8ab",
"f9a4b56c-ece0-4da4-bc9d-08c29ef941a2",
"9c4b3882-addc-48d9-8503-22f7d03d6309"
]
},
"preview_creative_id": "62537bbc-1a3a-4a40-b46f-43d181eac8ee"
}
}
]
}
Create a Lens Creative
Lens Creatives can run both in regular auction and in Reach and Frequency, for creation of Lens creatives see the Lens Section.
curl -X POST \
-d '{"creatives": [{"name":"Lens Creative","ad_account_id":"0b5176e0-9d5e-467c-8275-c1b619bd87d1","type":"LENS","shareable":true,"headline":"Headline Headline","brand_name":"Best Brand", "top_snap_media_id":"77f0c0a5-3374-4196-ac71-eb9fce49a5f3","ad_product":"LENS"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b52250700ff0c3438c927b7db0001737e616473617069736300016275696c642d31393039356634322d312d3138352d310001011b",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "0df4bc92-00c8-4a6d-af89-533def1e5750",
"updated_at": "2018-07-20T14:32:09.102Z",
"created_at": "2018-07-20T14:29:44.160Z",
"name": "Lens Creative",
"ad_account_id": "0b5176e0-9d5e-467c-8275-c1b619bd87d1",
"type": "LENS",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Headline Healine",
"brand_name": "Best Brand",
"top_snap_media_id": "77f0c0a5-3374-4196-ac71-eb9fce49a5f3",
"top_snap_crop_position": "MIDDLE",
"ad_product": "LENS"
}
}
]
}
Create a Lens Creative with Attachment
You can create a Lens Creative with any of the following attachments and the corresponding field then becomes required. The attachment unit will behave in the same way as it would in a Snap Ad. For measurement, you can also use the Snap Pixel with the attachment if it is a webview, make sure to associate the pixel_id at the Adsquad level. For attributes and examples, see the Lens Section.
Attachment For Lens | Creative Type | Required Field |
---|---|---|
WEB_VIEW | LENS_WEB_VIEW | web_view_properties |
APP_INSTALL | LENS_APP_INSTALL | app_install_properties |
DEEP_LINK | LENS_DEEP_LINK | deep_link_properties |
Lens Creatives are also available for Reach and Frequency Campaigns.
curl -X POST \
-d '{"creatives": [{"name":"Lens Creative","ad_account_id":"0b5176e0-9d5e-467c-8275-c1b619bd87d1","type":"LENS_WEB_VIEW","shareable":true,"headline":"Headline Headline","brand_name":"Best Brand", "top_snap_media_id":"77f0c0a5-3374-4196-ac71-eb9fce49a5f3","ad_product":"LENS", "web_view_properties": {"url": "http://snapchat.com/ads"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b52250700ff0c3438c927b7db0001737e616473617069736300016275696c642d31393039356634322d312d3138352d310001011b",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "0df4bc92-00c8-4a6d-af89-533def1e5750",
"updated_at": "2018-07-20T14:32:09.102Z",
"created_at": "2018-07-20T14:29:44.160Z",
"name": "Lens Creative",
"ad_account_id": "0b5176e0-9d5e-467c-8275-c1b619bd87d1",
"type": "LENS_WEB_VIEW",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Headline Healine",
"brand_name": "Best Brand",
"top_snap_media_id": "77f0c0a5-3374-4196-ac71-eb9fce49a5f3",
"top_snap_crop_position": "MIDDLE",
"ad_product": "LENS",
"web_view_properties": {
"url": "http://snapchat.com/ads"
}
}
}
]
}
Create a Collection Ad Creative
Additional Attributes
The following attributes should be added to the basic creative under the property collection_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
interaction_zone_id | ID of the interaction zone to be used | R | |
default_fallback_interaction_type | The interation type when user swipes up on the full unit | R | WEB_VIEW, DEEP_LINK (must match the interaction type of the creative elements in the collection) |
web_view_properties | Web View properties | Required if default_fallback_interaction_type=WEB_VIEW | Same as web_view_properties for Web View Creative |
deep_link_properties | Deep Link properties | Required if default_fallback_interaction_type=DEEP_LINK | Same as deep_link_properties for Creative with deep links |
For Collection Ad creatives, call_to_action
must be set to null, and the headline
property of the interaction zone is used instead.
curl -X POST \
-d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74","name" : "Collection Ad creative","type": "COLLECTION","top_snap_media_id": "a871dcfd-3970-4917-a44a-b251220ce731","headline": "Collection Ad headline","brand_name": "My brand","collection_properties":{"interaction_zone_id":"a218dc8b-7a79-4da6-9a1c-e5a581c7bd44","default_fallback_interaction_type":"WEB_VIEW","web_view_properties":{"url":"https://snapchat.com"}}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5bef549b00ff07105bd7e8604d0001737e616473617069736300016275696c642d61353965373533332d312d3232302d3100010144",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "e6ef3dea-0a5a-438e-928d-56726343d121",
"updated_at": "2018-11-16T23:37:01.555Z",
"created_at": "2018-11-16T23:37:01.555Z",
"name": "Collection Ad creative",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "COLLECTION",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Collection Ad headline",
"brand_name": "My brand",
"top_snap_media_id": "a871dcfd-3970-4917-a44a-b251220ce731",
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD",
"collection_properties": {
"interaction_zone_id": "a218dc8b-7a79-4da6-9a1c-e5a581c7bd44",
"default_fallback_interaction_type": "WEB_VIEW",
"web_view_properties": {
"url": "https://snapchat.com",
"deep_link_urls": [],
"block_preload": false
}
}
}
}
]
}
Update a Creative
curl -X PUT \
-d '{
"creatives": [
{
"ad_account_id": "12325ba6-7559-4000-9663-bace8adff5f2",
"brand_name": "Example Inc",
"id": "7772efab-028d-40ec-aa9d-7eb8f065c10a",
"headline": "For all Citrus Fans",
"web_view_properties":
{
"url": "https://www.example.com/intro?utm_source=snapchat&utm_medium=paidsocial&utm_campaign=2019_citrus",
"block_preload": true
},
"type": "WEB_VIEW",
"ad_product": "SNAP_AD",
"top_snap_media_id": "647e6398-7e44-4ae5-a19d-c400b93bce32",
"top_snap_crop_position": "MIDDLE",
"name": "Citrus Creative",
"call_to_action": "LISTEN",
"shareable": true,
"profile_properties":
{
"profile_id": "62cf5c50-8343-48d3-a0a7-3ed45b75fa10"
}
}]
}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/12325ba6-7559-4000-9663-bace8adff5f2/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5c3008ed00ff04a89c4d5c66150001737e616473617069736300016275696c642d31326365666331382d312d3232362d3000000003",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "7772efab-028d-40ec-aa9d-7eb8f065c10a",
"updated_at": "2019-01-11T21:21:50.991Z",
"created_at": "2018-12-05T16:04:09.772Z",
"name": "Citrus Creative",
"ad_account_id": "12325ba6-7559-4000-9663-bace8adff5f2",
"type": "WEB_VIEW",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "For all Citrus Fans",
"brand_name": "Example Inc",
"call_to_action": "LISTEN",
"top_snap_media_id": "647e6398-7e44-4ae5-a19d-c400b93bce32",
"top_snap_crop_position": "MIDDLE",
"web_view_properties": {
"url": "https://www.example.com/intro?utm_source=snapchat&utm_medium=paidsocial&utm_campaign=2019_citrus",
"deep_link_urls": [],
"block_preload": true
},
"ad_product": "SNAP_AD",
"profile_properties": {
"profile_id": "62cf5c50-8343-48d3-a0a7-3ed45b75fa10"
}
}
}
]
}
This endpoint will update the specified Creative. Making changes to a creative will impact all ads associated with the creative. These changes will trigger re-review of associated ads and the ads will be paused. Once the ads are re-approved, they will start delivering again.
Attributes that can be updated
Italicized attributes cannot be updated once a Creative is part of an Ad that has started serving.
Attribute | Required |
---|---|
brand_name | R |
call_to_action | R |
headline | R |
shareable | R |
name | R |
offer_disclaimer_id | O |
favorite_display_mode | O |
top_snap_media_id | R |
preview_creative_id | O |
forced_view_eligibility | O |
web_view_properties | Required |
---|---|
url | R |
block_preload | R |
app_install_properties | Required |
---|---|
app_name | R |
ios_app_id | R |
android_app_url | R |
icon_media_id | R |
product_page_id | O |
deep_link_properties | Required |
---|---|
deep_link_uri | R |
app_name | R |
ios_app_id | R |
android_app_url | R |
icon_media_id | R |
web_view_fallback_url | R |
fallback_type | R |
product_page_id | O |
preview_properties | Required |
---|---|
preview_media_id | R |
logo_media_id | R |
preview_headline | R |
composite_properties | Required |
---|---|
creative_ids | R |
ad_to_lens_properties | Required |
---|---|
lens_media_id | R |
Get All Creatives
curl "https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0171900ff0c73f50d5bd2f10001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010106",
"creatives": [
{
"sub_request_status": "success",
"creative": {
"id": "184fe3d0-ff80-4388-8d5f-05c340eff231",
"updated_at": "2016-08-14T06:54:38.229Z",
"created_at": "2016-08-14T06:54:38.229Z",
"name": "Creative LFV",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "LONGFORM_VIDEO",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"call_to_action": "WATCH",
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE",
"longform_video_properties": {
"video_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837"
}
}
},
{
"sub_request_status": "success",
"creative": {
"id": "1c7065c2-ad9f-41cc-b2c5-d48d9810439b",
"updated_at": "2016-08-14T06:56:48.631Z",
"created_at": "2016-08-14T06:56:48.631Z",
"name": "Creative App Install",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "APP_INSTALL",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"call_to_action": "INSTALL_NOW",
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE",
"app_install_properties": {
"app_name": "Cool App Yo",
"ios_app_id": "447188370",
"android_app_url": "com.snapchat.android",
"icon_media_id": "ab32d7e5-1f80-4e1a-a76b-3c543d2b28e4"
}
}
},
{
"sub_request_status": "success",
"creative": {
"id": "313e8415-6294-47d6-b064-5a0d9f21d224",
"updated_at": "2016-08-14T06:54:52.107Z",
"created_at": "2016-08-14T06:54:52.107Z",
"name": "Creative LFV 2",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "LONGFORM_VIDEO",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"call_to_action": "WATCH",
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE",
"longform_video_properties": {
"video_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837"
}
}
},
{
"sub_request_status": "success",
"creative": {
"id": "67e4296c-486b-4bf3-877b-f34e8eeb173c",
"updated_at": "2016-08-14T06:58:12.768Z",
"created_at": "2016-08-14T06:58:12.768Z",
"name": "Creative WV",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "WEB_VIEW",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"call_to_action": "VIEW_MORE",
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE",
"web_view_properties": {
"url": "http://snapchat.com/ads"
}
}
},
{
"sub_request_status": "success",
"creative": {
"id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"updated_at": "2016-08-14T06:45:04.300Z",
"created_at": "2016-08-14T06:45:04.300Z",
"name": "Creative Creative",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "SNAP_AD",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE"
}
}
]
}
This endpoint retrieves all creatives associated with an ad account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Get a Specific Creative
curl "https://adsapi.snapchat.com/v1/creatives/c1e6e929-acec-466f-b023-852b8cacc18f" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b017a400ff057ca1dcf703da0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010101",
"creatives": [
{
"sub_request_status": "success",
"creative": {
"id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"updated_at": "2016-08-14T06:45:04.300Z",
"created_at": "2016-08-14T06:45:04.300Z",
"name": "Creative Creative",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "SNAP_AD",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE"
}
}
]
}
This endpoint retrieves a specific Creative.
HTTP Request
GET https://adsapi.snapchat.com/v1/creatives/{creative_id}
URL Parameters
Parameter | Description |
---|---|
creative_id | The ID of the creative to retrieve |
Get Snapcode preview for a Creative
curl "https://adsapi.snapchat.com/v1/creatives/c1e6e929-acec-466f-b023-852b8cacc54f/snapcode" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5aa15e8000ff03acde535d9a200001737e616473617069736300016275696c642d62633562363761342d312d3134372d3600013326",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc54f",
"expires_at": "2018-03-09T15:51:33.248Z",
"snapcode_link": "https://adsapi.snapchat.com/snapcodeimage/c1e6e929-acec-466f-b023-852b8cacc54f/352a899e-4a9d-3fdf-8efe-9bac9b8a0a21"
}
This endpoint generates a snapcode preview for a specific creative, the lifetime of the snapcode is 7 days. The attribute expires_at
defines the time that the snapcode will stop functioning.
HTTP Request
GET https://adsapi.snapchat.com/v1/creatives/{creative_id}/snapcode
URL Parameters
Parameter | Description |
---|---|
creative_id | The ID of the creative to retrieve |
Associate Public Profiles with Creatives
To associate Public Profiles you can include the profile_properties
property to the creative during create or update. Then use the Sharing Policies API on the Business API to list all shared Public Profiles for an ad account or external organization.
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
'https://adsapi.snapchat.com/v1/adaccounts/12325ba6-7559-4000-9663-bace8adff5f2/creatives' \
-D '{
"creatives": [{
"ad_account_id": "12325ba6-7559-4000-9663-bace8adff5f2",
"brand_name": "Example Inc",
"id": "7772efab-028d-40ec-aa9d-7eb8f065c10a",
"headline": "For all Citrus Fans",
"web_view_properties":
{
"url": "https://www.example.com/intro?utm_source=snapchat&utm_medium=paidsocial&utm_campaign=2019_citrus",
"block_preload": true
},
"type": "WEB_VIEW",
"ad_product": "SNAP_AD",
"top_snap_media_id": "647e6398-7e44-4ae5-a19d-c400b93bce32",
"top_snap_crop_position": "MIDDLE",
"name": "Citrus Creative",
"call_to_action": "LISTEN",
"shareable": true,
"profile_properties":
{
"profile_id": "62cf5c50-8343-48d3-a0a7-3ed45b75fa10"
}
}]
}'
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5c3008ed00ff04a89c4d5c66150001737e616473617069736300016275696c642d31326365666331382d312d3232362d3000000003",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "7772efab-028d-40ec-aa9d-7eb8f065c10a",
"updated_at": "2019-01-11T21:21:50.991Z",
"created_at": "2018-12-05T16:04:09.772Z",
"name": "Citrus Creative",
"ad_account_id": "12325ba6-7559-4000-9663-bace8adff5f2",
"type": "WEB_VIEW",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "For all Citrus Fans",
"brand_name": "Example Inc",
"call_to_action": "LISTEN",
"top_snap_media_id": "647e6398-7e44-4ae5-a19d-c400b93bce32",
"top_snap_crop_position": "MIDDLE",
"web_view_properties": {
"url": "https://www.example.com/intro?utm_source=snapchat&utm_medium=paidsocial&utm_campaign=2019_citrus",
"deep_link_urls": [],
"block_preload": true
},
"ad_product": "SNAP_AD",
"profile_properties": {
"profile_id": "62cf5c50-8343-48d3-a0a7-3ed45b75fa10"
}
}
}
]
}
HTTP Request
You can associate a profile during create or update
POST/PUT https://adsapi.snapchat.com/v1/creatives/{creative_id}/snapcode
URL Parameters
Parameter | Description |
---|---|
creative_id | The ID of the creative to retrieve |
HTTP Request
You can associate a profile during create or update
POST/PUT https://adsapi.snapchat.com/v1/creatives/{creative_id}/snapcode
URL Parameters
Parameter | Description |
---|---|
creative_id | The ID of the creative to retrieve |
HTTP Request
You can associate a profile during create or update
POST/PUT https://adsapi.snapchat.com/v1/creatives/{creative_id}/snapcode
URL Parameters
Parameter | Description |
---|---|
creative_id | The ID of the creative to retrieve |