Conversion API Set Up (Beta)

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 Essential Access for instant approval. Elevated access is not required for Conversion API usage and requires an additional review period. Please choose Essential Access unless you decided you need Elevated access based on the access levels guideline. 
• 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 include the correct App ID in the Ads API Application. The App ID can be found in the Developer Portal under Projects & Apps. Example: 16489123
• Select Conversion API in the Ads API Application under “How will you use the Ads API?”
• For newly created applications, Ads API access will be limited to a small number of access tokens. For businesses that need to elevate their access beyond default limits, please review Increasing Access docs and ensure you communicate with your onboarding representative or account manager.

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:
  • 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

For the Conversion API Beta phase, you need to have both a Single Event Website Tag (SET) and a Universal Website Tag (UWT) to set up the conversion API integration. Both will be set up in the Ads Manager of the account you intend to send conversion events to. 

First, check if you have a Universal Website Tag in your Ads Manager's Events Manager already. This is usually created when creating your first event. 

If you don’t, follow the steps below. If you have a UWT already set up, skip to Creating a Single Event Tag and get Event ID section.

Creating a Universal Website Tag via Ads Manager:

1. Go to ads.twitter.com
2. Navigate to Tools section on the top left and click Events Manager
3. Select ‘Add events source’ on the top right
4. Select the Universal website tag (UWT)                         
5. Follow the instruction to set up your UWT
6. Enter the appropriate conversion event type and other details and ‘Save’
7. Find your Pixel ID (aka UWT ID) 
   1. You can find your pixel_id in the UWT you created in Events Manager 
   2. The ID (o9d7n in the screenshot) is your pixel_id and you should use it as your ‘pixel_id’ parameter

Creating a Single Event Tag and getting Event ID

Note: If you’d like to use an existing SET 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, similar to the instructions below. If you use both pixel and Conversion API for the same event, ensure to use the deduplication key to deduplicate events between Pixel and Conversion API for the same SET event. See section Testing Events and Deduplication for more information. 

    Method 1

    Creating a SET via Ads Manager

1. Go to ads.twitter.com 
2. Navigate to Tools section on the top left and click Events Manager
3. Select ‘Add events source' on the top right
4. Select the Single-event website tag (SET)
5. Enter the appropriate conversion event type and other details and ‘Save’
6. Find your Event ID (aka SET iD):
   1. You can find your Event ID in the SET you created in Events Manager:
   2. The  ID (o9d2g in the screenshot below) is your SET ID and you should use it as your event_id parameter
   3. Alternatively the parameter is found within the pixel code snippet as txn_id or find the URL of the SET as view_website_tag?id

    Method 2

    Creating a Single Event Website Tag via Ads API    

1. Using the user token for the appropriate ads account, make a request to POST https://ads-api.x.com/10/accounts/:account_id/web_event_tags (replace :account_id with your account ID) with appropriate parameters

2. Your Event ID is returned within a successful response as website_tag_id

Preparing Identifiers for Conversion Events 

We currently need at least one of the Twitter click ID (twclid) or the email as the identifier for a conversion event.

Prepare Twitter Click ID Identifier 

If possible, it’s recommended to always include Click ID in the conversion request. If email is available, it is not required to have a Click ID. One of both is sufficient; both are preferred in order to increase the match rate.

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.

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. 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.

As an example: 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d

Normalization and hashing guidelines are summarized here:

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 '/11/measurement/conversions/o9d7n' --data '
{
   "conversions":[
      {
         "conversion_time":"2022-02-18T01:14:00.603Z",
         "event_id":"o9d2g",
         "identifiers":[
            {
               "twclid":"23opevjt88psuo13lu8d020qkn"
            },
            {
               "hashed_email":"63dc92389e3326e3ee3d7e6e715fda270977b9d293d97760f89105c86b3e2f11"
            }
         ],
         "value":"20.00",
         "number_item":"3",
         "price_currency":"USD",
         "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

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 SET level. In other words, to deduplicate between pixel and CAPI requests, an advertiser has to use the same SET 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 

Troubleshooting and Support

For questions about error codes after calling the API, please see the section below. For all the other questions,  please do not hesitate to reach out to your Twitter representative and we will work on resolving them as soon as possible. 

Error Handling and Explanation

A single request will only be successful when there are zero errors for all conversions contained within it. In the case of any error within an individual conversion, the endpoint will emit a list of all applicable errors.

Twitter Ads API Error Codes Overview

Here is an overall comprehensive list of error codes in Ads API:

https://developer.twitter.com/en/docs/twitter-ads-api/response-codes

Successful Conversion API responses are indicated with a 200-series HTTP code and a JSON-based payload containing the object requested.

When there is a 500-series HTTP code, it’s related to a server issue instead of your request or account set up. Please check the Twitter API status page or the developer community forum in case others are having similar issues.

When there is a 400-series HTTP code, the common cases are 

• 400 Bad Request (request doesn’t fit standards)

• 401 Unauthorized (authentication issues)

• 403 Forbidden (API access issues associated with that Developer Account)

• 404 Not Found (URL or params might not be correct for the endpoint)

Conversion API error codes

400 Bad Request Scenarios

JSON Error Code Example

Request:

POST '/11/measurement/conversions/o6dkt'  --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dkt", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json'

Error message:

{"errors":[{"code":"INVALID_PARAMETER","message":"event_id (o6dkt) is not a single event tag (SET)","parameter":"event_id"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

Request:

twurl_ads -X POST '/11/measurement/conversions/o6dkt'  --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dl3", "identifiers": [{"twclid": ""}]}]}' --header 'Content-Type: application/json' 

Error message:

{"errors":[{"code":"INVALID_PARAMETER","message":"At least one user identifier must be provided","parameter":""}],"request":{"params":{"account_id":"18ce552mlaq"}}}

Request:

twurl_ads -X POST '/11/measurement/conversions/o6dkt'  --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"o6dl3", "identifiers": [{"hashed_email": "abc"}]}]}' --header 'Content-Type: application/json'

Error message:

{"errors":[{"code":"INVALID_PARAMETER","message":"hashed_email (abc) is not a valid SHA-256 hash","parameter":"hashed_email"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

Request:

twurl_ads -X POST '/11/measurement/conversions/o6dkt'  --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603", "event_id":"o6dl3", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json' 

Error message: 

{"errors":[{"code":"INVALID_PARAMETER","message":"Expected Time in yyyy-MM-ddTHH:mm:ss.SSSZ, got \"2022-06-16T01:14:00.603\" for conversion_time","parameter":"conversion_time"}],"request":{"params":{"account_id":"18ce552mlaq"}}}

401 Unauthorized

Reason: Authentication credentials missing or incorrect 

Solution: Follow the authentication steps in the Set Up documentation using one of the 3 authentication methods:

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.

403 Access Forbidden 

404 Not Found 

JSON Error Code Example

Request:

twurl_ads -X POST '/11/measurement/conversions/o8z6j'  --data '{"conversions":[{"conversion_time": "2022-06-16T01:14:00.603Z", "event_id":"abc", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]}' --header 'Content-Type: application/json'

Error message: 

{"errors":[{"code":"NOT_FOUND","message":"event_id (abc) does not belong to provided account","parameter":"event_id"},{"code":"INVALID_PARAMETER","message":"event_id (abc) is not a single event tag (SET)","parameter":"event_id"}],"request":{"params":{"account_id":"18ce55gze09"}}}