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

# Identify User

> Create or update a user profile with properties like name, email, and custom attributes via HTTP POST request.



## OpenAPI

````yaml POST /v1/identify
openapi: 3.0.0
info:
  title: Userpilot API
  version: 1.0.0
  termsOfService: https://userpilot.io/terms-of-service/
  description: >-
    Userpilot's API suite for user identification, event tracking, data
    import/export, and user/company management.


    Contact Support:
     Email: support@userpilot.com
  contact:
    name: Userpilot
    url: https://userpilot.io
    email: support@userpilot.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://{environment}.userpilot.io
    description: >-
      Analytical data endpoint for Userpilot API. Choose the appropriate
      environment based on your data residency requirements and account type.
    variables:
      environment:
        description: >-
          The Userpilot environment endpoint for your account. Most customers
          use the default US region (analytex), while EU customers with data
          residency requirements use the EU region (analytex-eu). You can find
          your specific endpoint URL in your Userpilot dashboard under
          [Environment Settings](https://run.userpilot.io/environment).
        enum:
          - analytex
          - analytex-eu
        default: analytex
security: []
paths:
  /v1/identify:
    parameters: []
    post:
      tags:
        - Real-time
      summary: Identify
      parameters:
        - name: Content-Type
          in: header
          required: false
          example: application/json
          schema:
            type: string
            default: application/json
        - name: Accept
          in: header
          required: false
          example: application/json
          schema:
            type: string
            default: application/json
        - $ref: '#/components/parameters/AuthorizationHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - user_id
              example:
                user_id: user_789456
                metadata:
                  name: Sarah Johnson
                  email: sarah.johnson@techstartup.com
                  job_title: Product Manager
                  department: Product
                  location: New York, NY
                  hire_date: '2022-03-15'
                  years_experience: 8
                  skills: Product Strategy, User Research, Agile
                  subscription_plan: Pro
                  last_login: '2024-01-15T10:30:00Z'
                  preferences_language: en
                  preferences_timezone: America/New_York
                  preferences_notifications: email
                company:
                  company_id: comp_techstartup_2024
                  name: TechStartup Inc.
                  industry: SaaS
                  size: 50-100
                  location: New York, NY
                  website: https://techstartup.com
                  subscription_tier: Enterprise
                  annual_revenue: $5M-$10M
                  founded_year: '2020'
                  primary_product: Project Management Platform
                  customer_count: 2500
                  team_engineering: 25
                  team_sales: 15
                  team_marketing: 8
                  team_support: 12
              properties:
                user_id:
                  type: string
                  description: >-
                    The unique identifier for the user. This is the ID that
                    Userpilot uses to identify the user.
                  example: '123987'
                metadata:
                  type: object
                  description: >-
                    Optional user metadata. You can add, remove, or modify any
                    properties as needed for your use case. Note: Only string
                    values are supported (numbers and dates should be sent as
                    strings).
                  additionalProperties: true
                  properties:
                    custom_user_property:
                      type: string
                      description: 'example: Name, Job title, etc.'
                company:
                  type: object
                  description: >-
                    Company information. If provided, `company_id` is required.
                    Additional company properties are optional metadata.
                  required:
                    - company_id
                  properties:
                    company_id:
                      type: string
                      description: >-
                        The unique identifier for the company. This is the ID
                        that Userpilot uses to identify the company.
                      example: company_123
                    custom_company_property:
                      type: string
                      description: 'example: Company name, Industry, etc.'
                  additionalProperties: true
      responses:
        '401':
          headers:
            Content-Type:
              schema:
                type: string
                default: application/json
              example: application/json
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        details:
                          type: string
                        error:
                          type: string
                        error_code:
                          type: string
                          format: color
                        message:
                          type: string
components:
  parameters:
    AuthorizationHeader:
      name: Authorization
      in: header
      required: true
      description: >-
        API authentication token in the format: `Token {{API_KEY}}`

        Obtain your API key from the [Userpilot Environment
        Settings](https://run.userpilot.io/environment).
      schema:
        type: string
        default: Token ABC_1234_EFGH_5678
      example: Token ABC_1234_EFGH_5678

````