Skip to main content

How it works

You define an event source (a stream of conversions you send with log_event) 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). 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 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.
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. Over MCP, call open_connections_page with a connectionId and accountId:
To read the same list as data, call get with the connection, its inventory and one account:
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:
Saving asks the seller account to confirm the dataset straight away. Read the event source to see where it stands:
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:
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. 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.

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. 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).
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:
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:
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