Segment Activation

Segment Activation

VERSION: 1.0.0

Product Overview

ID5 ID: Activate is a solution for data platforms who have their own identity solution for building user profiles, but need a way to activate that data with other platforms (typically DSPs, but could be data exchanges, SSPs, or any other platform that their data is sold through). Rather than ingesting a decrypting the ID5 ID and using it internally as an identifier, the data platform can pass ID5 their own user ID, along with any Partner Data, to ID5 where we will store it along with our ID5 ID for the user. When the platform is ready to activate their data, they make a request to ID5 with all of their user IDs (and/or Partner Data), and ID5 will return back the matching encrypted ID5 IDs that can be passed to their partners for decryption and usage.

User ID Flow



  1. The Publisher first loads its CMP and captures the user’s consent preferences. This is essential before any IDs are requested or delivered
  2. The Data Platform's tag is loaded and sends applicable data to its servers and returns its own User ID to the page, along with the ID5 JS API
  3. The ID5 API is initialized by the data tag and passes along its own User ID and any applicable Partner Data to ID5. This step is referred to below as "Ingestion"
  4. ID5 will store the Data Platform's User ID and any Partner Data and link them to the ID5 ID for the user
  5. After the Data Platform has collected enough data and built segments using its own User ID, it will be ready to push the data to its activation platform. At this point, a bulk request is made to ID5 server-side, passing all of the Data Platform's applicable User IDs and/or Partner Data. This step is referred to below as "Matching"
  6. ID5 uses the Data Platform's User IDs and/or Partner Data to lookup the matches it had stored in step 4 to retrieve the applicable ID5 IDs. These IDs are then returned, mapped to the original ID/Data, as encrypted ID5 IDs
  7. The encrypted  ID5 IDs are then sent to the Activation Platform as segments
  8. The Activation Platform decrypts the ID5 IDs and stores them for later use

Ingestion Details

As described in Step 3 above, ingestion takes place using the ID5 Javascript Library. The API must be initialized with the Data Platform's User ID or other Partner Data. The only difference from a standard implementation is that the ID5 ID will not be made available in the response to the API, as the Data Platform will have no use for it.

Matching Details

Overview

As described in Step 5 above, the matching request will be made from the Data Platform's server when it is ready to activate a set of users and needs to retrieve the freshly encrypted ID5 IDs.

Request

Example URL

Request Type

HTTP POST with JSON body is the only supported method

Request Headers

Content-Type: application/json; charset=UTF-8

Partner Number

The value  {PARTNER} in the above example url will be replaced by an ID5-provided Partner Number. This value will be static for you once we set you up in our system. You may use the example URL above during testing with the Partner Number 173. If you haven't already been assigned a Partner Number, please contact us to request one.

Limitations

A maximum of 1,000 users can be included in a single request.

Querystring Parameters

Name
Description
token
A permanent security token provided by ID5

Request Body

Name
Type
Required
Description
users
array
x
Array of Request User Objects

Request User Object

Name
Type
Required
Description
partner_user_id
string

The Data Platform User ID passed into ID5 during the Ingestion process. This corresponds to the key "5" in Partner Data for "partner-specific user id value"
email_sha256
string

Email hashed with SHA-256 that was provided during the Ingestion process.  This corresponds to the key "1" in Partner Data for "sha256 hashed email".

Example Request

{
  "users": [
    {
      "partner_user_id": "0x123"
    },
    {
      "email_sha256": "a150e219c0f8f3ad73f21a78c9376b15cb9ae96e36959f5406ed836f517f746s"
    }
  ]
}

Response

HTTP Response Codes

Code
Description
200 - OK
The request has been accepted.
400 - Bad Request
The request was unacceptable, most likely due to invalid parameters.
401 - Unauthorized
No valid API token provided.
403 - Forbidden
The API token does not have the permission to perform the request.
429 - Too Many Requests
Too many requests hit the API too quickly.

Body

Name

Type

Description

users
array
Array of Response User Objects
error
object
Error Object

Response User Object

Name

Type

Description

uid

string

The UID that is to be used for sharing with other parties. The value will be encrypted and will change periodically, even for the same set of inputs.

partner_user_id

string

The same partner_user_id that was provided on the request

email_sha256

string

The same email hashed with SHA-256 that was provided on the request

error

object

Error Object

Error Object

Name

Type

Description

code

string

For some errors that could be handled programmatically, a short string indicating the error code reported. Any of Error Codes .

message

string

A human-readable message providing more details about the error.

type

string

Any of Error Types

Error Codes

Name

Description

api_token_invalid

No token has been supplied.

api_token_not_authorized

The provided token does not have access to perform this method.

partner_id_invalid

The request provided an unknown partner id.

sha256_length_invalid

The length of the expected SHA-256 is not 64 characters.

request_format_invalid

The provided JSON body contains invalid syntax.

user_objects_invalid

The provided JSON body contains less than 1 or more than 1,000 Request User Objects.

Error Types

Name

Description

validation_error

Errors triggered when failing to validate fields.

invalid_request_error

Arises when the request has invalid parameters.

authentication_error

Failure to properly authenticate yourself in the request.

rate_limit_error

Too many requests hit the API too quickly.

Example Successful Response

{
  "users": [
    {
      "partner_user_id": "0x123",
      "uid": "ID5-1"
    },
    {
      "email_sha256": "a150e219c0f8f3ad73f21a78c9376b15cb9ae96e36959f5406ed836f517f746s",
      "uid": "ID5-2"
    }
  ]
}

Example Error Response

{
  "users": [
    {
      "error": {
        "code": "sha256_length_invalid",
        "message": "'150e219c0f8f3ad73f21a78c9376b15cb9ae96e36959f5406ed836f517f746s' does not conform to SHA-256",
        "type": "validation_error"
      },
      "email_sha256": "150e219c0f8f3ad73f21a78c9376b15cb9ae96e36959f5406ed836f517f746s"
    }
  ],
  "error": {
    "code": "user_objects_invalid",
    "message": "Rejected all user objects due to invalidation errors",
    "type": "validation_error"
  }
}