Real Conversions API

TBTaboola setup

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

Setup guide

Overview

adscapi sends server-side conversions to the Taboola bulk S2S endpoint (POST https://trc.taboola.com/{account-id}/log/3/bulk-s2s-action). Taboola matches each conversion by its click id (tblci), which it appends to every ad URL at click time — there is no hashed PII and no auth token. Capture the tblci value on landing, carry it to your backend, and pass it on the event as clickIds.tblci. adscapi forwards it unhashed only when ad-personalization consent is set; without a click id the event is a no-op.

Prerequisites

A Taboola advertiser account (Realize / Ads console).
The Taboola pixel installed, or a way to capture the tblci click id from the ad landing URL and store it against the user/session.

1. Create an account

Sign up at taboola.com and open the advertiser console (Realize).
Install the Taboola pixel so conversions can also be tracked in the browser (S2S complements the pixel for redundancy and better attribution).
Define your conversion events in the console so the name you send matches a configured event.

2. Get your credentials

Secret	Where to get it
`TABOOLA_ACCOUNT_ID`	Your Taboola account id (the numeric id in the console URL and reports, e.g. `1080075`). It is the `{account-id}` path segment.

No auth token is required — the bulk S2S endpoint is unauthenticated and keyed by the click id.

Capture the click id: Taboola appends tblci=<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.tblci. adscapi sends it as the click-id field, never hashed.

3. Configure adscapi

export TABOOLA_ACCOUNT_ID="…"   # numeric account id, the {account-id} path segment

4. Verify

adscapi verify --platform taboola

Send a test purchase with a real clickIds.tblci and confirm it lands in your Taboola conversions report. A 2xx/204 is success; the endpoint returns 204 No Content.

5. Event mapping

Canonical	Taboola
page_view	page_view
lead	lead
signup	signup
checkout_created	checkout_created
purchase	purchase

The name field is case-sensitive and must match a conversion event configured in your Taboola account. An unmapped canonical name is passed through as-is.

Troubleshooting

No conversions appear — the tblci click id is missing or wrong. It must be the exact value Taboola appended to the ad URL. adscapi no-ops when clickIds.tblci is absent or ad-personalization consent is off.
name not matching — the event name is case-sensitive and must match a conversion rule configured in the Taboola console.
Timestamps look off — Taboola wants milliseconds since the Unix epoch. adscapi converts your eventTime (seconds) automatically; send seconds, not milliseconds.
Revenue not recorded — send both value and currency; adscapi maps them to the optional revenue and currency fields.

1. Install adscapi

shell

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

2. Get Taboola's tokens

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

TABOOLA_ACCOUNT_ID

3. Set them for adscapi

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

shell

export TABOOLA_ACCOUNT_ID="…"

4. Verify

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

shell

npx adscapi check
npx adscapi verify --platform taboola

5. Track a conversion

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

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 Taboola payload preview.