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

# Identify a user

> Associate one or more identities with a Permutive user, allowing you to identify users in multiple ways.

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](https://dash.permutive.com/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.


## OpenAPI

````yaml POST /identify
openapi: 3.1.0
info:
  title: Identity API
  version: v2
servers:
  - url: https://api.permutive.app/v2.0
security: []
paths:
  /identify:
    post:
      tags:
        - v2.0
      summary: Identify a user
      description: >-
        Associate one or more identities with a Permutive user, allowing you to
        identify users in multiple ways.
      operationId: identifyUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentifyUser'
            example:
              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'
      responses:
        '200':
          description: Resolved identity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolvedIdentity'
              example:
                user_id: 2008c38f-dece-4570-976d-87593ed001c3
        '401':
          description: 'Unauthorized request: invalid or missing API key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              examples:
                Invalid API key:
                  summary: Invalid API key
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    error:
                      status: Unauthorized
                      code: 2000
                      message: The API key provided is invalid.
                      docs: https://docs.permutive.com/api/errors
                Missing authentication:
                  summary: Missing authentication
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    error:
                      status: Unauthorized
                      code: 2004
                      message: >-
                        The resource requires authentication, which was not
                        supplied with the request.
                      docs: https://docs.permutive.com/api/errors
        '500':
          description: 'Internal server error: unexpected error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
              example:
                request_id: 550e8400-e29b-41d4-a716-446655440000
                error:
                  status: InternalServerError
                  code: 5000
                  message: >-
                    An error of unspecified nature was encountered while
                    processing your request. Feel free to get in touch with us
                    at support@permutive.com referencing the Request ID.
                  docs: https://docs.permutive.com/api/errors
      security:
        - Header: []
        - Parameter: []
components:
  schemas:
    IdentifyUser:
      title: Identify response
      type: object
      required:
        - user_id
        - aliases
      properties:
        user_id:
          type: string
          format: uuid
          description: The Permutive user ID currently assigned to the user.
        aliases:
          type: array
          items:
            $ref: '#/components/schemas/PrioritizedAlias'
          description: >-
            A list of prioritized aliases that the user is associated with. If
            no aliases are provided, the user ID will be returned.
    ResolvedIdentity:
      title: Resolved identity
      type: object
      properties:
        user_id:
          type: string
          format: uuid
          description: The resolved user ID.
    HttpErrorResponse:
      title: HttpErrorResponse
      type: object
      required:
        - request_id
        - error
      properties:
        request_id:
          $ref: '#/components/schemas/RequestId'
        error:
          type: object
          description: Details of the error that occurred.
          required:
            - status
            - code
            - message
            - docs
          properties:
            status:
              type: string
              enum:
                - BadRequest
                - Unauthorized
                - NotFound
                - Conflict
                - Gone
                - InternalServerError
                - Forbidden
              description: The type of error that occurred.
            code:
              type: integer
              format: int32
              description: A numeric code that identifies the error.
            message:
              type: string
              description: A human-readable message describing the error.
            docs:
              type: string
              format: uri
              description: A URL to the documentation for the error.
            cause:
              type: string
              description: >-
                A human-readable message describing additional details of the
                error.
    PrioritizedAlias:
      title: PrioritizedAlias
      type: object
      required:
        - priority
        - tag
        - id
      properties:
        priority:
          type: integer
          format: int32
          description: The priority of the alias, where `0` is the highest priority.
        tag:
          type: string
          description: >-
            The tag is a string used to identify the type of alias, e.g.
            `email_sha256` or `myInternalID`.
        id:
          type: string
          description: >-
            The identifier for the alias, e.g. `user@example.com` or
            `1234567890`.
    RequestId:
      title: RequestId
      type: string
      format: uuid
      description: A unique identifier for the request that caused the error.
  securitySchemes:
    Header:
      type: apiKey
      name: X-API-Key
      in: header
    Parameter:
      type: apiKey
      name: k
      in: query

````