POST /data/advertiser (External Provider)

The POST /data/advertiser endpoint enables you, as an external provider, to upload first-party data on behalf of the specified advertiser 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.

NOTE: 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.
• The BaseBidCPM and TTLInMinutes (time-to-live in minutes) values 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.
• If your data comes from the European Economic Area, the United Kingdom (under the UK GDPR), or Switzerland, collectively GDPR Regions, it might be subject to policy restrictions.

Special requirements

If you are an advertiser in the Medical Health industry category, make sure the audience data you upload complies with the following requirements:

• It must not contain data about individuals in Washington or Nevada.
• It must include only the following data:
  • Consented data: You have affirmative consent from the individual to use and disclose data about their health for advertising purposes.
  • Modeled data: Identifiers are associated with individuals for whom you have no knowledge or evidence suggesting specific health conditions.

Request example

The following is a POST/data/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",
            "Data": [
                {
                    "Name": "1210",
                    "TimestampUtc": "2023-11-11T10:11:30+5000",
                    "TTLInMinutes": 43200,
                    "BaseBidCPM": 5,
                    "BidFactor": 1.5
                },
                {
                    "Name": "1160",
                    "TimestampUtc": "2023-11-13T09:35:30+5000",
                    "TTLInMinutes": 43200
                }
            ]
        },
        {
            "DAID": "a9342d1f-69f1-4bf8-bc2b-1f20eb451f21",
            "Data": [
                {
                    "Name": "1150",
                    "TimestampUtc": "2023-08-01T12:10:35+5000",
                    "TTLInMinutes": 43200
                }
            ]
        },
        {
            "UID2": "48MjlfIUZpOKNAm9nod7/jCLAXUYsnE1tpVHQSDS0uo=",
            "Data": [
                {
                    "Name": "1630",
                    "TimestampUtc": "2023-02-01T15:21:45+5000",
                    "TTLInMinutes": 43200
                }
            ]
        },
        {
            "UID2Token": "AdvertisingTokenmZ4dZgeuXXl6DhoXqbRXQbHlHhA96leN94U1uavZVspwKXlfWETZ3b/besPFFvJxNLLySg4QEYHUAiyUrNncgnm7ppu0mi6wU2CW6hssiuEkKfstbo9XWgRUbWNTM+ewMzXXM8G9j8Q=",
            "Data": [
                {
                    "Name": "1845",
                    "TimestampUtc": "2023-01-04T11:27:22+5000",
                    "TTLInMinutes": 43200
                }
            ]
        },
        {
            "RampID": "XY1005wXyWPB1SgpMUKIpzA0I3UaLEz-2lg0wFAr1PWK7FMhs", //This is a 49-character RampID example.
            "Data": [
                {
                    "Name": "1130",
                    "TimestampUtc": "2023-07-01T01:15:15+5000",
                    "TTLInMinutes": 43200
                }
            ]
        },
        {
            "RampID": "Xi1005p_iYcKP7ZlvFwwK9EwR8GKl_VJqIWUhEaAFmHLAjNOQ9b6OQzSkA43XiVFcTYQ9X", // This is a 70-character RampID example.
            "Data": [
                {
                    "Name": "1170",
                    "TimestampUtc": "2023-08-01T13:01:35+5000",
                    "TTLInMinutes": 43200
                },
                {
                    "Name": "1140",
                    "TimestampUtc": "2023-08-01T13:02:55+5000",
                    "TTLInMinutes": 43200
                }
            ]
        },
        {
            "ID5": "ID5-c62drGF0EC6wsCZVFDbTbZwi33eB0uZTIC8FxJpzsQ", //This must be a decrypted ID5 ID
            "Data": [
                {
                    "Name": "1800",
                    "TimestampUtc": "2023-10-01T12:49:13+5000",
                    "TTLInMinutes": 43200
                }
            ]
        },
        {
            "netID": "vp3hsuQk0I8gUEh-Y4gm3R6e8Wm7z8vkWrp_kjlXtKgbIYraTgAmKfm5kbo660gMo2lR4w",
            "Data": [
                {
                    "Name": "1345",
                    "TimestampUtc": "2023-10-01T12:49:13+5000",
                    "TTLInMinutes": 43200
                }
            ]
        },
        {
            "FirstId": "8934d279bba4c7d652a02f624dc334e3",
            "Data": [
                {
                    "Name": "1810",
                    "TimestampUtc": "2023-10-01T12:49:13+5000",
                    "TTLInMinutes": 43200
                }
            ]
        },
        {
            "UtiqId": "7f3ac21e-0d94-4b8a-9c17-6ee2f0a5d3b1",
            "Data": [
                {
                    "Name": "1850",
                    "TimestampUtc": "2023-10-01T12:49:13+5000",
                    "TTLInMinutes": 43200
                }
            ]
        }
    ]
}

Request object properties

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

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.

Optional optimization properties

You can include bid factors and base bid values in the upload request.

IMPORTANT: Be aware of the following interactions with other properties in the Platform API.

The following table lists the interactions with other optimizations.

For details on Platform API interactions, see FAQs.

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.

FAQs

The following is a list of commonly asked questions about segments.

What's the difference between version 1 and version 2?

The difference is that version 2 includes improvements to the response format and error handling. The rest of the API is the same: there are no changes to the request format or payload. The improvements yield better results, and we recommend upgrading as soon as possible. For details, see API versions.

How do I remove a user from a segment?

To remove a user from a segment, set the TTLInMinutes property to 0.

If you are looking to support opt-out or deletion requests and you want to delete the user from your segments, you must use the POST /data/deletion-optout/advertiser (External Provider) ID deletion opt-out endpoint.

What happens if a user is in two segments with different bid factors?

When a user is in segments with different bid factors, the multiplier uses the highest value.

What is the minimum and maximum bid that can be placed for a segment?

At minimum, a bid must be at least half of the BaseBidCPM.amount value set in the ad group, or the BaseBidCPM property for the segment. The maximum bid for a segment is set in the MaxBidCPM property in the ad group.

How do I default a segment back to ad group settings?

• To disable bid factor changes, you can upload a new segment with the same identifiers and set the BidFactor property to 1.

• To use the BaseBid ad group settings, you must delete the segment with the POST /data/deletion-optout/advertiser (External Provider) endpoint.