---
title: Add a User
slug: add-a-user
createdAt: 2024-10-09T15:32:02.370Z
---

### API Endpoint Documentation: `/api/users/add`

### Description:

This endpoint allows you to add one or more users to the system by sending a POST request. The request body contains user details such as name, email, password, and associated groups.

### Endpoint:

```text
POST https://admin.<your-site>.com/api/users/add
```

### Headers:

- **accept**: `application/json`
  Specifies that the request expects a JSON response.
- **authorization**: `Bearer <JWT Token>`
  A JSON Web Token (JWT) that authenticates the request. Replace `<JWT Token>` with a valid token.
- **content-type**: `application/json`
  Specifies that the request body is in JSON format.

### Request Body:

The request body should be in JSON format, containing an array of user objects to be added. Each user object contains the following fields:

- **name**: `string`
  The name of the user.
- **email**: `string`
  The email address of the user.
- **password**: `string`
  (Optional) The password for the user.
- **confirm\_password**: `string`
  (Optional) The password confirmation for the user.
- **image**: `string`
  (Optional) The URL of the user's profile image.
- **type**: `string`
  The role or type of the user (e.g., `user`, `admin`).
- **notifications**: `boolean`
  Specifies whether the user will receive notifications.
- **update**: `boolean`
  Indicates if the user's information should be updated.
- **groups**: `array`
  An array of group objects associated with the user. Each group contains:
  - **\_id**: `string`
    The group ID.
  - **workspace\_id**: `object`
    The workspace object associated with the group.
    - **\_id**: `string`
      The workspace ID.
    - **name**: `string`
      The workspace name.
  - **name**: `string`
    The group name.
  - **permissions**: `array`
    An array of permission objects associated with the group.
- **token**: `string`
  A valid authentication token (JWT) for adding users.

### Example Request Body:

```json
{
  "users": [
    {
      "name": "Matthew Kastner",
      "email": "matthew@clearsquare.co",
      "password": "",
      "confirm_password": "",
      "image": "",
      "type": "user",
      "notifications": false,
      "update": true,
      "groups": [
        {
          "_id": "756676a679549784d96514a2",
          "workspace_id": {
            "_id": "6567745179549784d96513ae",
            "name": "Internal Employees"
          },
          "name": "Basic Users",
          "permissions": [
            {
              "_id": "656faf7879549784d967e2bv",
              "page_id": "656faa7c79549784d967dfab",
              "filters": []
            }
          ]
        }
      ]
    }
  ],
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### Method:

- **POST**: Sends a request to add the specified user(s) to the system.

### Example Request (Node.js):

```javascript
const fetch = require('node-fetch');

const url = 'https://admin.<your-site>.com/api/users/add';
const options = {
  method: 'POST',
  headers: {
    'accept': 'application/json',
    'accept-language': 'en-US,en;q=0.9',
    'authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
    'content-type': 'application/json'
  },
  body: JSON.stringify({
    users: [
      {
        name: "Matthew Kastner",
        email: "Matthewkastner@gmail.com",
        password: "",
        confirm_password: "",
        image: "",
        type: "user", // Options: ["user", "editor"", "admin"]
        notifications: false,
        update: true,
        groups: [ // Assign the user to a group within a workspace.
          {
            _id: "756676a679549784d96514a2", // Group _id
            workspace_id: {
              _id: "6567745179549784d96513ae",
              name: "Internal Employees"
            },
            name: "Basic Users", // Group name
            permissions: [
              {
                _id: "656faf7879549784d967e2bv",
                page_id: "656faa7c79549784d967dfab",
                filters: []
              }
            ]
          }
        ]
      }
    ],
    token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  })
};

fetch(url, options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));
```

### Response:

The API will return a JSON response indicating the success or failure of the operation.

### Success Response (200):

```json
{
  "message": "User(s) added successfully",
  "status": "success"
}
```

### Error Response (400/401):

```json
{
  "message": "Invalid token or request body",
  "status": "error"
}
```

### Authentication:

This API requires a valid JWT token for authentication. Ensure that the token is included in the `authorization` header as `Bearer <JWT Token>`.

### Usage Notes:

- The `users` array can contain multiple users to be added in one request.
- Ensure that each user has a unique email address in the system.
- A valid JWT token must be included in the `authorization` header, otherwise the request will fail.