Implementing UIDs in bid requests

Unified IDs (UIDs) in bid requests originate in one of two ways: a publisher directly observes a user authentication event, or a publisher works with a third-party identity vendor (such as a person or household graph provider) to resolve a UID from previously collected data. In either case, the UID can be passed to The Trade Desk through any supply path, including OpenPath, OpenAds, or SSPs.

For a high-level overview of different types of UIDs, such as UID2s, EUIDs, raw UIDs, and tokens, see Unified IDs. For more details, such as how to generate a token, see the UID2 and EUID documentation.

Implementation guidelines

Here's what you need to know about implementing UIDs in bid requests:

Include the ID only when the following conditions are met:
- A UID is present.
- The id field value is not empty or null.
- For EUID, the user has given consent.
Send only a UID token (encrypted UID). Raw UIDs are not permitted in the bidstream.
Include ID provenance information (the source, inserter, and mm fields) alongside each UID. This communicates how the ID was matched or resolved.
When including multiple UIDs of the same type (UID2 or EUID) in a single bid request, do the following:
- Order them by decreasing confidence, placing the UID you are most confident in first. Alternatively, include only the single highest-confidence UID.
- Include each UID in its own eid object with its own set of ID provenance fields.

IMPORTANT: If you are an SSP, forward any UID you receive from a publisher without performing identity graphing.

Here's additional information to help with your implementation:

For best practices, see Identity.
For field reference, see User object in the The Trade Desk Standard Adapter specification.

Implementation examples

The following sections provide examples of code snippets that you can use as reference to implement a UID token in a bid request. For complete examples of these snippets in context, see Bid request and response examples.

Directly observed UID2

In this example, the publisher is both the source and the inserter. They directly observed the UID2 on their own property because the user was logged in or authenticated at the time. The mm value of 3 reflects this authenticated match method. The atype value of 3 indicates the ID is tied to an authenticated user context, and the rtiPartner value identifies UID2 as the identity provider.

{
  "user": {
    "eids": [
      {
        "source": "uidapi.com",
        "inserter": "publisher.com",
        "mm": 3,
        "uids": [
          {
            "id": "abc123aAbc2AbcDEF+ghi+JKLmnOPqrSTuv...",
            "atype": 3,
            "ext": {
              "rtiPartner": "UID2"
            }
          }
        ]
      }
    ]
  }
}

UID2 deterministic match by a third-party provider

In this example, the third-party provider identified in the matcher field resolved the UID2 using a deterministic match, meaning the user was actively logged in or authenticated at the time of the match. The mm value of 3 reflects this authenticated match method. The atype value of 3 indicates the ID is associated with an authenticated user context, and the rtiPartner value identifies UID2 as the identity provider.

{
  "user": {
    "eids": [
      {
        "source": "uidapi.com",
        "inserter": "inserter.com",
        "matcher": "graph-partner.com",
        "mm": 3,
        "uids": [
          {
            "id": "abc123aAbc2AbcDEF+ghi+JKLmnOPqrSTuv...",
            "atype": 3,
            "ext": {
              "rtiPartner": "UID2"
            }
          }
        ]
      }
    ]
  }
}

UID2 probabilistic match by a third-party provider

In this example, the third-party provider identified in the matcher field resolved the UID2 using a probabilistic match based on a previously collected email—for example, from a past newsletter signup, contest entry, or product purchase, stored in a first-party cookie. This method applies even after the user has logged out. The mm value of 4 reflects this probabilistic approach. The atype value of 3 indicates an authenticated user context, and rtiPartner identifies UID2 as the identity provider.

{
  "user": {
    "eids": [
      {
        "source": "uidapi.com",
        "inserter": "inserter.com",
        "matcher": "graph-partner.com",
        "mm": 4,
        "uids": [
          {
            "id": "abc123aAbc2AbcDEF+ghi+JKLmnOPqrSTuv...",
            "atype": 3,
            "ext": {
              "rtiPartner": "UID2"
            }
          }
        ]
      }
    ]
  }
}

TDID probabilistic match by a third-party provider

In this example, the third-party provider identified in the matcher field resolved the TDID using true bridging, which means connecting identity signals across devices or environments to establish a cross-device match. The mm value of 5 indicates this bridging match method. The atype value of 1 indicates a hardware device identifier (such as a mobile or CTV device), and the rtiPartner value identifies The Trade Desk's TDID as the identity provider.

{
  "user": {
    "eids": [
      {
        "inserter": "inserter.co",
        "matcher": "graphpartner.co",
        "mm": 5,
        "source": "adserver.org",
        "uids": [
          {
            "id": "abcd1234-ef56-ac78-bd90-efa1b2c3d4e5",
            "atype": 1,
            "ext": {
              "rtiPartner": "TDID"
            }
          }
        ]
      }
    ]
  }
}

Multiple UIDs in a single request

If you pass multiple UIDs of the same type in a single bid request, The Trade Desk selects a single UID to bid on using selection logic that considers multiple aspects, including ID quality. Here's a code snippet with two EUID tokens, ordered by decreasing confidence.

{
  "user": {
    "eids": [
      {
        "source": "euid.eu",
        "inserter": "publisher.com",
        "mm": 3,
        "uids": [
          {
            "id": "abc123aAbc2AbcDEF+ghi+JKLmnOPqrSTuv...",
            "atype": 3,
            "ext": {
              "rtiPartner": "EUID"
            }
          }
        ]
      },
      {
        "source": "euid.eu",
        "inserter": "publisher.com",
        "mm": 3,
        "uids": [
          {
            "id": "xyz789xXyz9XyzABC+def+MNOpqRSTuvWXy...",
            "atype": 3,
            "ext": {
              "rtiPartner": "EUID"
            }
          }
        ]
      }
    ]
  }
}