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'
• reserved_type must be set to 'REACH_AND_FREQUENCY'

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","reserved_type": "REACH_AND_FREQUENCY", "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",
        "reserved_type": "REACH_AND_FREQUENCY",
        "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.

1. Updating the AdSquad status to PAUSED
2. Deleting the AdSquad
3. Updating the Campaign status to PAUSED
4. Deleting the Campaign