Audiences

An audience is a set of people you target or exclude. Some you fill yourself by uploading emails (customer lists). Others the network fills from a pixel, a seed list or engagement with your Page or videos. Create every type with POST /v1/ads/audiences, then put its platformAudienceId in audienceInclude or audienceExclude on a create.

#Upload a customer list

curl -X POST https://api.pozy.ai/v1/ads/audiences \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
    "adAccountId": "act_1234567890",
    "name": "Customers - last 12 months",
    "type": "customer_list",
    "description": "Paid at least once since November 2025"
  }'

const res = await fetch("https://api.pozy.ai/v1/ads/audiences", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    accountId: "66b2e19d8c3f5a7e9d0b1c2d",
    adAccountId: "act_1234567890",
    name: "Customers - last 12 months",
    type: "customer_list",
    description: "Paid at least once since November 2025",
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
const audienceId = data.audience.id;

import os, requests

resp = requests.post(
    "https://api.pozy.ai/v1/ads/audiences",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={
        "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
        "adAccountId": "act_1234567890",
        "name": "Customers - last 12 months",
        "type": "customer_list",
        "description": "Paid at least once since November 2025",
    },
)
audience_id = resp.json()["audience"]["id"]

curl -X POST https://api.pozy.ai/v1/ads/audiences/66e5b2c3d4f5a6b7c8d9e0f1/users \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "users": [ { "email": "maria@example.com" }, { "email": "sam@example.org", "phone": "+14155551234" } ] }'

{ "message": "Users added", "numReceived": 2, "numInvalid": 0 }

#Hashing and matching

You send plain values. Pozy normalizes them (trims, lowercases emails, formats phones) and hashes them with SHA-256 before they leave Pozy, so the networks never receive raw contact details. You do not need to hash anything yourself.

A phone on a network that matches on email only is ignored. A row that cannot be read counts in numInvalid.

#Audience types

type on POST /v1/ads/audiences picks what the audience is built from.

Using a type on the wrong network's account returns 422. Meta's meta_engagement and LinkedIn's engagement are different audiences with different fields.

#Lookalikes on Meta

Upload members to the seed list first, then create the lookalike from it. Meta builds it from the seed's matched members, so check the seed's size with GET /v1/ads/audiences/{audienceId} before you create. ratio: 0.01 is the closest 1% of the country.

{
  "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
  "adAccountId": "act_1234567890",
  "name": "Lookalike 1% US - customers",
  "type": "lookalike",
  "sourceAudienceId": "23851234567890123",
  "country": "US",
  "ratio": 0.01
}

#LinkedIn company lists

Company lists target or exclude whole companies. Each row needs at least one of name, domain, website or linkedinPageUrl. LinkedIn matches rows against its company graph within 48 hours. To change the list, send the complete new list to POST /v1/ads/audiences/{audienceId}/companies: it replaces the old one.

#LinkedIn website retargeting

The audience fills only once the site has the LinkedIn Insight Tag installed and reporting visits (Pixels and tags). You can create it before the tag is live.

#Manage audiences

audience.id is Pozy's id, used in the paths above. platformAudienceId is the network's id, used in targeting and as a lookalike seed. Audiences build asynchronously on every network: a size or member read right after an upload can be empty. Read again after a minute instead of uploading again.

#Errors

#Endpoints