Search users in your organization

Introduction

For the complete control and overlook of the access in your organization you need to be able to export a list of users that have access to the application. If you wish to do so through the API this guide is for you.

In this guide, we're walking you through these scenarios:

Extract basic and full info about the users
Filter the results based on the group the user is assigned to

Each scenario uses the same endpoint, but the queries vary depending to what results you need.

Requirements

Circularo admin account: This grants you the necessary permissions to access user data.

Read more about Circularo administration - User administration
Group ID: we will show you in this guide how to retrieve it

Before we start

Please keep in mind that the maximum results of one query is 100.

This cannot be raised so if you have more users in your organization you need to loop through the results.

You can display results starting from a certain number using the from value.

Also the default number of records per response is 10 so if you need to have more you need to specify size value.

For example if you have 150 users in your organization and you need to show results from 100 - 150:

JSON

{
    "userQuery":{
        "from": 100,
        "size": 50,
    }
}

1. Get basic and full info

Basic info

This will let you see some basic information about the user.

Endpoint

CODE

POST /users/search

Request

JSON

POST /users/search?token=tOE6KOu2nLE0JeLpfvCNT6HCErGuDIDEmvfVidkc8QlK6SVKNZ3lzCRN7QuAnoM9

Response

JSON

{
  "results": [
    {
      "fullname": "Hugo Sonda",
      "image": null,
      "mail": "hugo@circularo.com",
      "recordType": "internal",
      "customFields": {},
      "hasActiveDelegation": false,
      "language": "en",
      "name": "hugo@circularo.com"
    },
    {
      "fullname": "Adam Smith",
      "image": null,
      "mail": "adam.smith@circularo.com",
      "recordType": "internal",
      "role": "Senior Retail Operations Assistant",
      "customFields": {},
      "hasActiveDelegation": false,
      "language": "en",
      "name": "adam.smith@circularo.com",
      "phone": "+971555666055"
    },
    {
      "fullname": "John Doe",
      "image": null,
      "mail": "john.doe@circularo.com",
      "recordType": "internal",
      "customFields": {},
      "hasActiveDelegation": false,
      "language": "en",
      "name": "john.doe@circularo.com"
    }
  ],
  "total": 3
}

Full info

This will let you see full information about each user.

Endpoint

CODE

POST /users/search

Request

JSON

POST /users/search?token=tOE6KOu2nLE0JeLpfvCNT6HCErGuDIDEmvfVidkc8QlK6SVKNZ3lzCRN7QuAnoM9

Content-Type: application/json

{
  "format": "full"
}

Response

JSON

{
  "results": [
    {
      "fullname": "Hugo Sonda",
      "image": null,
      "mail": "hugo@circularo.com",
      "recordType": "internal",
      "customFields": {},
      "hasActiveDelegation": false,
      "language": "en",
      "name": "hugo@circularo.com",
      "allowBiometricSignature": false,
      "autoTimezone": true,
      "backgroundJobs": [],
      "config": {
        "delegation": {
          "time": {}
        },
        "language": "en",
        "navigationOpen": true,
        "notifications": {
          "enableAlerts": false,
          "inApp": [
            ...
          ],
          "mail": [
            ...
          ]
        },
        "photo": {},
        "scheduler": true,
        "view": "tableView"
      },
      "createType": "internal",
      "dateformat": "dd/MM/yyyy",
      "disabledIntros": [
        "first_login"
      ],
      "filters": [],
      "firstDayOfWeek": 1,
      "group": [
        "9125c0ab-969d-4ce4-b106-8504b05f3ced",
        "70968ee6-b469-4085-a928-b09d511d549d",
        "2bfc3601-44b4-4d20-ac41-b108dd743b7e",
        "494f4f2f-4215-452c-b004-1bcad4706626"
      ],
      "id": "hugo@circularo.com",
      "identities": [],
      "lastReleaseAnnouncementSeen": "22.1.0",
      "marketing": false,
      "providers": [],
      "registeredOn": "2022-11-07T21:09:36.419Z",
      "status": "active",
      "statusChangedOn": "2023-08-10T13:00:39.866Z",
      "organization": "494f4f2f-4215-452c-b004-1bcad4706626",
      "templateUsage": [
        {
          "count": 1,
          "custom": false,
          "lastUsed": "2022-11-07T21:09:40.652Z",
          "template": "d_default"
        }
      ],
      "termsAccepted": true,
      "termsAcceptedOn": "2022-11-07T21:09:36.419Z",
      "timeformat": "h:mm a",
      "timezone": "Europe/Prague",
      "version": 2
    },
    ...
  ],
  "total": 3
}

2. Filter results based on user group

Since you can divide your users into different groups you can also retrieve a list of users that are inside these groups.

Step 1 - Retrieve Organization ID

Lets fetch the info from our account:

Endpoint

CODE

GET /users/:id

Request

JSON

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

Response

JSON

{
  ...
  "organization": "9125c0ab-969d-4ce4-b106-8504b05f3ced"
}

The response contains the following important properties:

organizationId - Located at organization in the response.
- Example value: 9125c0ab-969d-4ce4-b106-8504b05f3ced

Step 2 - Obtain Group ID

Upon determining our organization's ID, we can find out internal group IDs. The essential information we require is nested in the organizationGroups object:

Endpoint

CODE

GET /groups/:organizationId

Request

JSON

GET /groups/9125c0ab-969d-4ce4-b106-8504b05f3ced?token=tOE6KOu2nLE0JeLpfvCNT6HCErGuDIDEmvfVidkc8QlK6SVKNZ3lzCRN7QuAnoM9

Response

JSON

{
  "_id": "9125c0ab-969d-4ce4-b106-8504b05f3ced",  //Organization ID
  ...
  "name": "9125c0ab-969d-4ce4-b106-8504b05f3ced",
  "organization": "9125c0ab-969d-4ce4-b106-8504b05f3ced",
  "organizationGroups": {  //IDs of the different groups according to user role
    "admin": "c46ccb52-c109-449f-8700-954f87c79aa9",
    "prepare": "70968ee6-b469-4085-a928-b09d511d549d",
    "read": "b3d7e6e2-6eea-4b02-b615-c7e9e8a4529a",
    "sign": "df65a78d-bb8c-4f5b-9979-41f5a910fe63",
    "user": "3d314233-2c36-488e-bc12-a533adf0ed30"
  },
  "type": [
    "organization"
  ]
}

The response contains the following important properties:

userGroupId - Located at organizationGroups.user in the response.
- Example value: 3d314233-2c36-488e-bc12-a533adf0ed30

Step 3 - Search users in group

Endpoint

CODE

POST /users/search

Request

JSON

POST /users/search?token=tOE6KOu2nLE0JeLpfvCNT6HCErGuDIDEmvfVidkc8QlK6SVKNZ3lzCRN7QuAnoM9

Content-Type: application/json

{
  "userQuery": {
    "query": {
      "filter": [
        {
          "type": "terms",
          "field": "group",
          "value": [
            "3d314233-2c36-488e-bc12-a533adf0ed30"  //Replace with your group ID
          ]
        }
      ]
    }
  }
}

Response

JSON

{
  "results": [
    {
      "fullname": "Adam Smith",
      "image": null,
      "mail": "adam.smith@circularo.com",
      "recordType": "internal",
      "role": "Senior Retail Operations Assistant",
      "customFields": {},
      "hasActiveDelegation": false,
      "language": "en",
      "name": "adam.smith@circularo.com",
      "phone": "+971555666055"
    }
  ],
  "total": 1
}