Skip to main content
Skip table of contents

2. User Retrieval & Search

User Retrieval & Search

This scenario demonstrates how to retrieve user information and search for users within your Circularo organization. Effective user management requires the ability to find specific users, filter users by various criteria, and retrieve detailed user information.

Key features:

  • Retrieve detailed information about specific users

  • Search for users based on roles, groups, or other criteria

  • Find users within specific organization groups

  • Implement user discovery for administrative and integration purposes

Prerequisites

Before retrieving or searching for users, you need:

  • A valid authentication token with administrative privileges

  • Knowledge of your organization's structure and group hierarchy

  • Appropriate rights to view users

  • Understanding of the search query syntax for advanced filtering

Search Capabilities

Circularo provides powerful search capabilities for finding users:

  • Direct Lookup: Retrieve a specific user by ID or email address

  • Role-Based Search: Find users with specific roles in your organization

  • Group-Based Search: Locate users belonging to particular groups

  • Advanced Filtering: Combine multiple criteria for precise user discovery

Understanding Search Query Syntax

The user search endpoint uses Elasticsearch-like query syntax, allowing for sophisticated filtering:

  • term: Exact match on a single value (e.g., finding users with a specific role)

  • terms: Match against multiple possible values (e.g., finding users in any of several groups)

  • range: Find values within a specific range (e.g., users created within a date range)

The search capabilities demonstrated in this scenario can be extended with more complex queries for advanced use cases.

Step 1 - Retrieve Single User Details

This endpoint retrieves detailed information about a specific user by their ID (which is typically their email address). This is useful when you need comprehensive information about a particular user's profile, permissions, and organization membership.

  • Retrieves complete user profile information including status, groups, and organization

  • Requires the exact user ID (typically email address) for lookup

  • Returns all user attributes including configuration settings

  • Useful for administrative tasks and user profile management

This endpoint is ideal for retrieving detailed information about a known user. For discovering users based on criteria, use the search endpoint instead.

User retrieval operation requires administrative privileges. Only organization administrators or global administrators can perform this operation.

Endpoint

CODE 
GET /users/:id

Request

JSON 
GET /users/mary.griffin@circularo.com?token=ZmB4tQ7TRpRdbJ1uLM05oB2G3tKR4D3UDcoHP4jRmV5d6XMk4XdsDo9wvpOja2pS

Response

JSON 
{
  "id": "mary.griffin@circularo.com",
  "name": "mary.griffin@circularo.com",
  "mail": "mary.griffin@circularo.com",
  "fullname": "Mary Griffin",
  "role": "IT Manager",
  "group": [
    "4996164a-d0ae-4819-abc2-7127a9b3689a",
    ...
  ],
  "status": "active",
  "config": {
    ...
  },
  ...
  "organization": "4996164a-d0ae-4819-abc2-7127a9b3689a"
}

The response contains the following important properties:

  • organizationId - Located at organization in the response.

    • Organization ID, which can be used to fetch organization groups.

    • Example value: 4996164a-d0ae-4819-abc2-7127a9b3689a

The response contains comprehensive information about the requested user, including their profile details, group memberships, organization, and status.

  • The id, name, and mail fields typically contain the user's email address

  • The fullname field contains the user's display name

  • The group array contains IDs of all groups the user belongs to

  • The organization field identifies the user's organization

  • The status field indicates whether the account is active, newly created, or suspended

The organization ID returned in this response can be used to retrieve organization details and group information in subsequent requests.

Step 2 - Search Users by Role

This endpoint demonstrates how to search for users based on their role within the organization. This is useful when you need to find all users with specific responsibilities or job functions.

  • Searches across all the available users to find those with a specific role

  • Uses the powerful Elasticsearch-like query syntax for precise filtering

  • Returns a list of matching users with basic profile information

  • Supports pagination for handling large result sets

The search endpoint is highly flexible and can be used with various filter criteria. This example demonstrates role-based filtering, but the same approach can be applied to other user attributes.

Endpoint

CODE 
POST /users/search

Request

JSON 
POST /users/search?token=ZmB4tQ7TRpRdbJ1uLM05oB2G3tKR4D3UDcoHP4jRmV5d6XMk4XdsDo9wvpOja2pS

Content-Type: application/json

{
  "format": "minimal",  //Response format: \"minimal\" returns basic info, \"full\" returns complete user details
  "userQuery": {
    "query": {
      "filter": [
        {
          "type": "term",  //Search for exact match on the role field
          "field": "role",
          "value": "Consultant"
        }
      ]
    }
  }
}

Response

JSON 
{
  "results": [
    {
      "name": "derek.trotter@circularo.com",
      "mail": "derek.trotter@circularo.com",
      "fullname": "Derek Edward Trotter",
      "role": "Consultant",
      "recordType": "internal",
      ...
    },
    ...
  ],
  "total": 8
}

The response contains a list of users matching the specified role criteria, along with basic information about each user.

  • The results array contains the matching user records

  • Each user record includes basic information like name, email, fullname, and role

  • The total field indicates the total number of matching users

  • When using the "minimal" format, detailed information like groups and organization is omitted

For more detailed user information in the results, change the format parameter to "full" instead of "minimal".

Step 3 - Retrieve Organization Group IDs

Before searching for users by group membership, you need to retrieve the organization's group IDs. This endpoint fetches the organization details including all predefined group IDs that can be used for group-based user searches.

  • Retrieves the complete organization structure including all group IDs

  • Uses the organization ID obtained from the user profile in the first request

  • Returns IDs for predefined groups like admin, user, prepare, read, and sign

  • Provides essential information for group-based user searches

Endpoint

CODE 
GET /groups/:organizationId

Request

JSON 
GET /groups/4996164a-d0ae-4819-abc2-7127a9b3689a?token=ZmB4tQ7TRpRdbJ1uLM05oB2G3tKR4D3UDcoHP4jRmV5d6XMk4XdsDo9wvpOja2pS

Response

JSON 
{
  "_id": "4996164a-d0ae-4819-abc2-7127a9b3689a",  //Organization ID
  "name": "4996164a-d0ae-4819-abc2-7127a9b3689a",
  "organization": "4996164a-d0ae-4819-abc2-7127a9b3689a",
  "organizationGroups": {  //IDs of the different groups according to user role
    "admin": "7a864973-7a1c-4006-a09e-3873c685df72",
    "user": "cc415556-6c21-468d-ad28-0bdaca8be16b",
    "prepare": "5e6fac2a-547b-4fad-8b43-c46c2d1c7a13",
    "read": "77550db1-a859-41f4-a5df-531e0af76fc6",
    "sign": "e2ed5f3c-006f-4673-ae96-d66f63b6ae0c"
  },
  "type": [
    "organization"
  ],
  ...
}

The response contains the following important properties:

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

    • ID of the standard user group within the organization.

    • Example value: cc415556-6c21-468d-ad28-0bdaca8be16b

The response contains detailed information about the organization and its associated groups.

  • The _id, name, and organization fields contain the organization's unique identifier

  • The organizationGroups object contains IDs for all predefined groups

  • Each group ID is a unique identifier that can be used in group-based user searches

  • The type array indicates that this is an organization entity

Step 4 - Search Users by Group Membership

This endpoint demonstrates how to search for users based on their group membership. This is particularly useful for finding all users with specific permission levels or organizational roles.

  • Searches for all users belonging to a specific group (in this case, the standard user group)

  • Uses the group ID obtained from the previous organization groups request

  • Returns a list of matching users with basic profile information

  • Helps identify all users with a particular set of permissions

Group-based searches are powerful for administrative tasks like permission audits, bulk operations on specific user types, or identifying users with particular access levels.

Endpoint

CODE 
POST /users/search

Request

JSON 
POST /users/search?token=ZmB4tQ7TRpRdbJ1uLM05oB2G3tKR4D3UDcoHP4jRmV5d6XMk4XdsDo9wvpOja2pS

Content-Type: application/json

{
  "format": "minimal",  //Response format: \"minimal\" returns basic info, \"full\" returns complete user details
  "userQuery": {
    "query": {
      "filter": [
        {
          "type": "terms",  //Search for users belonging to specific groups
          "field": "group",
          "value": [
            "cc415556-6c21-468d-ad28-0bdaca8be16b"
          ]
        }
      ]
    }
  }
}

Response

JSON 
{
  "results": [
    {
      "name": "billy.spring@circularo.com",
      "mail": "billy.spring@circularo.com",
      "fullname": "Billy Spring",
      "role": "Retail Operations Assistant",
      "recordType": "internal",
      ...
    },
    ...
  ],
  "total": 46
}

The response contains a list of users belonging to the specified group, along with basic information about each user.

  • The results array contains the matching user records

  • Each user record includes basic information like name, email, fullname, and role

  • The total field indicates the total number of users in the specified group

  • When using the "minimal" format, detailed information like groups and organization is omitted

The "terms" query type allows searching for multiple possible values. You can include multiple group IDs in the value array to find users belonging to any of those groups.

User Retrieval & Search Summary

You have successfully learned how to retrieve user information and search for users using various criteria in Circularo.

Key Concepts

  • Direct User Lookup: Retrieving detailed information about specific users by ID

  • Role-Based Search: Finding users with specific roles or job functions

  • Group-Based Search: Locating users with particular permissions or organizational roles

  • Search Query Syntax: Using Elasticsearch-like queries for precise user filtering

  • Response Formats: Controlling the level of detail in search results with minimal or full formats

Next Steps

With your understanding of user retrieval and search capabilities, you can now:

  • Implement user discovery and lookup features in your integration

  • Create administrative dashboards with user filtering capabilities

  • Perform permission audits by identifying users with specific access levels

  • Build user management interfaces with search functionality

  • Implement more complex search queries combining multiple criteria

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 retrieval and search 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 a specific user's details
    const userResponse = await fetch(`${URL}${API_PATH}/users/john.smith@example.com?token=${TOKEN}`);
    if (!userResponse.ok) {
        throw new Error(`Failed to get user: ${userResponse.status} ${userResponse.statusText}`);
    }

    const userData = await userResponse.json();
    console.log(`Retrieved user details for: ${userData.fullname}`);
    console.log(`User organization: ${userData.organization}`);
    console.log(`User status: ${userData.status}`);

    const organizationId = userData.organization;

    // Step 2: Search for users with a specific role
    const roleSearchResponse = await fetch(`${URL}${API_PATH}/users/search?token=${TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            format: "minimal",
            userQuery: {
                query: {
                    filter: [
                        {
                            type: "term",
                            field: "role",
                            value: "Manager"
                        }
                    ]
                }
            }
        })
    });
    if (!roleSearchResponse.ok) {
        throw new Error(`Role search failed: ${roleSearchResponse.status} ${roleSearchResponse.statusText}`);
    }

    const roleSearchResults = await roleSearchResponse.json();
    console.log(`Found ${roleSearchResults.total} users with the role "Manager"`);
    console.log(`First manager: ${roleSearchResults.results[0].fullname}`);

    // Step 3: 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;
    console.log(`Retrieved user group ID: ${userGroupId}`);

    // Step 4: Search for users in the user group
    const groupSearchResponse = await fetch(`${URL}${API_PATH}/users/search?token=${TOKEN}`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            format: "minimal",
            userQuery: {
                query: {
                    filter: [
                        {
                            type: "terms",
                            field: "group",
                            value: [userGroupId]
                        }
                    ]
                }
            }
        })
    });
    if (!groupSearchResponse.ok) {
        throw new Error(`Group search failed: ${groupSearchResponse.status} ${groupSearchResponse.statusText}`);
    }

    const groupSearchResults = await groupSearchResponse.json();
    console.log(`Found ${groupSearchResults.total} users in the user group`);

} catch (error) {
    console.error('Error finding and managing users:', 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