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 |
| appid | x | 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:
| |
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. |
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. 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 valuableuniversal_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_uidorsignaturefields, 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_uidorsignaturefields, allowing them to decide if they would like to store the user ID under their own legal basis or not