Retrieve Users with the Get Users Endpoint
GET /api/v2/users endpoint allows you to retrieve a list of users. Using this endpoint, you can:
- Search based on a variety of criteria
- Select the fields to be returned
- Sort the returned results
This endpoint is eventually consistent, and as such, we recommend that you use this endpoint for back office processes such as changing the display name of an existing user.
To use the user search endpoints, you'll need to obtain a valid Access Token and provide it in the header of your call (replace the
YOUR_MGMT_API_ACCESS_TOKEN placeholder value).
Search for users
To search for users, make a
GET request to the /api/v2/users endpoint. Pass your search query to the
q parameter and set the
search_engine parameter to
For example, to search for a user whose email is exactly
For more information on other available parameters, check out the Management API Explorer documentation.
Below are some examples to show the kinds of queries you can make with the Management API.
|Search for all users whose name contains "john"||
|Search all users whose name is exactly "jane"||
|Search for all user names starting with "john"||
|Search for user names that start with "jane" and end with "smith"||
|Search for all users whose email is exactly "firstname.lastname@example.org"||
|Search for all users whose email is exactly "email@example.com" or "firstname.lastname@example.org" using
|Search for users without verified email||
|Search for users who have the
|Search for users from a specific connection||
|Search for all users that have never logged in||
|Search for all users who logged in before 2018||
|Search for all users whose last login was in December 2017||
|Search for all users with logins count >= 100 and <= 200||
|Search for all users with logins count >= 100||
|Search for all users with logins count > 100 and < 200||
|Search for all users whose email domain is "exampleco.com"||
Successful calls to the endpoint return a JSON object similar to the following:
This endpoint allows you to retrieve a maximum of 1000 users. If your results exceed this threshold, redefine your search. If you need a complete export of all of your users, instead use the export job or the User Import / Export extension.
If you get the error
414 Request-URI Too Large this means that your query string is larger than the supported length. In this case, refine your search.
We do not recommend that you use this endpoint for:
- Operations that require immediate consistency. Instead, use the Get Users by Email endpoint or the Get Users by ID endpoint.
- User exports. Instead, use the User Export endpoint.
- Operations that require user search as part of authentication processes. Instead, use the Get Users by Email endpoint or the Get Users by ID endpoint.
- Searching for Users for Account Linking by Email. Instead, use the Get Users by Email endpoint.