> ## 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.1.0
info:
  title: Scanova Management API (v2)
  description: >-
    The complete Scanova Management API — every endpoint available at
    management.scanova.io (QR codes, folders, tags, leads, forms, analytics,
    plans, shared users & roles), plus the token-creation and usage-stats
    endpoints used to authenticate against it. Every path and request/response
    shape below was verified live against a real API key and the actual running
    backend (Phase 7, 2026-08-16) — not guessed from reading urls.py alone.
  version: 2.0.0
servers:
  - url: https://management.scanova.io
    description: Management API — QR/folder/tag/lead/form/analytics/plans endpoints
security:
  - apiKeyAuth: []
paths:
  /multi-users/:
    get:
      summary: List shared users
      operationId: listManagedSharedUsers
      responses:
        '200':
          description: Paginated list of shared users invited to this account.
          content:
            application/json:
              example:
                count: 0
                next: null
                previous: null
                results: []
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Send your Management API key as the raw value of the Authorization
        header — no "Bearer " or "Token " prefix, and no other characters.
        Example: `Authorization: 401f7ac837da42b97f613d789819ff93537bee6a`. A
        header containing more than one space-separated part is rejected
        outright. Requests also require the request's Host header to be the
        management API host (e.g. management.scanova.io) — the same key sent to
        the regular API host will not authenticate.

````