X (Twitter) Conversions API
Overview
Section titled “Overview”Signals sends conversions from your server to X, so actions people take after seeing or engaging with your ads are measured even where the browser drops the event. Because the event does not depend on the browser, it survives ad blockers and cookie restrictions.
Use this destination to see which campaigns produce site visits, sign-ups and purchases, and to optimize spend against the outcome rather than the click.
Settle one thing before you plan the mapping. X matches on a hashed email address and does not accept a phone number, so a record with no email address cannot be matched here at all.
Supported sources
Section titled “Supported sources”This destination carries web conversions only. Offline, CRM and app events are not sent through it.
Prerequisites
Section titled “Prerequisites”Before connecting you need:
- An X Ads account.
- An X Business Manager account.
- An X Pixel already created, with the conversion events you intend to report configured against it.
- Server-side API permissions enabled on the account.
- A website or a marketing data system producing the conversions.
- A source connected in the same project. Events reach X through the source, so a connected destination on its own sends nothing.
Authentication
Section titled “Authentication”This connector uses single sign-on, so no X credentials are entered into Datahash.
- In Studio, open Destinations, find the X category, and click the X Conversions API tile.
- Click Sign in with X.
- Sign in with the X Ads account you want to connect.
- Click Authorize App, accept the permissions, and click Save.
The account you authenticate with is the account that gets connected. If you are already signed in to X as someone else, sign out first.
There is no manual credential path on this connector. Single sign-on is the only way to connect it.
Configuration
Section titled “Configuration”You are returned to Studio with the account details populated from the sign-in.
- Choose the Advertiser ID you want to send to.
- Choose the associated Pixel ID that events should be written against.
- Click Finish.
Both lists are filled from the account you authenticated with, so an advertiser or pixel that is missing means you signed in with the wrong account.
The events themselves come from the connected source. Event names and the identifiers used for matching are set by the source mapping, not here.
Manage instance
Section titled “Manage instance”To change the instance, open it from the Manage existing instance table, click the edit option in the menu to the top right, update the fields and click Finish.
Data & identifiers
Section titled “Data & identifiers”Send identifiers already hashed where you can. Plain text also works: they are normalized and SHA-256 hashed before they reach X.
Required
Section titled “Required”| Field | When it is required |
|---|---|
| Event name | Always. It has to match a conversion event configured against your X Pixel. |
| Event time | Always. UNIX timestamp. |
| Email address | Always. X matches on a hashed email address, and it is the only personal identifier this destination accepts. |
| Currency and value | Purchase events only. |
Optional
Section titled “Optional”| Field | Notes |
|---|---|
| Last modified date | When the record changed, where the source has one. |
| Product type, name, category, IDs, group ID, price and quantity | Product detail for the conversion. Product type takes product or product_group. |
| Number of items | The item count on the conversion. |
Best practices
Section titled “Best practices”- Collect an email address wherever you can. It is the only identifier X matches on, so a conversion without one cannot be attributed.
- Keep formatting clean at source: lowercase the email address and trim whitespace. Hashing a badly formatted value produces a hash that will never match.
- Configure the conversion events against the pixel in X before you map them in Studio, and use the same names on both sides. A name that differs by a capital letter is a different event.
- Check that the advertiser and pixel you selected are the ones the campaigns run against, particularly where a business holds several.
Troubleshooting & FAQ
Section titled “Troubleshooting & FAQ”No events appear in X. Confirm a source is connected in the same project and sending, and that the pixel you selected is the one the campaigns use. A connected destination on its own produces nothing.
Events arrive but are not attributed. Check that the event name matches a conversion event configured against the pixel. An event X does not recognize is received and not counted.
Match rates are low. Usually a missing or badly formatted email address. There is no phone number to fall back on with this destination, so the email address has to be right.
Sign-in succeeded but the wrong account is connected. The connection is made as whichever X account was signed in. Sign out of X, then reconnect with the right one.