Page tree
Skip to end of metadata
Go to start of metadata

Overview

VERSION: 2.0.7

The ID5 S2S Fetch Endpoint can be used to retrieve a Universal ID from ID5 for a single user server-side from a publisher/brand's server. This allows publishers to reduce page latency and ensure the ID is available at the time of the auction since it can be delivered with the page content.

Request

Example URL

https://id5-sync.com/gs/v2/{PARTNER}.json

Request Type

HTTP POST with JSON body is the preferred method as it eliminates any query string length limitations. However, if you cannot support POST, you may use a GET request and simply use the parameters as query string key/values instead of a JSON body.

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.

Available Parameters

Querystring

Name

Description

gdpr

0 or 1 if gdpr applies or not

gdpr_consent

TCF consent string, if applicable

Request Body

Name

Required

Description

partner

x

Partner Number provided by ID5 (same as the value used in the querystring)

v

x

Version of code calling us (i.e. Prebid.js version)

o

x

Origin of caller (Prebid, API, Index Exchange, etc)

rf


Referer URL

Web traffic only

u

x

Page URL

Web traffic only

appidx

Mobile App ID

Mobile app traffic only

top

x

0 or 1 whether the top window was accessible

s


ID5 Signature - the string returned in the response that is stored by the caller and sent back to ID5 on all requests. See below for details about the Signature

pd


Publisher Data - a base64 encoded string that contains any deterministic data available. Possible keys in the string are:

  • 0 = other
  • 1 = sha256 hashed email
  • 2 = sha256 hashed phone number
  • 3 = cross-domain publisher user id value
  • 4 = cross-domain publisher user id source (value provided by ID5)
  • 5 = publisher user id value

ipv4

x

The IPv4 address of the end-user’s device.

ua

x

The user agent string of the end-user’s device

ts

x

The timestamp of the user’s visit to the page in ISO 8601 timestamp format in UTC timezone (e.g. 2020-09-23T07:37:11Z). This value must be within 60 minutes of the time that the server request is being made.

Deriving the Publisher Data (pd) Value

Suppose you have an email address for the user, in this example it is myuser@domain.com, and want to share it with ID5 to strengthen the value of the UID we respond with. You also have your own user id for this user that you can share: ABC123.

First, perform a sha256 hash of the email, resulting in a string b50ca08271795a8e7e4012813f23d505193d75c0f2e2bb99baa63aa822f66ed3.

Next, create the raw pd string containing the keys 1 (for the hashed email) and 5 (for the publisher user id), separated by &’s (the order doesn’t matter):

1=b50ca08271795a8e7e4012813f23d505193d75c0f2e2bb99baa63aa822f66ed3&5=ABC123

Finally, base64 the entire raw pd string, resulting in the final pd value:

MT1iNTBjYTA4MjcxNzk1YThlN2U0MDEyODEzZjIzZDUwNTE5M2Q3NWMwZjJlMmJiOTliYWE2M2FhODIyZjY2ZWQzJjU9QUJDMTIz

Example Request

POST: https://id5-sync.com/gs/v2/173.json?gdpr=1&gdpr_consent=BOEFEAyOEFEAyAHABDENAI4AAAB9vABAASA

{
    "partner": "173",
    "v": "3.8.0",
    "o": "pbjs",
    "rf": "https://google.com",
    "u": "https://www.bbc.com/sport/football/scores-fixtures",
    "top": 1,
    "s": "1e74c8d77f4196311f90613ddac55062",
    "pd": "MT1iNTBjYTA4MjcxNzk1YThlN2U0MDEyODEzZjIzZDUwNTE5M2Q3NWMwZj
JlMmJiOTliYWE2M2FhODIyZjY2ZWQzJjU9QUJDMTIz",
	"ipv4": "123.123.123.123",
	"ua": "",
	"ts": "2020-09-23T07:37:11Z"
}

Response

Body

Name

Description

created_at

Timestamp when the user id was first created

id5_consent

Boolean; if ID5 had proper consent on the request to process the user’s data. See below for more information about how ID5 handles requests with and without consent.

signature

ID5 Signature - a string that must be stored by the caller and sent back to ID5 on all future requests. See below for details about the Signature

original_uid

The first UID that was created for this user. This is for reference only for the publisher and should not be shared with other partners. The value will be encrypted and will change periodically even for the same user on the same domain.

universal_uid

The UID that is to be used for sharing with other parties. This UID may be the same as the original_uid if ID5 has not linked the user to any other UIDs yet; or it may be a different value if ID5 has linked this user to another, more permanent UID. The value will be encrypted and will change periodically even for the same user on the same domain.

link_type

0 = ID5 has not linked this user across domains (i.e. original_uid == universal_uid)

1 = ID5 has made a probabilistic link to another UID

2 = ID5 has made a deterministic link to another UID

Example Response

{
    "created_at": "2020-01-04T15:27:34.538Z",
    "id5_consent": true,
    "signature": "1e74c8d77f4196311f90613ddac55062",
    "original_uid": "ID5-12345",
    "universal_uid": "ID5-67890",
    "link_type": 2
}

ID5 Signature

The ID5 Signature will be returned on every response from ID5 and contains all "user state" information necessary to support cross-domain reconciliation. As an example, this could include the following pieces of data:

  • Original UID value (the first UID ever generated for this user on this domain/publisher)
  • Cookie Birthdate
  • Last Seen Timestamp (from this domain/publisher)
  • Current Universal UID value
  • Link Type

The Signature is used only by ID5 (it will be encrypted with a private key) and must be passed in every request to ID5 (once we have provided the Signature in a response).

How ID5 Handles Privacy

If ID5 has the necessary legal basis to process the user’s data, ID5 will:

  • Attempt to read/write our 3rd party to access/store our ID
  • Attempt to link the publisher’s user ID (original_uid) with user IDs seen on other publishers in order to produce a more valuable universal_uid

If ID5 does NOT have a legal basis to process the user’s data, ID5 will:

  • NOT read or write any cookies
  • NOT provide a link between the publisher’s user ID (original_uid) and other user IDs seen on other publishers
  • Reply with the same user ID provided in the request, if present in the universal_uid or signature fields, potentially re-encrypting it if necessary
  • Generate a new user ID for the publisher if there was no ID present in the request in the universal_uid or signature fields, allowing them to decide if they would like to store the user ID under their own legal basis or not




  • No labels