> For the complete documentation index, see [llms.txt](https://docs.edgetag.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgetag.io/features/audience-api/how-it-works.md).

# 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

{% tabs %}
{% tab title="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 ).
{% endtab %}

{% tab title="TikTok Ads" %}
**What it does:** Creates or updates audience segments in TikTok Ads Manager.\
**Data handling:** Sends user identifiers to TikTok's audience API for matching.\
**Segment naming:** Prefixes with blotout\_ by default. Requires access token and advertiser ID.
{% endtab %}

{% tab title="Klaviyo" %}
**What it does**: Creates or updates segments and profiles in Klaviyo.\
**Data handling**: Creates/updates user profiles with email and phone, then associates them with the segment. Validates phone numbers (US, CA, UK, IE, AU,NZ). Falls back to email-only if phone is invalid.\
**Segment naming:** Prefixes with blotout\_ by default. Processes profiles in\
bulk.
{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.edgetag.io/features/audience-api/how-it-works.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.