Skip to main content
Skip table of contents

1. User Account Creation

User Account Creation

This scenario demonstrates how to create and manage user accounts within your organization. User account management is a fundamental administrative task that enables you to onboard team members, control access permissions, and maintain your organization's security.

Key features:

  • Create user accounts with different activation methods

  • Assign users to specific organizations and groups

  • Configure user permissions through group assignments

  • Manage the user onboarding process

Prerequisites

Before creating user accounts, you need:

  • A valid authentication token with administrative privileges

  • Knowledge of your organization's structure and group hierarchy

  • Understanding of the different user roles and permissions in your organization

User account creation requires administrator privileges. Only organization administrators or global administrators can perform these operations.

User Creation Methods

Circularo supports two primary methods for creating user accounts:

  • Invitation-Based: Send an invitation email to the user who must complete the registration process

  • Direct Creation: Create a fully active account with a predefined password, bypassing the invitation process

Each method has its advantages:

  • Invitation-Based: More secure as users set their own passwords, better user experience, automatic email notifications

  • Direct Creation: Immediate account availability, suitable for managed IT environments, allows batch provisioning

Understanding Organization Structure

Before creating users, it's important to understand Circularo's structure, which is designed for flexibility and security:

  • Organizations: These are the top-level containers. They are used to group all users and resources for a single company, or to separate different companies if they share the same system tenant.

  • Groups: Groups are the primary way to assign permissions. A user's final permissions are determined by a combination of all the groups they belong to.

Each organization has several predefined groups that determine user permissions. When creating a user, you must assign them to both the organization and the group.

Step 1 - Retrieve Organization ID

The first step in creating a user account is identifying the organization ID to which the user will belong. Organization IDs are unique identifiers that differ from display names and are required for user creation.

  • Organization IDs are required when assigning users to organizations

  • You can retrieve your organization ID from your own user profile

  • For organization administrators, this will return your current organization

  • For global administrators, you may need to query the groups endpoint to see all available organizations

Endpoint

CODE 
GET /users/:id

Request

JSON 
GET /users/john.doe@circularo.com?token=K0oLsav19H09IFNySquir78Fr0bnJWUiGzGHQPIj8v0xnkzbTwUU0XlCRDYSQbEV

Response

JSON 
{
  "organization": "007a9cd5-ec95-4eac-925d-d1ef5214adf9",
  ...
}

The response contains the following important properties:

  • organizationId - Located at organization in the response.

    • Example value: 007a9cd5-ec95-4eac-925d-d1ef5214adf9

The response contains your user profile information, including your organization ID. This ID is a unique identifier for your organization and will be used when creating new user accounts.

Step 2 - Retrieve Organization Group IDs

After obtaining the organization ID, the next step is to retrieve the group IDs within that organization. Each organization contains several predefined groups that determine user permissions and access levels.

  • Each organization has predefined groups with different permission levels

  • Users must be assigned to at least one group to determine their role

  • The group assignment controls what actions users can perform in the system

Group Types

  • Admin Group: Full administrative privileges within the organization

  • User Group: Standard user permissions for regular team members

  • Prepare Group: Lite user group focused on document preparation

  • Read Group: Lite user group with read-only access to documents

  • Sign Group: Lite user group focused on document signing

Endpoint

CODE 
GET /groups/:organizationId

Request

JSON 
GET /groups/007a9cd5-ec95-4eac-925d-d1ef5214adf9?token=K0oLsav19H09IFNySquir78Fr0bnJWUiGzGHQPIj8v0xnkzbTwUU0XlCRDYSQbEV

Response

JSON 
{
  "_id": "007a9cd5-ec95-4eac-925d-d1ef5214adf9",  //Organization ID
  "name": "007a9cd5-ec95-4eac-925d-d1ef5214adf9",
  "organization": "007a9cd5-ec95-4eac-925d-d1ef5214adf9",
  "organizationGroups": {  //IDs of the different groups according to user role
    "admin": "215892df-6ab0-4efd-99d4-20b84fe5585a",
    "user": "22af909c-8a08-45fa-8ba2-1e3b331065aa",
    "prepare": "4f9954fc-98a5-4b75-8bc6-57f0be86ef22",
    "read": "617f8fd7-b8e7-4f13-a4a7-7ca1140eca93",
    "sign": "a66a6263-2862-406f-90ba-cea2db597412"
  },
  "type": [
    "organization"
  ],
  ...
}

The response contains the following important properties:

  • adminGroupId - Located at organizationGroups.admin in the response.

    • This is user group for admin users.

    • Example value: 215892df-6ab0-4efd-99d4-20b84fe5585a

  • userGroupId - Located at organizationGroups.user in the response.

    • This is user group for regular users.

    • Example value: 22af909c-8a08-45fa-8ba2-1e3b331065aa

  • prepareGroupId - Located at organizationGroups.prepare in the response.

    • This is user group for lite users who have prepare only rights.

    • Example value: 4f9954fc-98a5-4b75-8bc6-57f0be86ef22

  • readGroupId - Located at organizationGroups.read in the response.

    • This is user group for lite users who have read only rights.

    • Example value: 617f8fd7-b8e7-4f13-a4a7-7ca1140eca93

  • signGroupId - Located at organizationGroups.sign in the response.

    • This is user group for lite users who have sign only rights.

    • Example value: a66a6263-2862-406f-90ba-cea2db597412

The response contains details about the organization and its associated groups. The organizationGroups object contains the IDs of all predefined groups within the organization.

When creating a user, you'll need to assign them to both the organization itself and at least one of these groups to determine their permissions.

For most regular users, assign them to the 'user' group. For administrators, use the 'admin' group. For limited-access users (lite users), consider the 'prepare', 'read' or 'sign' groups based on their needs.

Step 3A - Create User with Email Invitation

This endpoint demonstrates how to create a new user account using the invitation method. With this approach, the system creates an inactive account and sends an invitation email to the user. The user must then complete the registration process.

  • Creates a user account in 'newly_created' status (inactive until registration is completed)

  • Sends an invitation email to the user with instructions to complete registration

  • Assigns the user to the specified organization and group

  • Provides a secure onboarding experience as users set their own passwords

This is the recommended approach for most scenarios as it provides a better user experience and enhanced security by allowing users to set their own passwords.

Endpoint

CODE 
POST /users

Request

JSON 
POST /users?token=K0oLsav19H09IFNySquir78Fr0bnJWUiGzGHQPIj8v0xnkzbTwUU0XlCRDYSQbEV

Content-Type: application/json

{
  "sendMail": true,  //Set to true to send an invitation email to the user
  "users": [
    {
      "fullname": "Derek Edward Trotter",  //User's full name (display name)
      "mail": "api.test@circularo.com",  //User's email address (typically also used as username)
      "name": "api.test@circularo.com",  //User's login name (typically the email address)
      "group": [  //Group assignments determine user permissions
        "007a9cd5-ec95-4eac-925d-d1ef5214adf9",  //Organization ID
        "22af909c-8a08-45fa-8ba2-1e3b331065aa"  //Regular user group
      ],
      "organization": "007a9cd5-ec95-4eac-925d-d1ef5214adf9",  //Organization the user belongs to
      "status": "newly_created"  //Initial status - user must complete registration
    }
  ]
}

Response

JSON 
{
  "errors": false,
  "count": 1,
  "items": []
}

The user account has been successfully created in a 'newly_created' status. An invitation email has been sent to the user with instructions to complete their registration by setting a password.

  • The user will receive an email with a link to complete their registration

  • The account remains inactive until the user completes the registration process

  • Once registration is complete, the user's status will change to 'active'

  • The user will have access based on the assigned group permissions

Step 3B - Create Active User with Predefined Password

This endpoint demonstrates how to create a fully active user account with a predefined password. This method bypasses the invitation process, creating an account that is immediately ready for use.

  • Creates a user account in 'active' status (immediately usable)

  • Sets a predefined password for the user

  • Does not send any notification email to the user

  • Assigns the user to the specified organization and group

When using this method, you are responsible for securely communicating the account credentials to the user through your own channels. No automatic notification is sent.

Endpoint

CODE 
POST /users

Request

JSON 
POST /users?token=K0oLsav19H09IFNySquir78Fr0bnJWUiGzGHQPIj8v0xnkzbTwUU0XlCRDYSQbEV

Content-Type: application/json

{
  "sendMail": false,  //Set to false to prevent sending any notification email
  "users": [
    {
      "fullname": "Derek Edward Trotter",  //User's full name (display name)
      "mail": "api.test@circularo.com",  //User's email address (typically also used as username)
      "name": "api.test@circularo.com",  //User's login name (typically the email address)
      "password": "#del.boy!",  //Predefined password for the user
      "group": [  //Group assignments determine user permissions
        "007a9cd5-ec95-4eac-925d-d1ef5214adf9",  //Organization ID
        "22af909c-8a08-45fa-8ba2-1e3b331065aa"  //Regular user group
      ],
      "organization": "007a9cd5-ec95-4eac-925d-d1ef5214adf9",  //Organization the user belongs to
      "status": "active"  //Set account to active state (immediately usable)
    }
  ]
}

Response

JSON 
{
  "errors": false,
  "count": 1,
  "items": []
}

The user account has been successfully created in an 'active' status with the specified password. The account is immediately ready for use.

  • The account is fully active and can be used immediately

  • No notification email is sent to the user

  • You must communicate the username and password to the user through your own channels

  • The user will have access based on the assigned group permissions

This method is particularly useful for bulk user provisioning or in environments where IT departments manage user credentials and onboarding.

User Account Creation Summary

You have successfully learned how to create user accounts in Circularo using different methods.

Key Concepts

  • Organization Structure: Understanding the hierarchy of organizations and groups

  • User Roles: Assigning appropriate permissions through group membership

  • Invitation-Based Creation: Creating accounts that require user activation

  • Direct Creation: Creating immediately active accounts with predefined passwords

  • User Status: Managing the lifecycle state of user accounts (newly_created, active, etc.)

Next Steps

With your understanding of user account creation, you can now:

  • Implement user provisioning workflows in your integration

  • Create accounts with appropriate permissions based on user roles

  • Manage the user onboarding experience

  • Explore additional user management operations like updating and deactivating accounts

  • Implement batch user creation for efficient onboarding of multiple users

Example Implementation

See our OpenAPI documentation to learn about the full set of API endpoints and parameters.

Please use proper exception handling and function decomposition in your own code. The code is provided for illustrative purposes only and is not intended for production use.

JAVASCRIPT 
// User account creation example
const URL = "https://sandbox.circularo.com";
const API_PATH = "/api/v1";
const TOKEN = "YOUR_ADMIN_TOKEN"; // Must have administrative privileges

try {
    // Step 1: Retrieve your organization ID
    const orgResponse = await fetch(`${URL}${API_PATH}/users/current?token=${TOKEN}`);
    if (!orgResponse.ok) {
        throw new Error(`Failed to get organization: ${orgResponse.status} ${orgResponse.statusText}`);
    }

    const userData = await orgResponse.json();
    const organizationId = userData.organization;
    console.log(`Retrieved organization ID: ${organizationId}`);

    // Step 2: Retrieve organization group IDs
    const groupsResponse = await fetch(`${URL}${API_PATH}/groups/${organizationId}?token=${TOKEN}`);
    if (!groupsResponse.ok) {
        throw new Error(`Failed to get groups: ${groupsResponse.status} ${groupsResponse.statusText}`);
    }

    const groupsData = await groupsResponse.json();
    const userGroupId = groupsData.organizationGroups.user;
    const adminGroupId = groupsData.organizationGroups.admin;
    console.log(`Retrieved user group ID: ${userGroupId}`);
    console.log(`Retrieved admin group ID: ${adminGroupId}`);

    // Step 3A: Create a user with email invitation
    const inviteUserResponse = await fetch(`${URL}${API_PATH}/users?token=${TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            sendMail: true,
            users: [
                {
                    fullname: "John Smith",
                    mail: "john.smith@example.com",
                    name: "john.smith@example.com",
                    group: [
                        organizationId,
                        userGroupId
                    ],
                    organization: organizationId,
                    status: "newly_created"
                   }
            ]
        })
    });
    if (!inviteUserResponse.ok) {
        throw new Error(`Failed to invite user: ${inviteUserResponse.status} ${inviteUserResponse.statusText}`);
    }

    const inviteResult = await inviteUserResponse.json();
    console.log(`User invitation sent successfully. Created ${inviteResult.count} user(s).`);

    // Step 3B: Create an active user with predefined password
    const createActiveUserResponse = await fetch(`${URL}${API_PATH}/users?token=${TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            sendMail: false,
            users: [
                {
                    fullname: "Jane Doe",
                    mail: "jane.doe@example.com",
                    name: "jane.doe@example.com",
                    password: "SecurePassword123!",
                    group: [
                        organizationId,
                        adminGroupId
                    ],
                    organization: organizationId,
                    status: "active"
                }
            ]
        })
    });
    if (!createActiveUserResponse.ok) {
        throw new Error(`Failed to create active user: ${createActiveUserResponse.status} ${createActiveUserResponse.statusText}`);
    }

    const activeUserResult = await createActiveUserResponse.json();
    console.log(`Active user created successfully. Created ${activeUserResult.count} user(s).`);
    console.log("Remember to securely communicate the credentials to the user!");

} catch (error) {
    console.error('Error creating user accounts:', error.message);
}
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close