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

# Taboola

> Send conversion events to Taboola's S2S API for native advertising campaign optimization — powered by Upstack Signal.

<Note>
  **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs.
</Note>

## What it does

Taboola is a native advertising platform that displays sponsored content recommendations on publisher websites. Upstack Signal forwards storefront events — page views, product views, add-to-carts, and purchases — directly to Taboola's Server-to-Server (S2S) Conversion API for campaign optimization.

Server-side delivery means conversions reach Taboola even when the browser-side pixel is blocked by ad blockers, ITP, or cookie restrictions. Each event carries the click identifier (`tblci`) captured from ad clicks so Taboola can match the conversion back to the ad interaction that drove it.

<Warning>
  **Important limitation:** Taboola does **NOT** support enhanced matching via hashed email, phone, or other PII. Attribution relies **solely on the click ID (`tblci`)** captured from ad clicks. Events without a click ID cannot be attributed and are skipped.
</Warning>

## How it works

Upstack Signal runs as a dual-tracking layer alongside the Taboola browser pixel. The Upstack Pixel captures events in the browser and forwards each one to Upstack's edge infrastructure, where it is enriched with the Taboola click ID from cookie storage and sent to Taboola's S2S API as a server-side event.

**S2S priority for deduplication:** When both the browser pixel and S2S report the same event, Taboola keeps the S2S event and deduplicates the pixel event. This makes server-side preferred for accurate attribution.

**API behavior:** Taboola's S2S API returns HTTP 204 No Content for **all** requests, including invalid ones. There is no validation feedback from the API — use Taboola Backstage Test Events for verification.

**Authentication:** Unlike Meta, TikTok, and Google APIs, Taboola's S2S API is unauthenticated. Events are attributed via the click ID only.

## Setup

### Prerequisites

* A Taboola Backstage account with active campaigns
* The Upstack Pixel installed on your storefront
* Campaign URLs configured with the `tblci` click ID parameter

### Required credentials

| Field      | Description                     | Where to find                           |
| ---------- | ------------------------------- | --------------------------------------- |
| Account ID | Your numeric Taboola Account ID | Backstage → Account dropdown → Tracking |

### Configuration steps

1. In Upstack, navigate to **Settings** → **Destinations**
2. Click **Add Destination** and select **Taboola**
3. Enter your **Account ID** (numeric only)
4. Toggle **Enable Server-Side Tracking** to send events via the S2S API
5. Click **Save**

### Configure click ID tracking

For Taboola to attribute conversions, your campaign URLs must include the click ID parameter:

1. In Taboola Backstage, go to **Campaigns** → select your campaign
2. Add `?tblci={click_id}` to your destination URL (or `&tblci={click_id}` if URL already has parameters)
3. The Upstack Pixel will automatically capture and store the `tblci` value

<Note>
  The `tblci` parameter is case-sensitive. Ensure your URL uses lowercase `tblci`.
</Note>

## Event mapping

Upstack maps storefront events to Taboola events automatically:

| Upstack event          | Taboola event           | Key parameters                   | Notes                          |
| ---------------------- | ----------------------- | -------------------------------- | ------------------------------ |
| `Purchase`             | `make_purchase`         | `revenue`, `currency`, `orderid` | Primary conversion event       |
| `InitiateCheckout`     | `start_checkout`        | `revenue`, `currency`            | Checkout initiation            |
| `AddToCart`            | `add_to_cart`           | `quantity`                       | Cart additions                 |
| `ViewContent`          | `view_content`          | —                                | Product page views             |
| `PageView`             | `page_view`             | —                                | Page load                      |
| `Lead`                 | `lead`                  | `revenue`                        | Lead form submissions          |
| `SignUp`               | `complete_registration` | —                                | Account registration           |
| `CompleteRegistration` | `complete_registration` | —                                | Account registration           |
| `Search`               | `search`                | —                                | Site search                    |
| `Subscribe`            | `subscribe`             | —                                | Newsletter/subscription signup |

Every event includes the Taboola click ID (`tblci`) when available. **Events without a click ID are skipped** because Taboola cannot attribute them to any campaign.

<Warning>
  **Event names are case-sensitive.** Taboola event names must exactly match the conversion name configured in Taboola Realize. Upstack sends lowercase snake\_case names (e.g., `make_purchase`, `add_to_cart`).
</Warning>

## Field mapping

| Upstack field                          | Taboola field | Type   | Notes                                     |
| -------------------------------------- | ------------- | ------ | ----------------------------------------- |
| `context.properties.click.tblci`       | `click-id`    | string | **Required.** Click ID from ad click      |
| `data.value`                           | `revenue`     | number | Conversion value (decimal, no commas)     |
| `data.currency`                        | `currency`    | string | ISO 4217 (USD, EUR, GBP) — case-sensitive |
| `data.orderId` or `data.transactionId` | `orderid`     | string | Transaction ID for deduplication          |
| Aggregated from `items`                | `quantity`    | number | Total quantity across all items           |
| Event timestamp                        | `timestamp`   | number | Milliseconds since Unix epoch             |

## FAQ

<AccordionGroup>
  <Accordion title="How do I verify events are arriving in Taboola?">
    Open Taboola Backstage, navigate to **Tracking** → **Test Events**, and check that events are appearing. Note that Taboola's API returns 204 for all requests (even invalid ones), so the Test Events view is the only way to confirm events are being processed correctly.
  </Accordion>

  <Accordion title="Why are my attribution rates lower than other platforms?">
    Taboola does not support enhanced matching with hashed PII (email, phone, IP, user-agent). Attribution relies **solely** on the click ID (`tblci`). If a visitor clears cookies, uses a different device, or the click ID expires, the conversion cannot be attributed. This is a platform limitation, not an Upstack issue.
  </Accordion>

  <Accordion title="Will my events be counted twice if I run both the pixel and server-side?">
    No. When both the browser pixel and S2S report the same event, Taboola keeps the S2S event and deduplicates the pixel event. Including an `orderid` on purchase events further improves deduplication.
  </Accordion>

  <Accordion title="Do event names need to match exactly?">
    Yes — event names are **case-sensitive** and must exactly match the conversion name configured in Taboola Realize. Upstack sends standard lowercase snake\_case names like `make_purchase`, `add_to_cart`, etc.
  </Accordion>

  <Accordion title="What happens if the click ID is missing?">
    Events without a Taboola click ID are **skipped** and not sent to Taboola. This is intentional — Taboola cannot attribute conversions without a click ID, so sending them would inflate your event volume without improving attribution. Ensure your campaign URLs include `tblci={click_id}` so the Upstack Pixel can capture click IDs.
  </Accordion>

  <Accordion title="Why does the API always return 204?">
    Taboola's S2S API returns HTTP 204 No Content for **all** requests, including those with invalid data. This is by design. Use Taboola Backstage Test Events to verify events are being processed correctly.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="No conversions appearing in Taboola Backstage">
    If events aren't appearing after confirmed store traffic:

    **Steps to fix:**

    1. Verify your campaign URL includes `tblci={click_id}`
    2. Confirm the Upstack destination shows **Active** (green)
    3. Check that the Account ID matches your Backstage account
    4. Test with a real ad click — test traffic without `tblci` in the URL won't generate events
    5. Check Taboola Backstage → Tracking → Test Events for any incoming events
  </Accordion>

  <Accordion title="Invalid Account ID">
    The Account ID must be a numeric string (digits only).

    **Steps to fix:**

    1. Go to Taboola Backstage → Account dropdown → Tracking
    2. Copy the numeric Account ID (no spaces, no extra characters)
    3. Update the destination in Upstack with the correct ID
  </Accordion>

  <Accordion title="Low attribution rate compared to other platforms">
    This is expected due to Taboola's click-ID-only attribution model.

    **To maximize attribution:**

    * Ensure all campaigns include `tblci={click_id}` in the URL
    * Verify the Upstack Pixel is loading on all pages to capture click IDs
    * Check that first-party cookies are not being blocked by browser settings
    * Note that cross-device and returning-visitor conversions will not be attributed
  </Accordion>

  <Accordion title="Events appear to send but don't show in Backstage">
    Remember that Taboola's API returns 204 for all requests, even invalid ones.

    **Steps to fix:**

    1. Verify event names match exactly what's configured in Taboola Realize (case-sensitive)
    2. Ensure the `click-id` parameter is being sent correctly (hyphenated, not underscored)
    3. Check that revenue values don't contain commas
    4. Verify currency codes are uppercase ISO 4217 (USD, not usd)
  </Accordion>
</AccordionGroup>

<Note>
  For additional troubleshooting beyond Taboola-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination).
</Note>

## Related

<CardGroup cols={2}>
  <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding">
    How Upstack Signal forwards events to ad platforms via server-to-server APIs.
  </Card>

  <Card title="Identity resolution" icon="fingerprint" href="/pixel/identity-resolution">
    How Upstack matches anonymous visitors to known customers for higher match rates.
  </Card>

  <Card title="Outbrain destination" icon="rectangle-ad" href="/destinations/outbrain">
    Set up Outbrain's native advertising API — similar click-ID-only attribution model.
  </Card>

  <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination">
    End-to-end diagnostic guide when events aren't arriving at any destination.
  </Card>
</CardGroup>