Add New User - Scanova API Documentation

curl --request POST \
  --url https://management.scanova.io/multi-users/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'name=John Manager' \
  --form email=john.manager@company.com \
  --form access_level=1

{
  "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": []
}

POST

multi-users

curl --request POST \
  --url https://management.scanova.io/multi-users/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'name=John Manager' \
  --form email=john.manager@company.com \
  --form access_level=1

{
  "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": []
}

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

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

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

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

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)

{
  "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

Invitation Sent: User receives email invitation
Account Creation: User creates account or logs in
Invitation Acceptance: User accepts invitation
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

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

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

{
  "email": ["Enter a valid email address."]
}

Missing Required Fields

{
  "name": ["This field is required."],
  "email": ["This field is required."],
  "access_level": ["This field is required."]
}

Invalid Access Level

{
  "access_level": ["Invalid access level ID."]
}

User Already Exists

{
  "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

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.

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.

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.

Authorizations

Authorization

string

header

required

API key authentication. Enter your API key directly in the Authorization header.

Body

multipart/form-data

name

string

required

Name of the shared user

Example:

"Jon Doe"

string<email>

required

Email address of the shared user

Example:

"jon.doe@scanova.io"

access_level

string

required

Shared user access level id. Pre-defined access levels: Manager (1), Admin (2), Viewer (3)

Example:

"1"

Response

User created successfully

integer

Shared user relationship ID

Example:

479

shared_user

object

Show child attributes

access_level

object

Show child attributes

invitation_sent_on

string<date-time> | null

When the invitation was sent

Example:

"2023-09-11T16:28:22.227002+05:30"

invitation_accepted_on

string<date-time> | null

When the invitation was accepted

Example:

null

is_invitation_sent

boolean

Whether invitation has been sent

Example:

true

is_invitation_accepted

boolean

Whether invitation has been accepted

Example:

false

created

string<date-time>

When the user was added

Example:

"2023-09-11T16:28:22.223671+05:30"

modified

string<date-time>

When the user was last modified

Example:

"2023-09-11T16:28:22.227109+05:30"

​Overview

​Purpose

​User Invitation

​Account Management

​Request Body (Form Data)

​Access Level Options

​Default Roles

​Custom Roles

​Examples

​Add User with Manager Role

​Add User with Admin Role

​Add User with Viewer Role

​Add User with Custom Role

​Response

​Success Response (201 Created)

​Invitation Process

​Email Invitation

​Invitation Status

​Integration Examples

​JavaScript - Add User Form

​Python - Bulk User Addition

​PHP - User Invitation Form

​Error Handling

​Common Errors

​Invalid Email Format

​Missing Required Fields

​Invalid Access Level

​User Already Exists

​Best Practices

​User Management

​Security

​Communication

Authorizations

Body

Response

Overview

Purpose

User Invitation

Account Management

Request Body (Form Data)

Access Level Options

Default Roles

Custom Roles

Examples

Add User with Manager Role

Add User with Admin Role

Add User with Viewer Role

Add User with Custom Role

Response

Success Response (201 Created)

Invitation Process

Email Invitation

Invitation Status

Integration Examples

JavaScript - Add User Form

Python - Bulk User Addition

PHP - User Invitation Form

Error Handling

Common Errors

Invalid Email Format

Missing Required Fields

Invalid Access Level

User Already Exists

Best Practices

User Management

Security

Communication