> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt)

# Search for Users

API documentation for the FusionAuth Search for Users API.

# Search for Users

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](https://fusionauth.io/docs/get-started/core-concepts/users.md#user-search).

## 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](https://fusionauth.io/docs/get-started/core-concepts/users.md#database-search-engine).

version

Available Since Version 1.16.0

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Search for Users by Id

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

OpenAPI Spec

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Search for Users by a query string

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

OpenAPI Spec

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

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`BooleanoptionalDefaults to falseAvailable 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>optionalDefaults 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`UUIDoptional

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.

`numberOfResults`IntegeroptionalDefaults to 25

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

`queryString`Stringoptional

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`IntegeroptionalDefaults to 0

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

`sortFields`Arrayoptional

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`Stringrequired

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`StringoptionalDefaults to asc

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

*   `asc`
*   `desc`

#### Request Headers

`X-FusionAuth-TenantId`Stringoptional

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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information.

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

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`Stringoptional

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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information.

### Request Body

`expand`Array<String>optionalDefaults 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 `[]`.

`search.accurateTotal`BooleanoptionalDefaults to falseAvailable 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`.

`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`IntegeroptionalDefaults to 25

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

`search.queryString`Stringoptional

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.

`search.startRow`IntegeroptionalDefaults to 0

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

`search.sortFields`Arrayoptional

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`Stringrequired

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`StringoptionalDefaults to asc

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

*   `asc`
*   `desc`

#### Request Body Examples

*Example Request JSON searching by ids*

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

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

```json
{
  "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.*

```json
{
  "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.*

```json
{
  "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.*

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

## Elasticsearch Search Engine

The Elasticsearch engine has [advanced querying capabilities and better performance](https://fusionauth.io/docs/get-started/core-concepts/users.md#elasticsearch-search-engine). You can also review the [Elasticsearch search guide](https://fusionauth.io/docs/lifecycle/manage-users/search/user-search-with-elasticsearch.md) for more examples.

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Search for Users by Id

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

OpenAPI Spec

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Search for Users by a query string

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

OpenAPI Spec

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

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

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Search for Users by a raw JSON query

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

OpenAPI Spec

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Search for Users with a nextResults token

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

OpenAPI Spec

### Request Parameters

`accurateTotal`BooleanoptionalDefaults to falseAvailable 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>optionalDefaults 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`UUIDoptional

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.

`nextResults`StringoptionalAvailable 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](https://fusionauth.io/docs/lifecycle/manage-users/search.md#extended-pagination) for more information.

`numberOfResults`IntegeroptionalDefaults to 25

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

`query`StringoptionalAvailable 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](https://www.elastic.co/guide/en/elasticsearch/reference/6.3/nested.html) in the Elasticsearch mapping.

`queryString`Stringoptional

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](https://fusionauth.io/docs/reference/user-fields.md).

caution

FusionAuth adds wildcards to unscoped `queryString`s 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`IntegeroptionalDefaults to 0

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

`sortFields`Arrayoptional

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`StringoptionalDefaults 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`Stringoptional

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`StringoptionalDefaults to asc

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

*   `asc`
*   `desc`

#### Request Headers

`X-FusionAuth-TenantId`Stringoptional

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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information.

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

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`Stringoptional

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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information.

### Request Body

`expand`Array<String>optionalDefaults 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 `[]`.

`search.accurateTotal`BooleanoptionalDefaults to falseAvailable 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`.

`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`StringoptionalAvailable 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](https://fusionauth.io/docs/lifecycle/manage-users/search.md#extended-pagination) for more information.

`search.numberOfResults`IntegeroptionalDefaults to 25

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

`search.query`StringoptionalAvailable 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](https://www.elastic.co/guide/en/elasticsearch/reference/6.3/nested.html) in the Elasticsearch mapping.

`search.queryString`Stringoptional

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](https://fusionauth.io/docs/reference/user-fields.md).

caution

FusionAuth adds wildcards to unscoped `queryString`s 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.

`search.startRow`IntegeroptionalDefaults to 0

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

`search.sortFields`Arrayoptional

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`StringoptionalDefaults 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`Stringoptional

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`StringoptionalDefaults 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*

```json
{
  "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*

```json
{
  "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*

```json
{
  "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*

```json
{
  "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*

```json
{
  "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*

```json
{
  "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](https://fusionauth.io/docs/lifecycle/manage-users/search/user-search-with-elasticsearch.md) guide.

###### Unverified Registrations

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

*Query JSON*

```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*

```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*

```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*

```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*

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

And then escape and include it in this request JSON:

*Request JSON*

```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*

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

And then escape and include it in this request JSON:

*Request JSON*

```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*

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

And then escape and include it in this request JSON:

*Request JSON*

```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*

```json
{
  "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*

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

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

```json
{
  "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](https://fusionauth.io/docs/apis/errors.md) 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](https://fusionauth.io/docs/apis/authentication.md). |
| 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`StringAvailable 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](https://fusionauth.io/docs/lifecycle/manage-users/search.md#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](https://fusionauth.io/docs/reference/data-types.md#instants) this user's password was last checked to determine if it is compromised.

`users[x].connectorId`UUIDAvailable since 1.18.0

The unique Id of the [Connector](https://fusionauth.io/docs/lifecycle/migrate-users/connectors.md) 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](https://fusionauth.io/docs/reference/data-types.md#instants) 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`ArrayAvailable since 1.59.0

The list of identities that exist for a User.

`users[x].identities[x].displayValue`StringAvailable 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`LongAvailable since 1.59.0

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the identity was created.

`users[x].identities[x].lastLoginInstant`LongAvailable since 1.59.0

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) 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`LongAvailable since 1.59.0

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the identity was last updated.

`users[x].identities[x].moderationStatus`StringAvailable 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`StringAvailable 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`StringAvailable since 1.59.0

The value represented by the identity. The contents of this field depend on **users\[x\].identities\[x\].type**and 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`BooleanAvailable 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`LongAvailable since 1.59.0

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) 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`StringAvailable 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](https://fusionauth.io/docs/reference/data-types.md#instants) when the user was created.

`users[x].lastLoginInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) 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](https://fusionauth.io/docs/reference/data-types.md#instants) when the User was last updated.

`users[x].legacyIdentifier`StringAvailable 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](https://fusionauth.io/docs/reference/data-types.md#instants) 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`StringAvailable 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](https://fusionauth.io/docs/reference/data-types.md#instants) 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`StringAvailable 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](https://fusionauth.io/docs/reference/data-types.md#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](https://fusionauth.io/docs/reference/data-types.md#instants) that this registration was created.

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

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) 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](https://www.iana.org/time-zones) time zone format.

`users[x].registrations[x].tokens`Map<String,StringDEPRECATED

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](https://fusionauth.io/docs/apis/identity-providers/links.md).

`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:

*   [Email Verification](https://fusionauth.io/docs/lifecycle/manage-users/verification/gate-accounts-until-user-email-verified.md)
*   [Registration Verification](https://fusionauth.io/docs/lifecycle/manage-users/verification/registration-gate-accounts-until-verified.md)

`users[x].registrations[x].verifiedInstant`LongAvailable since 1.48.0

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) 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](https://www.iana.org/time-zones) 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`StringDEPRECATED

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`BooleanDEPRECATED

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`BooleanDEPRECATED

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:

*   [Email Verification](https://fusionauth.io/docs/lifecycle/manage-users/verification/gate-accounts-until-user-email-verified.md)
*   [Registration Verification](https://fusionauth.io/docs/lifecycle/manage-users/verification/registration-gate-accounts-until-verified.md)

Deprecated since 1.59.0

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

`users[x].verifiedInstant`LongAvailable since 1.48.0

The first [instant](https://fusionauth.io/docs/reference/data-types.md#instants) 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*

```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
    }
  ]
}
```