---
title: "Add users to audience"
method: POST
path: "/v1/ads/audiences/{audienceId}/users"
tags: ["Ad Audiences"]
---

# Add users to audience

`POST /v1/ads/audiences/{audienceId}/users`

## Request

- Base URL: `https://zernio.com/api`
- URL: `https://zernio.com/api/v1/ads/audiences/{audienceId}/users`
- Auth: HTTP bearer

Uploads customer emails (and phone numbers on Meta) to a customer list audience, hashed before they are sent.

Data is SHA256-hashed server-side before sending to the platform.
Email is used on every platform; phone is used on Meta only (other platforms ignore it). On TikTok and Pinterest,
the first upload also provisions the audience (deferred create). LinkedIn uploads are full-replace. Max 10,000 users per request.

customer_list only. A LinkedIn `company_list` audience takes company rows, not people: send those to
`POST /v1/ads/audiences/{audienceId}/companies`. This endpoint 422s for every other audience type.

## Path parameters

- `audienceId` string, required

## Request body

- object
  - `users` object[], required
    - `email` string, email
    - `phone` string

## Response `200`

Users added

- object
  - `message` string
  - `numReceived` integer
  - `numInvalid` integer

## Other responses

- `400`: Invalid input (malformed audienceId, empty users array, missing email/phone)
- `401`: Missing or invalid API key. `code` is `missing_credentials` when no Authorization header was sent and `invalid_credentials` when the key is unknown, revoked or expired.
- `403`: Ads access required. Legacy plans need the Ads add-on; included by default on usage-based plans. Also returned with code `ad_account_not_selected` when the connection has selected ad accounts and the ad account this request targets is not among them; `details` carries `accountId`, `adAccountId` and `selectedAdAccountIds`. Add the ad account to the selection (GET /v1/connect/{platform}/ads with adAccountIds, which replaces the selection) or use a connection that has it selected.
- `404`: Resource not found
- `422`: Audience is not a customer_list type or has no platform ID yet

## Changes

- **2026-10-06** `f8c8f34fb41a`: 1 warning
  - added the new `account` enum value to the `details/budgetScope` response property for the response status `401`
- **2026-10-02** `d556591af3f6`: 7 info
  - added the optional property `code` to the response with the `401` status
  - added the optional property `details` to the response with the `401` status
  - added the optional property `docUrl` to the response with the `401` status
  - added the optional property `param` to the response with the `401` status
  - …3 more

[Operation history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/ads/audiences/:audienceId/users/post.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) · [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/4e74db179e73?raw)