Overview
VERSION: 1.2.0
The Partner Signals endpoint is used to retrieve ID5 Universal IDs in bulk based on signals for a user that you have. Signals that are currently supported are only email addresses, however, more are in the pipeline.
Request
Example URL
https://api.id5-sync.com/partners/v1/{PARTNER}/signals?token={TOKEN}
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.
Available Parameters
Querystring
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 |
known_uids | array | Array of Uid Objects. These ID5 IDs have been previously observed and shall now be unified into a single user | |
email_sha256 | string | x | Email hashed with SHA-256 associated with the array of known_uids |
emails_sha256 | array | x | Email hashed with SHA-256 associated with the array of known_uids Not yet implemented. Please use email_sha256 for now |
country_alpha2 | string | ISO 3166-1 alpha-2 country code associated to the user Defaults to “AA” (i.e. globally applicable) if not supplied | |
partner_user_id | string | This identifier will be returned as-is for this Request User Object |
Uid Object
Name | Type | Required | Description |
uid | string | ID5 Universal ID that was previously provided (via this API or another integration). The provided signals (from the Request User Object) will be associated to either this or a newly/previously generated ID5 ID. |
Example Request
POST:https://api.id5-sync.com/partners/v1/173/signals?token=AABBCC
{
"users": [
{
"email_sha256": "4592092e1061c7ea85af2aed194621cc17a2762bae33a79bf8ce33fd0168b802"
},
{
"country_alpha2": "NL",
"email_sha256": "a150e219c0f8f3ad73f21a78c9376b15cb9ae96e36959f5406ed836f517f746s"
},
{
"known_uids": [
{
"uid": "ID5-123"
}
],
"country_alpha2": "AA",
"email_sha256": "g150e219c0f8f3ad73f21a78c9376b15cb9ae96e36959f5406ed836f517f746s"
},
{
"known_uids": [
{
"uid": "ID5-ABC"
}
],
"country_alpha2": "AA",
"partner_user_id": "0x112233",
"email_sha256": "g150e219c0f8f3ad73f21a78c9376b15cb9ae96e36959f5406ed836f517f746s"
}
]
}
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 signals. |
email_sha256 | string | The same email hashed with SHA-256 that was provided on the request |
country_alpha2 | string | The same ISO 3166-1 alpha-2 country code associated to the user that was provided on the request; if it was not provided, if ID5 has a country associated to the user we will return it, otherwise we will default to “AA” |
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. |
country_alpha2_invalid | The length of the expected ISO 3166 alpha-2 string is not two 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 10,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. |
Examples
Success Response
{
"users": [
{
"uid": "ID5-234",
"country_alpha2": "AA",
"email_sha256": "4592092e1061c7ea85af2aed194621cc17a2762bae33a79bf8ce33fd0168b802"
},
{
"uid": "ID5-342",
"country_alpha2": "NL",
"email_sha256": "a150e219c0f8f3ad73f21a78c9376b15cb9ae96e36959f5406ed836f517f746s"
},
{
"uid": "ID5-178",
"country_alpha2": "AA",
"email_sha256": "g150e219c0f8f3ad73f21a78c9376b15cb9ae96e36959f5406ed836f517f746s"
},
{
"uid": "ID5-178",
"country_alpha2": "AA",
"partner_user_id": "0x112233",
"email_sha256": "g150e219c0f8f3ad73f21a78c9376b15cb9ae96e36959f5406ed836f517f746s"
}
]
}
Error Response
{
"users": [
{
"error": {
"code": "country_alpha2_invalid",
"message": "'A' does not conform to ISO 3166-1 alpha-2",
"type": "validation_error"
},
"email_sha256": "4592092e1061c7ea85af2aed194621cc17a2762bae33a79bf8ce33fd0168b802",
"country_alpha2": "A"
},
{
"error": {
"code": "sha256_length_invalid",
"message": "'150e219c0f8f3ad73f21a78c9376b15cb9ae96e36959f5406ed836f517f746s' does not conform to SHA-256",
"type": "validation_error"
},
"email_sha256": "150e219c0f8f3ad73f21a78c9376b15cb9ae96e36959f5406ed836f517f746s",
"country_alpha2": "NL"
}
],
"error": {
"code": "user_objects_invalid",
"message": "Rejected all user objects due to invalidation errors",
"type": "validation_error"
}
}