Search for users

You can search for users matching certain attributes with the users.list method of the Directory API. This method accepts the query parameter which is a search query combining one or more search clauses. Each search clause is made up of three parts:

Field
User attribute that is searched. For example, givenName.
Operator
Test that is performed on the data to provide a match. For example, the : operator tests if a text attribute contains a value.
Value
The content of the attribute that is tested. For example, Jane.

Multiple clauses are separated by whitespace and are implicitly joined by an AND operator.

Fields

Field Value Type Operators Description
None specified string Compares against the value in givenName, familyName, or email.
name string =, : The concatenated value of givenName and familyName.
email string =, :, :{PREFIX}* The user's email addresses, including aliases.
givenName string =, :, :{PREFIX}* A user's given or first name.
familyName string =, :, :{PREFIX}* A user's family or last name.
isAdmin boolean = Whether a user has super adminstrator privileges.
isDelegatedAdmin boolean = Whether a user has delegated administrator privileges.
isSuspended boolean = Whether a user's account is suspended.
im string =, : IM network ID.
externalId string =, : External ID value.
manager string = The email address of a user's manager either directly or up the management chain.
managerId string = The ID of of a user's manager either directly or up the management chain.
directManager string = The email address of a user's direct manager.
directManagerId string = The ID of a user's direct manager.
address string : Matches all address fields.
addressPoBox string =, : A post office box.
addressExtended string =, : An extended address, such as one including a sub-region.
addressStreet string =, : A street address.
addressLocality string =, : A town or city of the an address.
addressRegion string =, : An abbreviated province or state.
addressPostalCode string =, : A ZIP or postal code.
addressCountry string =, : A country.
orgName string =, : An organization name.
orgTitle string =, : A user's title within the organization.
orgDepartment string =, : A department within the organization.
orgDescription string =, : An organization's description.
orgCostCenter string =, : The cost center of an organization.
phone string = A user's phone number.
orgUnitPath string = The full path of an org unit. This matches all org unit chains under the target. For example, 'orgUnitPath=/' returns all users in the organization.
isEnrolledIn2Sv boolean = Whether a user is enrolled in 2-step verification.
isEnforcedIn2Sv boolean = Whether 2-step verification is enforced for the user.
schemaName.fieldName ? ? A custom user attibute, referenced by it's schema and field name. The field must have its indexed property set to true.

Value Types

Value Type Equivalent Schema fieldType Notes
string STRING, EMAIL, PHONE Surround with single quotes ' if the query contains whitespace. Escape single quotes in queries with \', for example 'Valentine\'s Day'.
boolean BOOL Must have a value of true or false. Only supports the = operator.
number INT64, DOUBLE Must use a period as a decimal separator and no thousands seperator, for example 150430.25.
date DATE Specified in YYYY-MM-DD format, for example 2001-02-15.

Operators

Operator Supported Value Types Notes
= string, boolean, number, date The field and the value match exactly. For example, givenName=Jane matches all users with the givenName attribute "Jane", but not "Jane Ann". Supported on most string fields (see above).
: string The field contains the whole words within the value, in order. For example, a query with givenName:Jane matches users with givenName values of "Jane" and "Jane Ann", but not "Janet". A multi-word query for 'givenName:Mary Ann' would match values of "Mary Ann Evans" and "Sarah Mary Ann" but not "Ann Mary". Supported on most string fields (see above).
:{PREFIX}* string The field starts with the value. For example, a query with givenName:Jane* matches users with givenName values of "Jane", "Jane Ann", and "Janet" but not "Sarah Jane". Only supported on a limited set of string fields (see above). Not supported on custom attributes.
:[{MIN},{MAX}] number, date The field is within a range. To match, the field's value must be greater than or equal to {MIN} and less than {MAX}. Custom number attributes must specify a numericIndexingSpec in order to support this operator.
> number, date The field is greater than the value. Custom number attributes must specify a numericIndexingSpec in order to support this operator.
>= number, date The field is greater than or equal to the value. Custom number attributes must specify a numericIndexingSpec in order to support this operator.
< number, date The field is less than the value. Custom number attributes must specify a numericIndexingSpec in order to support this operator.
<= number, date The field is less than or equal to the value. Custom number attributes must specify a numericIndexingSpec in order to support this operator.

Examples

All queries use the users.list method, which has an HTTP request similar to the following (line breaks included for readability):

GET https://www.googleapis.com/admin/directory/v1/users
?domain=primary domain
&query=query parameters

The query parameters must be URL encoded. For example, the query query=givenName:Jane* is URL encoded as query=givenName%3AJane*. All examples on this page show unencoded query parameters. Client libraries handle this URL encoding automatically.

Search for a user by name

name='Jane Smith'

Search for users with a givenName OR familyName that contains a value

name:'Jane'

Search for users matching an email prefix

email:admin*

Search for all super administrators

isAdmin=true

Search for users with orgTitles containing Manager

orgTitle:Manager

Search for users with a common manager in their reporting chain

manager='janesmith@example.com'

Search for users with the same direct manager

directManager='bobjones@example.com'

Search for users in a given country

addressCountry='Sweden'

Search for users in a specific organization

orgName='Human Resources'

Search for managers in a specific organization

orgName=Engineering orgTitle:Manager

Search custom user attributes

Search for all employees that work on a specific project

EmploymentData.projects:'GeneGnomes'

Search for all employees in a specific location

EmploymentData.location='Atlanta'

Search for all employees above job level 7

EmploymentData.jobLevel>=7

Search for all employees with job levels that are >= 5 and < 8

EmploymentData.jobLevel:[5,8]

Search for all employees who are enrolled in 2-step verification

isEnrolledIn2Sv=true

Search for all employees who have 2-step verification enforced

isEnforcedIn2Sv=true

Send feedback about...

Directory API
Directory API