Search for Users

Edit on GitHubEdit MD

This API is used to search for Users. This API may be called using the GET or POST HTTP methods, examples of each are provided below. The POST method is provided to allow for a richer request object without worrying about exceeding the maximum length of a URL. Calling this API with either the GET or POST HTTP method will provide the same search results given the same query parameters.

Request#

Which search query parameters are available and how they behave depends on the search engine type. Read more about the different types of search engines.

Database Search Engine#

This is a good choice for smaller installs, embedded scenarios, or other places where the additional capability of Elasticsearch is not required.

version

Available Since Version 1.16.0

Search for Users by Id

GET/api/user/search?ids={uuid}&ids={uuid}

OpenAPI Spec

Search for Users by a query string

GET/api/user/search?queryString={queryString}

OpenAPI Spec

Search for Users by a query string and sort the response

GET/api/user/search?queryString={queryString}&sortFields[0].name={name}&sortFields[0].order={order}

OpenAPI Spec

Request Parameters#

accurateTotal Boolean optional Defaults to false Available since 1.24.0

Set this value equal to true to receive an accurate hit count on the API response.

By default the search engine will limit the hit count to 10,000 users. This means that even if your query may match more than 10,000 users, the returned total count will be 10,000. This is adequate for many use cases such as pagination and general purpose queries.

If you are looking for an accurate user count that can exceed 10,000 matches, you will want to set this value equal to true.

expand Array<String> optional Defaults to [memberships, registrations] Available since 1.48.0

This parameter allows you to optionally remove the memberships and registrations from the API response. Removing these fields from the response may improve performance on large search requests, specifically when you are managing application roles through User Registrations and Group Memberships.

For backwards compatibility, the default behavior will be to return both memberships and registrations.

To request only the registrations but omit the memberships from the response, provide a value of [registrations]. To omit both the memberships and registrations from the response, provide a value of [].

ids UUID optional

A User Id to retrieve. By specifying this URL parameter multiple times you can lookup multiple Users.

Using this parameter is mutually exclusive with the queryString field and is not paginated or sorted using the sortFields field.

caution

This field supports a maximum of 10,000 values.

numberOfResults Integer optional Defaults to 25

The number of search results to return. Used for pagination.

queryString String optional

A query string that is used to search for Users. Using this parameter is mutually exclusive with the ids field.

Database search limits effective queries to single search terms that may match the following fields on the User:

firstName
lastName
fullName
email
phoneNumber Available since 1.59.0
username

The search matches against all of these fields and any user with a matching field will be returned. The match is case-insensitive, and you may not search by prefix or suffix. Whitespace is not allowed in the search. Regular expressions may not be used. A value of * will match all records.

startRow Integer optional Defaults to 0

The start row within the search results to return. Used for pagination.

sortFields Array optional

An array of sort fields used to sort the result. The order the sort fields are provided will be maintained in the sorted output.

sortFields[x].name String required

The name of the field to sort.

Required if sortFields is provided.

The following field names are supported for the database search engine:

birthDate
email
fullName
id
insertInstant
lastLoginInstant
login
phoneNumber Available since 1.59.0
tenantId
username

sortFields[x].order String optional Defaults to asc

The order to sort the specified field. Possible values are:

asc
desc

Request Headers#

X-FusionAuth-TenantId String optional

The unique Id of the tenant used to scope this API request.

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Search for Users using a JSON request body. This allows for larger requests than are possible using request parameters.

POST/api/user/search

OpenAPI Spec

Request Headers#

X-FusionAuth-TenantId String optional

The unique Id of the tenant used to scope this API request.

See Making an API request using a Tenant Id for additional information.

Request Body#

expand Array<String> optional Defaults to [memberships, registrations] Available since 1.48.0

For backwards compatibility, the default behavior will be to return both memberships and registrations.

search.accurateTotal Boolean optional Defaults to false Available since 1.24.0

Set this value equal to true to receive an accurate hit count on the API response.

If you are looking for an accurate user count that can exceed 10,000 matches, you will want to set this value equal to true.

search.ids Array<UUID> optional

A list of User Ids to retrieve. When using this parameter, the results are not paginated or sorted using the sortFields.

The search.ids and queryString parameters are mutually exclusive, they are listed here in order of precedence.

search.numberOfResults Integer optional Defaults to 25

The number of search results to return. Used for pagination.

search.queryString String optional

A query string that is used to search for Users. Using this parameter is mutually exclusive with the ids field.

Database search limits effective queries to single search terms that may match the following fields on the User:

firstName
lastName
fullName
email
phoneNumber Available since 1.59.0
username

search.startRow Integer optional Defaults to 0

The start row within the search results to return. Used for pagination.

search.sortFields Array optional

An array of sort fields used to sort the result. The order the sort fields are provided will be maintained in the sorted output.

search.sortFields[x].name String required

The name of the field to sort.

Required if sortFields is provided.

The following field names are supported for the database search engine:

birthDate
email
fullName
id
insertInstant
lastLoginInstant
login
phoneNumber Available since 1.59.0
tenantId
username

search.sortFields[x].order String optional Defaults to asc

The order to sort the specified field. Possible values are:

asc
desc

Request Body Examples#

Example Request JSON searching by ids

{
  "search": {
    "ids": [
      "a6e3ed2d-582b-4ec3-aa3f-4323c8f39fe9",
      "00000000-0000-0001-0000-000000000000"
    ]
  }
}

Example Request JSON searching by queryString for users with an email address

{
  "search": {
    "numberOfResults": 25,
    "queryString": "@fusionauth.io",
    "sortFields": [
      {
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

Example Request JSON searching by queryString for users with a firstName, lastName, fullName, email or username containing piper.

{
  "search": {
    "numberOfResults": 25,
    "queryString": "piper",
    "sortFields": [
      {
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

Available since 1.59.0

Example Request JSON searching by queryString for users with a phoneNumber.

{
  "search": {
    "numberOfResults": 25,
    "queryString": "303-555-1212",
    "sortFields": [
      {
        "name": "phoneNumber",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

Example Request JSON to retrieve the first 50 users, ordered by email address, ascending.

{
  "search": {
    "numberOfResults": 25,
    "queryString": "*",
    "sortFields": [
      {
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

Elasticsearch Search Engine#

The Elasticsearch engine has advanced querying capabilities and better performance. You can also review the Elasticsearch search guide for more examples.

Search for Users by Id

GET/api/user/search?ids={uuid}&ids={uuid}

OpenAPI Spec

Search for Users by a query string

GET/api/user/search?queryString={queryString}

OpenAPI Spec

Search for Users by a query string and sort the response

GET/api/user/search?queryString={queryString}&sortFields[0].name={name}&sortFields[0].order={order}

OpenAPI Spec

Search for Users by a raw JSON query

GET/api/user/search?query={query}

OpenAPI Spec

Search for Users with a nextResults token

GET/api/user/search?nextResults={nextResults}

OpenAPI Spec

Request Parameters#

accurateTotal Boolean optional Defaults to false Available since 1.24.0

Set this value equal to true to receive an accurate hit count on the API response.

If you are looking for an accurate user count that can exceed 10,000 matches, you will want to set this value equal to true.

expand Array<String> optional Defaults to [memberships, registrations] Available since 1.48.0

For backwards compatibility, the default behavior will be to return both memberships and registrations.

ids UUID optional

A User Id to retrieve. By specifying this URL parameter multiple times you can lookup multiple Users.

Using this parameter is mutually exclusive with the query and queryString fields and is not paginated or sorted using sortFields field.

Using this parameter will not hit the Elasticsearch index, instead it will cause users to be retrieved by Id only.

caution

This field supports a maximum of 10,000 values.

nextResults String optional Available since 1.48.0

The encoded token returned in the nextResults field of a previous search response. Providing this token will return a result set for the page following the last result from the previous search response.

This parameter can be used to successfully page past the max_result_window limitation.

This parameter cannot be used with the ids, query, queryString, or sortFields parameters. The startRow parameter must be 0 or omitted.

See Extended Pagination for more information.

numberOfResults Integer optional Defaults to 25

The number of search results to return. Used for pagination.

query String optional Available since 1.13.0

The raw JSON Elasticsearch query that is used to search for Users. The ids, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

It is necessary to use the query parameter when querying against registrations in order to achieve expected results, as this field is defined as a nested datatype in the Elasticsearch mapping.

queryString String optional

The Elasticsearch query string that is used to search for Users. The ids, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

The match is case-insensitive. Whitespace is allowed in the search, but must be URL escaped; for example, using %20 for a space character. Elasticsearch compatible regular expressions may be used, so you may search by prefix or suffix using the * wildcard.

You may search against specific fields like so: email:*fusionauth.io. This will match only users with a fusionauth.io email address. Here are the available fields for matching.

caution

FusionAuth adds wildcards to unscoped queryStrings in order to match the broadest set of results. Depending on the specifics of the system, a leading wildcard on a search term can significantly reduce search performance. In order to improve search performance, limit the search to a single field by specifying it in the queryString followed by a : to prevent the pre-processing by FusionAuth.

startRow Integer optional Defaults to 0

The start row within the search results to return. Used for pagination.

sortFields Array optional

An array of sort fields used to sort the result. The order the sort fields are provided will be maintained in the sorted output.

sortFields[x].missing String optional Defaults to _last

The value to substitute if this field is not defined. Two special values may be used:

_first When the field is not defined sort this record first.
_last When the field is not defined sort this record last.

sortFields[x].name String optional

The name of the field to sort.

Required if sortFields is provided.

Due to how the search index is structured not all fields on the user are sortable. The following field names are currently supported.

birthDate
email
fullName
id" since="1.13.0
insertInstant
lastLoginInstant" since="1.13.0
login
phoneNumber
registrations.applicationId
registrations.id
registrations.insertInstant
registrations.lastLoginInstant
registrations.roles
tenantId
username

sortFields[x].order String optional Defaults to asc

The order to sort the specified field. Possible values are:

asc
desc

Request Headers#

X-FusionAuth-TenantId String optional

The unique Id of the tenant used to scope this API request.

See Making an API request using a Tenant Id for additional information.

Search for Users using a JSON request body. This allows for larger requests than are possible using request parameters.

POST/api/user/search

OpenAPI Spec

Request Headers#

X-FusionAuth-TenantId String optional

The unique Id of the tenant used to scope this API request.

See Making an API request using a Tenant Id for additional information.

Request Body#

expand Array<String> optional Defaults to [memberships, registrations] Available since 1.48.0

For backwards compatibility, the default behavior will be to return both memberships and registrations.

search.accurateTotal Boolean optional Defaults to false Available since 1.24.0

Set this value equal to true to receive an accurate hit count on the API response.

If you are looking for an accurate user count that can exceed 10,000 matches, you will want to set this value equal to true.

search.ids Array<UUID> optional

A list of User Ids to retrieve. When using this parameter, the results are not paginated or sorted using the sortFields.

The search.ids, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

Using this parameter will not hit the Elasticsearch index, instead it will cause users to be retrieved by Id only.

search.nextResults String optional Available since 1.48.0

This parameter can be used to successfully page past the max_result_window limitation.

This parameter cannot be used with the ids, query, queryString, or sortFields parameters. The startRow parameter must be 0 or omitted.

See Extended Pagination for more information.

search.numberOfResults Integer optional Defaults to 25

The number of search results to return. Used for pagination.

search.query String optional Available since 1.13.0

The raw JSON Elasticsearch query that is used to search for Users. The ids, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

It is necessary to use the search.query parameter when querying against registrations in order to achieve expected results, as this field is defined as a nested datatype in the Elasticsearch mapping.

search.queryString String optional

The Elasticsearch query string that is used to search for Users. The ids, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

You may search against specific fields like so: email:*fusionauth.io. This will match only users with a fusionauth.io email address. Here are the available fields for matching.

caution

search.startRow Integer optional Defaults to 0

The start row within the search results to return. Used for pagination.

search.sortFields Array optional

An array of sort fields used to sort the result. The order the sort fields are provided will be maintained in the sorted output.

search.sortFields[x].missing String optional Defaults to _last

The value to substitute if this field is not defined. Two special values may be used:

_first When the field is not defined sort this record first.
_last When the field is not defined sort this record last.

search.sortFields[x].name String optional

The name of the field to sort.

Required if sortFields is provided.

Due to how the search index is structured not all fields on the user are sortable. The following field names are currently supported.

birthDate
email
fullName
id" since="1.13.0
insertInstant
lastLoginInstant" since="1.13.0
login
phoneNumber
registrations.applicationId
registrations.id
registrations.insertInstant
registrations.lastLoginInstant
registrations.roles
tenantId
username

search.sortFields[x].order String optional Defaults to asc

The order to sort the specified field. Possible values are:

asc
desc

Request Body Examples#

Search Using Ids#

Example Request JSON searching by ids

{
  "search": {
    "ids": [
      "a6e3ed2d-582b-4ec3-aa3f-4323c8f39fe9",
      "00000000-0000-0001-0000-000000000000"
    ]
  }
}

Search Using A Query String#

Example Request JSON searching by queryString for users with an email address matching a pattern

{
  "search": {
    "numberOfResults": 25,
    "queryString": "email:*@fusionauth.io",
    "sortFields": [
      {
        "missing": "_first",
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

Available since 1.59.0

Example Request JSON searching by queryString for users with a phone number matching a pattern

{
  "search": {
    "numberOfResults": 25,
    "queryString": "phoneNumber:303*",
    "sortFields": [
      {
        "missing": "_first",
        "name": "phoneNumber",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

Example Request JSON searching by queryString for users belonging to a specific group

{
  "search": {
    "numberOfResults": 25,
    "queryString": "memberships.groupId:7f318a9d-3de4-4ded-9b53-1d97fd730868",
    "sortFields": [
      {
        "missing": "_first",
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

Example Request JSON searching by queryString for users of a specific tenant. A global API key must be used, and you may not use the X-FusionAuth-TenantId header when the search parameters include tenantId

{
  "search": {
    "numberOfResults": 25,
    "queryString": "tenantId:39666465-6535-3731-3139-666363356438",
    "sortFields": [
      {
        "missing": "_first",
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

Example Request JSON searching by queryString for active users with a certain email address without MFA enabled

{
  "search": {
    "numberOfResults": 25,
    "queryString": "email:/.*example.com/ AND active:true AND !(_exists_:twoFactor)",
    "sortFields": [
      {
        "missing": "_first",
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

Search Using A Query#

Searches using query have two parts. You must build the JSON query parameter, then escape it and include it in a request.

A request includes not only a query, but also additional search parameters, such as sorting or pagination. For more, see the Searching Users With Elasticsearch guide.

Unverified Registrations#

To search for users with unverified Registrations for a specific Application, you'd use this JSON for the query:

Query JSON

{
  "bool": {
    "must": [
      {
        "nested": {
          "path": "registrations",
          "query": {
            "bool": {
              "must": [
                {
                  "match": {
                    "registrations.applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32"
                  }
                },
                {
                  "match": {
                    "registrations.verified": false
                  }
                }
              ]
            }
          }
        }
      }
    ]
  }
}

And then escape and include it in this request JSON:

Request JSON

{
  "search": {
    "numberOfResults": 25,
    "query": "{\"bool\":{\"must\":[{\"nested\":{\"path\":\"registrations\",\"query\":{\"bool\":{\"must\":[{\"match\":{\"registrations.applicationId\":\"3c219e58-ed0e-4b18-ad48-f4f92793ae32\"}},{\"match\":{\"registrations.verified\":false}}]}}}}]}}",
    "sortFields": [
      {
        "missing": "_first",
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

Specific Role#

To search for users with a Role in an Application, you'd use this JSON for the query:

Query JSON

{
  "bool": {
    "must": [
      [
        {
          "nested": {
            "path": "registrations",
            "query": {
              "bool": {
                "must": [
                  {
                    "match": {
                      "registrations.applicationId": "c50329fa-93e5-4618-8d9f-73d0ab069a54"
                    }
                  },
                  {
                    "match": {
                      "registrations.roles": "admin"
                    }
                  }
                ]
              }
            }
          }
        }
      ]
    ]
  }
}

And then escape and include it in this request JSON:

Request JSON

{
  "search": {
    "numberOfResults": 25,
    "query": "{\"bool\":{\"must\":[[{\"nested\":{\"path\":\"registrations\",\"query\":{\"bool\":{\"must\":[{\"match\":{\"registrations.applicationId\":\"c50329fa-93e5-4618-8d9f-73d0ab069a54\"}},{\"match\":{\"registrations.roles\":\"admin\"}}]}}}}]]}}",
    "sortFields": [
      {
        "missing": "_first",
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

Specific Email Address#

To search for users with a certain email address, you'd use this JSON for the query:

Query JSON

{
  "match": {
    "email": {
      "query": "dinesh@fusionauth.io"
    }
  }
}

And then escape and include it in this request JSON:

Request JSON

{
  "search": {
    "numberOfResults": 25,
    "query": "{\"match\":{\"email\":{\"query\":\"dinesh@fusionauth.io\"}}}",
    "sortFields": [
      {
        "missing": "_first",
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

Specific Phone Number#

Available since 1.59.0

To search for users with a certain phone number that:

Has any country code
Begins with the 303 area code
Has a local number portion beginning with 555

You'd use this JSON for the query:

Query JSON

{
  "wildcard": {
    "phoneNumber": {
      "value": "*(303) 555*"
    }
  }
}

And then escape and include it in this request JSON:

Request JSON

{
  "search": {
    "numberOfResults": 25,
    "query": "{\"wildcard\":{\"phoneNumber\":{\"value\":\"*(303) 555*\"}}}",
    "sortFields": [
      {
        "missing": "_first",
        "name": "phoneNumber",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

Boolean User Data Attribute#

To search for users with custom user data attribute of dataMigrated with a value equal to true, you'd use this JSON for the query:

Query JSON

{
  "match": {
    "data.userMigrated": {
      "query": "true"
    }
  }
}

And then escape and include it in this request JSON:

Request JSON

{
  "search": {
    "numberOfResults": 25,
    "query": "{\"match\":{\"data.userMigrated\":{\"query\":\"true\"}}}",
    "sortFields": [
      {
        "missing": "_first",
        "name": "email",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

Additional Query Examples#

Below are additional query examples. The request JSON, in which the query must be escaped and included, is omitted.

Example JSON for the query parameter to search for users with a price range in their registration data

{
  "bool": {
    "must": [
      {
        "nested": {
          "path": "registrations",
          "query": {
            "range": {
              "registrations.data.minprice": {
                "gte": 50000,
                "lte": 100000
              }
            }
          }
        }
      }
    ]
  }
}

Example JSON for the query parameter to search for users with any value for userMigrated

{
  "constant_score": {
    "filter": {
      "exists": {
        "field": "data.userMigrated"
      }
    }
  }
}

Example Request JSON searching by nextResults for users using a token returned in a previous search response

{
  "search": {
    "numberOfResults": 25,
    "nextResults": "eyJscyI6WyIxLjAwMTQ2MTkiLG51bGwsInRlc3R1c2VyOTkwOUBsb2NhbC5jb20iLCJjNmI4ZjQyNC0wOTRjLTQ1MWYtYWMxNS05Y2ZkODI3NTZlNGEiXSwicXMiOiIqIiwic2YiOltdfQ"
  }
}

Response#

The response contains the User objects that were found as part of the lookup or search. Both the database and Elasticsearch search engines return the response in the same format.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you requested doesn't exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body#

expandable Array<String> Available since 1.48.0

The available expandable properties that are not expanded in the response.

For example, if you set the expand request parameter to [registrations] then the value of this parameter in the response will be [memberships] indicating that the memberships property was not expanded.

nextResults String Available since 1.48.0

A token that can be used in subsequent search requests to page forward after the last result of the current response.

This value will not be returned when FusionAuth is configured to use the database search engine.

See Extended Pagination for more information.

total Long

The number of users that matched the search criteria. The number of results in the response will be equal to the numberOfResults provided on the request, if not provided the default number of results will be returned.

This value may cap out at 10,000 even if more users are found based upon the provided search query. Use the accurateTotal request parameter if you require this value to represent the actual number of matching users in the search index when your query may match more than 10,000 users.

users Array

The list of User objects.

users[x].active Boolean

True if the User is active. False if the User has been deactivated. Deactivated Users will not be able to log in.

users[x].birthDate String

The User's birthdate formatted as YYYY-MM-DD

users[x].breachedPasswordLastCheckedInstant Long

The instant this user's password was last checked to determine if it is compromised.

users[x].connectorId UUID Available since 1.18.0

The unique Id of the Connector associated with the System of Record being used to authenticate the user.

users[x].cleanSpeakId UUID

This Id is used by FusionAuth when the User's username is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak.

users[x].data Object

An object that can hold any information about the User that should be persisted.

users[x].data.email String

This field will be used as the email address if no users[x].email field is found.

This feature was removed in version 1.26.0 and added back in 1.27.2.

users[x].email String

The User's email address.

users[x].expiry Long

The expiration instant of the User's account. An expired user is not permitted to log in.

users[x].firstName String

The first name of the User.

users[x].fullName String

The User's full name as a separate field that is not calculated from firstName and lastName.

users[x].id UUID

The User's unique Id.

users[x].identities Array Available since 1.59.0

The list of identities that exist for a User.

users[x].identities[x].displayValue String Available since 1.59.0

The display value for the identity. Only used for username type identities. If the unique username feature is not enabled, this value will be the same as users[x].identities[x].value. Otherwise, it will be the username the User has chosen. For primary username identities, this will be the same value as users[x].username.

users[x].identities[x].insertInstant Long Available since 1.59.0

The instant when the identity was created.

users[x].identities[x].lastLoginInstant Long Available since 1.59.0

The instant when the identity was last used to log in. If a User has multiple identity types (username, email, and phoneNumber), then this value will represent the specific identity they last used to log in. This contrasts with users[x].lastLoginInstant, which represents the last time any of the User's identities was used to log in.

note

Identity provider logins will not be reflected here (see users[x].lastLoginInstant for a field that includes identity provider logins).

users[x].identities[x].lastUpdateInstant Long Available since 1.59.0

The instant when the identity was last updated.

users[x].identities[x].moderationStatus String Available since 1.59.0

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

ACTIVE - the username is active
PENDING - the username is pending approval/moderation
REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

Only used for username type identities. For primary username identities, this will be the same value as users[x].usernameStatus.

users[x].identities[x].type String Available since 1.59.0

The identity type. The possible values are:

email - identities defined by an email address
phoneNumber - identities defined by a phone number
username - identities defined by a username

users[x].identities[x].value String Available since 1.59.0

The value represented by the identity. The contents of this field depend on users[x].identities[x].typeand will be one of the following:

Email address - The User's email address, always lower cased. For primary email identities, this will be the same value as users[x].email
Phone number - The User's phone number, in E.164 canonical format. For primary phone number identities, this will be the same value as users[x].phoneNumber
Username - User's username - this will be the same as users[x].identities[x].displayValue. For primary username identities, this will be the same value as users[x].username

This value is unique within a tenant for a particular users[x].identities[x].type.

note

If the unique usernames feature is enabled, value will be the unique username (within the tenant). For primary username identities, this will also be the same value as users[x].uniqueUsername.

users[x].identities[x].verified Boolean Available since 1.59.0

Whether verification was actually performed on the identity by FusionAuth. This is used in combination with the users[x].identities[x].verifiedReason to decide whether an identity needs verification.

users[x].identities[x].verifiedInstant Long Available since 1.59.0

The instant when verification was performed on the identity. This field is only populated when verification was actually performed on the identity by FusionAuth.

users[x].identities[x].verifiedReason String Available since 1.59.0

The reason the User's identity was verified or not verified. The possible values are:

Skipped - Verification was skipped due to the skipVerification parameter on the request
Trusted - Identity was created via an identity provider or a connector
Unverifiable - FusionAuth doesn't know how to verify this identity type. Usernames are an example
Implicit - Verification was implicitly performed by sending a set password or passwordless message
Pending - Tenant policy requires verification but no verification has been performed yet
Completed - Verification was performed by FusionAuth
Disabled - Tenant policy did not require verification
Import - User was imported so verification was not performed by FusionAuth

If this field is Disabled, Import, Skipped, Trusted, or Unverifiable, then verification will not be required, regardless of the users[x].identities[x].verified value. For Implicit, Pending, or Completed, the identity will require verification if users[x].identities[x].verified is false.

users[x].imageUrl String

The URL that points to an image file that is the User's profile image.

users[x].insertInstant Long

The instant when the user was created.

users[x].lastLoginInstant Long

The instant when the User logged in last. See users[x].identities[x].lastLoginInstant for more granular information based on identity.

users[x].lastName String

The User's last name.

users[x].lastUpdateInstant Long

The instant when the User was last updated.

users[x].legacyIdentifier String Available since 1.67

Used to override the sub claim in tokens issued by the Legacy Identity Provider Adapter.

This value is immutable after the user is created and is unique within the tenant when non-null.

users[x].memberships Array

The list of memberships for the User.

users[x].memberships[x].data Object

An object that can hold any information about the User for this membership that should be persisted.

users[x].memberships[x].groupId UUID

The Id of the Group of this membership.

users[x].memberships[x].id UUID

The unique Id of this membership.

users[x].memberships[x].insertInstant Long

The instant that the membership was created.

users[x].middleName String

The User's middle name.

users[x].mobilePhone String

The User's mobile phone number. This is useful if you will be sending push notifications or SMS messages to the User.

note

This differs from users[x].phoneNumber and cannot be used to log in.

users[x].parentEmail String Available since 1.7.0

The email address of the user's parent or guardian. If this value was provided during a create or update operation, this value will only remain until the child is claimed by a parent.

users[x].passwordChangeRequired Boolean

Indicates that the User's password needs to be changed during their next login attempt.

users[x].passwordLastUpdateInstant Long

The instant that the User last changed their password.

note

Since version 1.59.0, if a user does not currently have a password, this field will not be returned in the response.

users[x].phoneNumber String Available since 1.59.0

The User's primary phone number. The phone number is stored and returned in E.164 canonical format, however a phone number is considered unique regardless of the format. 303-555-1212 is considered equal to +13035551212 so either version of this phone number can be used whenever providing it as input to an API.

note

This differs from users[x].mobilePhone in that users[x].phoneNumber can be used to log in, just like an email address or a username.

users[x].preferredLanguages Array<String>

An array of locale strings that give, in order, the User's preferred languages. These are important for email templates and other localizable text. See Locales.

users[x].registrations Array

The list of registrations for the User. This will include registrations for inactive applications.

users[x].registrations[x].applicationId UUID

The Id of the Application that this registration is for.

users[x].registrations[x].authenticationToken String

The Authentication Token for this registration (if one exists).

users[x].registrations[x].cleanSpeakId UUID

This Id is used by FusionAuth when the User's username for this registration is sent to CleanSpeak to be moderated (filtered and potentially sent to the approval queue). It is the content Id of the username inside CleanSpeak.

users[x].registrations[x].data Object

An object that can hold any information about the User for this registration that should be persisted.

users[x].registrations[x].id UUID

The Id of this registration.

users[x].registrations[x].insertInstant Long

The instant that this registration was created.

users[x].registrations[x].lastLoginInstant Long

The instant that the User last logged into the Application for this registration.

users[x].registrations[x].preferredLanguages Array<String>

An array of locale strings that give, in order, the User's preferred languages for this registration. These are important for email templates and other localizable text.

users[x].registrations[x].roles Array<String>

The list of roles that the User has for this registration. The string is the role's Name not the role's Id, e.g. admin or user-role.

users[x].registrations[x].timezone String

The User's preferred timezone for this registration. The string will be in an IANA time zone format.

users[x].registrations[x].tokens Map<String,String DEPRECATED

A map that contains tokens returned from identity providers.

For example, if this user has authenticated using the Facebook Identity Provider, the Facebook access token will be available in this map, keyed by name Facebook. For an OpenID Connect Identity provider, or other generic providers, if a token is stored it will be keyed by the Identity Provider unique Id.

Removed in 1.28.0

The token returned and stored from the Identity Provider is now stored in the IdP link and is retrievable using the Identity Provider Link API.

users[x].registrations[x].username String

The username of the User for this registration only. This is for display purposes and cannot be used to log in.

users[x].registrations[x].usernameStatus String

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

ACTIVE - the username is active
PENDING - the username is pending approval/moderation
REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

users[x].registrations[x].verified Boolean

This value indicates if this User's registration has been verified.

For additional information, see these tutorials:

users[x].registrations[x].verifiedInstant Long Available since 1.48.0

The instant that this registration was verified.

users[x].tenantId UUID

The Id of the Tenant that this User belongs to.

users[x].timezone String

The User's preferred timezone. This can be used as a default to display instants, and it is recommended that you allow Users to change this per-session. The string will be in an IANA time zone format.

users[x].twoFactor.methods[x].authenticator.algorithm String

The algorithm used by the TOTP authenticator. With the current implementation, this will always be HmacSHA1.

users[x].twoFactor.methods[x].authenticator.codeLength Integer

The length of code generated by the TOTP. With the current implementation, this will always be 6.

users[x].twoFactor.methods[x].authenticator.timeStep Integer

The time-step size in seconds. With the current implementation, this will always be 30.

users[x].twoFactor.methods[x].email String

The value of the email address for this method. Only present if users[x].twoFactor.methods[x].method is email.

users[x].twoFactor.methods[x].id String

The unique Id of the method.

users[x].twoFactor.methods[x].lastUsed Boolean

true if this method was used most recently.

users[x].twoFactor.methods[x].method String

The type of this method. There will also be an object with the same value containing additional information about this method. The possible values are:

authenticator
email
sms

users[x].twoFactor.methods[x].mobilePhone String

The value of the mobile phone for this method. Only present if users[x].twoFactor.methods[x].method is sms.

users[x].twoFactorDelivery String DEPRECATED

The User's preferred delivery for verification codes during a two-factor login request.

The possible values are:

None
TextMessage

Removed in 1.26.0

users[x].twoFactorEnabled Boolean DEPRECATED

Determines if the User has two-factor authentication enabled for their account or not.

Removed in 1.26.0

users[x].username String

The username of the User.

users[x].usernameStatus String

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

ACTIVE - the username is active
PENDING - the username is pending approval/moderation
REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

users[x].verified Boolean DEPRECATED

Whether or not the User's primary email identity has been verified. This does NOT indicate whether phone number identity types are verified.

For additional information, see these tutorials:

Deprecated since 1.59.0

See users[x].identities[x].verified and users[x].identities[x].verifiedReason.

users[x].verifiedInstant Long Available since 1.48.0

The first instant that the User's primary email address or phone number was verified. This value is immutable and cannot change for a user once set.

Example Search Results Response JSON

{
  "expandable": [],
  "nextResults": "eyJscyI6WyIxLjAwMTQ2MTkiLG51bGwsInRlc3R1c2VyOTkwOUBsb2NhbC5jb20iLCJjNmI4ZjQyNC0wOTRjLTQ1MWYtYWMxNS05Y2ZkODI3NTZlNGEiXSwicXMiOiIqIiwic2YiOltdfQ",
  "total": 1,
  "users": [
    {
      "active": true,
      "birthDate": "1976-05-30",
      "breachedPasswordLastCheckedInstant": 1471786483322,
      "breachedPasswordStatus": "None",
      "data": {
        "displayName": "Johnny Boy",
        "favoriteColors": [
          "Red",
          "Blue"
        ]
      },
      "email": "example@fusionauth.io",
      "expiry": 1571786483322,
      "firstName": "John",
      "fullName": "John Doe",
      "id": "00000000-0000-0001-0000-000000000000",
      "identities": [
        {
          "insertInstant": 1742936980069,
          "lastLoginInstant": 1742936980069,
          "lastUpdateInstant": 1742936980069,
          "primary": true,
          "type": "email",
          "value": "example@fusionauth.io",
          "verified": false,
          "verifiedReason": "Disabled"
        },
        {
          "insertInstant": 1742936980069,
          "lastLoginInstant": 1742936980069,
          "lastUpdateInstant": 1742936980069,
          "primary": true,
          "type": "phoneNumber",
          "value": "+13035551212",
          "verified": false,
          "verifiedReason": "Disabled"
        },
        {
          "displayValue": "johnny123",
          "insertInstant": 1742936980069,
          "lastLoginInstant": 1742936980069,
          "lastUpdateInstant": 1742936980069,
          "moderationStatus": "ACTIVE",
          "primary": true,
          "type": "username",
          "value": "johnny123",
          "verified": false,
          "verifiedReason": "Unverifiable"
        }
      ],
      "imageUrl": "http://65.media.tumblr.com/tumblr_l7dbl0MHbU1qz50x3o1_500.png",
      "insertInstant": 1742936980069,
      "lastLoginInstant": 1742936980069,
      "lastName": "Doe",
      "middleName": "William",
      "mobilePhone": "303-555-1234",
      "passwordChangeRequired": false,
      "passwordLastUpdateInstant": 1742936980069,
      "phoneNumber": "+13035551212",
      "preferredLanguages": [
        "en",
        "fr"
      ],
      "registrations": [
        {
          "applicationId": "10000000-0000-0002-0000-000000000001",
          "data": {
            "displayName": "Johnny",
            "favoriteSports": [
              "Football",
              "Basketball"
            ]
          },
          "id": "00000000-0000-0002-0000-000000000000",
          "insertInstant": 1742936980069,
          "lastLoginInstant": 1742936980069,
          "preferredLanguages": [
            "en",
            "fr"
          ],
          "roles": [
            "user",
            "community_helper"
          ],
          "username": "johnny123",
          "usernameStatus": "ACTIVE",
          "verified": true,
          "verifiedInstant": 1742936980069
        }
      ],
      "timezone": "America/Denver",
      "tenantId": "f24aca2b-ce4a-4dad-951a-c9d690e71415",
      "twoFactor": {
        "methods": [
          {
            "authenticator": {
              "algorithm": "HmacSHA1",
              "codeLength": 6,
              "timeStep": 30
            },
            "id": "35VW",
            "method": "authenticator"
          },
          {
            "id": "V7SH",
            "method": "sms",
            "mobilePhone": "555-555-5555"
          },
          {
            "email": "example@fusionauth.io",
            "id": "7K2G",
            "method": "email"
          }
        ]
      },
      "usernameStatus": "ACTIVE",
      "username": "johnny123",
      "verified": true,
      "verifiedInstant": 1742936980069
    }
  ]
}