POST /track/realtimeconversion

The POST /track/realtimeconversion endpoint enables you to upload conversion events to the platform in real-time.

Prerequisites

Before you can send conversion events, you must have a captured event and a unique ID of the user who triggered the event. For details and FAQs, see Real-time conversion events.

Technical requirements

Here's what you need to know to use this endpoint:

• The Real-Time Conversion Events API is accessible via HTTPS requests using the JSON format.
• You must specify the Content-Type: application/json header.
• This endpoint does not require authentication.

Request size limits

The total request size may not exceed 28.6 MB. There's no limit on the number of events you can send.

TIP: To upload a larger file, split it into several smaller files that meet the request size requirements. For details, see the individual endpoints.

Request example

The following is a JSON example with the request properties that you can use to communicate real-time conversion events to The Trade Desk. Specifically, the example shows the resulting JSON for a First Purchase event for booking two hotel rooms, a Deluxe Twin and King Terrace, from an Android device at the IP address 7.7.7.7 with revenue tracking enabled and sent by advertiser GenericMart with ID 4w1ba8e.

{
  "data": [
    {
      "adv": "4w1ba8e",
      "pixel_id": "hc7ihke",
      "value": 25.97,
      "currency": "USD",
      "event_name": "purchase",
      "client_ip": "7.7.7.7",
      "referrer_url": "site.com",
      "adid": "A4AAAAs6ZBcEbwAPoFhVV7CNW5W-4R-9TKDNL4RS0ctkw1U-IkNOXSnWczvwOMgCQaXHPf3Gd1o1W6IBmlZBFIloM67XOsOgwP5jUrQrclGkq1zBJJUJmOFTe6sJJA7pM1GP9gLd-hz5did6baZvcKd8DXkUYM-WALRZFnzHivu_1YEsC_CeXNdMexKDN7EwSQ6L5eZvOd1F1RkF_nLy_J0twg",
      "adid_type": "UID2",
      "tdid": "660e1d86-6796-463a-be86-897993136018",
      "daid": "3ecef5dd-21da-4a9d-a6d7-cd541666bc1e",
      "idfa": "cc9d5044-5837-4bcd-b339-26115f56deb6",
      "aaid": "8887b1e6-82cd-4b44-b36e-1a25655349a1",
      "naid": "9aa5696c-af88-4127-bfdb-107b12417913",
      "idl": "XY1234wXyWPB1SgpMUKIpzA0I3UaLEz-2lg0wFAr1PWK7FMhs",
      "imp": "49gCBlwj-9d33-0927-s9g7-sd7nF3D248d5",
      "uid2_token": "A4AAAAs6ZBcEbwAPoFhVV7CNW5W-4R-9TKDNL4RS0ctkw1U-IkNOXSnWczvwOMgCQaXHPf3Gd1o1W6IBmlZBFIloM67XOsOgwP5jUrQrclGkq1zBJJUJmOFTe6sJJA7pM1GP9gLd-hz5did6baZvcKd8DXkUYM-WALRZFnzHivu_1YEsC_CeXNdMexKDN7EwSQ6L5eZvOd1F1RkF_nLy_J0twg",
      "country": "United States",
      "region": "TX",
      "NielsenDMA": "678",
      "city": "US ELP",
      "zip": "10004",
      "order_id": "abc123XyZ",
      "items": [
        {
          "item_code": "203319203",
          "name": "Deluxe Twin Room",
          "qty": 1,
          "price": 264.00,
          "cat": "23",
          "item_brand": "Sample Hotel Group"
        },
        {
          "item_code": "#2234567892",
          "name": "King Terrace Suite",
          "qty": 1,
          "price": 399.00,
          "cat": "1110",
          "item_brand": "Sample Hotel Group"
        }
      ],
      "privacy_settings": [
        {
          "privacy_type": "GDPR",
          "is_applicable": true,
          "consent_string": "12345"
        }
      ],
      "data_processing_option": {
        "policies": [
          "LDU"
        ],
        "region": "US-CO"
      },
      "td1": "Spring 2026 Promo"
    }
  ]
}

Request properties

The following table lists all the conversion event properties that JSON requests to the POST /track/realtimeconversion endpoint support.

* © 2026, The Nielsen Company (US), LLC. The DMA® data is used pursuant to a license from The Nielsen Company (US), LLC. Any use and/or reproduction of these materials without the express written consent of The Nielsen Company (US), LLC, is strictly prohibited. DMA® data is valid for the period 2025 - 2026. DMA® is a registered service mark of The Nielsen Company (US), LLC and is used pursuant to license.

Item properties

The following table lists the items object properties that contain item-level information.

Privacy settings properties

The following table lists the privacy_settings object properties.

Data processing option properties

The following table lists the data_processing_option object properties that you can use to signal users' opt-out choices in US states with applicable privacy laws.

Event names

The Trade Desk provides a list of events that you can map to an event tracker without any additional configuration. Here's what you need to know about the event names list:

• The list is ordered from bottom-funnel actions, such as purchases (which are most desired), to top-funnel actions (that occur less consistently or are less critical).
• Some event names have similar functions (for example, InitiateCheckout and startcheckout) and are shown together. You can use whichever one, depending on your business needs.
• To map an event to an event tracker, in a Real-Time Conversion Events API call, set the pixel_id value to your tracking tag ID and the event_name with any of the following names. For details, see the Event mapping.

NOTE: To configure and manage events as a merchant with a product catalog, you need to use the platform UI. For details, see Item-Level Event Tracking in the Knowledge Portal.

Custom line-item dynamic parameters

When you include an items array in your request, The Trade Desk automatically maps item-level fields to the td1-td10 fields to support dynamic rules for commerce use cases. You do not need to populate the td1-td10 fields yourself — the platform derives these values from your items payload. This mapping occurs only on rule-matched conversion copies. The original conversion record always reflects your payload as sent.

If you do not include an items array in your request, the td1-td10 fields are available as general-purpose custom fields. You can use them to pass any additional conversion metadata relevant to your use case.

IMPORTANT: If your payload includes both an items array and explicit td1-td10 values, the item-based mapping will overwrite your td1-td10 values on any rule-matched copies. Avoid populating the td1-td10 fields manually if you are also sending an items array. If you have a use case that requires both, contact your Trade Desk representative to understand how these fields interact and their downstream impact on optimization and reporting prior to implementation.

Response format

Here's what you need to know about the Real-Time Conversion Events API responses:

• If an error or a warning occurs when processing a request, the API returns a batch response that includes a message for the entire batch and any applicable details for each failed event in it.
• The API supports partial success and specifies errors or warnings for the failed events in the response but does not fail the entire request.

TIP: For troubleshooting tips and other details about using this API, see FAQs.

The Real-Time Conversion Events API response uses the following format:

{
   "Message": null,
   "EventResponses": [
            {
         "EventIndex": 23,
         "EventErrors": [],
         "EventWarnings": [
            {
               "Warning": "Warning code",
               "WarningMessage": "Warning description."
            }
         ],
         "Successful": true // a warning was issued for the event but it processed successfully
      },
      {
         "EventIndex": 31,
         "EventErrors": [
            {
               "Error": "Error code",
               "ErrorMessage": "Error description."
            }
         ],
         "EventWarnings": [],
         "Successful": false // an event error occurred
      }
   ]
}

The following table lists the response object properties.

Event Response object properties

The following table lists the EventResponse object properties that contain information about event errors, or warnings, that might have occurred when processing the request.

Error code and responses

The following table provides a list of common errors and their respective HTTP error codes.

Here's an example of a successful response with no individual event issues:

{
   "Message": null,
   "EventResponses": []
}

Here's an example of a partially successful response with an event that is missing property values:

{
   "Message": null,
   "EventResponses":[
      {
         "EventIndex":0,
         "EventErrors":[
            {
               "Error":"MissingOrInvalidADIDType",
               "ErrorMessage":"The request is missing or has an invalid adid_type parameter. Value provided ''. Valid ADID types are: TDID, IDFA, AAID, NAID, UID2, EUID."
            },
            {
               "Error":"MissingOrInvalidTrackingTagId",
               "ErrorMessage":"The request is missing or has an invalid tracker_id parameter. Value provided ''."
            }
         ],
         "EventWarnings":[],
         "Successful":false
      }
   ]
}

Here's an example of a failed response:

{
   "Message": "The provided request could not be interpreted (no json data).",
   "EventResponses":[]
}