We recommend that you deploy ID5 in CTV environments via a server to server integration. We do support alternative integration pathways depending on your requirements. If required, please reach out to your ID5 customer services representative.
To ensure accurate identity resolution, clients should provide signals, such as hashed emails in the request. We also expect you to store the 'signature' provided in our response on the user's device and provision it to us in future requests for the same user. This is integral to an optimal set up since it helps us re-identify consenting users even if their signals change as well as respect opt out requests.
Below are general instructions on how to retrieve an ID5 ID server-side for CTV inventory and make it available in bid requests to your demand partners. The auction should be delayed in order to retrieve the user’s privacy preferences and the ID5 ID prior to sending out bid requests; the amount you delay may vary and so we recommend making it configurable for optimization purposes.
Check local storage cache for an available ID5 ID
With the ID you now have from step 1 above (from request or cache), prepare the data for the bid request.
universal_uidlink_typeInclude this data in each bid request to your demand partners as an eids array. For more information on how this is typically done, you can review Sending the ID5 ID to DSPs.
The response we return for the request will need to be cached as some of the response data needs to be used in future requests for your users. Use the ts parameter sent in the request in order to set a TTL for the cache refresh and a TTL for the cache deletion.
¶ North America
¶ Global
HTTP POST with JSON body.
Content-Type: application/json
The PARTNER in the request body will be an ID5-provided Partner Number. This value will be static for you once we set you up in our system. You may use the endpoint during testing with the Partner Number 173. If you haven't already been assigned a Partner Number, please contact us to request one.
| Name | Required | Type | Description | Format | Example |
|---|---|---|---|---|---|
| ts | x | string | Timestamp in form of string which extends the ISO-8601 extended offset date-time format to add the time-zone | yyyymmddThhmmss<ffffff>+|-hhmm |
2013-02-01T12:52:34+09:00 |
| partner | x | integer | Partner Number provided by ID5 | int32 | 173 |
| appid | x | string | The store ID of the app in an app store (e.g., Apple App Store, Google Play). | ||
| ottid | when available | string | The user ID provided by the OTT/OEM. This will be the equivalent of an hard signal 3rd party cookie. | ||
| ctvid | when available | string | The specific user id for the CTV ecosystem the user is observed in, as received by the CTV/OTT/Publisher provider | 00000000-34sd-gfss-sd54-12345678abcd |
|
| ctvid_type | when available | string | CTV ID type | tifa |
|
| ver | x | Application version | |||
| ip | x | string | IPv4 address closest to device | ipv4 dot-decimal | |
| ua | x | string | The User Agent of the device's default browser | Mozilla/5.0 (Linux; Android 11; moto e20 Build/RONS31.267-88-3; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/109.0.5414.118 Mobile Safari/537.36 | |
| hardware_code | x | string | The code pertaining to the device (i.e. TV model) | ||
| signature | when available | string | The ID5 signature from a previous call, cached on the device or your server-side | ||
| gdpr | integer | 1 if gdpr applies to this request, 0 otherwise | |||
| gdpr_consent | string | (where applicable) the TCF compliant consent string or see 'allowed_vendors' | |||
| allowed_vendors | string array | ID5 Partner identifiers (starting with 'ID5-') or IAB Vendor IDs https://iabeurope.eu/vendor-list-tcf/ of vendors allowed to use the ID5ID | ['ID5-78','134'] |
||
| us_privacy | string | US Privacy Consent https://docs.prebid.org/dev-docs/modules/consentManagementUsp.html | 1YNN |
||
| gpp_sid | string | The GPP section ID(s) in force for the current transaction. In most cases, this field should have a single section ID. In rare occasions where such a single section ID can not be determined, the field may contain up to 2 values, separated by a comma. More information in GPP documentation | 6,7 |
||
| gpp_string | string | A valid IAB Global Privacy Platform consent string. | DBABzw~1---~BAAAAAAAAQA.QA |
||
| hem | string | sha256 hash of the cleansed e-mail address. Learn how to cleanse the data here https://wiki.id5.io/en/identitycloud/retrieve-id5-ids/passing-partner-data-to-id5 | sha256 | f97ea86ed181d60b0ba62a30579f1e10ad71eaf21b548e173de75718065c533f |
|
| phone | string | sha256 hash of the cleansed phone number | sha256 | ||
| idfv | string | Apple ID for Vendors | uuid | 3fa85f64-5717-4562-b3fc-2c963f66afa6 |
|
| puid | string | Partner specific user ID | |||
| ipv6 | string | The IPV6 of the device | ipv6 | 2001:0db8:5b96:0000:0000:426f:8e17:642a |
|
| country | string | Country the user is located in | ISO-3166-1-alpha-2 | AD |
|
| region | string | Region code using ISO-3166-2; 2-letter state code if USA | ISO-3166-2; 2-letter state code if USA | ||
| city | string | City using United Nations Code for Trade & Transport Locations format | United Nations Code for Trade & Transport Locations format: https://unece.org/trade/uncefact/unlocode-country-subdivisions-iso-3166-2 | ||
| accept_language | string | A string representing languages accepted by end-user device, should be compatible with browser Accept-Language header | Accept-Language header format | de-DE,de;q=0.9,en-US;q=0.8,en;q=0.7 |
|
| segments | objects array | The segment ids a user may belong to and the destination platform that the segments should be pushed to. Only certain destination platforms are supported and there are backend configurations that need to be made in both ID5's and the destination platform's systems before this feature can be used. Please reach out to your ID5 representative or contact@id5.io for more information and to get started. | Array of segment objects (see below Segment object) | [{ "destination": "999", "ids": [ "12345", "67890" ] }] |
| Name | Required | Type | Description | Example |
|---|---|---|---|---|
| destination | x | string | The destination platform. Should be the IAB Vendor ID | '999' |
| ids | x | string array | List of segment ids to add the user to | [ '12345', '67890' ] |
| Name | Required | Type | Description | Format | Example |
|---|---|---|---|---|---|
| created_at | x | string | Timestamp in form of string which extends the ISO-8601 extended offset date-time format to add the time-zone | yyyymmddThhmmss<ffffff>+|-hhmm |
2013-02-01T12:52:34+09:00 |
| original_uid | x | string | A 1st party user ID that will be stable for this user on the domain. 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 (while the underlying value is stable). If ID5 did not have consent, then the value will be "0 | ||
| universal_uid | x | 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 user on the same domain. If ID5 did not have consent, then the value will be "0" | ||
| privacy | x | object | An object containing privacy information (see below) | ||
| signature | x | string | ID5 Signature - a string that must be stored by the caller (cached on the device or your server-side) and sent back to ID5 on all future requests. See below for details about the Signature (see below for more details) | ||
| ext | x | object | See below extension object |
| Name | Required | Type | Description | Format | Example |
|---|---|---|---|---|---|
| jurisdiction | x | string | The legal jurisdiction applicable to the request (e.g. "gdpr", "ccpa", etc), based on the location the request was made from | enum | gdpr |
| id5_consent | x | boolean | Indicates if ID5 had proper consent on the request to process the user’s personal data. See below for more information about how ID5 handles requests with and without consent. |
| Name | Type | Description | Example |
|---|---|---|---|
| linktype | integer | See details here | 1 |
| Name | Type | Description | Example |
|---|---|---|---|
| code | string | A code which univocally identifies the error | - partner_id_invalid - sha256_length_invalid - request_format_invalid - user_object_invalid - internal_id5_error |
| message | string | Human readable message about the error | - unknown partner - failed to parse json POST - missing ua - missing ts - ts older than allowed - invalid ts format - Fetch of ID5 ID disabled. Please contact ID5 to enable it. - Request from a country which is disallowed. Please contact ID5 to enable it. |
| type | string | A code which identifies the class of error | - validation_error - invalid_request_error - authentication_error |
curl "https://api.id5-sync.com/gc/v1" -X POST -H 'Content-Type: application/json' -d '{
"ts": "2023-09-19T12:32:34+02:00",
"partner": 173,
"ver": "1.0",
"ip": "4.5.6.7",
"ua": "Mozilla/5.0 (Linux; Android 11; moto e20 Build/RONS31.267-88-3; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/109.0.5414.118 Mobile Safari/537.36",
"appuid": "ABCDE12345.com.example.foo",
"gpp_sid": "2",
"gpp_string": "DBAA",
"accept_language": "de-DE,de;q=0.9,en-US;q=0.8,en;q=0.7"
}'
http response status code = 200 with response
{
"created_at": "2013-02-01T12:52:34+09:00",
"original_uid": "string",
"universal_uid": "string",
"privacy": {
"jurisdiction": "gdpr",
"id5_consent": true
},
"signature": "string",
"ext": {
"linkType": 0
}
}
http response status code = 400 with response
{
"code": "partner_id_invalid",
"message": "unknown partner",
"type": "invalid_request_error"
}
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:
The Signature is used only by ID5 (it will be encrypted with a private key) and must be passed in every subsequent request to ID5.