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
3 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.
To search multiple fields in a query, add each search clause, separated by a
space. The operation is an implicit AND
.
Fields
| Field | Value Type | Operators | Description |
|---|---|---|---|
|
None specified
|
string | Compare 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 administrator privileges. |
isDelegatedAdmin
|
boolean | =
|
Whether a user has delegated administrator privileges. |
isSuspended
|
boolean | =
|
Whether a user's account is suspended. |
isArchived
|
boolean | =
|
Whether a user's account is archived. |
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 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 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. This field can only be used when viewType=admin_view
. |
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 attribute
, referenced by its 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 separator, 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://admin.googleapis.com/admin/directory/v1/users?domain= DOMAIN_NAME
&query= QUERY_PARAMETERS
Search for a user by name
The name
query field tests on the concatenated value of givenName
and familyName
. A query for name='Jane'
returns no results for a user with givenName='Jane'
and familyName='Smith'
.
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 vVerification
isEnrolledIn2Sv=true
Search for all employees who have 2-Step Verification enforced
isEnforcedIn2Sv=true
