# Invite user

URL: /en/docs/api/v1/users/post
Last Updated: 2026-07-30T21:15:44.974Z

## Description
No description available.

## Available Actions
- Execute POST request
- View request parameters
- View response schema
- Get code examples
- Navigate to related topics
- View step-by-step instructions
- Get best practices

## Content
### POST /api/v1/users

**Invite user**

Create a new user invitation with specified role and permissions. User will receive an invitation email to set up their account.

**Authentication:** Bearer token (`Authorization: Bearer <token>`)

**Request body** (`application/json`) - required:

- `first_name` (string, required): User's first name
- `last_name` (string, required): User's last name
- `email` (string (email), required): User's email address
- `role` (enum: admin | account_manager | content_manager | viewer, required): User's role in the system

Example (Invite administrator):

```json
{
  "email": "admin@example.com",
  "first_name": "John",
  "last_name": "Admin",
  "role": "admin"
}
```

Example (Invite account manager):

```json
{
  "email": "manager@example.com",
  "first_name": "Jane",
  "last_name": "Manager",
  "role": "account_manager"
}
```

Example (Invite viewer):

```json
{
  "email": "viewer@example.com",
  "first_name": "Bob",
  "last_name": "Viewer",
  "role": "viewer"
}
```

**Responses:**

- `201` - User invitation created successfully
  - `success` (boolean)
  - `data` (object)
    - `user` (User (object))
      - `id` (string (uuid)): Unique user identifier
      - `first_name` (string): User's first name
      - `last_name` (string): User's last name
      - `email` (string (email)): User's email address
      - `role` (object): User's role information
        - `name` (string): Display name of the user's role
      - `status` (enum: active | invited | suspended | archived): User account status
      - `title` (string): User's job title
      - `theme` (enum: light | dark | system): User's UI theme preference
      - `language` (string): User's language preference
    - `createdUserId` (string): ID of the created user
- `400` - Bad Request - validation failed
  - `error` (string): Validation error message

  Example (Validation Error):
  
  ```json
  {
  "error": "Invalid input: email: Invalid email address"
}
  ```

  Example (Invalid Role):
  
  ```json
  {
  "error": "Invalid role specified."
}
  ```
- `401` - Unauthorized
- `403` - Forbidden - Admin role required
- `409` - Conflict - user with this email already exists
- `500` - Internal server error

**Code samples:**

cURL:

```bash
curl -X POST "https://app.orbiqhq.com/api/v1/users" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "role": "viewer"
}'
```