Searching Users with the REST API

This document explains how to search users through the Monosign REST API. You can search by user name, by e-mail address, by first name and last name and by profile values, and you can combine these criteria in one request.

Request

Before you start

• Create an access key for your application. The steps are described in Custom Application REST API Integration.

• Open the application and check Source Using Type. If it is System Default or Disabled, the request is refused. With Only defined to Application, the list contains only the users of the user sources defined on the application.

Search options at a glance

• All criteria in one request are combined with AND: a user is returned only when every criterion matches. To return the users who match at least one criterion, send Match (section 8).

• Spaces at the start and at the end of a search text are removed. An empty text is not applied as a criterion.

• The characters %, _ and [ are searched as ordinary characters. They are not wildcards.

1. Search by user name or e-mail

SearchText looks for the text in the user name and in the e-mail address. A user is returned when one of the two matches. The search is not case-sensitive.

{
  "SearchText": "john",
  "SearchCondition": "Starts"
}

2. Search by name

With "SearchCondition": "Starts", SearchText searches word by word in the user name, the e-mail address, the first name, the last name and every profile property that is marked as searchable. A user is returned when every word you send is the start of a word in one of these fields.

{
  "SearchText": "john smith",
  "SearchCondition": "Starts"
}

• The result is the same on SQL Server and on PostgreSQL.

• At most five words are used. When you send more, the five longest words are used.

• The domain of an e-mail address is not searched as a word: example does not find [email protected].

• First Name and Last Name are searchable by default. To search in another profile property, open the property in Management (Directory, Profiles, Properties), turn on Searchable on the Advanced tab and save. The values that already exist become searchable a short time later. A masked property is never searched.

• With IsExact set to true, the search by name is not used (section 4).

Is the search by name ready?

The background work is done by Search Token Service. In Management, open System, then Services, and find the row Search Token Service. The Status column shows where it stands. There is one row for each service node.

Below the status, the row shows the counts Tenants, Tenants up to date, Searchable fields and Searchable fields filled. The work is finished when the two tenant counts are equal and the two field counts are equal.

The service runs on a service node in Batch mode. When no node runs it, the search by name does not become active.

3. Search only in the user name or only in the e-mail

Use UserName to search only in the user name, and Email to search only in the e-mail address. Both always work as "contains" and are not case-sensitive. SearchCondition does not change them. When you send both, both must match.

{
  "UserName": "john",
  "Email": "@example.com"
}

4. Exact match

With IsExact set to true, SearchText, UserName and Email must be equal to the whole value, and SearchCondition is ignored.

{
  "SearchText": "[email protected]",
  "IsExact": true
}

5. Search by profile values

ProfileFilter is a list of filters. Each filter has a Property (the name of a profile property, for example FirstName), a Condition and, for most conditions, a Value. When you send several filters, all of them must match.

{
  "ProfileFilter": [
    {
      "Property": "FirstName",
      "Condition": "Contains",
      "Value": "joh"
    },
    {
      "Property": "Department",
      "Condition": "Eq",
      "Value": "IT"
    },
    {
      "Property": "Manager",
      "Condition": "NotNull"
    }
  ]
}

• Starts, Ends and Contains are not case-sensitive.

• Eq and Neq compare the whole stored value. Upper and lower case follow the database: not case-sensitive on SQL Server with its default collation, case-sensitive on PostgreSQL.

• For Eq and Neq, send the value in the type the property stores: "Value": "5" is a text and "Value": 5 is a number, and they do not match each other.

• Property is the name of the profile property. When no property has exactly this name, a name that differs only in upper and lower case is accepted.

• The comparison conditions Gt, Gtq, Lt and Ltq are not supported for profile values and return an error.

6. Combining criteria

You can send text criteria, profile filters and the other fields together. This example returns the users of the user source corp who have a word that starts with john in their user name, e-mail, first name or last name, and whose department is IT:

{
  "SearchText": "john",
  "SearchCondition": "Starts",
  "SourceName": "corp",
  "ProfileFilter": [
    {
      "Property": "Department",
      "Condition": "Eq",
      "Value": "IT"
    }
  ],
  "IncludeProfile": true,
  "Page": 1,
  "PageSize": 100
}

7. Other fields that change the result

To search in all users, whatever their state:

{
  "SearchText": "john",
  "IgnoreIsActiveParameter": true,
  "StateParameter": true,
  "State": "All"
}

8. Match any criterion

By default every criterion must match. With "Match": "Any", a user is returned when at least one of UserName, Email, SearchText and the ProfileFilter items matches. This example returns the users whose department is IT or Finance:

{
  "Match": "Any",
  "ProfileFilter": [
    {
      "Property": "Department",
      "Condition": "Eq",
      "Value": "IT"
    },
    {
      "Property": "Department",
      "Condition": "Eq",
      "Value": "Finance"
    }
  ]
}

• Match accepts All (default, alias And) and Any (alias Or).

• The fields of section 7 are never part of it. User source, state, IsActive, groups, updated date and user id always apply.

• To find users by first name or last name, you do not need Match: the search by name (section 2) looks in both and is much faster.

9. Fast search

How fast the list answers depends on how the text is matched. On a large directory, choose a match that can use an index.

On a test directory with 310,000 users, the same search answered in about 6 seconds with Contains and in less than 1 second with Starts.

• SearchCondition is Contains when you do not send it. For a fast search, always send Starts or Eq.

• UserName and Email work as "contains". To search by the start of a user name or an e-mail address, use SearchText with Starts.

• Keep PageSize small when you show the result to a person, for example 20 or 50.

• Send IncludeProfile, IncludeGroups and IncludeProfilePhoto only when you need them.

• Starts does not find a text in the middle of a word. When you need that, use Contains and expect a longer answer time.

In Postman

1. Create a request with the method POST and the URL https://api.monofor.com/v1.4/users/list (use the API address of your own installation).

2. On the Headers tab, add MonoSign-AppId and MonoSign-AppKey with the values of your application access key.

3. On the Body tab, select raw and JSON, and paste the body below.

4. Click Send. Postman shows the answer time next to the status.

{
  "SearchText": "john.sm",
  "SearchCondition": "Starts",
  "Page": 1,
  "PageSize": 50
}

Paging and response

• Page is the page number and starts at 1.

• PageSize is 100 when you do not send it. The maximum is 1000; a larger value is reduced to the maximum.

• Users are ordered by user name.

• ItemCount is the total number of matching users and PageCount is the number of pages. Read the next pages by increasing Page until it reaches PageCount.

Example response (shortened; each user has more fields than shown here):

{
  "Code": 1,
  "Data": {
    "PageCount": 1,
    "PageSize": 100,
    "CurrentPage": 1,
    "ItemCount": 1,
    "List": [
      {
        "UserId": "bbce41c7-f363-4724-999e-16c3d2293f78",
        "UserName": "john.smith",
        "Email": "[email protected]",
        "SourceName": "corp",
        "State": 1,
        "IsActive": true
      }
    ]
  },
  "Success": true
}

When no user matches, the request is still successful: Success is true, ItemCount is 0, the list is empty and the message is There is no user with these parameters.

Errors

When a criterion cannot be applied or a value of the body cannot be read, the response has Success set to false and one of these messages. No user is returned.

Examples

You can call the API with your programming language. The cURL command below sends the first example. For the other examples, replace the body.

curl --location --request POST 'https://api.monofor.com/v1.4/users/list' \
--header 'MonoSign-AppId: <your-app-id>' \
--header 'MonoSign-AppKey: <your-app-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "Page": 1,
  "PageSize": 1000
}'

All active users, with their user source

Without a search criterion, the list contains every active user in the Enabled state. Each user in the response has SourceName and SourceTitle, the user source the user comes from. Read every page as described in Paging and response.

{
  "Page": 1,
  "PageSize": 1000
}

To get the active users of one user source only, add SourceName:

{
  "SourceName": "corp",
  "Page": 1,
  "PageSize": 1000
}

Search users by user name

The users whose user name contains john:

{
  "UserName": "john"
}

The user whose user name is exactly john.smith:

{
  "UserName": "john.smith",
  "IsExact": true
}

Search a user by e-mail address

The user whose e-mail address is [email protected]. Eq compares the whole text with the user name and with the e-mail address, and it is not case-sensitive on both databases:

{
  "SearchText": "[email protected]",
  "SearchCondition": "Eq"
}

The users whose e-mail address contains @example.com:

{
  "Email": "@example.com"
}

Search users by name

The users who have a word that starts with john and a word that starts with smith in their first name, last name, user name or e-mail address (section 2). IncludeProfile adds the first name and the last name to each user in the response:

{
  "SearchText": "john smith",
  "SearchCondition": "Starts",
  "IncludeProfile": true
}

Search users by a profile value

The users whose department is IT:

{
  "ProfileFilter": [
    {
      "Property": "Department",
      "Condition": "Eq",
      "Value": "IT"
    }
  ],
  "IncludeProfile": true,
  "Page": 1,
  "PageSize": 100
}

Users created or changed since a date

Use this to keep another system up to date. UpdatedDate returns the users created or updated on or after the date. The example includes every state, so that disabled and removed users are returned too:

{
  "UpdatedDate": "2026-11-01T00:00:00Z",
  "IgnoreIsActiveParameter": true,
  "StateParameter": true,
  "State": "All",
  "Page": 1,
  "PageSize": 1000
}

Disabled users

{
  "StateParameter": true,
  "State": "Disabled",
  "IgnoreIsActiveParameter": true
}

One user by id, with profile and groups

{
  "UserId": "bbce41c7-f363-4724-999e-16c3d2293f78",
  "IncludeProfile": true,
  "IncludeGroups": true
}

Users with an empty profile value

The users who have no manager:

{
  "ProfileFilter": [
    {
      "Property": "Manager",
      "Condition": "Null"
    }
  ]
}

Users by name in one user source

The users of the user source corp who have a word that starts with john in their name, user name or e-mail address:

{
  "SearchText": "john",
  "SearchCondition": "Starts",
  "SourceName": "corp",
  "Page": 1,
  "PageSize": 50
}

Users who match one of several criteria

The users whose department is IT or Finance (section 8):

{
  "Match": "Any",
  "ProfileFilter": [
    {
      "Property": "Department",
      "Condition": "Eq",
      "Value": "IT"
    },
    {
      "Property": "Department",
      "Condition": "Eq",
      "Value": "Finance"
    }
  ]
}