Skip to main content
POST
/
identify
Identify a user
curl --request POST \
  --url https://api.permutive.app/v2.0/identify \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "user_id": "2008c38f-dece-4570-976d-87593ed001c3",
  "aliases": [
    {
      "priority": 0,
      "tag": "email_sha256",
      "id": "user@example.com"
    },
    {
      "priority": 1,
      "tag": "some-third-party-id-provider",
      "id": "1234567890"
    }
  ]
}
'
{
  "user_id": "2008c38f-dece-4570-976d-87593ed001c3"
}

Documentation Index

Fetch the complete documentation index at: https://docs.permutive.com/llms.txt

Use this file to discover all available pages before exploring further.

There are a couple of scenarios for this endpoint, depending on whether the user has been identified before:
  1. None of the provided identities have been seen before: The API will create new identities for those provided and associate them with the Permutive user ID. This means in the future all the provided identities will map to the same Permutive user ID.
  2. Some or all of the provided identities have been seen before: There are two sub-scenarios:
    • Case A: When all of the provided identities are associated with the same Permutive user ID, this user is returned and no further action is taken.
    • Case B: When the provided identities are associated with different Permutive user IDs, the identity with the highest priority (lowest number) takes precedence, and all other identities will then be synchronized to map to this user ID.

​
Identity tags

The identity tag(s) passed in the request body of the request (e.g. email_sha256, appnexus) must be from the identity tag allow-list configured in the Settings section of the Permutive dashboard. If an identity tag included in the identify call is not in the allow-list, it will be ignored and not associated with the Permutive user ID.

​
Identity priorities

Prioritized aliases allow customers to express which identifiers they consider most reliable or authoritative for resolving user identities. When multiple aliases are provided, priorities are used to determine the order in which aliases are attempted for future resolution to a Permutive user ID, where priority 0 has the highest priority.

Authorizations

​
X-API-Key
string
header
required

Body

application/json
​
user_id
string<uuid>
required

The Permutive user ID currently assigned to the user.

​
aliases
PrioritizedAlias · object[]
required

A list of prioritized aliases that the user is associated with. If no aliases are provided, the user ID will be returned.

Response

Resolved identity

​
user_id
string<uuid>

The resolved user ID.