How It Works

Request Validation The API validates the incoming request: it must be multipart/form-data , the users field must be a valid JSON array, and the array must contain at least one user.

Payload Parsing The form data fields (name, type, batch, users) are extracted. The type defaults to "custom" if not provided. The batch and users fields are parsed from JSON strings.

Telemetry Logging The API records tracing data (audience name, session ID, batch sequence, user count, type) for observability and debugging.

Provider Fan-Out The system iterates through all configured providers that support audience syncing. For each provider and each tag configuration, a task is created. Each provider receives:

• The full audience payload (name, type, batch, users)

• The disablePrefix flag

• Provider-specific configuration variables (API keys, account IDs, etc.)

Provider Processing Each provider independently:

• Looks up or creates the audience segment in its platform

• Transforms user data to its required format (e.g., SHA256 hashing for Facebook)

• Uploads the user list to the platform's API

Response In default (async) mode, the API responds immediately with success while providers process in the background. In sync mode ( ?sync=true ), it waits for all providers and returns errors if any failed.

Supported Providers

Facebook (Meta Ads)

What it does: Creates or updates Custom Audiences in Facebook Ads Manager.

Data handling: Hashes user PII (email, phone, country) using SHA256 before sending to Facebook's API. Supports both primary and custom audience types.

Segment naming: Prefixes with blotout_ by default (e.g., blotout_High_Value_Customers ).

TikTok Ads

Klaviyo