Web conversions

title: Web conversions keywords: [“web conversions”, “conversion tracking”, “web conversion tracking”, “conversions”, “track conversions”, “conversion API”] description: * The primary requirement of Conversion API is having a [Developer Account](https://developer.--- import from ‘/snippets/button.mdx’;

Conversion API Set Up

Prerequisites

Ads API Access - New Applications

* The primary requirement of Conversion API is having a Developer Account and Ads API Access. The process is outlined in the Ads API Getting Started guide. Please note the following: Step 1: Developer Account * When applying for a Developer Account, apply for one of our subscription plans for instant approval. * Note: As a best practice we highly recommend using your official company X handle to create a developer account and apply to have Ads API access. If the developer account is associated with a developer handle, there is no way to transfer those credentials, if needed. It is best to house under a company account for continual management and utilize Multi-user login, as needed. Otherwise at minimum, the account should be set up with non-default settings (header image, avatar, bio description, and bio URL) and use Two-Factor Authentication. Step 2: Ads API Application * Make sure to have the correct App ID ready for your Ads API Application. The App ID can be found in the Developer Console under Projects & Apps. Example: 16489123 * Request access to the Ads API by reaching out to your X representative.

Ads API Access - Existing Applications

* If you already have an actively used Ads API application, both the application and existing access tokens may be used for the Conversion API.

Access Tokens

* User Access Tokens for the user handle owning the Ads API application can be generated and retrieved directly from the Developer Console. This is called your “personal access token” because it is intended to be used for your own X handle. Overall information about authentication and the Developer Console can be found here. * User Access Tokens for user handles other than the handle owning the Ads API application must be generated with a 3-legged OAuth flow. Options for generating the Access Token with 3-legged OAuth include: * Command Line with Web-based Authorization via twurl utility * Command Line with PIN-based Authorization * Custom web flow implementing the 3-legged OAuth pattern * Any user tokens used with the Conversion API must be for users with AD_MANAGER or ACCOUNT_ADMIN access level, which can be checked via the authenticated_user_access endpoint. * Note: the tokens themselves (after creation per above) can be shared to users without the AD_MANAGER or ACCOUNT_ADMIN access level for usage.

Steps

Creating the Conversion API event

To use the Conversion API, you need to create a new conversion event in Ads Manager or use an existing event already created and used with the X Pixel. If you hope to do deduplication between pixel and conversion API events, you need to use the existing event you created for Pixel.

Option 1: Using an Existing Conversion Event in Ads Manager

If you’d like to use an existing event that you’re already using with the X pixel, that is possible and you’ll need to take the Event ID from that event. If you use both pixel and Conversion API for the same event, ensure to use the deduplication key in both Pixel code snippet and Conversion API request (as conversion_id) to deduplicate events between Pixel and Conversion API for the same event. See section d. Testing Events and Deduplication for more information.

Option 2: Creating a New Conversion Event in Ads Manager:

It’s important to have an Event Source created in the Events Manager before you create an event. To verify if you have an Event Source (X Pixel) added to your account, go to Events Manager and see if you have X Pixel on your left menu. If you don’t have an Event source added yet, please follow the steps below to create an Event source. 1. Go to ads.x.com 2. Navigate to Tools section on the top left and click Events Manager 3. Select Add event source on the top right to Add an event source if you do not have aad X pixel event source on your left sidebar yet 1. The ID of X pixel event source is your Pixel ID Now you have an Event source and Pixel ID. You need to create an event inside the event source for the conversion events you hope to track: 1. Inside the X pixel event source, select Add events on the right side 2. Select Install with Conversion API 3. You will see the Pixel ID and Event ID of this event that will be used in the API 1. The ID of the event is your Event ID 4. Click Save and you will have your conversion event created and ready to go

Preparing Identifiers for Conversion Events

We currently need at least one identifier to be passed such as Click ID (twclid), email address, or phone number. If using IP address or user agent, a second identifier must be sent for proper conversion matching. Passing more identifiers will yield a higher conversion matching rate.


Customer matching field	Format	Hashing required?
X Click ID	X generated (learn more)	No
Email Address	Remove leading and trailing spaces	Required (SHA256)
Phone Number	E164 Standard	Required (SHA256)


IP Address	Remove leading and trailing spaces	No
User Agent	Remove leading and trailing spaces	No

1. Prepare X Click ID Identifier

It’s recommended to always include Click ID in the conversion request The Click ID should be parsed out of the query string parameter twclid when it is available after the user navigates to the destination website. Basic JavaScript code example:

var queryString = document.location.search;
if (queryString.has('twclid') {
  twitterClickID = getParam(queryString, 'twclid');
  // Recommended next steps: Logging, insert into local storage
}

It is recommended to: 1. Always parse the twclid value when it is present in the URL query parameters. 2. Store the data alongside relevant form fields or conversion event information. Tying the Click ID to conversion events and workflow information enables scenarios such as batch processing, algorithms to analyze and create conversion events based upon multiple website navigation flows, and bulk uploads. The Event Source URL should be URL Encoded and is meant to represent the web page that triggered the event.

2. Prepare Email Identifier

Supported customer matching fields may be sent but should be normalized and, when required, hashed to protect privacy. The information must be hashed using SHA256, without salt. For example, for an email address test@x.com, it should be sent to us in a hashed format: d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62.

3. Prepare Phone Identifier

The phone number should be passed in using E164 Standard and the information must be hashed using SHA256, without salt. For example, for a US phone number: +11234567890, it should be sent to us in a hashed format: 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231.

4. Prepare IP Address Identifier

The IP Address is required to be passed in conjunction with another identifier (twclid, email address, phone number or user agent). No hashing is required for this identifier. This value is written in dotted-decimal notation, with four numbers separated by periods. As an example, a user’s IP Address may be 8.25.197.25.

5. Prepare User Agent Identifier

The User Agent is required to be passed in conjunction with another identifier (twclid, email address, phone number or IP address). No hashing is required for this identifier. This identifier allows the server to identify the application, operating system, vendor, and/or version of the requesting user agent. For example, this value can be passed as Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36.

Constructing the conversion event request

POST: version/measurement/conversions/:pixel_id Send conversion events for a particular ad account. The response code should be checked for success (HTTP 200 OK). It is recommended to have a retry mechanism and basic logging in place in case of error codes are returned. For detailed information about the endpoint’s URL and POST body parameters, please see the API Reference section.

Example Request (formatted for readability)

    twurl -H 'ads-api.x.com' -X POST '/12/measurement/conversions/oka17' --data '
    {
      "conversions":[
         {
            "conversion_time":"2022-02-18T01:14:00.603Z",
            "event_id":"ol288",
            "identifiers":[
               {
                  "twclid":"23opevjt88psuo13lu8d020qkn"
               },
               {
                  "hashed_email":"d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62"
               },
               {
                  "hashed_phone_number":"1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231"
               },
               {
                  "ip_address":"1.0.0.0",
                  "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"
               }
            ],
            "value":"20.00",
            "number_items":3,
            "conversion_id":"23294827",
            "description":"Pet supply purchases",
            "contents":[
               {
                  "content_id":"1",
                  "content_name":"Blankets",
                  "content_type":"Pet supplies",
                  "content_price":100.99,
                  "num_items":1,
                  "content_group_id":"123"
               }
            ]
         }
      ]
    }' --header 'Content-Type: application/json'

Example Response

{"request": {
 "params": {
     "account_id":"18ce552mlaq"}
 },
 "data": {
    "conversions_processed":1,
     "debug_id":"ff02e052-36e4-47d6-bdf0-6d8986446562"}
}

Rate Limit

The rate limit will be 60,000 events per account, per 15 minute interval. Note that your server code may be required to implement logic outside of this request call, including: 1. Instrumenting user actions (logging) to be able to send correct conversion data per event 2. Any necessary logic to filter out conversion events of users that have exercised relevant privacy choices - for example, if they have opted out of tracking or the sale of their personal information on the advertiser website 3. Integration with event triggers and pages as to capture events and send conversions

Overview

Fundamentals

Resources

Measurement

Web conversions

Conversion API Set Up

Prerequisites

Ads API Access - New Applications

Ads API Access - Existing Applications

Access Tokens

Steps

Creating the Conversion API event

Option 1: Using an Existing Conversion Event in Ads Manager

Option 2: Creating a New Conversion Event in Ads Manager:

Preparing Identifiers for Conversion Events

1. Prepare X Click ID Identifier

2. Prepare Email Identifier

3. Prepare Phone Identifier

4. Prepare IP Address Identifier

5. Prepare User Agent Identifier

Constructing the conversion event request

Example Request (formatted for readability)

Example Response

Rate Limit

Testing Events and Deduplication

Test

Overview

Fundamentals

Resources

Measurement

Documentation Index

​Conversion API Set Up

​Prerequisites

​Ads API Access - New Applications

​Ads API Access - Existing Applications

​Access Tokens

​Steps

​Creating the Conversion API event

Option 1: Using an Existing Conversion Event in Ads Manager

Option 2: Creating a New Conversion Event in Ads Manager:

​Preparing Identifiers for Conversion Events

​1. Prepare X Click ID Identifier

​2. Prepare Email Identifier

​3. Prepare Phone Identifier

​4. Prepare IP Address Identifier

​5. Prepare User Agent Identifier

​Constructing the conversion event request

​Example Request (formatted for readability)

​Example Response

​Rate Limit

​Testing Events and Deduplication

​Test

Conversion API Set Up

Prerequisites

Ads API Access - New Applications

Ads API Access - Existing Applications

Access Tokens

Steps

Creating the Conversion API event

Preparing Identifiers for Conversion Events

1. Prepare X Click ID Identifier

2. Prepare Email Identifier

3. Prepare Phone Identifier

4. Prepare IP Address Identifier

5. Prepare User Agent Identifier

Constructing the conversion event request

Example Request (formatted for readability)

Example Response

Rate Limit

Testing Events and Deduplication

Test