​
Conversion API Set Up

​
Prerequisites 

​
Ads API Access - New Applications

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 Portal 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 portal. 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 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 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 fieldFormatHashing required?
X Click IDX generated (learn more)No
Email AddressRemove leading and trailing spacesRequired (SHA256)
Phone NumberE164 StandardRequired (SHA256)
IP AddressRemove leading and trailing spacesNo
User AgentRemove leading and trailing spacesNo

​
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

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

​
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

​
Conversion Tracking (Overview)

​
Summary

Conversion tracking enables you to measure the number of X users that perform a desired action after viewing and engaging with your ads on X. It will provide you the capability to measure which of your campaigns drive actions such as site visits, sign ups, and purchases. This provides advertisers with the off-X measurement capabilities to understand the performance of their direct-response ads so that they can cost-effectively acquire customers. Using a conversion tag, advertisers can track user conversions and tie them back to ad campaigns on X. This gives them the visibility to optimize their campaigns to meet their cost-per-acquisition (CPA) goals. There are a variety of website actions that an advertiser can measure with conversion tracking. They can select one or more, in accordance with the action(s) they are looking to drive with their ad campaign:
  • Site visit: User visits a landing page on an advertiser’s site
  • Purchase: User completes a purchase of a product or service on the advertiser’s site
  • Download: User downloads a file, such as a white paper or software package, from the advertiser’s site
  • Sign up: User signs up for the advertiser’s service, newsletter, or email communication
  • Custom: This is a catch-all category for a custom action that does not fall into one of the categories above
X’s conversion tracking gives advertisers a full view of conversion attribution. Compared with third-party measurement systems that clients may have been using in lieu of X’s own conversion tracking capability, such as unique click-URLs paired with third party tracking tags, X’s conversion tag offers the ability for advertiser to track conversions attributed to mid and upper funnel engagements such as Tweet expands, Retweets, favorites, replies, and follows, as well as impressions.

​
FAQ

​
Troubleshooting and Support for Conversion API

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.

​
X Ads API Error Codes Overview

Here is an overall comprehensive list of error codes in Ads API: https://developer.x.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 X 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

ReasonTypeError Message
Missing Identifier Error (currently hashed email or X click ID - twclid)400 Bad RequestAt least one user identifier must be provided
Invalid hashed email400 Bad RequestHashed_email is not a valid SHA-256 hash
The type of event_id is not a single event tag (SET)400 Bad RequestEvent_id (<event_id>) is not a single event tag (SET)
Requested conversion events exceed the limit (currently 500 events per request)400 Bad RequestConversion count limit is 500
Missing Event ID400 Bad RequestEvent ID was not found

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

ReasonTypeError Message
The developer account you’re using does not have Ads API Access. Apply for access here.403 Unauthorized ClientThe client application with id <> making this request does not have access to X Ads API. Ensure your application has advertiser-api access. Use ‘twurl accounts’ and ‘twurl set default <username> <key>’ to change the application you’re using.

​
404 Not Found 

ReasonTypeError Message
The request URL or params is not correct for the endpoint404 Route Not FoundThe requested resource could not be found
You do not have access to the account that owns the pixel_id/Universal website tag404 Not FoundUser <user_id> does not have access to account <account_id>. Type ‘sn <user_id>’ to get the handle of the user. Use ‘twurl accounts’ and ‘twurl set default \u003Cusername\u003E’ to change the user you’re using.
The event id does not belong to the provided account associated with the pixel ID (UWT ID)404 Not Foundevent_id <event_id> does not belong to provided account

​
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"}}}

​
API reference index

For the complete API reference, select an endpoint from the list:

​
Web Conversions

Conversion APImeasurement/conversions/:pixel_id
Web Event Tagaccounts/:account_id/web_event_tags

​
Web Conversions

POST version/measurement/conversions/:pixel_id Send website conversion events for a single Event Tag ID. 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 error codes are returned. The rate limit will be 100,000 request per 15 minute interval per account (each request allows 500 events).
Resource URL
https://ads-api.x.com/12/measurement/conversions/:pixel_id
Request URL Parameters
NameDescription
pixel_id
required		The Base Tag ID for an ad account. This represents that base36 encoded value for an ad account’s Base Tag ID.

Type: string

Example: o8z6j
conversions
required		The object in POST body of the API request. List of conversion events. Up to 500 conversion events may be provided. See the table below for supported fields.

Type: array

Example: "conversions":[{"conversion_time": "2022-02-18T01:14:00.603Z", "event_id":"o87ne", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}], "conversion_id": "23294827"}]
conversions object
NameDescription
conversion_time
required		The time, expressed in ISO 8601.

Type: string

Example: 2017-10-05T00:00:00Z
event_id
required		The base-36 ID of a specific event. It matches a pre-configured event contained within this ad account. This is called ID in the corresponding event in Events Manager.

Type: string

Example: o87ne or tw-o8z6j-o87ne (tw-pixel_id-event-id) both accepted
identifiers
required		A list of identifier objects to match the conversion event to. Supported fields are listed in a table below. At least one of the identifier objects is required.

If using IP address or user agent, a second identifier must be sent for proper conversion matching.

Type: array

Example: "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"},{"hashed_email": "e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8"}]
number_items
optional		The number of items being purchased in the event. Must be a positive number greater than zero.

Type: integer

Example: 4
price_currency
optional		The currency of items being purchased in the event, expressed in ISO-4217. See Currency for detailed information.

Type: string

Default: USD

Example: JPY
value
optional		The price value of items being purchased in the event, represented in price_currency currency.

Type: double

Example: 100.00
conversion_id
optional		For deduplication between pixel and conversion API conversions. An identifier for a conversion event that can be used for de-duplication between Web Pixel and Conversion API conversions in the same event tag. See the Conversions Guide’s Testing Events and Deduplication section for more information.

Type: string

Example: 23294827
description
optional		Description with any additional information on the conversions.

Type: string

Example: test conversion
contents
optional		List of details relating to a specific product/content to provide granular information. See table below for supported fields.

Type: array

Example: contents": [{"content_id": "1", "content_name": "Blankets", "content_type": "home improvement", "content_price": 100.99, "num_items": 1, "content_group_id": "123"}, {"content_id": "2"}]
identifiers object
NameDescription
twclid
sometimes required		Click ID as parsed from the click-through URL. It’s required if no other identifier is added.

Type: string

Example: 26l6412g5p4iyj65a2oic2ayg2
hashed_email
sometimes required		An email address hashed with SHA256. The text must be lowercase, remove any trailing or leading spaces before hashing. It’s required if no other identifier is added.

Type: string

Example: For test-email@test.com = e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8
hashed_phone_number
sometimes required		A phone number with E164 format and hashed with SHA256. The phone number must be in E164 format before hashing. It’s required if no other identifier is added.

Type: string

Example: For +11234567890 = 1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231 
ip_address
sometimes required		This value is written in dotted-decimal notation, with four numbers separated by periods.

IP address is required to be passed in conjunction with another identifier (twclid, email address, phone number or user agent).

Type: string

Example: 8.25.197.25
**user_agent **
sometimes required		This identifier allows the server to identify the application, operating system, vendor, and/or version of the requesting user agent.

User Agent is required to be passed in conjunction with another identifier (twclid, email address, phone number or IP address).

Type: string

Example: 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.
contents object
NameDescription
content_id
optional		SKU or GTIN; identifier that represents the content.

Type: string

Example: jhp
content_group_id
optional		ID associated with a group of product variants

Type: integer

Example: group 1
content_name
optional		Name of the product or service.

Type: string

Example: radio flyer
content_price
optional		Price of the product or service.

Type: double

Example: 5.00
content_type
optional		Category for the product that was purchased.

Type: string

Example: clothes
num_items
optional		Number of products purchased

Type: integer

Example: 1
Response Parameters
NameDescription
conversions_processedNumber of conversions successfully processed

Type: integer

Example: 1
debug_idA debug UUID that can be used for subsequent investigations

Type: string

Example: ff02e052-36e4-47d6-bdf0-6d8986446562
Example Request
    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 Request
    {
       "request":{
          "params":{
             "account_id":"18ce552mlaq"
          }
       },
       "data":{
          "conversions_processed":1,
          "debug_id":"ff02e052-36e4-47d6-bdf0-6d8986446562"
       }
    }

​
Web Event Tags

GET accounts/:account_id/web_event_tags Retrieve details for some or all web event tags associated with the current account.

​
Resource URL

https://ads-api.x.com/12/accounts/:account_id/web_event_tags

​
Parameters

NameDescription
account_id
required		The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
count
optional		Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional		Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow
sort_by
optional		Sorts by supported attribute in ascending or descending order. See Sorting for more information.

Type: string

Example: created_at-asc
web_event_tag_ids
optional		Scope the response to just the desired web event tags by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: o3bk1
with_deleted
optional		Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false
with_total_count
optional		Include the total_count response attribute.

Note: This parameter and cursor are exclusive.

Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.

Type: boolean

Default: false
Possible values: true, false

​
Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags?web_event_tag_ids=o3bk1

​
Example Response

    {
      "request": {
        "params": {
          "web_event_tag_ids": [
            "o3bk1"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "web event tag",
          "view_through_window": 7,
          "click_window": 7,
          "embed_code": "<script src="//platform.x.com/oct.js" type="text/javascript"></script><script type="text/javascript">twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img height="1" width="1" style="display:none;" alt=""  src="https://analytics.x.com/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /><img height="1" width="1" style="display:none;" alt=""  src="//t.co/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /></noscript>",
          "id": "o3bk1",
          "retargeting_enabled": false,
          "last_tracked_at": "2021-05-22T17:00:04Z",
          "status": "TRACKING",
          "type": "DOWNLOAD",
          "website_tag_id": "ny3od",
          "deleted": false
        }
      ]
    }

​
GET accounts/:account_id/web_event_tags/:web_event_tag_id

Retrieve a specific web event tag associated with the current account.
Resource URL
https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id
Parameters
NameDescription
account_id
required		The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
web_event_tag_id
required		A reference to the web event tag you are operating with in the request.

Type: string

Example: o3bk1
with_deleted
optional		Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false
Example Request
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1
Example Response
    {
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "web event tag",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src="//platform.x.com/oct.js" type="text/javascript"></script><script type="text/javascript">twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img height="1" width="1" style="display:none;" alt=""  src="https://analytics.x.com/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /><img height="1" width="1" style="display:none;" alt=""  src="//t.co/i/adsct?txn_id=ny3od&amp;p_id=Twitter&amp;tw_sale_amount=0&amp;tw_order_quantity=0" /></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "TRACKING",
        "type": "DOWNLOAD",
        "website_tag_id": "ny3od",
        "deleted": false
      }
    }

​
POST accounts/:account_id/web_event_tags

Create a new web event tag associated with the current account.

​
Resource URL

https://ads-api.x.com/12/accounts/:account_id/web_event_tags

​
Parameters

NameDescription
account_id
required		The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
click_window
required		The click window for this web tag.

Note: Only the possible values listed below are accepted.

Type: int

Possible values: 1, 7, 14, 30
name
required		The name of the web tag.

Type: string

Example: Sample single conversion event
retargeting_enabled
required		Indicates if retargeting should be enabled for this web tag.

Type: boolean

Possible values: true, false
type
required		The type of web tag.

Type: enum

Possible values: ADDED_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, CHECKOUT_INITIATED, CONTENT_VIEW, CUSTOM, DOWNLOAD, PRODUCT_CUSTOMIZATION,PURCHASE, SEARCH, SIGN_UP, SITE_VISIT, START_TRIAL, SUBSCRIBE

(On UI, SITE_VISIT is shown as “Page view” and SIGN_UP is shown as “Lead”)
view_through_window
required		The view through window for this web tag. This value must always be less than or equal to the click_window value.

Note: Only the possible values listed below are accepted.

Type: int

Possible values: 0, 1, 7, 14, 30
Example Request
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags?click_window=7&name=web event tag&retargeting_enabled=false&type=SITE_VISIT&view_through_window=7

​
Example Response

    {
      "data": {
        "name": "web event tag",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": null,
        "status": "UNVERIFIED",
        "type": "SITE_VISIT",
        "website_tag_id": "ny3od",
        "deleted": false
      },
      "request": {
        "params": {
          "name": "web event tag",
          "view_through_window": 7,
          "click_window": 7,
          "retargeting_enabled": false,
          "account_id": "18ce54d4x5t",
          "type": "SITE_VISIT"
        }
      }
    }

​
PUT accounts/:account_id/web_event_tags/:web_event_tag_id

Update a web event tag associated with the current account.
Resource URL
https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id

​
Parameters

NameDescription
account_id
required		The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
web_event_tag_id
required		The identifier for a web tag on the current account.

Type: string

Example: o3bk1
click_window
optional		The click window for this web tag.

Note: Only the possible values listed below are accepted.

Type: int

Possible values: 1, 7, 14, 30
name
optional		The name of the web tag.

Type: string

Example: Sample single conversion event
retargeting_enabled
optional		Indicates if retargeting should be enabled for this web tag.

Type: boolean

Possible values: true, false
type
optional		The type of web tag.

Type: enum

Possible values: Possible values: ADDED_PAYMENT_INFO, ADD_TO_CART, ADD_TO_WISHLIST, CHECKOUT_INITIATED, CONTENT_VIEW, CUSTOM, DOWNLOAD, PRODUCT_CUSTOMIZATION,PURCHASE, SEARCH, SIGN_UP, SITE_VISIT, START_TRIAL, SUBSCRIBE

(On UI, SITE_VISIT is shown as “Page view” and SIGN_UP is shown as “Lead”)
view_through_window
optional		The view through window for this web tag. This value must always be less than or equal to the click_window value.

Note: Only the possible values listed below are accepted.

Type: int

Possible values: 0, 1, 7, 14, 30

​
Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1?type=DOWNLOAD

​
Example Response

    {
      "data": {
        "name": "web event tag",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "UNVERIFIED",
        "type": "DOWNLOAD",
        "website_tag_id": "ny3od",
        "deleted": false
      },
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "type": "DOWNLOAD",
          "account_id": "18ce54d4x5t"
        }
      }
    }

​
DELETE accounts/:account_id/web_event_tags/:web_event_tag_id

Delete a specific web event tag associated to the current account.

​
Resource URL

https://ads-api.x.com/12/accounts/:account_id/web_event_tags/:web_event_tag_id
Parameters
NameDescription
account_id
required		The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
web_event_tag_id
required		The identifier for a web tag on the current account.

Type: string

Example: o3bk1
Example Request
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/web_event_tags/o3bk1
Example Response
    {
      "data": {
        "name": "web event tag",
        "view_through_window": 7,
        "click_window": 7,
        "embed_code": "<script src='"//platform.x.com/oct.js"' type='"text/javascript"'></script><script type='"text/javascript"'>twttr.conversion.trackPid('ny3od',  { tw_sale_amount: 0, tw_order_quantity: 0 });</script><noscript><img alt='""' height='"1"' src='"https://analytics.x.com/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/><img alt='""' height='"1"' src='"//t.co/i/adsct?txn_id=ny3od&p_id=Twitter&tw_sale_amount=0&tw_order_quantity=0"' style='"display:none;"' width='"1"'/></noscript>",
        "id": "o3bk1",
        "retargeting_enabled": false,
        "last_tracked_at": "2021-05-22T17:00:04Z",
        "status": "UNVERIFIED",
        "type": "DOWNLOAD",
        "website_tag_id": "ny3od",
        "deleted": true
      },
      "request": {
        "params": {
          "web_event_tag_id": "o3bk1",
          "account_id": "18ce54d4x5t"
        }
      }
    }