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

> Creates a new user

# Create

## Constraints

| Item                         | Constraint                                   | Notes                                                       |
| ---------------------------- | -------------------------------------------- | ----------------------------------------------------------- |
| UID character limit          | 100 characters                               | Alphanumeric with dashes only; spaces not allowed           |
| User name                    | 100 characters (UTF8mb4)                     | Supports all languages and emojis                           |
| Avatar URL                   | 3000 characters max                          | CometChat doesn't store the image; no resolution limit      |
| Profile URL                  | 3000 characters max                          | Same as avatar                                              |
| Metadata                     | 5 KB max (within 10 KB POST limit)           | Store custom key-value pairs                                |
| Tags                         | Up to 25 tags, 100 characters each (UTF8mb4) | Enable filtering and searching                              |
| Maximum groups per user      | 2000                                         | Must leave existing groups to join new ones beyond limit    |
| Maximum friends per user     | 1000                                         | Bidirectional relationships count toward both users' limits |
| Maximum auth tokens per user | 100 active (rolling retention)               | Oldest tokens are archived when limit is exceeded           |
| Maximum Bot users per app    | 25                                           | Special accounts for automated messaging                    |
| Maximum users per app        | No limit                                     | Pricing based on Monthly Active Users (MAU)                 |

For the complete error reference, see [Error Guide](/articles/error-guide).


## OpenAPI

````yaml post /users
openapi: 3.0.0
info:
  title: Chat APIs
  description: Manage messages, users, groups for a particular app using our Chat API.
  version: '3.0'
servers:
  - url: https://{appId}.api-{region}.cometchat.io/v3
    variables:
      appId:
        default: appId
        description: (Required) App ID
      region:
        enum:
          - us
          - eu
          - in
        default: us
        description: Select Region
security: []
tags:
  - name: API Keys
    description: The API keys are used to authorise the APIs
  - name: Roles
    description: The roles are used to give user access rights
  - name: Users
    description: The REST collection for users.
  - name: Auth Tokens
    description: The auth tokens are used to login end users using client SDKs.
  - name: Blocked Users
    description: The REST collections for blocked users.
  - name: Friends
    description: List,add and remove friends by passing UID in path variables
  - name: Groups
    description: The REST collections for groups.
  - name: Banned Users
    description: Ban and Unban user by passing other UID in path variables.
  - name: Group Members
    description: The REST collections for group members.
  - name: Messages
    description: The REST collections for messages.
  - name: Conversations
    description: The REST collections for conversations.
  - name: Restrict Features
    description: Allows Restricting Features
  - name: Metrics
    description: Allows accessing Data Metrics
  - name: Triggers
    description: Allows adding triggers to a webhook.
  - name: Webhooks
    description: Allows accessing Webhooks.
  - name: Notifications
    description: Allows configuring Notifications core.
paths:
  /users:
    post:
      tags:
        - Users
      summary: Create
      description: Creates a new user
      operationId: create-user
      requestBody:
        content:
          application/json:
            schema:
              required:
                - uid
                - name
              properties:
                uid:
                  description: >-
                    Unique identifier of the user. Please refer to
                    https://prodocs.cometchat.com/docs/concepts#uid
                  type: string
                name:
                  description: Display name of the user.
                  type: string
                avatar:
                  description: URL to profile picture of the user.
                  type: string
                link:
                  description: URL to profile page.
                  type: string
                role:
                  description: User role of the user for role based access control.
                  type: string
                statusMessage:
                  description: >-
                    A message providing context related to the user's current
                    status or mood.
                  type: string
                metadata:
                  description: >-
                    Additional information about the user as JSON. If you plan
                    to use [Email
                    Notification](doc:android-extensions-email-notification#section-configure-your-backend-to-store-emails)
                    or [SMS
                    Notification](doc:android-extensions-sms-notification#section-configure-your-backend-to-store-phone-number)
                    extensions, Please add the private metadata here.
                  properties:
                    '@private':
                      properties:
                        email:
                          type: string
                        contactNumber:
                          type: string
                      type: object
                  type: object
                  default:
                    '@private':
                      email: user@email.com
                      contactNumber: '0123456789'
                tags:
                  description: A list of tags to identify specific users.
                  type: array
                  items:
                    type: string
                  default: []
                withAuthToken:
                  description: Includes authToken of created user in response.
                  type: boolean
              type: object
      responses:
        '200':
          description: Create User
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: object
                type: object
              example:
                data:
                  uid: cometchat-uid-6
                  name: Barry Allen
                  link: https://cometchat.com
                  avatar: >-
                    https://assets.cometchat.io/sampleapp/v2/groups/cometchat-guid-1.webp
                  metadata:
                    rawMetadata: '{''gender'':''Male''}'
                  status: offline
                  role: manager
                  createdAt: 1638354015
                  tags:
                    - Engineer
                    - manager
                  authToken: cometchat-uid-6_16383540156641d37a023c75d26f4c22a21ff126
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      description: API Key with fullAccess scope(i.e. Rest API Key from the Dashboard).
      name: apikey
      in: header

````