Skip to content
adscapi
← Platforms
Real Conversions API

OBOutbrain setup

Set Outbrain’s tokens once. Then every ads.conversions.track() call fans the event out to Outbrain server-side — no per-platform code.

Setup guide

Overview

adscapi sends server-side conversions to Outbrain Amplify's unifiedPixel endpoint (GET https://tr.outbrain.com/unifiedPixel). Outbrain matches each conversion by ob_click_id, which it appends to the ad landing-page URL at click time — there is no hashed PII on the request. Capture ob_click_id on landing, carry it to your backend, and pass it on the event as clickIds.ob_click_id. Without a click id the event is a no-op. OUTBRAIN_TOKEN is the account gate (it activates the platform); the pixel request itself is keyed by the click id.

Docs: Outbrain server-to-server integrations.

Prerequisites

  • An Outbrain Amplify advertiser account.
  • Conversion events created in Amplify whose names match what adscapi will send (spaces, not underscores — Amplify does not allow _ in conversion names).
  • A way to capture ob_click_id from the landing-page URL and store it against the user/session.

1. Create an account

  1. Sign up at amplify.outbrain.com and open your advertiser account.
  2. Under Conversions, create the events you will fire (purchase, lead, page view, …). Names are case-sensitive and cannot contain _.
  3. Confirm your campaigns append ob_click_id to landing URLs (Outbrain does this by default on Amplify click tracking).

2. Get your credentials

Secret Where to get it
OUTBRAIN_MARKETER_ID Amplify → account settings / the numeric Marketer ID in the console URL and reports.
OUTBRAIN_TOKEN Amplify → account / API access. The token that proves this advertiser is configured; it is the gate.

Capture the click id: Outbrain appends ob_click_id=<click_id> to your ad landing URLs. Read it on arrival, persist it against the session/user, and pass it on the event as clickIds.ob_click_id. adscapi sends it unhashed.

3. Configure adscapi

export OUTBRAIN_MARKETER_ID="…"   # numeric marketer / advertiser id
export OUTBRAIN_TOKEN="…"         # Amplify account token (platform gate)

4. Verify

adscapi verify --platform outbrain

Send a test purchase with a real clickIds.ob_click_id and confirm it lands in Amplify conversions. A 2xx is success.

5. Event mapping

Canonical Outbrain
page_view page view
lead lead
signup_start signup start
signup signup
checkout_created checkout created
purchase purchase
reply_generated reply generated
upgrade_clicked upgrade clicked

name is the advertiser-created Amplify conversion name (case-sensitive; _ is not allowed). Create matching events in Amplify before you fire them.

Optional value fields: value → orderValue, transactionId → orderId, currency → currency (uppercased).

Troubleshooting

  • No conversions appear — ob_click_id is missing or wrong. It must be the exact value Outbrain appended to the ad URL. adscapi no-ops when clickIds.ob_click_id is absent.
  • name not matching — Amplify conversion names cannot contain _. adscapi maps canonical names to space-separated custom names (page view, signup start). Create those exact names in the dashboard.
  • Secrets set but nothing fires — both OUTBRAIN_MARKETER_ID and OUTBRAIN_TOKEN must be present; either missing is a silent no-op.
  • HTTP 4xx — click id rejected or conversion name unknown. Check the click id and that the Amplify conversion exists with the exact name.

1. Install adscapi

shell
npm install adscapi
# or run without installing:
npx adscapi platforms

2. Get Outbrain's tokens

Outbrain activates once all of these are set. Run npx adscapi platforms to see them, then get each value from Outbrain’s ads or events dashboard.

OUTBRAIN_MARKETER_IDOUTBRAIN_TOKEN

3. Set them for adscapi

Export the tokens in the environment that runs your server or the adscapi CLI.

shell
export OUTBRAIN_MARKETER_ID="…"
export OUTBRAIN_TOKEN="…"

4. Verify

check confirms the secrets are present; verify calls Outbrain’s API to confirm they are valid.

shell
npx adscapi check
npx adscapi verify --platform outbrain

5. Track a conversion

One call, sent to Outbrain and every other configured platform. Pass raw email — adscapi hashes per platform. Consent is required.

ts
import { createAdscapi } from 'adscapi';

const ads = createAdscapi();

const results = await ads.conversions.track({
  name: 'purchase',
  value: 49,
  currency: 'USD',
  user: { email: 'buyer@example.com' },
  consent: { adUserData: true, adPersonalization: true },
});

See the exact request on the Outbrain payload preview.