POST /data/thirdparty

The POST /data/thirdparty endpoint enables you to upload third-party data for the specified ID for use in audience targeting.

Setup

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

• This endpoint uses the data integration environment.
• Some IDs, such as raw UID2s, raw EUIDs, and their respective tokens, are case sensitive. Pass all IDs and tokens without changing the case. Mismatched IDs can cause ID parsing or token decryption errors.

Request preparation guidelines

Here are some recommendations for preparing requests:

• The total request size may not exceed 2.5 MB, which is approximately 10,000 IDs. If needed, split large requests into several smaller requests that meet the size requirements.
• As user IDs near their time to live (TTL) expiration, you need to update the respective segments before the expiration date and use this endpoint to send data only for the updated segments to refresh them.
• The TTLInMinutes value must be non-negative.
• You can upload multiple IDs in the same request by listing them as separate objects in the Items array.
• Only one of the supported ID types is allowed per object in the Items array, but the array may contain objects with different ID types.

Request example

The following is a POST/data/thirdparty example with different types of IDs in the Items array used for demonstration purposes.

{
   "DataProviderId":"abc1234x",
   "Items":[
      {
         "TDID":"123e4567-e89b-12d3-a456-426652340000",
         "Data":[
            {
               "Name":"ax7m",
               "TimestampUtc": "2023-11-11T10:11:30+5000",
               "TTLInMinutes":43200
            },
            {
               "Name":"bt9q",
               "TimestampUtc": "2023-11-13T09:35:30+5000",
               "TTLInMinutes":43200
            }
         ]
      },
      {
         "DAID":"a9342d1f-69f1-4bf8-bc2b-1f20eb451f21",
         "Data":[
            {
               "Name":"cj3r",
               "TimestampUtc": "2023-08-01T12:10:35+5000",
               "TTLInMinutes":43200
            }
         ]
      },
      {
         "UID2":"48MjlfIUZpOKNAm9nod7/jCLAXUYsnE1tpVHQSDS0uo=",
         "Data":[
            {
               "Name":"dk4s",
               "TimestampUtc": "2023-02-01T15:21:45+5000",
               "TTLInMinutes":43200
            }
         ]
      },
      {
         "UID2Token":"AdvertisingTokenmZ4dZgeuXXl6DhoXqbRXQbHlHhA96leN94U1uavZVspwKXlfWETZ3b/besPFFvJxNLLySg4QEYHUAiyUrNncgnm7ppu0mi6wU2CW6hssiuEkKfstbo9XWgRUbWNTM+ewMzXXM8G9j8Q=",
         "Data":[
            {
               "Name":"el5t",
               "TimestampUtc": "2023-01-04T11:27:22+5000",
               "TTLInMinutes":43200
            }
         ]
      },
      {
         "RampID":"XY1005wXyWPB1SgpMUKIpzA0I3UaLEz-2lg0wFAr1PWK7FMhs", //This is a 49-character RampID example.
         "Data":[
            {
               "Name":"fm6u",
               "TimestampUtc": "2023-07-01T01:15:15+5000",
               "TTLInMinutes":43200
            }
         ]
      },
      {
         "RampID":"Xi1005p_iYcKP7ZlvFwwK9EwR8GKl_VJqIWUhEaAFmHLAjNOQ9b6OQzSkA43XiVFcTYQ9X", // This is a 70-character RampID example.
         "Data":[
            {
               "Name":"gn7v",
               "TimestampUtc": "2023-08-01T13:01:35+5000",
               "TTLInMinutes":43200
            },
            {
               "Name":"am8p",
               "TimestampUtc": "2023-08-01T13:02:55+5000",
               "TTLInMinutes":43200
            }
         ]
      },
      {
         "ID5":"ID5-c62drGF0EC6wsCZVFDbTbZwi33eB0uZTIC8FxJpzsQ", //This must be a decrypted ID5 ID
         "Data":[
            {
               "Name":"hp8w",
               "TimestampUtc": "2023-10-01T12:49:13+5000",
               "TTLInMinutes":43200
            }
         ]
      },
      {
         "netID":"vp3hsuQk0I8gUEh-Y4gm3R6e8Wm7z8vkWrp_kjlXtKgbIYraTgAmKfm5kbo660gMo2lR4w",
         "Data":[
            {
               "Name":"iq9x",
               "TimestampUtc": "2023-10-01T12:49:13+5000",
               "TTLInMinutes":43200
            }
         ]
      },
      {
         "FirstId":"8934d279bba4c7d652a02f624dc334e3",
         "Data":[
            {
               "Name":"jr0y",
               "TimestampUtc":"2023-10-01T12:49:13+5000",
               "TTLInMinutes":43200
            }
         ]
      },
      {
         "UtiqId":"7f3ac21e-0d94-4b8a-9c17-6ee2f0a5d3b1",
         "Data":[
            {
               "Name":"kr1z",
               "TimestampUtc":"2023-10-01T12:49:13+5000",
               "TTLInMinutes":43200
            }
         ]
      }
   ]
}

Request object properties

The following table lists the POST /data/thirdparty request object properties.

Items object array

The following table lists the properties required for each array object in the Items object array.

Supported ID types

The following table lists the ID types currently supported in Items object arrays. Each array object must contain one ID.

Data object

The following table lists the Data object properties. The Data object specifies the segments to which to add the specified ID and the amount of time during which the data is to remain active.

Timestamp in UTC

The TimestampUtc field serves three purposes:

• Relative ordering: It determines whether an incoming operation takes effect relative to what is already stored for that user-segment pair.
• Expiration: It is the reference point from which the TTLInMinutes value is measured to determine when the user-segment pair expires.
• Recency: It determines the recency of the user-segment pair for evaluating its targeting exclusion and bid adjustments.

Relative ordering

When a request is received for an existing user-segment pair, its TimestampUtc value is compared against the value already stored for that pair. The request takes effect if:

• The timestamp is newer than the stored value.
• The timestamp equals the stored value, but its TTLInMinutes value is higher.
• No record of the pair exists.

The following sections describe additional ordering behavior for closely timed requests and for deletions.

• Ordering guarantees

To guarantee ordering for closely spaced requests on the same pair, set their TimestampUtc values at least 2 minutes apart. Requests on the same user-segment pair that are sent within seconds of each other can be applied out of order, regardless of the order in which they are sent.

When two requests on the same pair share the same timestamp, the one with the higher TTLInMinutes value wins.

• Ordering with deletions

To preserve request ordering, when a user-segment pair is deleted (TTLInMinutes = 0), its TimestampUtc value is retained for at least 6 hours from the timestamp of the deletion. To re-insert the pair after deletion, set a timestamp newer than the one sent with the deletion, or omit the field.

Expiration

The user-segment pair expires at TimestampUtc + TTLInMinutes with the following limits:

• A timestamp whose expiration (TimestampUtc + TTLInMinutes) is more than 1 hour in the past is not supported.
• A timestamp more than 1 hour in the future is not supported.

Recency

The TimestampUtc value is the recency date used for resolving the following:

• Whether a targeting exclusion applies to the user-segment pair. For details, see RecencyExclusionWindowInMinutes.
• Which bid adjustment bracket applies to the user-segment pair. For details, see RecencyWindowInMinutes.

Versioning

Two versions of the Data API are available. The difference is the response format. For details, see API versions. This documentation includes both versions of the response error information.

API versions

Version 2 of the Data API is available, and includes improvements to the API response. Version 1 is fully supported, but is being deprecated. We recommend upgrading as soon as possible.

To use version 2, see Response (v2).

For details on the version timeline, see Data API version 2 with improved error handling and response format.

The following table compares the two versions.

Using the custom header

To use version 2, add the following custom header:

• Header name: TTD-Version
• Value: 2

For example: TTD-Version: 2

NOTE: The custom header is required only if you want to use a version that is not the default. Valid values for this header are 1 or 2, and if you're using the default version, currently version 1, there is no need to include the extra header.

What you need to know

Here's what you need to know about returned responses for both versions:

• If the entire request fails with no items processed, an error response is returned.
• If the request succeeds, any items that failed appear in the FailedLines array. All other items are processed.
• If the FailedLines array is empty, all items succeeded.
• Successfully processed data becomes targetable within 15–30 minutes.

IMPORTANT: A 200 OK status code does not indicate complete success. Always check the FailedLines array for line-level errors.

Response (v2)

To use version 2, you'll need to:

• Use a new custom header. For details, see Using the custom header.
• Update how you parse error responses. The new responses are in JSON format.

The following sections provide details about success and failed responses for version 2, including response format, response examples, and error messaging.

Success response (v2)

If the request is successful, the response has an HTTP status code of 200 OK and includes a FailedLines array with details of any items that were not processed.

Success response example (v2)

The following is an example of a success response with one FailedLines entry:

{
  "FailedLines": [
    {
      "ErrorCode": "ItemDeserializationError",
      "Message": "Item number 2: A deserialization error occurred. Could not find member 'xTDID' on object of type 'AdvertiserDataItem'. Path 'Items[1].xTDID', line 14, position 16.",
      "ItemNumber": "2"
    }
  ]
}

Success response object properties

The following table lists the object properties for a successful response.

FailedLine object properties (v2)

The following table lists the FailedLine object properties for version 2 of the Data APIs.

FailedLine error codes and messages (v2)

The following table lists the error codes that might be returned from this endpoint in a FailedLine entry in the FailedLines object, with the reason for each error. This information is for version 2 of the Data API.

Failed response (v2)

If the request fails with no lines processed, a failed response is returned.

Failed response example (v2)

The error response is JSON and includes ErrorCode and Message properties. For example, the following response would return a 403 Forbidden HTTP status code:

{
  "ErrorCode": "TargetingDataLimitReached",
  "Message": "The maximum allowed targeting data elements limit for the specified advertiser/data provider has been reached."
}

Failed response object properties (v2)

The following table lists the object properties for a failed response.

Failed response error codes and messages (v2)

The following table provides a list of common failed response errors and their respective HTTP status codes.

IMPORTANT: When the rate limit for an API endpoint is exceeded, the server returns a 429 status code and prevents execution. Your code must be able to handle this type of error. For example, upon receiving a 429 error, wait up to one hour before retrying or reduce request volume to remain within rate limits. See also Rate limits.

Response (v1, legacy)

Version 1 is the default. The following sections provide details about error responses for version 1, including response format and error messaging.

Success response object properties

The following table lists the object properties for a successful response.

FailedLine object properties (v1)

The following table lists the FailedLine object properties for version 1 of the Data APIs.

Failed response error codes and messages (v1)

If the request fails with no lines processed, a failed response is returned. In version 1, the error response is a string. The following table provides a list of common errors and their respective HTTP status codes.

IMPORTANT: When the rate limit for an API endpoint is exceeded, the server returns a 429 status code and prevents execution. Your code must be able to handle this type of error. For example, upon receiving a 429 error, wait up to one hour before retrying or reduce request volume to remain within rate limits. See also Rate limits.