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 Twitter 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 Portal under Projects & Apps. Example: 16489123
Request access to the Ads API by reaching out to your Twitter 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 portal. This is called your “personal access token” because it is intended to be used for your own Twitter handle. Overall information about authentication and the developer portal 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:
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 Twitter 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 Twitter 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 (Twitter Pixel) added to your account, go to Events Manager and see if you have Twitter 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.

Go to ads.twitter.com
Navigate to Tools section on the top left and click Events Manager
Select Add event source on the top right to Add an event source if you do not have aad Twitter pixel event source on your left sidebar yet
1. The ID of Twitter 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:

Inside the Twitter pixel event source, select Add events on the right side
Select Install with Conversion API
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
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?
Twitter Click ID	Twitter 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 Twitter 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:

Always parse the twclid value when it is present in the URL query parameters.
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@twitter.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:

Instrumenting user actions (logging) to be able to send correct conversion data per event
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
Integration with event triggers and pages as to capture events and send conversions

Testing Events and Deduplication

Testing Events

When your event has successfully received conversion events, within 12 to 24 hours the status of the ‘Single event web tag’ should show TRACKING upon the Conversion Tracking page of the Ads Manager. It will not impact in-flight campaigns to send conversions via the Conversion API.

You may also check the analytics results of your conversion event per tag ID by:

Ads Manager data export (Analytics for Website Conversion Tracking help page)
Exporting data via the Ads API (segmentation_type=CONVERSION_TAGS)

Duplication between Pixel and Conversion API

If you hope to deduplicate conversions between Pixel and Conversion API requests, we have conversion_id as the deduplication key. The deduplication only happens at the event level. In other words, to deduplicate between pixel and CAPI requests, an advertiser has to use the same event in both pixel and CAPI requests, in addition to using the same conversion_id. Deduplication can only happen to events that are received within a 48h time frame