AddCustomAudienceUsers

Updates a custom audience to add the specified users.

Procedure Specific Info

Configuration

Interacting with custom audience users requires configuring both a schema and payload. The PayloadSchema maps out the PII that will be represented in PayloadData.

PayloadSchema can be set as a single key, resulting in a 1-dimensional array in PayloadData:

EXECUTE AddCustomAudienceUsers 
	@CustomAudienceId='123456789123456789',
	@PayloadSchema='EMAIL_SHA256',
	@PayloadData='["31c5543c1734d25c7206f5fd591525d0295bec6fe84ff82f946a34fe970a1e66", "7df7e024c945682f00f2c6410593f407dec0e870af2a9147a62ac459db35d6b8", ...]'

PayloadSchema can also be set as a JSON array with multiple keys, resulting in a 2-dimensional array in PayloadData:

EXECUTE AddCustomAudienceUsers 
	@CustomAudienceId='120208749119170125',
	@PayloadSchema='["EMAIL", "LN"]', 
	@PayloadData='[
					[
						"[email protected]",
						"Exampleman"
					],
					[
						"[email protected]",
						"Exampletoo"
					],
					...
				  ]'

To apply the "Limited Data Use" flag to users, it should be specified with the special "DATA_PROCESSING_OPTIONS" key in PayloadSchema, and must be provided as a nested array member in PayloadData. If using LDU and non-LDU rows in the same payload, an empty array should be used where LDU is disabled:

EXECUTE AddCustomAudienceUsers 
	@CustomAudienceId='120208749119170125',
	@PayloadSchema='["EMAIL", "DATA_PROCESSING_OPTIONS"]', 
	@PayloadData='[
					[
						"[email protected]",
						"Exampleman",
						["LDU"]
					],
					[
						"[email protected]",
						"Exampletoo",
						[]
					],
					...
				  ]'

Session Management

Facebook Ads only allows a maximum of 10000 users to be added to a custom audience in a single request. If more than 10000 (or PageSize, if set) rows are present in PayloadData, the add-in will break the provided PayloadData down into multiple requests. Note that the SessionId parameter must be set in this case.

Hashing and Normalization

Facebook Ads has strict hashing and normalization rules for Customer File Custom Audience User information submitted through the API. The add-in will handle hashing data (where appropriate) if the HashData parameter is set to true, but not normalizing data. See the Facebook Ads API docs for more information on the necessary data normalization.

Note: For single-key schema, only pre-hashed datatypes (E.G. 'EMAIL_SHA256') are supported by the Facebook Ads API. The add-in expects these data types to already be hashed when provided.

Input


Name	Type	Description
CustomAudienceId	String	The ID of the custom audience to add users to.
PayloadSchema	String	Type of information represented by PayloadData. Should be either a single string, or a JSON array with multiple key types. Supported key types are: EXTERN_ID, EMAIL, PHONE, GEN, DOBY, DOBM, DOBD, LN, FN, FI, CT, ST, ZIP, MADID, COUNTRY
PayloadData	String	JSON array containing keys for each user to add to custom audience. If using multiple key types in schema, should be a two-dimensional array, with each row containing multiple keys in order specified in PayloadSchema.
PayloadAppIds	String	JSON array of integer app IDs used by users being uploaded. Required if PayloadSchema is a Facebook UID and the IDs were collected by an app integration.
PayloadPageIds	String	JSON array of integer page IDs used by users being uploaded. Required if schema is a Facebook UID and the IDs were collected by a Page webhook integration.
PayloadDataSourceType	String	Type of the underlying custom audience. Supported values are: UNKNOWN, FILE_IMPORTED, EVENT_BASED, SEED_BASED, THIRD_PARTY_IMPORTED, COPY_PASTE, CONTACT_IMPORTER, HOUSEHOLD_AUDIENCE
PayloadDataSourceSubType	String	SubType of the underlying custom audience. Supported values are: ANYTHING, NOTHING, HASHES, USER_IDS, HASHES_OR_USER_IDS, MOBILE_ADVERTISER_IDS, EXTERNAL_IDS, MULTI_HASHES, TOKENS, EXTERNAL_IDS_MIX, HOUSEHOLD_EXPANSION, SUBSCRIBER_LIST, WEB_PIXEL_HITS, MOBILE_APP_EVENTS, MOBILE_APP_COMBINATION_EVENTS, VIDEO_EVENTS, WEB_PIXEL_COMBINATION_EVENTS, PLATFORM, MULTI_DATA_EVENTS, IG_BUSINESS_EVENTS, STORE_VISIT_EVENTS, INSTANT_ARTICLE_EVENTS, FB_EVENT_SIGNALS, FACEBOOK_WIFI_EVENTS, AR_EXPERIENCE_EVENTS, AR_EFFECTS_EVENTS, MESSENGER_ONSITE_SUBSCRIPTION, WHATSAPP_SUBSCRIBER_POOL, MARKETPLACE_LISTINGS, AD_CAMPAIGN, GROUP_EVENTS, ENGAGEMENT_EVENT_USERS, CUSTOM_AUDIENCE_USERS, PAGE_FANS, CONVERSION_PIXEL_HITS, APP_USERS, S_EXPR, DYNAMIC_RULE, CAMPAIGN_CONVERSIONS, WEB_PIXEL_HITS_CUSTOM_AUDIENCE_USERS, MOBILE_APP_CUSTOM_AUDIENCE_USERS, COMBINATION_CUSTOM_AUDIENCE_USERS, VIDEO_EVENT_USERS, FB_PIXEL_HITS, IG_PROMOTED_POST, PLACE_VISITS, OFFLINE_EVENT_USERS, EXPANDED_AUDIENCE, SEED_LIST, PARTNER_CATEGORY_USERS, PAGE_SMART_AUDIENCE, MULTICOUNTRY_COMBINATION, PLATFORM_USERS, MULTI_EVENT_SOURCE, SMART_AUDIENCE, LOOKALIKE_PLATFORM, SIGNAL_SOURCE, MAIL_CHIMP_EMAIL_HASHES, CONSTANT_CONTACTS_EMAIL_HASHES, COPY_PASTE_EMAIL_HASHES, CUSTOM_DATA_TARGETING, CONTACT_IMPORTER, DATA_FILE
HashData	String	Boolean value indicating if provider should handle hashing of data. Set to true to have the connector hash the provided data before sending to the service. Defaults to false.
SessionId	String	Session ID for upload involving more than 'PageSize' users (default of 10000). If PayloadData contains more than 'PageSize' records, set this value to a positive 64-bit integer.
PageSize	String	Number of records to include in 'PayloadData' in each request. Maximum and default of 10000.

Result Set Columns


Name	Type	Description
Result	String	Success or Failure.
NumReceived	String	Number of custom audience users received as reported by Facebook Marketing API.
NumInvalidEntries	String	Number of invalid entries in PayloadData as reported by Facebook Marketing API.
InvalidEntrySamples	String	JSON map representing samples of invalid entries.