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

# Add New User

> Add a new user to your account by sending an invitation. The user will receive an email invitation to join your account with the specified role.

## Overview

Adds a new user to your account by sending them an invitation email. The user will receive an email invitation to join your account with the specified role and permissions.

## Purpose

### **User Invitation**

* **Invite Team Members**: Add colleagues to your account
* **Role Assignment**: Assign appropriate access levels
* **Email Invitations**: Send automated invitation emails
* **Access Control**: Control what users can do

### **Account Management**

* **Team Collaboration**: Enable team access to QR codes
* **Permission Management**: Assign specific roles and permissions
* **User Onboarding**: Streamline user addition process
* **Access Auditing**: Track who has access to what

## Request Body (Form Data)

| Field          | Type   | Required | Description                                       | Example                |
| -------------- | ------ | -------- | ------------------------------------------------- | ---------------------- |
| `name`         | string | Yes      | Name of the shared user                           | `"Jon Doe"`            |
| `email`        | string | Yes      | Email address of the shared user                  | `"jon.doe@scanova.io"` |
| `access_level` | string | Yes      | Access level ID (Manager: 1, Admin: 2, Viewer: 3) | `"1"`                  |

## Access Level Options

### **Default Roles**

* **Manager (ID: 1)**: Can create, edit, and manage QR codes
* **Admin (ID: 2)**: Full access including user management
* **Viewer (ID: 3)**: Read-only access to QR codes and analytics

### **Custom Roles**

* **Custom IDs**: Use custom role IDs created in your account
* **Specific Permissions**: Custom roles with tailored permissions
* **Flexible Access**: Create roles for specific use cases

## Examples

### **Add User with Manager Role**

```bash theme={null}
curl -X POST "https://management.scanova.io/multi-users/" \
  -H "Authorization: YOUR_API_KEY" \
  -F "name=John Manager" \
  -F "email=john.manager@company.com" \
  -F "access_level=1"
```

### **Add User with Admin Role**

```bash theme={null}
curl -X POST "https://management.scanova.io/multi-users/" \
  -H "Authorization: YOUR_API_KEY" \
  -F "name=Jane Admin" \
  -F "email=jane.admin@company.com" \
  -F "access_level=2"
```

### **Add User with Viewer Role**

```bash theme={null}
curl -X POST "https://management.scanova.io/multi-users/" \
  -H "Authorization: YOUR_API_KEY" \
  -F "name=Bob Viewer" \
  -F "email=bob.viewer@company.com" \
  -F "access_level=3"
```

### **Add User with Custom Role**

```bash theme={null}
curl -X POST "https://management.scanova.io/multi-users/" \
  -H "Authorization: YOUR_API_KEY" \
  -F "name=Custom User" \
  -F "email=custom.user@company.com" \
  -F "access_level=135"
```

## Response

### **Success Response (201 Created)**

```json theme={null}
{
  "id": 479,
  "shared_user": {
    "id": 1452,
    "first_name": "Jon Doe",
    "last_name": "",
    "full_name": "Jon Doe",
    "email": "jon.doe@scanova.io",
    "is_shared": true,
    "date_joined": "2023-09-11T16:28:22.113793+05:30",
    "is_social_signup": false,
    "is_sso_login": false,
    "has_usable_password": true,
    "language": "en",
    "last_login": null,
    "first_login": false,
    "enforce_mfa": false,
    "mfa_enabled": false,
    "mfa_status": "Disabled"
  },
  "access_level": {
    "id": 1,
    "name": "Manager",
    "permissions": [
      {
        "id": 22,
        "code": "QR_CODE_CAN_ADD",
        "name": "Can Add QR Code",
        "description": "Can add QR Code",
        "is_boolean": true
      },
      {
        "id": 23,
        "code": "QR_CODE_CAN_VIEW",
        "name": "Can view QR Code",
        "description": "Can view QR Code",
        "is_boolean": true
      },
      {
        "id": 24,
        "code": "QR_CODE_CAN_EDIT",
        "name": "Can edit QR Code",
        "description": "Can edit QR Code",
        "is_boolean": true
      },
      {
        "id": 26,
        "code": "QR_CODE_CAN_DOWNLOAD",
        "name": "Can download QR code",
        "description": "Can download QR Code",
        "is_boolean": true
      },
      {
        "id": 1,
        "code": "ANALYTICS_CAN_VIEW",
        "name": "Analytics Can View",
        "description": "Can view analytics",
        "is_boolean": true
      }
    ],
    "is_custom": false
  },
  "invitation_sent_on": "2023-09-11T16:28:22.227002+05:30",
  "invitation_accepted_on": null,
  "is_invitation_sent": true,
  "is_invitation_accepted": false,
  "created": "2023-09-11T16:28:22.223671+05:30",
  "modified": "2023-09-11T16:28:22.227109+05:30",
  "tags": []
}
```

## Invitation Process

### **Email Invitation**

1. **Invitation Sent**: User receives email invitation
2. **Account Creation**: User creates account or logs in
3. **Invitation Acceptance**: User accepts invitation
4. **Access Granted**: User gains access to your account

### **Invitation Status**

* **`is_invitation_sent: true`**: Invitation email has been sent
* **`is_invitation_accepted: false`**: User hasn't accepted yet
* **`invitation_sent_on`**: Timestamp when invitation was sent
* **`invitation_accepted_on: null`**: Will be set when user accepts

## Integration Examples

### **JavaScript - Add User Form**

```javascript theme={null}
async function addUser(userData) {
  try {
    const formData = new FormData();
    formData.append('name', userData.name);
    formData.append('email', userData.email);
    formData.append('access_level', userData.accessLevel);
    
    const response = await fetch('https://management.scanova.io/multi-users/', {
      method: 'POST',
      headers: {
        'Authorization': 'YOUR_API_KEY'
      },
      body: formData
    });
    
    if (response.ok) {
      const newUser = await response.json();
      console.log('User added successfully:', newUser);
      
      // Show success message
      showMessage(`User ${newUser.shared_user.full_name} has been invited!`);
      
      // Refresh user list
      refreshUserList();
      
      return newUser;
    } else {
      const error = await response.json();
      throw new Error(error.detail || 'Failed to add user');
    }
  } catch (error) {
    console.error('Error adding user:', error);
    showMessage('Error adding user: ' + error.message, 'error');
    return null;
  }
}

// Usage
const userData = {
  name: 'John Manager',
  email: 'john.manager@company.com',
  accessLevel: '1'
};

addUser(userData);
```

### **Python - Bulk User Addition**

```python theme={null}
import requests

def add_user(name, email, access_level):
    url = "https://management.scanova.io/multi-users/"
    headers = {"Authorization": "YOUR_API_KEY"}
    
    data = {
        'name': name,
        'email': email,
        'access_level': str(access_level)
    }
    
    try:
        response = requests.post(url, headers=headers, data=data)
        response.raise_for_status()
        
        user = response.json()
        print(f"User {user['shared_user']['full_name']} added successfully!")
        print(f"Invitation sent to: {user['shared_user']['email']}")
        print(f"Role: {user['access_level']['name']}")
        
        return user
        
    except requests.exceptions.RequestException as e:
        print(f"Error adding user {name}: {e}")
        return None

def add_multiple_users(users):
    """Add multiple users from a list"""
    results = []
    
    for user in users:
        result = add_user(user['name'], user['email'], user['access_level'])
        results.append(result)
    
    return results

# Usage
users_to_add = [
    {'name': 'John Manager', 'email': 'john@company.com', 'access_level': 1},
    {'name': 'Jane Admin', 'email': 'jane@company.com', 'access_level': 2},
    {'name': 'Bob Viewer', 'email': 'bob@company.com', 'access_level': 3}
]

results = add_multiple_users(users_to_add)
```

### **PHP - User Invitation Form**

```php theme={null}
<?php
function addUser($name, $email, $accessLevel) {
    $url = "https://management.scanova.io/multi-users/";
    $headers = [
        "Authorization: YOUR_API_KEY"
    ];
    
    $data = [
        'name' => $name,
        'email' => $email,
        'access_level' => (string)$accessLevel
    ];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 201) {
        $user = json_decode($response, true);
        echo "User {$user['shared_user']['full_name']} added successfully!<br>";
        echo "Invitation sent to: {$user['shared_user']['email']}<br>";
        echo "Role: {$user['access_level']['name']}<br>";
        return $user;
    } else {
        echo "Error adding user: " . $response;
        return null;
    }
}

// Handle form submission
if ($_POST['submit']) {
    $name = $_POST['name'];
    $email = $_POST['email'];
    $accessLevel = $_POST['access_level'];
    
    $result = addUser($name, $email, $accessLevel);
}

// HTML Form
?>
<form method="POST">
    <label>Name: <input type="text" name="name" required></label><br>
    <label>Email: <input type="email" name="email" required></label><br>
    <label>Role: 
        <select name="access_level" required>
            <option value="1">Manager</option>
            <option value="2">Admin</option>
            <option value="3">Viewer</option>
        </select>
    </label><br>
    <input type="submit" name="submit" value="Add User">
</form>
```

## Error Handling

### **Common Errors**

#### **Invalid Email Format**

```json theme={null}
{
  "email": ["Enter a valid email address."]
}
```

#### **Missing Required Fields**

```json theme={null}
{
  "name": ["This field is required."],
  "email": ["This field is required."],
  "access_level": ["This field is required."]
}
```

#### **Invalid Access Level**

```json theme={null}
{
  "access_level": ["Invalid access level ID."]
}
```

#### **User Already Exists**

```json theme={null}
{
  "email": ["User with this email already exists."]
}
```

## Best Practices

### **User Management**

* **Validate Email**: Ensure email addresses are valid
* **Choose Appropriate Roles**: Assign roles based on user needs
* **Monitor Invitations**: Track invitation acceptance
* **Regular Audits**: Review user access regularly

### **Security**

* **Principle of Least Privilege**: Give users minimum required access
* **Regular Reviews**: Periodically review user permissions
* **Remove Inactive Users**: Remove users who no longer need access
* **Monitor Activity**: Track user activity and access patterns

### **Communication**

* **Clear Instructions**: Provide clear instructions to invited users
* **Follow Up**: Follow up on pending invitations
* **Documentation**: Document user roles and permissions
* **Training**: Provide training on account features

<Note>
  When you add a user, they will receive an email invitation to join your account. The user must accept the invitation before they can access your account.
</Note>

<Warning>
  Make sure to assign appropriate roles to users. Admin users have full access to your account including the ability to add and remove other users.
</Warning>

<Info>
  You can add users with custom roles by using the custom role ID instead of the default role IDs (1, 2, 3). Use the Get User Roles endpoint to see available custom roles.
</Info>


## OpenAPI

````yaml POST /multi-users/
openapi: 3.0.0
info:
  title: Scanova API - User Management
  description: >-
    User management endpoints for managing shared users, roles, and permissions
    in your Scanova account. These endpoints allow you to invite users, assign
    roles, and manage access levels.
  version: 1.0.0
servers:
  - url: https://management.scanova.io
    description: Scanova Management API Server
security:
  - apiKeyAuth: []
paths:
  /multi-users/:
    post:
      tags:
        - User Management
      summary: Add New User
      description: >-
        Add a new user to your account by sending an invitation. The user will
        receive an email invitation to join your account with the specified
        role.
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - name
                - email
                - access_level
              properties:
                name:
                  type: string
                  description: Name of the shared user
                  example: Jon Doe
                email:
                  type: string
                  format: email
                  description: Email address of the shared user
                  example: jon.doe@scanova.io
                access_level:
                  type: string
                  description: >-
                    Shared user access level id. Pre-defined access levels:
                    Manager (1), Admin (2), Viewer (3)
                  example: '1'
            examples:
              add_manager:
                summary: Add user with Manager role
                value:
                  name: John Manager
                  email: john.manager@company.com
                  access_level: '1'
              add_admin:
                summary: Add user with Admin role
                value:
                  name: Jane Admin
                  email: jane.admin@company.com
                  access_level: '2'
              add_viewer:
                summary: Add user with Viewer role
                value:
                  name: Bob Viewer
                  email: bob.viewer@company.com
                  access_level: '3'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SharedUser'
              examples:
                user_created:
                  summary: Successfully created user
                  value:
                    id: 479
                    shared_user:
                      id: 1452
                      first_name: Jon Doe
                      last_name: ''
                      full_name: Jon Doe
                      email: jon.doe@scanova.io
                      is_shared: true
                      date_joined: '2023-09-11T16:28:22.113793+05:30'
                      is_social_signup: false
                      is_sso_login: false
                      has_usable_password: true
                      language: en
                      last_login: null
                      first_login: false
                      enforce_mfa: false
                      mfa_enabled: false
                      mfa_status: Disabled
                    access_level:
                      id: 1
                      name: Manager
                      permissions:
                        - id: 22
                          code: QR_CODE_CAN_ADD
                          name: Can Add QR Code
                          description: Can add QR Code
                          is_boolean: true
                      is_custom: false
                    invitation_sent_on: '2023-09-11T16:28:22.227002+05:30'
                    invitation_accepted_on: null
                    is_invitation_sent: true
                    is_invitation_accepted: false
                    created: '2023-09-11T16:28:22.223671+05:30'
                    modified: '2023-09-11T16:28:22.227109+05:30'
                    tags: []
        '400':
          description: Bad request - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationErrorResponse'
      security:
        - apiKeyAuth: []
components:
  schemas:
    SharedUser:
      type: object
      properties:
        id:
          type: integer
          description: Shared user relationship ID
          example: 479
        shared_user:
          $ref: '#/components/schemas/User'
        access_level:
          $ref: '#/components/schemas/AccessLevel'
        invitation_sent_on:
          type: string
          format: date-time
          nullable: true
          description: When the invitation was sent
          example: '2023-09-11T16:28:22.227002+05:30'
        invitation_accepted_on:
          type: string
          format: date-time
          nullable: true
          description: When the invitation was accepted
          example: null
        is_invitation_sent:
          type: boolean
          description: Whether invitation has been sent
          example: true
        is_invitation_accepted:
          type: boolean
          description: Whether invitation has been accepted
          example: false
        created:
          type: string
          format: date-time
          description: When the user was added
          example: '2023-09-11T16:28:22.223671+05:30'
        modified:
          type: string
          format: date-time
          description: When the user was last modified
          example: '2023-09-11T16:28:22.227109+05:30'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/UserTag'
          description: Tags assigned to the user
    ValidationErrorResponse:
      type: object
      properties:
        field_name:
          type: array
          items:
            type: string
          example:
            - This field is required.
    AuthenticationErrorResponse:
      type: object
      properties:
        detail:
          type: string
          example: Authentication credentials were not provided.
    User:
      type: object
      properties:
        id:
          type: integer
          description: User ID
          example: 1452
        first_name:
          type: string
          description: User's first name
          example: Jon
        last_name:
          type: string
          description: User's last name
          example: Doe
        full_name:
          type: string
          description: User's full name
          example: Jon Doe
        email:
          type: string
          format: email
          description: User's email address
          example: jon.doe@scanova.io
        is_shared:
          type: boolean
          description: Whether this is a shared user
          example: true
        date_joined:
          type: string
          format: date-time
          description: When the user joined
          example: '2023-09-11T16:28:22.113793+05:30'
        is_social_signup:
          type: boolean
          description: Whether user signed up via social login
          example: false
        is_sso_login:
          type: boolean
          description: Whether user uses SSO login
          example: false
        has_usable_password:
          type: boolean
          description: Whether user has a usable password
          example: true
        language:
          type: string
          description: User's preferred language
          example: en
        last_login:
          type: string
          format: date-time
          nullable: true
          description: User's last login time
          example: null
        first_login:
          type: boolean
          description: Whether this is the user's first login
          example: false
        enforce_mfa:
          type: boolean
          description: Whether MFA is enforced for this user
          example: false
        mfa_enabled:
          type: boolean
          description: Whether MFA is enabled for this user
          example: false
        mfa_status:
          type: string
          description: MFA status
          example: Disabled
    AccessLevel:
      type: object
      properties:
        id:
          type: integer
          description: Access level ID
          example: 1
        name:
          type: string
          description: Access level name
          example: Manager
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
          description: List of permissions for this access level
        is_custom:
          type: boolean
          description: Whether this is a custom role or default role
          example: false
    UserTag:
      type: object
      properties:
        id:
          type: integer
          description: Tag ID
          example: 2950
        name:
          type: string
          description: Tag name
          example: SOCIAL ALL FIELDS
    Permission:
      type: object
      properties:
        id:
          type: integer
          description: Permission ID
          example: 22
        code:
          type: string
          description: Permission code
          example: QR_CODE_CAN_ADD
        name:
          type: string
          description: Permission name
          example: Can Add QR Code
        description:
          type: string
          description: Permission description
          example: Can add QR Code
        is_boolean:
          type: boolean
          description: Whether this is a boolean permission
          example: true
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key authentication. Enter your API key directly in the Authorization
        header.

````