User Search Query Syntax
When searching for users, you can create queries using Lucene query syntax to refine your search.
The query string is parsed into a series of terms and operators:
A term can be a single word such as
jane
orsmith
.A term can be a phrase surrounded by double quotes (
"green apple"
), which will match all words in the phrase in the same order.A term without a field name will not match text in the user metadata fields.
Multiple terms can be grouped together with parentheses to form sub-queries.
Search values for the normalized user fields (
email
,name
,given_name
,family_name
, andnickname
) are case insensitive. All other fields (including allapp_metadata
/user_metadata
fields) are case sensitive.Operators (
AND
,OR
,NOT
) work on all normalized user fields and root metadata fields.
Searchable fields
You can search for users using all the normalized user profile fields and the fields below:
Search Field | Data Type | Description |
---|---|---|
phone_number |
text | The user's phone number. Only valid for users with SMS connections. |
phone_verified |
boolean | The true/false value indicating whether the user's phone number has been verified. Only valid for users with SMS connections. |
logins_count |
integer | The number of times the user has logged in. If a user is blocked and logs in, the blocked session is counted in logins_count and updates the last_login value. |
created_at |
date time | The timestamp of when the user profile was first created. |
updated_at |
date time | The timestamp of when the user's profile was last updated/modified. |
last_login |
date time | The timestamp of when the user last logged in. In case you are this property from inside a Rule using the user object, its value will be the one associated with the login that triggered the rule (since rules execute after the actual login). |
last_ip |
text (valid IP address) | The IP address associated with the user's last login. |
blocked |
boolean | The true or false value indicating if the user has been blocked. Note: true only brings back users who are blocked via the Admin Dashboard and Management API; it does not bring back users blocked by brute force anomaly detection. |
email.domain |
text | The domain part of the user's email. |
Metadata fields may be used with:
Boolean
Numeric: (integer or double)
Text
Objects: In order to search a scalar value nested in another object, use the path to the field. For example,
app_metadata.subscription.plan:"gold"
Arrays: In order to search fields in objects nested arrays, use the path to the field and ignore the array level. For example,
user_metadata.addresses.city:"Paris"
Range and wildcard searches are not available on user metadata fields.
Exact match
To find exact matches, use double quotes: name:"jane smith"
.
For example, to find users with the name jane smith
, use q=name:"jane smith"
:
curl --request GET \
--url 'https://YOUR_DOMAIN/api/v2/users?q=name%3A%22jane%20smith%22&search_engine=v3' \
--header 'authorization: Bearer YOUR_MGMT_API_ACCESS_TOKEN'
var client = new RestClient("https://YOUR_DOMAIN/api/v2/users?q=name%3A%22jane%20smith%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=name%3A%22jane%20smith%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=name%3A%22jane%20smith%22&search_engine=v3")
.header("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")
.asString();
var axios = require("axios").default;
var options = {
method: 'GET',
url: 'https://YOUR_DOMAIN/api/v2/users',
params: {q: 'name:"jane smith"', search_engine: 'v3'},
headers: {authorization: 'Bearer YOUR_MGMT_API_ACCESS_TOKEN'}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});
#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=name%3A%22jane%20smith%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, [
CURLOPT_URL => "https://YOUR_DOMAIN/api/v2/users?q=name%3A%22jane%20smith%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 => [
"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=name%3A%22jane%20smith%22&search_engine=v3", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
require 'uri'
require 'net/http'
require 'openssl'
url = URI("https://YOUR_DOMAIN/api/v2/users?q=name%3A%22jane%20smith%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"]
let request = NSMutableURLRequest(url: NSURL(string: "https://YOUR_DOMAIN/api/v2/users?q=name%3A%22jane%20smith%22&search_engine=v3")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
Wildcards
Wildcard searches can be run on terms using the asterisk character (*
) to replace zero or more characters. Wildcard searches are not available on user metadata fields.
Here are some examples:
name:john*
returns all users withjohn
at the beginning of their names.name:j*
returns all users withj
at the beginning of their names.q=name:john*
returns all users whose names start withjohn
.For suffix matching, literals must have 3 characters or more. For example,
name:*usa
is allowed, butname:*sa
is not.
curl --request GET \
--url 'https://YOUR_DOMAIN/api/v2/users?q=name%3Ajohn*&search_engine=v3' \
--header 'authorization: Bearer YOUR_MGMT_API_ACCESS_TOKEN'
var client = new RestClient("https://YOUR_DOMAIN/api/v2/users?q=name%3Ajohn*&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=name%3Ajohn*&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=name%3Ajohn*&search_engine=v3")
.header("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")
.asString();
var axios = require("axios").default;
var options = {
method: 'GET',
url: 'https://YOUR_DOMAIN/api/v2/users',
params: {q: 'name:john*', search_engine: 'v3'},
headers: {authorization: 'Bearer YOUR_MGMT_API_ACCESS_TOKEN'}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});
#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=name%3Ajohn*&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, [
CURLOPT_URL => "https://YOUR_DOMAIN/api/v2/users?q=name%3Ajohn*&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 => [
"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=name%3Ajohn*&search_engine=v3", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
require 'uri'
require 'net/http'
require 'openssl'
url = URI("https://YOUR_DOMAIN/api/v2/users?q=name%3Ajohn*&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"]
let request = NSMutableURLRequest(url: NSURL(string: "https://YOUR_DOMAIN/api/v2/users?q=name%3Ajohn*&search_engine=v3")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
Ranges
You can use ranges in your user search queries. Range searches are not available on user metadata fields.
For inclusive ranges use square brackets:
[min TO max]
.For exclusive ranges use curly brackets:
{min TO max}
.Curly and square brackets can be combined in the same range expression:
logins_count:[100 TO 200}
.Use ranges in combination with wildcards. For example, to find all users with more than 100 logins, use
q=logins_count:{100 TO *]
.
curl --request GET \
--url 'https://YOUR_DOMAIN/api/v2/users?q=logins_count%3A%7B100%20TO%20*%5D&search_engine=v3' \
--header 'authorization: Bearer YOUR_MGMT_API_ACCESS_TOKEN'
var client = new RestClient("https://YOUR_DOMAIN/api/v2/users?q=logins_count%3A%7B100%20TO%20*%5D&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=logins_count%3A%7B100%20TO%20*%5D&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=logins_count%3A%7B100%20TO%20*%5D&search_engine=v3")
.header("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")
.asString();
var axios = require("axios").default;
var options = {
method: 'GET',
url: 'https://YOUR_DOMAIN/api/v2/users',
params: {q: 'logins_count:{100 TO *]', search_engine: 'v3'},
headers: {authorization: 'Bearer YOUR_MGMT_API_ACCESS_TOKEN'}
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});
#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=logins_count%3A%7B100%20TO%20*%5D&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, [
CURLOPT_URL => "https://YOUR_DOMAIN/api/v2/users?q=logins_count%3A%7B100%20TO%20*%5D&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 => [
"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=logins_count%3A%7B100%20TO%20*%5D&search_engine=v3", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
require 'uri'
require 'net/http'
require 'openssl'
url = URI("https://YOUR_DOMAIN/api/v2/users?q=logins_count%3A%7B100%20TO%20*%5D&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"]
let request = NSMutableURLRequest(url: NSURL(string: "https://YOUR_DOMAIN/api/v2/users?q=logins_count%3A%7B100%20TO%20*%5D&search_engine=v3")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()