conversions

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 60,000 events per account, per 15 minute interval.

Resource URL

https://ads-api.twitter.com/11/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: o6dkt

Post Body Parameters

These parameters must be included in the JSON Post Body of the API request.

Name Description
conversions
required

List of conversions. Max of 500 conversion objects. See the table below for supported fields.

Type: Array

Example: "conversions":[{"conversion_time": "2022-02-18T01:14:00.603Z", "event_id":"o6dl3", "identifiers": [{"twclid": "23opevjt88psuo13lu8d020qkn"}]}]

contents
optional

List of details relating to a specific product/content to provide granular information. See table below for supported fields.

Type: List

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

conversion_id
optional

An identifier for a conversion event that can be used for de-duplication between Web Pixel and Conversion API conversions in the same SET. See the Conversions Guide for more information.

Type: string

Example: 23294827

description
optional

Description with any additional information on the conversions.

Type: string

Example: test conversion

event_source_url
optional

The URL-encoded URL source of the conversion event.

Type: string

Example: https%3A%2F%2Fwww.twitter.com%2Fhome

search_string
optional

Text that was searched for on the advertiser’s website.

Type: string

Example: bananas

conversions object

Name Description
conversion_time
required

The time, expressed in ISO 8601, that the line item will stop serving.

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 Single Event Website Tag in Ads Manager and Ads API.

Type: string

Example: ny3d

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 (twclid or email) is required.

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 type of a currency to filter results by, identified using ISO-4217. This is a three-letter string such as "USD".

Type: string

Example: JPY

value
optional

The price value of items being purchased, represented in price_currency currency.

Type: double

Example: 100.00

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 hashed_email identifier is not added.

Type: string

Example: 26l6412g5p4iyj65a2oic2ayg2

hashed_email
sometimes required

A hashed email address (SHA256). The text must be lowercase, remove any trailing or leading spaces before hashing. It's required if twclid identifier is not added.

Type: string

Example: For test-email@test.com = e586883b2b4faf78d48300a79e0e15138d664cdf796ffb86e533170a9893eda8

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

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

Example: 1

Response Parameters

Name Description
conversions_processed

Number of conversions successfully processed

Type: int

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.twitter.com' -X POST '/11/measurement/conversions/o8z6j' --data '
{
  "conversions": [
    {
      "conversion_time": "2022-02-18T01:14:00.603Z",
      "event_id": "o87ne",
      "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"
  }
}