Reach and Frequency Guide
Reach and Frequency buying allows advertisers to purchase reach-optimized campaigns via the API. This feature is currently in beta and available on a whitelist basis only. Please contact your Snap Account Manager to setup access.
Create R&F Campaign
- Campaign status must be set to 'ACTIVE'
- buy_model must be set to 'RESERVED'
- objective must be set to 'BRAND_AWARENESS'
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"campaigns": [{"name": "Audience Filter Campaign", "ad_account_id": "3b0fbace-04b4-4f04-a425-33b5e0af1dab", "status": "ACTIVE", "start_time": "2018-08-11T22:00:00.000Z", "buy_model": "RESERVED", "objective": "BRAND_AWARENESS"}]}' \
"https://adsapi.snapchat.com/v1/adaccounts/3b0fbace-04b4-4f04-a425-33b5e0af1dab/campaigns"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b002ad00ff07e1f50fd2267f0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
"campaigns": [
{
"sub_request_status": "success",
"campaign": {
"id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
"updated_at": "2016-08-14T05:33:33.876Z",
"created_at": "2016-08-14T05:33:33.876Z",
"name": "Audience Filter Campaign",
"ad_account_id": "3b0fbace-04b4-4f04-a425-33b5e0af1dab",
"status": "ACTIVE",
"start_time": "2018-08-11T22:00:00.000Z",
"objective": "BRAND_AWARENESS",
"buy_model": "RESERVED"
}
}
]
}
This will create a campaign within a specified ad account. Once a R&F campaign is booked we do not allow for edits to the campaign or ad squad. Edits, or a re-booking, is only allowed if the initial booking fails.
Re-booking is done only if your initial R&F Ad Squad booking request is FAILED. In addition, we reserve the right to remove any advertiser from the R&F program if we see an excessive number of cancellations.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/campaigns
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad_account_id | Ad Account ID |
Create a Forecasting Request
Before creating the Reach & Frequency Ad Squad you will need to make a forecasting request using the Ad Squad with the placement, targeting spec and frequency cap that you wish to use.
The forecasting request will return a reach curve showing the estimated reach based on your targeting and which budget you need to apply for a certain estimated reach.
- Reach & Frequency Lenses and Single Image and Video ads are currently available in the Australia, Belgium, Brazil, Canada, Denmark, France, Germany, India, Ireland, Italy, Kuwait, Mexico, Netherlands, Norway, Saudi Arabia, Spain, Sweden, UAE, UK, and US.
- Minimum reach of at least 500,000 unique users.
- Booking / Set-Up Timing: No less than 12 hours in advance and no greater than 365 days from current time.
- Radius targeting and LOI targeting are not permitted.
- Customer List targeting is allowed but dependent on Customer List segments being available for forecasting.
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"placement_v2":{"config":"AUTOMATIC"},"targeting":{"geos":[{"country_code":"us"}],"demographics":[{"gender":"MALE"}]},"delivery_constraint":"REACH_AND_FREQUENCY","start_time":"2020-08-28T14:08:04+01:00","end_time":"2020-09-29T14:08:04+01:00","optimization_goal":"VIDEO_VIEWS","cap_and_exclusion_config":{"frequency_cap_config":[{"frequency_cap_count":1,"frequency_cap_type":"IMPRESSIONS","time_interval":7,"frequency_cap_interval":"DAYS"}]}}' \
"https://adsapi.snapchat.com/v1/adaccounts/3b0fbace-04b4-4f04-a425-33b5e0af1dab/reserved_forecasting"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b3e5c9600ff0675dc615cb9090001737e616473617069736300016275696c642d31346237626365612d312d3138312d300001010b",
"reach_frequency_curve": [
{
"impression": 254240,
"reach": 250320,
"budget_micro": 610557576
},
{
"impression": 1300320,
"reach": 1211840,
"budget_micro": 3121198726
},
// snip
{
"impression": 102770081,
"reach": 29095360,
"budget_micro": 729561535468
},
{
"impression": 104879041,
"reach": 29445920,
"budget_micro": 847933759640
}
],
"display_message": "",
"debug_message": "",
}
}
Required Ad Squad attributes - Forecasting request
| Attribute | Description | Possible Values |
|---|---|---|
| placement_v2 | Placement for the Ads | Placement V2 |
| targeting | Targeting of the Ads | Targeting Spec |
| delivery_constraint | REACH_AND_FREQUENCY | |
| start_time | Start time | |
| end_time | End time | |
| type | Ad Squad type | SNAP_ADS, LENS |
| optimization_goal | Optimization Goal based on Ad Squad type | For SNAP_ADS the optimization_goal has to be VIDEO_VIEWS, for LENS the optimization_goal has to be USES |
| cap_and_exclusion_config | Frequency Cap Spec |
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/reserved_forecasting
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad_account_id | Ad Account ID |
Create R&F Ad Squad
When creating the Reach & Frequency ad squad you should use the same Ad Squad values used in the Forecast request for Placement V2,
targeting and frequency cap. Additionally you should also use the values impression, reach and budget_micro returned in the forecast.
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adsquads": [{"name": "Snap Ad, United States, All Genders, All Ages", "placement_v2": {"config": "AUTOMATIC"}, "start_time": "2018-07-08T15:13:36-07:00", "end_time": "2018-08-07T15:13:36-07:00", "delivery_constraint": "REACH_AND_FREQUENCY", "pixel_id": null, "campaign_id": "319bcd47-3d99-4d3b-a39a-33c3fbea470b", "daily_budget_micro": null, "targeting": {"geos": [{"country_code": "us"}]}, "cap_and_exclusion_config": {"frequency_cap_config": [{"frequency_cap_count": 2, "time_interval": 7, "frequency_cap_interval": "DAYS", "frequency_cap_type": "IMPRESSIONS"}]},"type": "SNAP_ADS", "conversion_window": null, "status": "ACTIVE", "auto_bid": false, "optimization_goal": "VIDEO_VIEWS", "reach_goal": 39084400, "impression_goal": 132528801, "lifetime_budget_micro": 484048584430, "reach_and_frequency_status": "PENDING"}]}' \
https://adsapi.snapchat.com/v1/campaigns/a09f983a-06ac-4081-9659-7bc9e1cd6888/adsquads
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b3e983d00ff059adbd17a39bd0001737e7465616d6b6f363139000161646d616e616765722d6170693a6275696c642d31623031633134632d312d3138322d3000010116",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "5fd79efb-e544-4d43-9e59-9e6a88f8232e",
"updated_at": "2018-07-05T22:14:21.824Z",
"created_at": "2018-07-05T22:14:21.824Z",
"name": "Snap Ad, United States, All Genders, All Ages",
"status": "ACTIVE",
"campaign_id": "319bcd47-3d99-4d3b-a39a-33c3fbea470b",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"auto_bid": false,
"lifetime_budget_micro": 484048584430,
"start_time": "2018-07-08T22:13:36.000Z",
"end_time": "2018-08-07T22:13:36.000Z",
"optimization_goal": "VIDEO_VIEWS",
"impression_goal": 132528801,
"reach_goal": 39084400,
"cap_and_exclusion_config": {
"frequency_cap_config": [
{
"frequency_cap_count": 2,
"frequency_cap_type": "IMPRESSIONS",
"time_interval": 7,
"frequency_cap_interval": "DAYS"
}
],
"is_industry_exclusive": false,
"is_industry_competitively_separated": false
},
"delivery_constraint": "REACH_AND_FREQUENCY",
// Will automatically update to ACTIVE or FAILED
"reach_and_frequency_status": "PENDING",
"reach_and_frequency_rate_micro": 3652402
}
}
]
}
This creates an Ad Squad within a Campaign. For R&F Ad Squads there can only be one Ad Squad under a Campaign.
Attributes for R&F Ad Squad
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| campaign_id | Campaign ID | R | |
| bid_micro | Max Bid (micro-currency) | Must not be included | |
| billing_event | Billing Event | R | IMPRESSION |
| daily_budget_micro | Daily Budget (micro-currency) | R | Must be set to null |
| start_time | Start time | R | Must be greater than or equal to 2 days and less than or equal to 90 days from current time |
| end_time | End time | R | DIfference between end_time and start_time must be greater than or equal to 3 days and less than or equal to 90 days |
| name | Ad Squad name | R | |
| optimization_goal | Optimization Goal | R | Must be set to VIDEO_VIEWS (Optimizes for Reach and Frequency) for Snap Ads, or USES for Lenses |
| placement_v2 | Placement | R | Json object containing advanced placement options See placement_v2 |
| status | Ad Squad status | R | Must be set to ACTIVE |
| targeting | Targeting spec | R | |
| type | Ad Squad Type | R | SNAP_ADS, LENS |
| included_content_types | Content Type to be included | O | NEWS, ENTERTAINMENT, SCIENCE_TECHNOLOGY, BEAUTY_FASHION, MENS_LIFESTYLE, WOMENS_LIFESTYLE, GENERAL_LIFESTYLE, FOOD, SPORTS, YOUNG_BOLD |
| excluded_content_types | Content Type to be excluded | O | NEWS, ENTERTAINMENT, SCIENCE_TECHNOLOGY, BEAUTY_FASHION, MENS_LIFESTYLE, WOMENS_LIFESTYLE, GENERAL_LIFESTYLE, FOOD, SPORTS, YOUNG_BOLD |
| cap_and_exclusion_config | The frequency cap and exclusion spec | R | |
| lifetime_budget_micro | Lifetime budget (micro-currency) | R | Must match the desired budget value defined as budget_micro in the forecasting request |
| reach_goal | Reach goal as specified in the Forecasting request | R | Must match the reach value in the forecasting request |
| impression_goal | Impression goal as specified in the Forecasting request | R | Must match the impression value in the forecasting request |
| ad_scheduling_config | The schedule for running ads | N/A | Should not be set |
| auto_bid | Allow Snapchat to automatically set the bid to recommended amount | R | Must be set to 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 | R | Must be set to false |
| pixel_id | Pixel to be associated with the Ad Squad | O | |
| delivery_constraint | Type of delivery | R | REACH_AND_FREQUENCY |
| reach_and_frequency_status | Status of the reach and frequency booking | R | Must be set to PENDING which automatically updates to ACTIVE or FAILED after booking |
HTTP Request
POST https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads
Parameters
| Parameter | Default | Description |
|---|---|---|
| campaign_id | Campaign ID |
Updating R&F Ad Squads and Rebooking
Once you create an AdSquad the reach_and_frequency_status will be PENDING. This will be automatically updated to ACTIVE or FAILED by our booking service within a minute. If it is FAILED, you can rebook with the same Ad Squad by doing an UPDATE on the AdSquad.
You would issue a new Forecasting Request and then update the Ad Squad, providing the ID, while setting the reach_and_frequency_status from FAILED to PENDING, passing new impression_goal, reach_goal, and lifetime_budget_micro values from the forecast.
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"adsquads": [{"id": "39df6afb-fbea-4a9d-8b5e-8899ab4f4890", "name": "Snap Ad, United States, All Genders, All Ages", "type": "SNAP_AD", "status": "ACTIVE", "campaign_id": "cfeb4b9c-8464-4498-9906-b4eb2d6c56ac", "placement_v2": {"config": "AUTOMATIC"}, "auto_bid": false, "lifetime_budget_micro": 200000000000, "optimization_goal": "VIDEO_VIEWS", "targeting": {"geos": [{"operation": "INCLUDE", "country_code": "us"}], "regulated_content": false}, "start_time": "2018-07-08T15:13:36-07:00", "end_time": "2018-08-07T15:13:36-07:00", "cap_and_exclusion_config": {"frequency_cap_config": [{"frequency_cap_count": 4, "time_interval": 7, "frequency_cap_interval": "DAYS", "frequency_cap_type": "IMPRESSIONS"}]}, "delivery_constraint": "REACH_AND_FREQUENCY", "reach_goal": 2263600, "lifetime_budget_micro": 200000000000, "impression_goal": 13975600, "reach_and_frequency_status": "PENDING"}]}'
https://adsapi.snapchat.com/v1/campaigns/cfeb4b9c-8464-4498-9906-b4eb2d6c56ac/adsquads
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b3e983d00ff059adbd17a39bd0001737e7465616d6b6f363139000161646d616e616765722d6170693a6275696c642d31623031633134632d312d3138322d3000010116",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "5fd79efb-e544-4d43-9e59-9e6a88f8232e",
"updated_at": "2018-07-05T22:14:21.824Z",
"created_at": "2018-07-05T22:14:21.824Z",
"name": "Snap Ad, United States, All Genders, All Ages",
"status": "ACTIVE",
"campaign_id": "319bcd47-3d99-4d3b-a39a-33c3fbea470b",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"auto_bid": false,
"lifetime_budget_micro": 200000000000,
"start_time": "2018-07-08T22:13:36.000Z",
"end_time": "2018-08-07T22:13:36.000Z",
"optimization_goal": "VIDEO_VIEWS",
"impression_goal": 13975600,
"reach_goal": 2263600,
"cap_and_exclusion_config": {
"frequency_cap_config": [
{
"frequency_cap_count": 4,
"frequency_cap_type": "IMPRESSIONS",
"time_interval": 7,
"frequency_cap_interval": "DAYS"
}
],
"is_industry_exclusive": false,
"is_industry_competitively_separated": false
},
"delivery_constraint": "REACH_AND_FREQUENCY",
// Will automatically update to ACTIVE or FAILED
"reach_and_frequency_status": "PENDING",
"reach_and_frequency_rate_micro": 3652402
}
}
]
}
This endpoint will update a specified ad squad.
Attributes that must be updated
| Attribute | Description |
|---|---|
| reach_and_frequency_status | Must be set back to PENDING |
| impression_goal | Must be set to new value from new forecasting request |
| reach_goal | Must be set to new value from new forecasting request |
| lifetime_budget_micro | Must be set to new value from new forecasting request |
HTTP Request
PUT https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads
Parameters
| Parameter | Default | Description |
|---|---|---|
| campaign_id | Campaign ID |
Create the Ad
R&F can be used with creatives of type Snap Ads or type Lens. Ads follow the type of creative as explained here
Cancelling R&F booking
There are four ways to cancel a booking. Please be aware that cancelling bookings frequently will lead to removal from the R&F program.
- Updating the AdSquad status to PAUSED
- Deleting the AdSquad
- Updating the Campaign status to PAUSED
- Deleting the Campaign
Was this page helpful?