POST /data/deletion-optout/advertiser (External Provider)

Enables you to delete data from audience segments for the specified user ID on behalf of an advertiser.

If you're a merchant or data partner looking to delete IDs shared with The Trade Desk via a product catalog, use the POST /data/deletion-optout/merchant endpoint.

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.

IMPORTANT: If you are using signature header authentication instead of token authentication, encode the body of your request with your secret key using the TtdSignature and TtdSignature-dp header.

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.
• You can delete 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 with different ID types

The following is a POST /data/deletion-optout/advertiser example with an external provider and different types of IDs in the Items array used for demonstration purposes.

{
    "DataProviderId": "PROVIDER_ID_PLACEHOLDER",
    "AdvertiserId": "ADVERTISER_ID_PLACEHOLDER",
    "Items": [
        {
            "TDID": "123e4567-e89b-12d3-a456-426652340000",
            "DAID": "a9342d1f-69f1-4bf8-bc2b-1f20eb451f21",
            "UID2": "48MjlfIUZpOKNAm9nod7/jCLAXUYsnE1tpVHQSDS0uo=",
            "UID2Token": "AdvertisingTokenmZ4dZgeuXXl6DhoXqbRXQbHlHhA96leN94U1uavZVspwKXlfWETZ3bbesPFFvJxNLLySg4QEYHUAiyUrNncgnm7ppu0mi6wU2CW6hssiuEkKfstbo9XWgRUbWNTM+ewMzXXM8G9j8Q=", 
            "ID5": "ID5-c62drGF0EC6wsCZVFDbTbZwi33eB0uZTIC8FxJpzsQ", //This must be a decrypted ID5 ID
            "netID": "vp3hsuQk0I8gUEh-Y4gm3R6e8Wm7z8vkWrp_kjlXtKgbIYraTgAmKfm5kbo660gMo2lR4w",
            "FirstId": "8934d279bba4c7d652a02f624dc334e3",
            "UtiqId": "7f3ac21e-0d94-4b8a-9c17-6ee2f0a5d3b1"
        }
    ],
    "RequestType": 0
}

NOTE: If you prefer, you can list different IDs separately in the Items object. This does not affect how the IDs are processed.

Request example with the same ID type

The following is a POST /data/deletion-optout/advertiser example with an external provider and the same types of IDs in the Items array, RampID, used for demonstration purposes.

{
    "DataProviderId": "PROVIDER_ID_PLACEHOLDER",
    "AdvertiserId": "ADVERTISER_ID_PLACEHOLDER",
    "Items": [
        {
            "RampID": "XY1005wXyWPB1SgpMUKIpzA0I3UaLEz-2lg0wFAr1PWK7FMhs"  // This is a 49-character RampID example.
        },
        {
            "RampID": "Xi1005p_iYcKP7ZlvFwwK9EwR8GKl_VJqIWUhEaAFmHLAjNOQ9b6OQzSkA43XiVFcTYQ9X"  // This is a 70-character RampID example.
        }
    ],
    "RequestType": 0
}

Request object properties

The following table lists the POST /data/deletion-optout/advertiser 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.

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.

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.