Skip to main content

​
Overview

The /identify endpoint is one of the methods for adding identities to your Identity Graph. It accepts a Permutive user ID (or generates a new one) and a prioritized list of identities, then links all provided identities to the resolved Permutive ID through identity resolution.
Prerequisites:
  • Permutive SDK installed and configured for your platform
  • Identifiers configured in Identity > Identifiers dashboard
  • User has authenticated or identifier is available

​
Steps

1

Configure identifiers in dashboard

Before sending identities, ensure the identifier types are configured in Identity > Identifiers. Identities with unconfigured identity types will not be added to the graph.
2

Prepare identity data

Collect the identity values you want to send. Each identity consists of:
  • Type: The identifier type (e.g., email_sha256, appnexus, user_id)
  • Value: The actual identifier string
  • Priority: Integer where 0 = highest priority (optional, defaults to order in array)
3

Call identify endpoint

Implement the identify call with your platform’s SDK or API. The system checks identities in priority order until it finds a match, then links all provided identities to that Permutive ID.
4

Set identity priority

Order identities by priority, placing the most stable and persistent identifiers first (priority 0). This improves identity resolution rates by checking the most reliable identifiers first.
5

Handle response

The identify endpoint returns the resolved Permutive ID. Store this ID for future identify calls to maintain consistency across sessions.

​
Platform-Specific Implementation

​
Web SDK

permutive.identify([
  {
    id: "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae", // SHA-256 hash of email
    tag: "email_sha256",
    priority: 0
  },
  {
    id: "abc123",
    tag: "appnexus",
    priority: 1
  }
]);

​
iOS SDK

let identities = [
    // Use the SHA-256 hash of the email, not the plaintext email
    Identity(id: "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae", tag: "email_sha256", priority: 0),
    Identity(id: "abc123", tag: "appnexus", priority: 1)
]
Permutive.shared.identify(identities: identities)

​
Android SDK

val identities = listOf(
    // Use the SHA-256 hash of the email, not the plaintext email
    Identity(id = "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae", tag = "email_sha256", priority = 0),
    Identity(id = "abc123", tag = "appnexus", priority = 1)
)
Permutive.identify(identities)

​
API Direct

curl -X POST https://api.permutive.com/v2.0/identify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "user_id": "permutive-user-id-or-new",
    "identities": [
      {"id": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae", "tag": "email_sha256", "priority": 0},
      {"id": "abc123", "tag": "appnexus", "priority": 1}
    ]
  }'
Tips for identity resolution:
  • Place the most stable, persistent identifiers first (priority 0) - typically hashed emails or authenticated user IDs
  • Call identify whenever a user authenticates or a new identifier becomes available
  • Ensure consistent identifier formats (e.g., always hash emails the same way)
  • Use the same Permutive ID across sessions when available to maintain user continuity
  • Call identify on every page load or app launch to maintain identity resolution
Important:
  • Identities with identifier types not configured in the dashboard will be ignored
  • A user cannot have multiple identities of the same identifier type
  • Identity resolution happens in real-time; allow time for propagation across systems
  • Priority order matters - identities are checked sequentially until a match is found

​
Next Steps

Configuring Identifiers

Set up identifier types before sending identities

Identity Insights

Analyze identity overlap and resolution effectiveness

Back to Identity Graph

Return to Identity Graph overview