pooriaarab Taboola Ads
Taboola Realize supports two documented conversion paths: the Taboola Pixel and server-to-server (S2S) tracking. Use both when the funnel permits it. See the tracking overview.
Use ad-conversion-hub for the canonical event envelope, consent gate, identity rules, retry policy, and adapter contract. Pair it with ad-experiments for one-audience tests, seed sizing, PII-export authorization, and payment-provider truth.
Account and access
Apply for an advertiser account through Taboola's account form. Backstage API
credentials come from a Taboola Account Manager or the documented support route.
See Backstage API welcome.
The Backstage API manages campaigns, reports, and automation. Its documented
OAuth API is not the S2S conversion endpoint. Keep those integrations separate.
See Backstage API scope
and conversion tracking.
Taboola defines no environment-variable names. The hub convention may map these
as TABOOLA_ACCOUNT_ID, TABOOLA_CLIENT_ID, TABOOLA_CLIENT_SECRET, and
TABOOLA_ACCESS_TOKEN. See authentication basics.
Backstage uses the Client Credentials flow at
https://backstage.taboola.com/backstage/oauth/token. Send form-encoded
client_id, client_secret, and grant_type=client_credentials.
See Client Credentials flow.
The response includes a bearer access token with expires_in: 43200 and no
refresh token. The token endpoint must not have a trailing slash.
See token response and notes.
Use the bearer token in the Authorization header for Backstage requests.
Taboola's sample request also uses Content-Type: application/json.
See authentication basics.
Client-side Taboola Pixel
Install the base pixel in the <head> of every relevant page. Replace every
<account_id> placeholder with the numeric Taboola Account ID.
See manual base-pixel installation.
<!-- Taboola Pixel Code -->
<script type="text/javascript">
window._tfa = window._tfa || [];
window._tfa.push({notify: "event", name: "page_view", id: <account_id>});
!function (t, f, a, x) {
if (!document.getElementById(x)) {
t.async = 1;
t.src = a;
t.id = x;
f.parentNode.insertBefore(t, f);
}
}(document.createElement("script"), document.getElementsByTagName("script")[0],
"//cdn.taboola.com/libtrc/unip/<account_id>/tfa.js", "tb_tfa_script");
</script>
<!-- End of Taboola Pixel Code -->
Taboola recommends Google Tag Manager or a Shopify app for base-pixel setup. Manual installation requires custom development. See pixel installation options. Create event-based conversions in Realize, then use the generated event code. The base pixel must already exist, or Taboola will not record the event. See defining conversions and event pixels. URL-based conversions need only the base pixel. Event-based conversions need an event pixel or the corresponding generated event code. See event-pixel requirements.
Rule setup and event mapping
In Realize, select Tracking → Conversions → + New Conversion. Choose a URL or event conversion, assign a mandatory category, and choose a descriptive name. See conversion rules. Use these adapter event names unless the campaign has an established naming scheme. They are local choices, not Taboola-reserved event names.
| Hub event | Realize Event Name | Dispatch condition |
|---|---|---|
page_view |
page_view |
Base pixel page load |
view_content |
view_content |
Meaningful content or plan view |
lead |
lead |
Confirmed lead submission |
signup |
signup |
Completed account registration |
begin_checkout |
begin_checkout |
Checkout begins |
purchase |
purchase |
Payment provider confirms the charge |
subscription_start |
subscription_start |
Paid subscription activates |
refund |
No default dispatch | Reconcile in payment truth |
Taboola allows a unique descriptive Event Name, and the name sent by S2S must match that field exactly. The Conversion Name is only descriptive. See manual S2S rule setup.
Create a distinct event-based rule for each non-page_view event you measure;
page_view uses the URL-based rule from the base pixel load instead. Keep the
hub's canonical event_id internally; the documented S2S contract does not
define it. See S2S fields.
Server-side conversions API
Taboola's documented direct server surface is manual S2S tracking, not a named Conversions API. It supports one conversion per postback URL or batches through a bulk endpoint. See manual S2S integration. For one event, send a request to the documented postback URL. The required parameters are the case-sensitive Taboola Click ID and exact Event Name.
https://trc.taboola.com/actions-handler/log/3/s2s-action?click-id=CLICK_ID&name=EVENT_NAME
URL-encode click-id, name, and every optional parameter value. An Event
Name from a custom naming scheme or an orderid containing spaces, &, or
other reserved characters will otherwise corrupt the query string or match the
wrong Event Name.
Optional parameters are revenue, currency, quantity, and orderid.
The postback uses a three-letter currency code, and the account default applies
when currency is omitted.
See S2S postback parameters.
The bulk endpoint is:
POST https://trc.taboola.com/{account-id}/log/3/bulk-s2s-action
Content-Type: application/json
Its body contains one actions array. Each action requires click-id,
timestamp, and name; timestamp is milliseconds since Unix Epoch.
Optional fields are revenue, currency, quantity, and orderid.
See bulk S2S fields.
Limit each bulk request to 1,000 conversions. The endpoint passes no
authentication and returns 204 No Content with an empty body.
That response means receipt and asynchronous processing, not valid data.
See bulk limits and response.
Dispatch after confirmation and use the hub's retry policy. Do not treat 204
as attribution. See ad-conversion-hub.
Identity and consent
For Taboola First Party Data, submit hashed Email IDs or demographic data. Demographic data requires user consent, and Taboola says not to submit any First Party Data when age is under 18. See Submitting First Party Data.
Trim surrounding whitespace and lowercase email before hashing with SHA-256.
Use the resulting hash in the pixel's unified_id parameter; do not send raw
email in that field.
See Taboola hashing guidance.
The S2S contract defines no identity fields. Require hub measurement consent before pixel or identity dispatch. See S2S fields and the hub contract.
Click ID and first-party cookie
Taboola automatically appends tblci={click_id} to ad URLs by default.
The Click ID is case-sensitive and must pass through without truncation or
corruption. See manual Click ID handling.
Capture tblci on the landing request. Store it in a cookie, local storage, or
similar first-party mechanism, then carry it into the CRM or server event.
See CRM S2S tracking.
If the landing system cannot accept tblci, configure a custom URL parameter
whose value remains exactly {click_id}. The server request still uses
click-id, with the hyphen.
See custom Click ID parameters.
The cited Click ID docs define no Taboola cookie name or Click ID retention period. Use hub policy instead.
S2S requires click-id. If no Click ID exists, keep the first-party event in
the hub and do not send an invalid Taboola S2S request.
See postback required parameters.
Deduplication
Taboola deduplicates within the same Click ID context. With dual-method tracking, Taboola keeps the S2S event when the same event arrives through S2S and Pixel. Same-channel duplicates use heuristic deduplication. See conversion deduplication.
The documented example deduplicates a repeated S2S event within one minute when Click ID, Event Name, and Order ID match. See deduplication examples. Do not treat S2S as generally idempotent: a retry sent after that window (for example, a hub retry following a lost or timed-out postback response) is not guaranteed to be deduplicated and can be counted as a second conversion. Keep retries inside the documented window, or reconcile ambiguous double-sends against payment-provider truth instead of resending blindly.
Use the same Click ID and Event Name across dispatches. Send orderid for
purchase events when an order identifier exists. See deduplication
and postback fields.
Realize settings that override code
The Realize conversion rule controls the Event Name, category, fixed value, click-through window, view-through window, and inclusion in total conversions. See S2S rule settings.
The documented click-through window ranges from 1–30 days, with a 30-day default. The view-through window ranges from 1–24 hours, with a 24-hour default. See conversion-window settings.
Include important conversions in total conversions when the campaign should optimize toward them. Include total value when needed for default reporting. See conversion reporting settings.
Create URL-based rules only when a page visit is the intended conversion. Create event-based rules for actions such as lead submission or purchase. See conversion types.
Verification
Use Realize Tracking → Conversions → Test Events. Enter the ad URL exactly, including tracking parameters, then generate the QR code or desktop test link. See Testing Tool.
Disable ad blockers during testing. Test on mobile and desktop, and use a browser that supports third-party cookies for the most accurate matching test. See Testing Tool guidelines.
Move through the funnel and inspect the Events Received pane. Expand events
with error icons, and check User Matching for Taboola Click ID and Cookie ID.
See Testing Tool event details.
For S2S, use the server-event test flow and include the test Click ID from the generated URL. Check the conversion rule's Status, Last Received, and Events Received columns. Allow up to 20 minutes for the conversion to appear. See S2S verification and alternative S2S verification.
Use the Backstage Campaign Summary Report at
/reports/campaign-summary/dimensions/{dimension_id}. Add
include_multi_conversions=true for supported conversion columns.
See standard reports.
Treat receipt as ingestion proof only. Reconcile purchases and refunds with payment-provider truth before comparing Realize attribution. See bulk response.
Common pitfalls and security
- Do not use Backstage campaigns as a conversion endpoint. Use S2S postback or bulk.
- Do not send
tblcito S2S. The S2S parameter isclick-id; see S2S integration. - Do not change Event Name casing or spelling without updating every dispatch. See rule setup.
- Do not use Conversion Name for S2S matching. Taboola uses Event Name; see postback fields.
- Do not fire event code before the base pixel exists. See conversion definitions.
- Do not retry bulk requests as if
204proved every record was valid. See bulk response. - Do not send raw email or demographic data without the hub consent decision. See First Party Data.
- Do not invent
event_idor extra S2S fields. See S2S fields. - Keep
client_secretand Backstage tokens server-side. Taboola calls the client secret confidential; see authentication. - Keep the adapter non-blocking for checkout. A vendor failure must not fail the payment webhook. See ad-conversion-hub.
Taboola supports pixel and CRM Custom Audiences, plus Lookalike Audiences. See audience targeting.
Official sources checked (2026-08-29)
- Tracking overview
- Manual base pixel · Event pixels · Defining conversions
- Manual S2S integration · Postback URL · Bulk S2S
- CRM S2S · Click ID verification · Alternative S2S verification
- Deduplication · First Party Data · Dynamic values
- Testing Tool · URL parameters
- Backstage welcome · Authentication · Client Credentials
- Standard reports · Audience targeting · Lookalike audience object