> ## 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.

# Get User List

> Get a list of all users in your account including shared users, their roles, and invitation status.

## Overview

Retrieves a paginated list of all users in your account, including the account owner and all shared users. This endpoint provides comprehensive information about each user's role, invitation status, and activity.

## Purpose

### **User Management**

* **View All Users**: See everyone who has access to your account
* **Monitor Invitations**: Track invitation status and acceptance
* **Role Overview**: See what roles users have been assigned
* **Activity Tracking**: Monitor user login activity and engagement

### **Account Administration**

* **User Audit**: Review all users and their access levels
* **Invitation Management**: Track pending and accepted invitations
* **Access Control**: Understand who has access to what
* **User Activity**: Monitor user engagement and activity

## Query Parameters

| Parameter | Type    | Required | Description                                | Example |
| --------- | ------- | -------- | ------------------------------------------ | ------- |
| `page`    | integer | No       | Page number for pagination (starts from 1) | `1`     |

## Response Structure

The response includes pagination information and an array of user objects:

| Field      | Type         | Description                               |
| ---------- | ------------ | ----------------------------------------- |
| `count`    | integer      | Total number of users in the account      |
| `next`     | integer/null | Next page number (null if no more pages)  |
| `previous` | integer/null | Previous page number (null if first page) |
| `results`  | array        | Array of user objects                     |

### **User Object Structure**

Each user in the `results` array contains:

| Field                    | Type        | Description                          |
| ------------------------ | ----------- | ------------------------------------ |
| `id`                     | integer     | Shared user relationship ID          |
| `shared_user`            | object      | User details (name, email, etc.)     |
| `access_level`           | object      | User's role and permissions          |
| `invitation_sent_on`     | string/null | When invitation was sent             |
| `invitation_accepted_on` | string/null | When invitation was accepted         |
| `is_invitation_sent`     | boolean     | Whether invitation has been sent     |
| `is_invitation_accepted` | boolean     | Whether invitation has been accepted |
| `created`                | string      | When user was added to account       |
| `modified`               | string      | When user was last modified          |
| `tags`                   | array       | Tags assigned to the user            |

## Examples

### **Get All Users**

```bash theme={null}
curl -X GET "https://management.scanova.io/multi-users/" \
  -H "Authorization: YOUR_API_KEY"
```

### **Get Specific Page**

```bash theme={null}
curl -X GET "https://management.scanova.io/multi-users/?page=2" \
  -H "Authorization: YOUR_API_KEY"
```

### **Response Example**

```json theme={null}
{
  "count": 22,
  "next": 2,
  "previous": null,
  "results": [
    {
      "id": 0,
      "shared_user": {
        "id": 560,
        "first_name": "Akshay",
        "last_name": "",
        "full_name": "Akshay",
        "email": "akshay.sharma@scanova.io",
        "is_shared": false,
        "date_joined": "2022-07-15T15:36:23.251791+05:30",
        "is_social_signup": false,
        "is_sso_login": false,
        "has_usable_password": true,
        "language": "en",
        "last_login": "2023-09-12T15:32:09.549594+05:30",
        "first_login": false,
        "enforce_mfa": false,
        "mfa_enabled": false,
        "mfa_status": "Disabled"
      },
      "access_level": {
        "id": 0,
        "name": "OWNER"
      },
      "invitation_sent_on": null,
      "invitation_accepted_on": null,
      "is_invitation_sent": false,
      "is_invitation_accepted": false,
      "created": "2022-07-15T15:36:23.251791+05:30",
      "modified": "2022-07-15T15:36:23.251791+05:30",
      "tags": []
    },
    {
      "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": []
    }
  ]
}
```

## User Status Indicators

### **Account Owner**

* **`is_shared: false`**: Indicates the account owner
* **`access_level.name: "OWNER"`**: Has full account access
* **No invitation fields**: Owner doesn't need invitations

### **Shared Users**

* **`is_shared: true`**: Indicates invited users
* **Invitation Status**: Track invitation lifecycle
* **Role-based Access**: Limited by assigned role

### **Invitation Status**

* **Pending**: `is_invitation_sent: true`, `is_invitation_accepted: false`
* **Accepted**: `is_invitation_sent: true`, `is_invitation_accepted: true`
* **Never Sent**: `is_invitation_sent: false` (shouldn't happen)

## Integration Examples

### **JavaScript - Display User List**

```javascript theme={null}
async function getUserList(page = 1) {
  try {
    const response = await fetch(`https://management.scanova.io/multi-users/?page=${page}`, {
      method: 'GET',
      headers: {
        'Authorization': 'YOUR_API_KEY'
      }
    });
    
    if (response.ok) {
      const data = await response.json();
      
      // Display users in a table
      const userTable = document.getElementById('userTable');
      data.results.forEach(user => {
        const row = document.createElement('tr');
        row.innerHTML = `
          <td>${user.shared_user.full_name}</td>
          <td>${user.shared_user.email}</td>
          <td>${user.access_level.name}</td>
          <td>${user.is_invitation_accepted ? 'Active' : 'Pending'}</td>
          <td>${user.shared_user.last_login ? new Date(user.shared_user.last_login).toLocaleDateString() : 'Never'}</td>
        `;
        userTable.appendChild(row);
      });
      
      // Handle pagination
      if (data.next) {
        document.getElementById('nextPage').style.display = 'block';
        document.getElementById('nextPage').onclick = () => getUserList(data.next);
      }
      
      return data;
    } else {
      throw new Error('Failed to fetch users');
    }
  } catch (error) {
    console.error('Error fetching users:', error);
    return null;
  }
}

// Usage
getUserList();
```

### **Python - User Management Dashboard**

```python theme={null}
import requests
from datetime import datetime

def get_user_list(page=1):
    url = "https://management.scanova.io/multi-users/"
    headers = {"Authorization": "YOUR_API_KEY"}
    params = {"page": page}
    
    try:
        response = requests.get(url, headers=headers, params=params)
        response.raise_for_status()
        
        data = response.json()
        
        print(f"Total Users: {data['count']}")
        print(f"Page {page} of {(data['count'] // 20) + 1}")
        print("-" * 80)
        
        for user in data['results']:
            user_info = user['shared_user']
            access_level = user['access_level']
            
            print(f"Name: {user_info['full_name']}")
            print(f"Email: {user_info['email']}")
            print(f"Role: {access_level['name']}")
            print(f"Status: {'Active' if user['is_invitation_accepted'] else 'Pending'}")
            print(f"Last Login: {user_info['last_login'] or 'Never'}")
            print("-" * 40)
        
        return data
        
    except requests.exceptions.RequestException as e:
        print(f"Error fetching users: {e}")
        return None

# Usage
user_data = get_user_list()
```

### **PHP - User List with Pagination**

```php theme={null}
<?php
function getUserList($page = 1) {
    $url = "https://management.scanova.io/multi-users/";
    $headers = [
        "Authorization: YOUR_API_KEY"
    ];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url . "?page=" . $page);
    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 === 200) {
        $data = json_decode($response, true);
        
        echo "<h3>Users (Page $page of " . ceil($data['count'] / 20) . ")</h3>";
        echo "<table border='1'>";
        echo "<tr><th>Name</th><th>Email</th><th>Role</th><th>Status</th><th>Last Login</th></tr>";
        
        foreach ($data['results'] as $user) {
            $userInfo = $user['shared_user'];
            $accessLevel = $user['access_level'];
            $status = $user['is_invitation_accepted'] ? 'Active' : 'Pending';
            $lastLogin = $userInfo['last_login'] ? date('Y-m-d', strtotime($userInfo['last_login'])) : 'Never';
            
            echo "<tr>";
            echo "<td>{$userInfo['full_name']}</td>";
            echo "<td>{$userInfo['email']}</td>";
            echo "<td>{$accessLevel['name']}</td>";
            echo "<td>$status</td>";
            echo "<td>$lastLogin</td>";
            echo "</tr>";
        }
        
        echo "</table>";
        
        // Pagination
        if ($data['next']) {
            echo "<a href='?page={$data['next']}'>Next Page</a>";
        }
        if ($data['previous']) {
            echo "<a href='?page={$data['previous']}'>Previous Page</a>";
        }
        
        return $data;
    } else {
        echo "Error fetching users";
        return null;
    }
}

// Usage
$page = isset($_GET['page']) ? (int)$_GET['page'] : 1;
$userData = getUserList($page);
?>
```

## Use Cases

### **User Management Dashboard**

* **User Overview**: Display all users in your account
* **Status Monitoring**: Track invitation and acceptance status
* **Role Management**: See who has what access level
* **Activity Tracking**: Monitor user login activity

### **Administrative Tools**

* **User Audit**: Review all users and their access
* **Invitation Tracking**: Monitor pending invitations
* **Access Control**: Understand user permissions
* **User Activity**: Track user engagement

### **API Integration**

* **User Synchronization**: Sync user data with external systems
* **Access Control**: Implement role-based access control
* **User Analytics**: Analyze user activity and engagement
* **Automated Management**: Automate user management tasks

<Note>
  This endpoint provides comprehensive user information including invitation status, roles, and activity. Use this data to manage user access and monitor account activity.
</Note>

<Info>
  The account owner (is\_shared: false) will always appear first in the list and has full access to the account. Shared users have limited access based on their assigned roles.
</Info>


## OpenAPI

````yaml GET /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/:
    get:
      tags:
        - User Management
      summary: Get User List
      description: >-
        Get a list of all users in your account including shared users, their
        roles, and invitation status.
      parameters:
        - name: page
          in: query
          description: Page number for pagination
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 1
      responses:
        '200':
          description: List of users in the account
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Total number of users
                    example: 22
                  next:
                    type: integer
                    nullable: true
                    description: Next page number
                    example: 2
                  previous:
                    type: integer
                    nullable: true
                    description: Previous page number
                    example: null
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/SharedUser'
              examples:
                user_list:
                  summary: User list with pagination
                  value:
                    count: 22
                    next: 2
                    previous: null
                    results:
                      - id: 0
                        shared_user:
                          id: 560
                          first_name: Akshay
                          last_name: ''
                          full_name: Akshay
                          email: akshay.sharma@scanova.io
                          is_shared: false
                          date_joined: '2022-07-15T15:36:23.251791+05:30'
                          is_social_signup: false
                          is_sso_login: false
                          has_usable_password: true
                          language: en
                          last_login: '2023-09-12T15:32:09.549594+05:30'
                          first_login: false
                          enforce_mfa: false
                          mfa_enabled: false
                          mfa_status: Disabled
                        access_level:
                          id: 0
                          name: OWNER
                        invitation_sent_on: null
                        invitation_accepted_on: null
                        is_invitation_sent: false
                        is_invitation_accepted: false
                        created: '2022-07-15T15:36:23.251791+05:30'
                        modified: '2022-07-15T15:36:23.251791+05:30'
                        tags: []
        '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
    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.

````