AddUsersToAudience

This action adds users to an existing Facebook Ads custom audience using a matching key or a combination of keys, such as email addresses, phone numbers, names, or mobile advertiser IDs.

Skyvia sends the supplied data to Facebook Ads without normalizing or hashing it. Prepare the values according to Facebook's rules for the selected schema, including SHA-256 hashing where required. For plain email addresses, use AddUserEmailsToAudience to let Skyvia normalize and hash them automatically.

Action Parameters

| Parameter | Description | | AudienceId |String, required. ID of the existing custom audience. You can find it in the Audiences object. | | Schema |String, required. Matching key, such as EMAIL_SHA256, or a JSON array of matching keys, such as ["EMAIL", "FN", "LN"].| | Data |String, required. JSON array of user data corresponding to Schema. For multiple keys, supply an array of rows with values in the same order as the keys. Normalize and hash values where Facebook requires it.| | IsRaw |Boolean, optional. Facebook's is_raw flag for matching keys. Set to false for combined keys such as LN_FN_ZIP, or true for individual keys, as required by the selected schema. This flag does not make Skyvia hash the input.| | Session |String, optional. JSON object with upload session information, such as session_id, batch_seq, last_batch_flag, and estimated_num_total, for tracking batches.| | DataSource |String, optional. JSON object describing the audience data source through its type and subtype.| | AppIds |String, optional. JSON array of app IDs. Required by Facebook when using Facebook user IDs collected through an app integration.| | PageIds |String, optional. JSON array of page IDs. Required by Facebook when using Facebook user IDs collected through a Page webhook integration.|

For example, with Schema set to EMAIL_SHA256, Data can contain this JSON array with the SHA-256 hash of the normalized address mary@example.com:

["f1904cf1a9d73a55fa5de0ac823c4403ded71afd4c3248d00bdcd0866552bb79"]

For a multi-key schema such as ["EMAIL", "FN", "LN"], use a two-dimensional Data array. Each row contains the prepared email, first-name, and last-name values in that order. Leave an unknown key's value as an empty string.

See Facebook's Custom Audience Users reference for payload options and hashing and normalization rules for preparing matching keys.

Result

The action submits the user data to Facebook Ads and returns the following fields:

|Field |Type |Description | |AudienceId |String |ID of the audience receiving the data. | |SessionId |String |Upload session ID returned by Facebook Ads. | |NumReceived |Int32 |Number of submitted user entries received by Facebook Ads for the session. This is not a count of matched audience members. | |NumInvalidEntries |Int32 |Number of entries reported as invalid by Facebook Ads. | |InvalidEntrySamples |String |Samples of invalid entries returned by Facebook Ads. |

Facebook processes audience updates asynchronously, so the audience's membership may not change immediately.