> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seerstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Identify a user

> Associate traits and attributes with a user ID. Once identified, all future events with this user_id will be enriched with these attributes.



## OpenAPI

````yaml api-reference/openapi.json post /identify
openapi: 3.1.0
info:
  title: SeerStack API
  description: >-
    The SeerStack API allows you to send events, identify users, and track user
    behavior in your applications.
  version: 1.0.0
  contact:
    name: SeerStack Support
    url: https://seerstack.com
servers:
  - url: https://api.seerstack.com
    description: Production API
security:
  - bearerAuth: []
tags:
  - name: Events
    description: Track user actions and system events
  - name: Users
    description: Manage user identities and attributes
paths:
  /identify:
    post:
      tags:
        - Users
      summary: Identify a user
      description: >-
        Associate traits and attributes with a user ID. Once identified, all
        future events with this user_id will be enriched with these attributes.
      operationId: identifyUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentifyRequest'
            examples:
              basic:
                summary: Basic identification
                value:
                  user_id: user_123
                  email: user@example.com
              full:
                summary: Full identification with attributes
                value:
                  user_id: user_123
                  email: grace@hopper.com
                  name: Grace Hopper
                  attributes:
                    plan: enterprise
                    team_size: 15
                    is_admin: true
      responses:
        '200':
          description: User identified successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                success: true
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Missing or invalid API key
      x-codeSamples:
        - lang: typescript
          label: TypeScript SDK
          source: |-
            import Seerstack from 'seerstack';

            const client = new Seerstack({
              apiKey: process.env['SEERSTACK_API_KEY'],
            });

            const response = await client.users.identify({
              user_id: 'user_123',
              email: 'grace@hopper.com',
              name: 'Grace Hopper',
              attributes: {
                plan: 'enterprise',
                team_size: 15,
                is_admin: true
              }
            });

            console.log(response.success);
        - lang: ruby
          label: Ruby SDK
          source: |-
            require "seerstack"

            seerstack = Seerstack::Client.new(
              api_key: ENV["SEERSTACK_API_KEY"]
            )

            response = seerstack.users.identify(
              user_id: "user_123",
              email: "grace@hopper.com",
              name: "Grace Hopper",
              attributes: {
                plan: "enterprise",
                team_size: 15,
                is_admin: true
              }
            )

            puts(response.success)
        - lang: bash
          label: cURL
          source: |-
            curl -X POST https://api.seerstack.com/identify \
              -H "Authorization: Bearer $SEERSTACK_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "user_id": "user_123",
                "email": "grace@hopper.com",
                "name": "Grace Hopper",
                "attributes": {
                  "plan": "enterprise",
                  "team_size": 15,
                  "is_admin": true
                }
              }'
components:
  schemas:
    IdentifyRequest:
      type: object
      required:
        - user_id
      properties:
        user_id:
          type: string
          description: >-
            Your internal user ID. Use a stable identifier like a database
            primary key.
          example: user_123
        email:
          type: string
          format: email
          description: The user's email address.
          example: grace@hopper.com
        name:
          type: string
          description: The user's display name.
          example: Grace Hopper
        attributes:
          type: object
          additionalProperties: true
          description: >-
            Custom attributes to associate with the user. These can be used for
            filtering in the dashboard.
          example:
            plan: enterprise
            team_size: 15
            is_admin: true
    SuccessResponse:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
          description: Indicates whether the operation was successful.
          example: true
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: A human-readable error message.
          example: Missing or invalid API key
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Use your SeerStack API key as a Bearer token. You can find your API key
        in the SeerStack Dashboard under Settings > Developer.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.