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

# Create User

> Create a new user in your organization via API. Requires API key authentication.

## Create User

Create a new user in your organization via API.

### Headers

```
Authorization: Bearer <your-api-key>
Content-Type: application/json
```

### Request Body

```json theme={null}
{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "role": "TECHNICIAN",
  "phoneNumber": "+1234567890",
  "npiNumber": "1234567890",
  "shouldSendSMS": false,
  "recertificationDate": "2025-01-15T00:00:00Z",
  "providerPayors": ["abc123"]
}
```

### Field Descriptions

* `firstName` (required): User's first name
* `lastName` (required): User's last name
* `email` (optional): User's email address (must be unique)
* `role` (optional): Role to assign the new user. Defaults to `TECHNICIAN`.
  * Assignable roles: `ADMIN`, `BILLING_MANAGER`, `SCHEDULING_MANAGER`, `CLINICIAN`, `TECHNICIAN`, `PATIENT`, `CAREGIVER`, `CLINICAL_ADMIN`, `PAYROLL_ADMIN`
  * The roles you may assign are further limited by your own role. If you request a role you are not permitted to create, the request is rejected with a `403`.
* `phoneNumber` (optional): User's phone number
* `npiNumber` (optional): National Provider Identifier number
* `shouldSendSMS` (optional): Whether to send SMS notifications (defaults to `false`)
* `recertificationDate` (optional): Recertification date for the user (ISO 8601 format)
* `providerPayors` (optional): Assigns the provided payors to the User, if exists

### Success Response (200)

```json theme={null}
{
  "message": "User created successfully",
  "user": {
    "publicId": "usr_1234567890_abc123def",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "role": "TECHNICIAN",
    "phoneNumber": "+1234567890",
    "npiNumber": "1234567890",
    "shouldSendSMS": false,
    "createdAt": "2025-01-15T10:30:00Z",
    "organization": {
      "name": "Example Organization",
      "publicId": "org_abc123def456"
    }
  }
}
```

<Note>
  The user object returned by this endpoint differs from the one returned by the
  [Get All Users](/api-reference/endpoint/users/get) and
  [Get User By Id](/api-reference/endpoint/users/get-by-id) endpoints, which return
  demographic fields such as `sex`, `birthDate`, and address information.
</Note>

### Error Responses

#### 400 - Validation Error

```json theme={null}
{
  "error": "Validation error",
  "details": [
    {
      "code": "invalid_string",
      "message": "Valid email is required",
      "path": ["email"]
    }
  ]
}
```

#### 401 - Unauthorized

```json theme={null}
{
  "error": "API key required"
}
```

#### 401 - Invalid API Key

```json theme={null}
{
  "error": "Invalid API key"
}
```

#### 403 - Forbidden

Returned when your role does not permit creating a user with the requested role.

```json theme={null}
{
  "error": "Access denied"
}
```

## Examples

### cURL Example

```bash theme={null}
# Create a user
curl -X POST https://app.hipp.health/api/v1/users \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane.smith@example.com",
    "role": "CLINICIAN",
    "phoneNumber": "+1234567890"
  }'
```

### JavaScript Example

```javascript theme={null}
const createUser = async (userData) => {
  const response = await fetch("/api/v1/users", {
    method: "POST",
    headers: {
      Authorization: "Bearer your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(userData),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error);
  }

  return response.json();
};

// Usage
try {
  const result = await createUser({
    firstName: "Jane",
    lastName: "Smith",
    email: "jane.smith@example.com",
    role: "CLINICIAN",
  });
  console.log("User created:", result.user);
} catch (error) {
  console.error("Error creating user:", error.message);
}
```


## OpenAPI

````yaml POST /v1/users
openapi: 3.0.0
info:
  title: Hipp Health API
  version: 1.0.0
  description: API for managing users and resources within your Hipp Health organization
servers:
  - url: https://app.hipp.health/api
    description: Production Server
security: []
paths:
  /v1/users:
    post:
      tags:
        - users
      summary: Create a new user
      description: >-
        Create a new user in your organization via API. Requires API key
        authentication.
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            examples:
              basic:
                summary: Basic user creation
                value:
                  firstName: John
                  lastName: Doe
                  email: john.doe@example.com
                  role: TECHNICIAN
              complete:
                summary: Complete user creation
                value:
                  firstName: Jane
                  lastName: Smith
                  email: jane.smith@example.com
                  role: CLINICIAN
                  phoneNumber: '+1234567890'
                  npiNumber: '1234567890'
                  shouldSendSMS: false
                  providerPayors:
                    - abc123
      responses:
        '200':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUserResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      security:
        - BearerAuth: []
components:
  schemas:
    CreateUserRequest:
      type: object
      properties:
        firstName:
          type: string
          minLength: 1
          description: User's first name
        lastName:
          type: string
          minLength: 1
          description: User's last name
        email:
          type: string
          format: email
          description: User's email address (must be unique)
        role:
          type: string
          enum:
            - ADMIN
            - BILLING_MANAGER
            - SCHEDULING_MANAGER
            - CLINICIAN
            - TECHNICIAN
            - PATIENT
            - CAREGIVER
            - CLINICAL_ADMIN
            - PAYROLL_ADMIN
          default: TECHNICIAN
          description: >-
            Role to assign the new user (defaults to TECHNICIAN). The roles you
            may assign are further restricted by your own role; requesting a
            role you are not permitted to create returns 403.
        phoneNumber:
          type: string
          description: User's phone number
        npiNumber:
          type: string
          description: National Provider Identifier number
        shouldSendSMS:
          type: boolean
          default: false
          description: Whether to send SMS notifications
        recertificationDate:
          type: string
          format: date-time
          description: Recertification date for the user
        providerPayors:
          type: array
          items:
            type: string
          description: Assigns the provided payors to the User, if exists
      required:
        - firstName
        - lastName
    CreateUserResponse:
      type: object
      properties:
        message:
          type: string
          example: User created successfully
        user:
          $ref: '#/components/schemas/CreatedUser'
    CreatedUser:
      type: object
      description: >-
        The user returned immediately after creation. This shape differs from
        the User object returned by the list and get-by-id endpoints.
      properties:
        publicId:
          type: string
          description: User public identifier
        firstName:
          type: string
          nullable: true
          description: User's first name
        lastName:
          type: string
          nullable: true
          description: User's last name
        email:
          type: string
          nullable: true
          description: User's email address
        role:
          $ref: '#/components/schemas/UserRole'
        phoneNumber:
          type: string
          nullable: true
          description: User's phone number
        npiNumber:
          type: string
          nullable: true
          description: National Provider Identifier number
        shouldSendSMS:
          type: boolean
          description: Whether SMS notifications are enabled for the user
        createdAt:
          type: string
          format: date-time
          description: Timestamp the user was created
        organization:
          type: object
          description: Organization the user was created in
          properties:
            name:
              type: string
            publicId:
              type: string
          required:
            - name
            - publicId
      required:
        - publicId
        - role
    ValidationError:
      type: object
      properties:
        error:
          type: string
          example: Validation error
        details:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: invalid_string
              message:
                type: string
                example: Valid email is required
              path:
                type: array
                items:
                  type: string
                example:
                  - email
    UserRole:
      type: string
      enum:
        - ADMIN
        - BILLING_MANAGER
        - SCHEDULING_MANAGER
        - CLINICIAN
        - TECHNICIAN
        - PATIENT
        - CAREGIVER
        - HIPP_ADMIN
        - HIPP_BILLING_MANAGER
        - CLINICAL_ADMIN
        - PAYROLL_ADMIN
        - CLINICAL_SUPERADMIN
      description: >-
        User role. All values may be returned by the API; a smaller subset may
        be assigned when creating a user (see the create user endpoint). Note
        that HIPP_ADMIN users are never returned by the list users endpoint.
  responses:
    '400':
      description: Bad Request - Validation Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: API key required
    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Access denied
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: An unexpected error occurred
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        API key authentication. Include your API key in the Authorization header
        as 'Bearer <your-api-key>'

````