> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use your event sources and audiences on each seller account

> Map your event sources and audiences to the pixels, datasets and lists on each seller account, so conversion goals and audience targeting work on every platform you buy on

## How it works

You define an **event source** (a stream of conversions you send with
[`log_event`](https://docs.apostra.com/v2/guides/log-events)) or an **audience** (a list of people you
sync with `save_audience`) once, for the advertiser. A seller account such as a
Meta ad account or a Snap ad account only understands its own objects: a Meta
dataset, a Snap Pixel, a TikTok pixel, a LinkedIn conversion rule, a Meta Custom
Audience. A **mapping** tells Apostra which of those objects is the same thing
as yours on that account.

There are two kinds of object on a seller account:

* **Yours, once mapped.** A pixel you map to one of your event sources works
  in every campaign that runs on that account. An audience you map is checked
  on the account and shows the seller's size and match rate there. An audience
  already on an ad account mapped to an advertiser is that advertiser's audience
  already, mapped for you (see
  [Audiences already on your ad accounts](https://docs.apostra.com/v2/guides/map-event-sources-and-audiences.md#audiences-already-on-your-ad-accounts)). A campaign
  can target or exclude it on a seller that takes mapped audiences, and a
  seller that does not take them blocks the campaign's launch.
  [Campaign audiences](https://docs.apostra.com/v3/campaign-targeting.md#campaign-audiences-and-catalogs)
  lists which sellers take them.
* **Seller-managed or unmapped.** Objects that belong to one storefront, such as
  a Meta Instant Forms leads source, or any object you leave unmapped, stay
  specific to that storefront. They pass through unchanged and are usable in
  that storefront's own campaigns. You cannot map your event sources to
  seller-managed objects: a save that names one is refused with
  `VALIDATION_ERROR` on the entry's `platformId`.

The flow is always map, confirm, buy:

1. **Map.** Save the mapping with `sellerAccounts` on `save_event_source` or
   `save_audience`, or pick it on the Connections page.
2. **Confirm.** Apostra asks the seller account to confirm the object is there.
   The mapping reads `pending`, then `synced`, typically within a minute. An
   audience also reports the seller's own size and match rate.
3. **Buy.** When a media buy's optimization goal names your event source, or
   its campaign targets or excludes your audience, Apostra sends the seller the
   mapped platform object instead of your id.

Apostra never creates a pixel or a dataset for you. Create it in the platform's
own console first, then map it. Saving a mapping reads what is on the account and
records one id; it never changes anything on the platform.

> [!NOTE]
>
> **Action needed if you name your own event sources in conversion goals.** Map
> each event source on every seller account you buy on. A media buy whose goal
> names an event source with no mapping on that account fails before anything
> reaches the seller, unless the event source's own id is the id of a pixel or
> dataset on that account: then that pixel is used, as if you had mapped it.
> Goals that carry a raw platform pixel id, buys with no event goal, and a Meta
> product's explicit `pixelId` behave as before.

## Find what is on each account

Open the Connections page for one connected account. It lists the pixels,
datasets and audiences already there, and whether each is yours (**Mapped to**)
or only on that storefront. On Meta, the list holds every audience your
connection can see on the ad account, including audiences you made in Meta
such as lookalike and website audiences. Partner segments shared by a data
provider are not listed and cannot be mapped. See
[Open Media Partners](https://docs.apostra.com/v2/buyer/storefronts/tasks/open-connections-page.md#event-sources-and-audiences-on-a-connected-account).

Over MCP, call `open_connections_page` with a `connectionId` and `accountId`:

```json theme={null}
{
  "name": "open_connections_page",
  "arguments": { "connectionId": "992", "accountId": "301" }
}
```

To read the same list as data, call `get` with the connection, its inventory and
one account:

```json theme={null}
{
  "kind": "connection",
  "id": "992",
  "include": ["inventory"],
  "connectionAccountId": "301",
  "connectionInventoryObjectType": "event_source"
}
```

Each inventory item carries the platform's own id as `upstreamObjectId`. That is
the value you pass as `platformId` when you map. The account `id` (here `301`) is
the `accounts[].id` from `get({ "kind": "connection", "id": "992" })`.

The inventory read returns live audience and event-source presences. Set
`connectionInventoryObjectType` to `audience` or `event_source` to inspect one
kind. Continue a longer result with `connectionInventoryOffset`; each page has
at most 50 rows. Terminal presences remain on the V2 compatibility read and
are deliberately excluded from V3 inventory.

## Map an event source

Save the event source with `sellerAccounts`. Each entry names the seller account
and the id of the object on it:

```json theme={null}
{
  "advertiserId": "42",
  "idempotencyKey": "map-purchase-completed-2026-10-11-001",
  "eventSources": [
    {
      "eventSourceId": "purchase-completed",
      "name": "Purchase Completed",
      "eventTypes": ["purchase"],
      "actionSource": "website",
      "valueCurrencies": ["USD"],
      "sellerAccounts": [
        { "accountId": "301", "platformId": "1234567890123456" }
      ]
    }
  ]
}
```

Saving asks the seller account to confirm the dataset straight away. Read the
event source to see where it stands:

```json theme={null}
{
  "kind": "event_source",
  "id": "purchase-completed",
  "advertiserId": "42"
}
```

```json theme={null}
{
  "eventSourceId": "purchase-completed",
  "name": "Purchase Completed",
  "sellerAccounts": [
    {
      "accountId": "301",
      "storefront": { "id": "84", "name": "Meta" },
      "platformId": "1234567890123456",
      "status": "synced",
      "lastSyncedAt": "2026-10-11T14:02:11.000Z",
      "health": null
    }
  ]
}
```

`platformId` is the object you mapped, from the moment you save it. `status` is
`pending` until the seller account confirms it, then `synced`. If you change the
mapping on an account that already uses a confirmed object, `platformId` shows
the new one and the account reads `pending`, or names why the seller refused
it, while media buys already on that account keep using the confirmed one. Mapping an event source sends none of your conversion data to the
seller: Apostra only checks which pixel or dataset on the account the source
uses. So mapping needs no data-sharing setting, and the **Conversion events**
switch on the Connections page does not affect it.

### Event types must match

A destination that declares the event types it accepts must accept every type
your source records. A LinkedIn conversion rule records one type, so it maps only
to a source whose `eventTypes` are all on that rule's list. A source with no
`eventTypes` records every type, so it maps only to a destination that declares
none. Meta, Snap and TikTok datasets and pixels accept all types. A mismatch is
refused at save time with `VALIDATION_ERROR` on the entry's `platformId`. Narrow
the source's `eventTypes`, or map a destination that accepts them.

## Use the source in a campaign goal

Name the event source in an event goal. Use your own `event_source_id`, not the
platform's id:

```json theme={null}
{
  "campaignId": "5501",
  "idempotencyKey": "campaign-5501-goal-2026-10-11-001",
  "optimizationGoals": [
    {
      "kind": "event",
      "event_sources": [
        {
          "event_source_id": "purchase-completed",
          "event_type": "purchase",
          "value_field": "order_total"
        }
      ],
      "attribution_window": { "post_click": { "interval": 7, "unit": "days" } },
      "priority": 1
    }
  ]
}
```

When a media buy on that account is created from this goal, the request Apostra
sends the seller carries the mapped dataset id. Your media buy keeps showing your
own `event_source_id`. Seller-managed sources and a platform's built-in events
are sent unchanged.

### When a buy is refused

A media buy whose goal names an event source that cannot be used on that account
fails before anything reaches the seller. A read of the media buy shows
`errorCode: "invalid_request"`, owned by you (`buyer_input`), and the failure
reason starts with one of the codes below. Fix the cause, then create a new media
buy.

| Code | What it means | Fix |
| - | - | - |
| `SELLER_EVENT_SOURCE_DESTINATION_AMBIGUOUS` | The account has pixels or datasets, and you mapped none for this source | Map one: `sellerAccounts` on `save_event_source`, or **Map** on the Connections page |
| `SELLER_EVENT_SOURCE_DESTINATION_MISSING` | The account has none, or the one you named is not on the account, or does not accept every event type your source records | Create the pixel or dataset in the platform's console and map it, or map one that accepts your source's event types |
| `SELLER_OBJECT_TYPE_UNSUPPORTED` | This seller cannot take event sources, such as a managed seller agent | Optimize toward a metric instead, or buy from a seller account that can take event sources |

A mapping that is still being confirmed is not a refusal: the buy is held and
sent once the mapping reads `synced`. If a Meta product on the buy sets an
explicit `pixelId` that differs from the dataset you mapped, the buy is refused
for the conflict. Remove the explicit `pixelId` or map the same dataset.

The full list of blocker codes and what each media-buy state does is in
[Measurement and incrementality](https://docs.apostra.com/v2/guides/measurement-incrementality.md#how-a-source-reaches-each-seller-account).

## Audiences already on your ad accounts

An audience that already exists on a seller account needs no upload and no
mapping. Every live audience on an ad platform account you connected directly,
such as a Meta ad account, that is mapped to an advertiser becomes one of that
advertiser's audiences on its own, already mapped to that account. That
includes a Meta Custom Audience, website audience or lookalike made in Ads
Manager. An account reached through a sales agent is not synced this way; map
an audience there as described in
[Map an audience](https://docs.apostra.com/v2/guides/map-event-sources-and-audiences.md#map-an-audience). Apostra gives it its own `audienceId`, such as
`aud_4fX9kQ2mT7bR1vLz8NcYp`, the first time it sees it. The platform's own
audience id, such as `23850000000012345`, is the `platformId` of its
`sellerAccounts[]` entry for that account, and it carries the platform's name.
One platform audience is one audience: a Meta audience shared into two of the
advertiser's ad accounts is one audience mapped to both. It appears in
`get({ "kind": "audience", "advertiserId": "42" })` once Apostra's hourly read
of the account lists it.

Its `sellerAccounts[]` entry for the account reads `synced` once the platform
reports the audience ready. Target or exclude it by its `audienceId`; Apostra
sends the platform its own id. A platform audience id in `audience_include` or
`audience_exclude` is not an `audienceId`, so a buy that names one is refused.
When the audience is deleted on the platform, or the account no
longer lists it, it stays in the list but reads `SELLER_AUDIENCE_MISSING` on
that account, and a buy that names it is refused. Nothing is uploaded for these
audiences. Their members and name are managed on the platform, so
`save_audience` refuses with `VALIDATION_ERROR` to add or remove their members,
rename them or delete them.

## Map an audience

Map one of your own audiences the same way. The audience must already exist:
save its members first, then map it once it appears in the advertiser's audience
list: `get({ "kind": "audience", "advertiserId": "42" })`. An audience read
takes the advertiser, not an audience id, and returns every audience for it, 50
per page (`audienceOffset` pages on).

```json theme={null}
{
  "advertiserId": "42",
  "audiences": [
    {
      "audienceId": "loyal-customers",
      "sellerAccounts": [
        { "accountId": "301", "platformId": "23850000000012345" }
      ]
    }
  ]
}
```

An entry that only maps sends no members. Saving asks the seller account to
confirm the audience is there. Read it back with the same listing,
`get({ "kind": "audience", "advertiserId": "42" })`, and find the audience by
`audienceId`; each of its `sellerAccounts[]` entries carries `status`, `platformId`, and, once confirmed, the seller's own size
and match in `match`:

```json theme={null}
{
  "accountId": "301",
  "storefront": { "id": "84", "name": "Meta" },
  "platformId": "23850000000012345",
  "status": "synced",
  "blocker": null,
  "lastSyncedAt": "2026-10-11T14:03:40.000Z",
  "match": {
    "matched_count": 48210,
    "effective_match_rate": 0.62
  }
}
```

`match` is `null` until the mapping is confirmed or when the seller reports
nothing. If the audience is not on the account, or the seller reports it
deleted, suspended or failed, the mapping reads `SELLER_AUDIENCE_MISSING`.
Check the id on the Connections page and map the right audience.
If the platform lists the audience but cannot deliver ads to it yet, because it
is still being built or is too small, the mapping stays `pending` with
`SELLER_OBJECT_SYNC_PENDING`. It is checked again about every hour and confirms
once the platform can deliver to it, so you don't need to map it again.

A media buy that needs an audience the account can't use is refused before
anything reaches the seller. Its failure reason starts with the blocker code and
names the audience by name and audience id. For an audience the platform lists
but can't deliver to yet, the code is `SELLER_OBJECT_SYNC_PENDING` with
correctable recovery, and the reason says what the platform reported. If the
platform is still processing the audience, wait for it to finish. If the
platform reports the audience below its minimum size for targeting, waiting
will not help, and the reason says so. Add members to an audience you sync with
`save_audience`. For an audience synced in from the ad account, rebuild or
refresh it on the platform. Meta, for example, reports an inactive lookalike as
too small. Or remove the audience from the media buy. Create the media buy again
once the mapping reads `synced`. `SELLER_OBJECT_SYNC_FAILED` is kept for a check
that failed outright.

On a seller that takes campaign audiences, a media buy whose
`audience_include` or `audience_exclude` names an id that is not one of the
advertiser's audiences is refused the same way, with
`SELLER_AUDIENCE_MISSING`, and its reason names each such id. Use an
`audienceId` that `get({ "kind": "audience", "advertiserId": "42" })` lists, or
create the audience with `save_audience`.

## Unmap

To end a mapping, send the account with `unmap: true` instead of a `platformId`.
This works the same on `save_event_source` and `save_audience`:

```json theme={null}
{
  "advertiserId": "42",
  "idempotencyKey": "unmap-purchase-completed-2026-10-11-002",
  "eventSources": [
    {
      "eventSourceId": "purchase-completed",
      "sellerAccounts": [{ "accountId": "301", "unmap": true }]
    }
  ]
}
```

Unmapping ends Apostra's mapping on that account only. It never deletes or
changes the pixel, dataset or audience on the platform. While a live media buy
uses the mapping, the unmap fails with `INVALID_STATE` and names the media buys;
unmap once they have ended or been canceled. A later media buy on that account
that names the source fails as if it were never mapped.

## Troubleshooting

| What you see | Cause | Fix |
| - | - | - |
| Mapping stays `pending` | The seller account has not confirmed it yet | Wait a minute and read again. If it shows a blocker, follow the fix for that code above |
| `VALIDATION_ERROR` on `platformId` when saving | The destination's declared event types do not cover every type your source records, or the destination is managed by the seller | Map a pixel or dataset you manage that accepts your source's event types, or narrow the source's `eventTypes` |
| `REFERENCE_NOT_FOUND` when saving | The `accountId` is not an active connected account of yours, or the audience does not exist yet | Take `accountId` from `get({ "kind": "connection" })`. An audience already on an ad account mapped to the advertiser appears on its own, with its own `audienceId`, once the account's hourly read lists it; for a new audience, save its members first |
| `VALIDATION_ERROR` on `audienceId` when saving members | The audience is already on one of your ad accounts, so its members and name are managed there | Change it on the platform, or save your list under a new `audienceId` |
| `INVALID_STATE` when unmapping | A live media buy uses the mapping | Unmap after the media buys end or are canceled |
| Account shows `status: "failed"` with `SELLER_OBJECT_TYPE_UNSUPPORTED` | The seller cannot take event sources or audiences | Use a seller account that can, or optimize toward a metric |
| An account shows nothing to map | The account has not been read yet, or the seller does not list its objects | Each account is read about once an hour. If the seller will not list, enter the platform id by hand on the Connections page |

## Related

* [Log events](https://docs.apostra.com/v2/guides/log-events.md): send conversions to a registered event source.
* [Measurement and incrementality](https://docs.apostra.com/v2/guides/measurement-incrementality.md): how a source reaches each seller account and every refusal code.
* [Open Media Partners](https://docs.apostra.com/v2/buyer/storefronts/tasks/open-connections-page.md): the Connections page and its account inventory.
* [V3 tool reference](https://docs.apostra.com/v3/tool-reference.md): `save_event_source`, `save_audience`, and the connection inventory read.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.