X Ads

Send website conversions to X (formerly Twitter) through the X Ads Conversion API.

Why route X Ads through Datafly Signal

• Conversions survive ad blockers and tracking prevention. Signal sends the event from your own infrastructure, so the conversions X optimises against are not filtered by the browser.
• Identifiers are hashed before they leave your infrastructure. Signal normalises and applies SHA-256 inside your own deployment, so X receives match keys, not raw personal data.
• Click and cookie identifiers are captured first-party and replayed on later conversions, so attribution survives when the landing-page cookie has expired.
• One consent decision governs every destination. X is gated by the same consent state as the rest of your stack, so a withdrawal applies everywhere at once.
• Presets for Retail, Travel, Media and Insurance. The mapping starts from a working configuration for your vertical, and every field can be changed afterwards.

Prerequisites

1. An X Ads account with an X Pixel event source (Tools > Events Manager). Copy the Pixel ID.
2. For each conversion type you track, create an event with Install with Conversion API (or reuse your Pixel event so X can deduplicate) and copy its Event ID (for example tw-o8z3j-o8z3k).
3. In Events Manager choose Install Pixel > Manual > Conversion API > Generate access token and copy the Conversion API access token. No developer app or OAuth signing is needed.

Configuration

Configure in Signal

1. In the Management UI, go to Integrations > Integration Library and select X Ads.
2. Choose a preset, fill in the fields above and choose the pipelines and consent categories (advertising destinations default to marketing).
3. Click Install Integration.

Or with the Management API:

curl -X POST http://localhost:8084/v1/admin/integration-catalog/x_ads/install \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "X Ads", "variant": "default", "config": {"pixel_id": "o8z3j", "access_token": "..."}, "delivery_mode": "server_side"}'

API endpoint

POST https://ads-api.x.com/12/measurement/conversions/{{pixel_id}}

Authentication: X-Pixel-Token: <Conversion API access token> header. Allow egress to ads-api.x.com from the network your delivery workers run on.

Presets and event mapping

Every preset sends only the fields it maps (the strict output contract is on). Events not listed are not sent.

Retail (ecommerce)

Full retail funnel: page views, product and list views, search, wishlist, add to cart, checkout, payment info and purchases with contents, value, currency and the order ID as conversion ID for Pixel deduplication.

Travel (travel)

Travel funnel: destination, flight and hotel searches, listing views and saves, booking start, payment and completed bookings, and leads.

Media (media)

Publisher and subscription funnel: content views, sign-ups, leads, podcast and paid subscriptions.

Default (default)

X Conversion API core funnel: page views, content views, search, add to cart, checkout, leads, sign-ups and purchases, matched on the X click ID, hashed email and phone, IP and user agent. Each conversion type is routed to the Events Manager event ID configured for it.

Insurance (insurance)

Insurance quote and policy funnel: quote requests and leads as Lead conversions (the Signal event name in description), checkout, payment info and policy purchases as Purchase with the policy number as conversion ID.

Identity and hashing

Email, phone and names come from datafly.identify() traits (a legacy properties.email / properties.phone is read when no trait is set). Raw personal data is never sent.

Deduplication and consent

event_id is the Events Manager event ID of the conversion type, read from the per-type Event ID field or the Default Event ID. An event whose type has no event ID is not sent. conversion_id carries the Signal event ID, or the order ID on purchases, and must match the Pixel’s conversion_id for deduplication.

Example: purchase (Default preset)

datafly.identify('crm-user-7', { email: 'jane.doe@example.com', phone: '07700 900123', first_name: 'Jane', last_name: 'Doe' });
datafly.track('purchase', {
  transaction_id: 'T_1001', value: 139.99, currency: 'GBP',
  items: [
    { item_id: 'SKU_1', item_name: 'Helmet', item_category: 'Motorbike', item_brand: 'Shoei', price: 120.00, quantity: 2 },
    { item_id: 'SKU_2', item_name: 'Gloves', price: 19.99, quantity: 1 }
  ]
});

Request Signal sends (rendered from the preset):

{
  "conversions": [
    {
      "contents": [
        {
          "content_id": "SKU_1",
          "content_name": "Helmet",
          "content_price": 120,
          "content_type": "Motorbike",
          "num_items": 2
        },
        {
          "content_id": "SKU_2",
          "content_name": "Gloves",
          "content_price": 19.99,
          "num_items": 1
        }
      ],
      "conversion_id": "T_1001",
      "conversion_time": "2025-09-22T00:13:20.123Z",
      "event_id": "tw-o8z3j-purch",
      "event_source_url": "https://shop.example.co.uk/p/123?utm_source=x",
      "identifiers": [
        {
          "hashed_email": "86e0b9e56c17cc4d12387e1949b85053fbe73bc3ce5a1188713a9d300cc6133d",
          "hashed_phone_number": "a8acc3a90a7b4e4dc65e93db9240ed26523050ef754d63b75b5161de76781436",
          "ip_address": "203.0.113.7",
          "twclid": "twclick",
          "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
        }
      ],
      "number_items": 2,
      "price_currency": "GBP",
      "value": 139.99
    }
  ]
}

Known limitations

• number_items is the number of order lines, not the unit total (#1389).

Troubleshooting