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 本製品 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 本製品 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 本製品 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. |