Web Conversions
POST version/measurement/conversions/:pixel_id¶
Send website conversion events for a single Universal Website Tag pixel 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 of 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.twitter.com/12/measurement/conversions/:pixel_id
Request URL Parameters¶
| Name | Description |
|---|---|
pixel_id required |
The Universal Website Tag (UWT) ID for an ad account. This
represents that base36 encoded value for an ad account’s UWT id. Type: string Example: |
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 object
| Name | Description |
|---|---|
conversion_time required |
The time, expressed in ISO 8601. Type: string Example: |
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:
|
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 ( Type: array Example:
|
number_items optional |
The number of items being purchased in the event. Must be a positive number greater than zero. Type: integer Example:
|
price_currency optional |
The currency of items being purchased in the event, expressed in ISO-4217. See Currency for detailed information. Type: string Default:
Example: |
value optional |
The price value of items being purchased in the event,
represented in Type: double Example: |
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:
|
description optional |
Description with any additional information on the conversions. Type: string Example:
|
contents optional |
List of details relating to a specific product/content to provide granular information. See table below for supported fields. Type: array Example:
|
identifiers object (at least one of the identifiers is required)
| Name | Description |
|---|---|
twclid sometimes required |
Twitter Click ID as parsed from the click-through URL. It's required if no other identifier is added. Type: string Example: |
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 |
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
|
contents object
| Name | Description |
|---|---|
content_id optional |
SKU or GTIN; identifier that represents the content. Type: string Example: |
content_group_id optional |
ID associated with a group of product variants Type: integer Example: |
content_name optional |
Name of the product or service. Type: string Example:
|
content_price optional |
Price of the product or service. Type: double Example: |
content_type optional |
Category for the product that was purchased. Type: string Example: |
num_items optional |
Number of products purchased Type: integer Example:
|
Response Parameters¶
| Name | Description |
|---|---|
conversions_processed |
Number of conversions successfully processed Type: integer Example: |
debug_id |
A debug UUID that can be used for subsequent investigations Type: string Example:
|
Example Request¶
twurl -H 'ads-api.twitter.com' -X POST '/12/measurement/conversions/o8z6j' --data '
{
"conversions":[
{
"conversion_time":"2022-02-18T01:14:00.603Z",
"event_id":"o87ne",
"identifiers":[
{
"twclid":"23opevjt88psuo13lu8d020qkn"
},
{
"hashed_email":"d360d510a224510f373931ce2d6215a799f5a9c1cef221b0149b6b6b50cced62"
},
{
"hashed_phone_number":"1fa6b8d986d9b9cd01bf36951815158bbde9f520c0567c835dfe34783d0a4231"
}
],
"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"
}
}