Web Conversions

conversions

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

Name Description
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

Name Description
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

Name Description
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

Name Description
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

Name Description
conversions_processed

Number of conversions successfully processed

Type: integer

Example: 1

debug_id

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