> ## 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.

# Adding Identities via Identify Endpoint

> How to implement the /identify endpoint across Web, iOS, Android, and API platforms, including priority configuration

## 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.

<Info>
  **Prerequisites:**

  * Permutive SDK installed and configured for your platform
  * Identifiers configured in Identity > Identifiers dashboard
  * User has authenticated or identifier is available
</Info>

## Steps

<Steps>
  <Step title="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.
  </Step>

  <Step title="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)
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Handle response">
    The identify endpoint returns the resolved Permutive ID. Store this ID for future identify calls to maintain consistency across sessions.
  </Step>
</Steps>

### Platform-Specific Implementation

#### Web SDK

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

#### iOS SDK

```swift theme={"dark"}
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

```kotlin theme={"dark"}
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

```bash theme={"dark"}
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}
    ]
  }'
```

<Tip>
  **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
</Tip>

<Warning>
  **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
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuring Identifiers" icon="sliders" href="/guides/signals/identity/configuring-identifiers">
    Set up identifier types before sending identities
  </Card>

  <Card title="Identity Insights" icon="chart-line" href="/products/signals/identity/identity-insights">
    Analyze identity overlap and resolution effectiveness
  </Card>

  <Card title="Back to Identity Graph" icon="arrow-left" href="/products/signals/identity/identity-graph">
    Return to Identity Graph overview
  </Card>
</CardGroup>