Ad Engagement

Ad Engagement Audiences provide a way to target users who have taken a specific action on ads with an ad account or specific campaign(s) within an ad account.

Attributes

Attribute	Description	Required	Possible Values
name	Audience segment name	R	375 characters max
ad_account_id	Ad account ID for the new audience	R	XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
engagement_specs	An array of first-party engagement specs	R	See below example
source_type	Overall data source type	R	ENGAGEMENT
source_subtype	Overall data source subtype	R	AD_ENGAGEMENT
retention_in_days	# of days to retain audience members	R	Keep this value at 395 days

Engagement Specs

Each object in engagement_specs is OR(ed) by default, it's the only operative supported.

Attribute	Description	Required	Possible Values
engagement_type	The type of engagement the user had with the entity	R	SNAP_ADS_SWIPE_UP, SNAP_ADS_TOP_VIEW_THRU_100, PROMOTED_STORY_TAP, CREATIVE_TOOLS_USE, PAID_IMPRESSIONS, NATIVE_LEAD_GEN_SUBMITTED
source_type	The entity type used to seed the audience	R	AD_SQUAD, CAMPAIGN, AD_ACCOUNT
source_id	The ID of the entity used to seed the audience, these entities must live in the Ad Account specified for the segment	R

Engagement type

This table describes the user engagements available via the engagement_type attribute.

Description	engagement_type
Clicked on an Image or a Video Ad	SNAP_ADS_SWIPE_UP
Completed watching a Top Snap video ad	SNAP_ADS_TOP_VIEW_THRU_100
Opened a Story Ad	PROMOTED_STORY_TAP
Shared or saved a Lens or a Filter	CREATIVE_TOOLS_USE
Were served a paid Ad impression	PAID_IMPRESSIONS
Submitted a native lead generation form	NATIVE_LEAD_GEN_SUBMITTED

Example request

In this example, the first engagement spec item specifies any Promoted Story Tap within the specified Campaign Id. The second engagement spec item again sets the conditions of a Promoted Story Tap but this time within the specified Ad Account Id.

curl -X POST 'https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/segments' \
--header 'Authorization: Bearer meowmeowmeow' \
--header 'Content-Type: application/json' \
--data '{
  "segments": [
    {
      "name": "Ad_Engagement_Test",
      "ad_account_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "engagement_specs": [
        {
          "engagement_type": "PROMOTED_STORY_TAP",
          "source_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
          "source_type": "CAMPAIGN"
        },
        {
          "engagement_type": "PROMOTED_STORY_TAP",
          "source_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
          "source_type": "AD_ACCOUNT"
        }
      ],
      "source_type": "ENGAGEMENT",
      "source_subtype": "AD_ENGAGEMENT",
      "retention_in_days": 395
    }
  ]
}'