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

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

TypeRequired

Description

users

array

x

Array of Request User Objects

Request User Object

Name

TypeRequired

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

TypeRequired

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

usersarrayArray of Response User Objects
errorobjectError 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.

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"
  }
}





  • No labels