Docs

Retrieve Users with the Get Users Endpoint

Versionv3

The 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.

Prerequisite

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 v3.

Example request

For example, to search for a user whose email is exactly jane@exampleco.com, use q=email:"jane@exampleco.com":


curl --request GET \
  --url 'https://YOUR_DOMAIN/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3' \
  --header 'authorization: Bearer YOUR_MGMT_API_ACCESS_TOKEN'
var client = new RestClient("https://YOUR_DOMAIN/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN");
IRestResponse response = client.Execute(request);
package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://YOUR_DOMAIN/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://YOUR_DOMAIN/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3")
  .header("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")
  .asString();
var request = require("request");

var options = { method: 'GET',
  url: 'https://YOUR_DOMAIN/api/v2/users',
  qs: { q: 'email:"jane@exampleco.com"', search_engine: 'v3' },
  headers: { authorization: 'Bearer YOUR_MGMT_API_ACCESS_TOKEN' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_MGMT_API_ACCESS_TOKEN" };

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://YOUR_DOMAIN/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3"]
                                                       cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                   timeoutInterval:10.0];
[request setHTTPMethod:@"GET"];
[request setAllHTTPHeaderFields:headers];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                            completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                                                if (error) {
                                                    NSLog(@"%@", error);
                                                } else {
                                                    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
                                                    NSLog(@"%@", httpResponse);
                                                }
                                            }];
[dataTask resume];
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://YOUR_DOMAIN/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "authorization: Bearer YOUR_MGMT_API_ACCESS_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
import http.client

conn = http.client.HTTPSConnection("")

headers = { 'authorization': "Bearer YOUR_MGMT_API_ACCESS_TOKEN" }

conn.request("GET", "/YOUR_DOMAIN/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
require 'uri'
require 'net/http'

url = URI("https://YOUR_DOMAIN/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Bearer YOUR_MGMT_API_ACCESS_TOKEN'

response = http.request(request)
puts response.read_body
import Foundation

let headers = ["authorization": "Bearer YOUR_MGMT_API_ACCESS_TOKEN"]

var request = NSMutableURLRequest(URL: NSURL(string: "https://YOUR_DOMAIN/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3")!,
                                        cachePolicy: .UseProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.HTTPMethod = "GET"
request.allHTTPHeaderFields = headers

let session = NSURLSession.sharedSession()
let dataTask = session.dataTaskWithRequest(request, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    println(error)
  } else {
    let httpResponse = response as? NSHTTPURLResponse
    println(httpResponse)
  }
})

dataTask.resume()

For more information on other available parameters, check out the Management API Explorer documentation.

Sample queries

Below are some examples to show the kinds of queries you can make with the Management API.

Use case Query
Search for all users whose name contains "john" name:*john*
Search all users whose name is exactly "jane" name:"jane"
Search for all user names starting with "john" name:john*
Search for user names that start with "jane" and end with "smith" name:jane*smith
Search for all users whose email is exactly "john@exampleco.com" email:"john@exampleco.com"
Search for all users whose email is exactly "john@exampleco.com" or "jane@exampleco.com" using OR email:("john@exampleco.com" OR "jane@exampleco.com")
Search for users without verified email email_verified:false OR NOT _exists_:email_verified
Search for users who have the user_metadata field named full_name with the value of "John Smith" user_metadata.full_name:"John Smith"
Search for users from a specific connection identities.connection:"google-oauth2"
Search for all users that have never logged in (NOT _exists_:logins_count OR logins_count:0)
Search for all users who logged in before 2018 last_login:[* TO 2017-12-31]
Search for all users whose last login was in December 2017 last_login:{2017-11 TO 2017-12], last_login:[2017-12-01 TO 2017-12-31]
Search for all users with logins count >= 100 and <= 200 logins_count:[100 TO 200]
Search for all users with logins count >= 100 logins_count:[100 TO *]
Search for all users with logins count > 100 and < 200 logins_count:{100 TO 200}
Search for all users whose email domain is "exampleco.com" email.domain:"exampleco.com"

Sample results

Successful calls to the endpoint return a JSON object similar to the following:

[
  {
    "email": "john.doe@gmail.com",
    "email_verified": false,
    "username": "johndoe",
    "phone_number": "+199999999999999",
    "phone_verified": false,
    "user_id": "usr_5457edea1b8f33391a000004",
    "created_at": "",
    "updated_at": "",
    "identities": [
      {
        "connection": "Initial-Connection",
        "user_id": "5457edea1b8f22891a000004",
        "provider": "auth0",
        "isSocial": false
      }
    ],
    "app_metadata": {},
    "user_metadata": {},
    "picture": "",
    "name": "",
    "nickname": "",
    "multifactor": [
      ""
    ],
    "last_ip": "",
    "last_login": "",
    "logins_count": 0,
    "blocked": false,
    "given_name": "",
    "family_name": ""
  }
]

Limitations

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:

Keep reading