REST Resource: users

Resource: User

The Directory API allows you to create and manage your account's users, user aliases, and user Google profile photos. For more information about common tasks, see the User Accounts Developer's Guide and the User Aliases Developer's Guide.

JSON representation 
{
  "id": string,
  "primaryEmail": string,
  "password": value,
  "hashFunction": string,
  "isAdmin": boolean,
  "isDelegatedAdmin": boolean,
  "agreedToTerms": boolean,
  "suspended": boolean,
  "changePasswordAtNextLogin": boolean,
  "ipWhitelisted": boolean,
  "name": {
    object (UserName)
  },
  "kind": string,
  "etag": string,
  "emails": value,
  "externalIds": value,
  "relations": value,
  "aliases": [
    string
  ],
  "isMailboxSetup": boolean,
  "customerId": string,
  "addresses": value,
  "organizations": value,
  "lastLoginTime": string,
  "phones": value,
  "suspensionReason": string,
  "thumbnailPhotoUrl": string,
  "languages": value,
  "posixAccounts": value,
  "creationTime": string,
  "nonEditableAliases": [
    string
  ],
  "sshPublicKeys": value,
  "notes": value,
  "websites": value,
  "locations": value,
  "includeInGlobalAddressList": boolean,
  "keywords": value,
  "deletionTime": string,
  "gender": value,
  "thumbnailPhotoEtag": string,
  "ims": value,
  "customSchemas": value,
  "isEnrolledIn2Sv": boolean,
  "isEnforcedIn2Sv": boolean,
  "archived": boolean,
  "orgUnitPath": string,
  "recoveryEmail": string,
  "recoveryPhone": string
}
Fields
id

string

The unique ID for the user. A user id can be used as a user request URI's userKey.
primaryEmail

string

The user's primary email address. This property is required in a request to create a user account. The primaryEmail must be unique and cannot be an alias of another user.
password

value (Value format)

Stores the password for the user account. The user's password value is required when creating a user account. It's optional when updating a user and should only be provided if the user is updating their account password. The password value is never returned in the API's response body.

A password can contain any combination of ASCII characters, and must be between 8-100 characters.

We recommend sending the password parameter as a hexadecimal-encoded hash value and setting hashFunction accordingly. If hashFunction is specified, the password must be a valid hash key.
hashFunction

string

Stores the hash format of the password property. The following hashFunction values are allowed:

  • MD5 - Accepts simple hex-encoded values.
  • SHA-1 - Accepts simple hex-encoded values.
  • crypt - Compliant with the C crypt library. Supports the DES, MD5 (hash prefix $1$), SHA-256 (hash prefix $5$), and SHA-512 (hash prefix $6$) hash algorithms.

If rounds are specified as part of the prefix, they must be 10,000 or fewer.
isAdmin

boolean

Output only. Indicates a user with super admininistrator privileges. The isAdmin property can only be edited in the Make a user an administrator operation ( makeAdmin method). If edited in the user insert or update methods, the edit is ignored by the API service.
isDelegatedAdmin

boolean

Output only. Indicates if the user is a delegated administrator.
Delegated administrators are supported by the API but cannot create or undelete users, or make users administrators. These requests are ignored by the API service.
Roles and privileges for administrators are assigned using the Admin console.
agreedToTerms

boolean

Output only. This property is true if the user has completed an initial login and accepted the Terms of Service agreement.
suspended

boolean

Indicates if user is suspended.
changePasswordAtNextLogin

boolean

Indicates if the user is forced to change their password at next login. This setting doesn't apply when the user signs in via a third-party identity provider.
ipWhitelisted

boolean

If true, the user's IP address is subject to a deprecated IP address allowlist configuration.
name

object (UserName)

Holds the given and family names of the user, and the read-only fullName value. The maximum number of characters in the givenName and in the familyName values is 60. In addition, name values support unicode/UTF-8 characters, and can contain spaces, letters (a-z), numbers (0-9), dashes (-), forward slashes (/), and periods (.). For more information about character usage rules, see the administration help center. Maximum allowed data size for this field is 1KB.
kind

string

Output only. The type of the API resource. For Users resources, the value is admin#directory#user.
etag

string

Output only. ETag of the resource.
emails

value (Value format)

The list of the user's email addresses. The maximum allowed data size is 10KB.

Fields

emails[].address

string

The user's email address. Also serves as the email ID. This value can be the user's primary email address or an alias.

emails[].customType

string

If the email address type is custom, this property contains the custom value and must be set.

emails[].primary

boolean

Indicates if this is the user's primary email. Only one entry can be marked as primary.

emails[].type

string

The type of the email account. If set to custom, customType must also be set.

Acceptable values: custom, home, other, work.
externalIds

value (Value format)

The list of external IDs for the user, such as an employee or network ID. The maximum allowed data size is 2KB.

Fields

externalIds[].customType

string

If the external ID type is custom, this property contains the custom value and must be set.

externalIds[].type

string

The type of external ID. If set to custom, customType must also be set.

Acceptable values: account, custom, customer, login_id, network, organization.

externalIds[].value

string

The value of the external ID.
relations

value (Value format)

The list of the user's relationships to other users. The maximum allowed data size for this field is 2KB. For more information, see Manage user accounts.

Fields

relations[].customType

string

If the relationship type is custom, this property contains the custom value and must be set.

relations[].type

string

The type of relationship. If set to custom, customType must also be set.

Acceptable values:
  • admin_assistant
  • assistant
  • brother
  • child
  • custom
  • domestic_partner
  • dotted_line_manager
  • exec_assistant
  • father
  • friend
  • manager
  • mother
  • parent
  • partner
  • referred_by
  • relative
  • sister
  • spouse

relations[].value

string

The email address of the person the user is related to.
aliases[]

string

Output only. The list of the user's alias email addresses.
isMailboxSetup

boolean

Output only. Indicates if the user's Google mailbox is created. This property is only applicable if the user has been assigned a Gmail license.
customerId

string

Output only. The customer ID to retrieve all account users.
You can use the alias my_customer to represent your account's customerId.
As a reseller administrator, you can use the resold customer account's customerId. To get a customerId, use the account's primary domain in the domain parameter of a users.list request.
addresses

value (Value format)

The list of the user's addresses. The maximum allowed data size is 10KB.

Fields

addresses[].country

string

Country.

addresses[].countryCode

string

The country code. Uses the ISO 3166-1 standard.

addresses[].customType

string

If the address type is custom, this property contains the custom value and must be set.

addresses[].extendedAddress

string

For extended addresses, such as an address that includes a sub-region.

addresses[].formatted

string

A full and unstructured postal address. This is not synced with the structured address fields. Includes the following attributes: street address, P.O. box, city, state/province, ZIP/postal code, country/region.

addresses[].locality

string

The town or city of the address.

addresses[].poBox

string

The post office box, if present.

addresses[].postalCode

string

The ZIP or postal code, if applicable.

addresses[].primary

boolean

If this is the user's primary address. The addresses list may contain only one primary address.

addresses[].region

string

The abbreviated province or state.

addresses[].sourceIsStructured

boolean

Indicates if the user-supplied address was formatted. Formatted addresses are not currently supported.

addresses[].streetAddress

string

The street address, such as 1600 Amphitheatre Parkway. Whitespace within the string is ignored; however, newlines are significant.

addresses[].type

string

The address type. If set to custom, customType must also be set.

Acceptable values: custom, home, other, work.
organizations

value (Value format)

The list of organizations the user belongs to. The maximum allowed data size is 10KB.

Fields

organizations[].costCenter

string

The cost center of the user's organization.

organizations[].customType

string

If the value of type is custom, this property contains the custom type.

organizations[].department

string

Specifies the department within the organization, such as sales or engineering.

organizations[].description

string

The description of the organization.

organizations[].domain

string

The domain the organization belongs to.

organizations[].fullTimeEquivalent

integer

The full-time equivalent millipercent within the organization (100000 = 100%).

organizations[].location

string

The physical location of the organization. This does not need to be a fully qualified address.

organizations[].name

string

The name of the organization.

organizations[].primary

boolean

Indicates if this is the user's primary organization. A user may only have one primary organization.

organizations[].symbol

string

Text string symbol of the organization. For example, the text symbol for Google is GOOG.

organizations[].title

string

The user's title within the organization. For example, member or engineer.

organizations[].type

string

The type of organization.

Acceptable values: domain_only, school, unknown, work.
lastLoginTime

string

Output only. The last time the user logged into the user's account. The value is in ISO 8601 date and time format. The time is the complete date plus hours, minutes, and seconds in the form YYYY-MM-DDThh:mm:ssTZD. For example, 2010-04-05T17:30:04+01:00.
phones

value (Value format)

A list of the user's phone numbers. The maximum allowed data size is 1KB.

Fields

phones[].customType

string

If the phone number type is custom, this property contains the custom value and must be set.

phones[].primary

boolean

If true, this is the user's primary phone number. A user may only have one primary phone number.

phones[].type

string

The type of phone number. If set to custom, customType must also be set.

Acceptable values: assistant, callback, car, company_main, custom, grand_central, home, home_fax, isdn, main, mobile, other, other_fax, pager, radio, telex, tty_tdd, work, work_fax, work_mobile, work_pager.

phones[].value

string

A human-readable phone number. It may be in any telephone number format.
suspensionReason

string

Output only. Has the reason a user account is suspended either by the administrator or by Google at the time of suspension. The property is returned only if the suspended property is true.
thumbnailPhotoUrl

string

Output only. The URL of the user's profile photo. The URL might be temporary or private.
languages

value (Value format)

The list of the user's languages. The maximum allowed data size is 1KB.

Fields

languages[].customLanguage

string

Other language. User can provide their own language name if there is no corresponding ISO 639 language code. If this is set, languageCode can't be set.

languages[].languageCode

string

ISO 639 string representation of a language. See Language Codes for the list of supported codes. Valid language codes outside the supported set will be accepted by the API but may lead to unexpected behavior. Illegal values cause SchemaException. If this is set, customLanguage can't be set.

languages[].preference

string

Optional. If present, controls whether the specified languageCode is the user's preferred language. If customLanguage is set, this can't be set. Allowed values are preferred and not_preferred.
posixAccounts

value (Value format)

The list of POSIX account information for the user.

Fields

posixAccounts[].accountId

string

A POSIX account field identifier.

posixAccounts[].gecos

string

The GECOS (user information) for this account.

posixAccounts[].gid

unsigned long

The default group ID.

posixAccounts[].homeDirectory

string

The path to the home directory for this account.

posixAccounts[].operatingSystemType

string

The operating system type for this account.

Acceptable values: linux, unspecified, windows.

posixAccounts[].primary

boolean

If this is user's primary account within the SystemId.

posixAccounts[].shell

string

The path to the login shell for this account.

posixAccounts[].systemId

string

System identifier for which account Username or Uid apply to.

posixAccounts[].uid

unsigned long

The POSIX compliant user ID.

posixAccounts[].username

string

The username of the account.
creationTime

string

Output only. The time the user's account was created. The value is in ISO 8601 date and time format. The time is the complete date plus hours, minutes, and seconds in the form YYYY-MM-DDThh:mm:ssTZD. For example, 2010-04-05T17:30:04+01:00.
nonEditableAliases[]

string

Output only. The list of the user's non-editable alias email addresses. These are typically outside the account's primary domain or sub-domain.
sshPublicKeys

value (Value format)

A list of SSH public keys.

Fields

sshPublicKeys[].expirationTimeUsec

long

An expiration time in microseconds since epoch.

sshPublicKeys[].fingerprint

string

A SHA-256 fingerprint of the SSH public key. (Read-only)

sshPublicKeys[].key

string

An SSH public key.
notes

value (Value format)

Notes for the user as a nested object.

Fields

notes.contentType

string

Content type of note, either plain text or HTML. Default is plain text.

Acceptable values: text_plain, text_html.

notes.value

string

Contents of notes.
websites

value (Value format)

The list of the user's websites.

Fields

websites[].customType

string

If the website type is custom, this property contains the custom value and must be set.

websites[].primary

boolean

If true, this is the user's primary website.

websites[].type

string

The type or purpose of the website. For example, a website could be labeled as home or blog. Alternatively, an entry can have a custom type. If set to custom, customType must also be set.

Acceptable values: app_install_page, blog, custom, ftp, home, home_page, other, profile, reservations, resume, work.

websites[].value

string

The URL of the website.
locations

value (Value format)

The list of the user's locations. The maximum allowed data size is 10KB.

Fields

locations[].area

string

Textual location. This is most useful for display purposes to concisely describe the location. For example, Mountain View, CA or Near Seattle.

locations[].buildingId

string

Building identifier.

locations[].customType

string

If the location type is custom, this property contains the custom value and must be set.

locations[].deskCode

string

Most specific textual code of individual desk location.

locations[].floorName

string

Floor name/number.

locations[].floorSection

string

Floor section. More specific location within the floor. For example, if a floor is divided into sections A, B, and C, this field would identify one of those values.

locations[].type

string

The location type. If set to custom, customType must also be set.

Acceptable values: custom, default, desk.
includeInGlobalAddressList

boolean

Indicates if the user's profile is visible in the Google Workspace global address list when the contact sharing feature is enabled for the domain. For more information about excluding user profiles, see the administration help center.
keywords

value (Value format)

The list of the user's keywords. The maximum allowed data size is 1KB.

Fields

keywords[].customType

string

If the keyword type is custom, this property contains the custom value and must be set.

keywords[].type

string

Each entry can have a type which indicates standard type of that entry.

For example, keyword could be of type occupation or outlook. In addition to the standard type, an entry can have a custom type and can give it any name. If set to custom, customType must also be set.

Acceptable values: custom, mission, occupation, outlook.

keywords[].value

string

Keyword.
deletionTime

string

Output only. The time the user's account was deleted. The value is in ISO 8601 date and time format. The time is the complete date plus hours, minutes, and seconds in the form YYYY-MM-DDThh:mm:ssTZD. For example 2010-04-05T17:30:04+01:00.
gender

value (Value format)

A nested object containing the user's gender. Maximum allowed data size for this field is 1KB.

Fields

gender.addressMeAs

string

A human-readable string containing the proper way to refer to the profile owner by humans, for example "he/him/his" or "they/them/their."

gender.customGender

string

Name of a custom gender.

gender.type

string

 The type of gender.

Acceptable values:
  • female
  • male
  • other
  • unknown

thumbnailPhotoEtag

string

Output only. ETag of the user's photo (Read-only)
ims

value (Value format)

The user's Instant Messenger (IM) accounts. A user account can have multiple ims properties, but only one of these ims properties can be the primary IM contact.

Fields

ims[].customProtocol

string

If the protocol value is custom_protocol, this property holds the custom protocol's string.

ims[].customType

string

If the IM type is custom, this property contains the custom value and must be set.

ims[].im

string

The user's IM network ID.

ims[].primary

boolean

If this is the user's primary IM. Only one entry in the IM list can have a value of true.

ims[].protocol

string

 An IM protocol identifies the IM network. The value can be a custom network or the standard network.

Acceptable values:
  • aim: AOL Instant Messenger protocol
  • custom_protocol: A custom IM network protocol
  • gtalk: Google Talk protocol
  • icq: ICQ protocol
  • jabber: Jabber protocol
  • msn: MSN Messenger protocol
  • net_meeting: Net Meeting protocol
  • qq: QQ protocol
  • skype: Skype protocol
  • yahoo: Yahoo Messenger protocol

ims[].type

string

The type of IM account. If set to custom, customType must also be set.

Acceptable values: custom, home, other, work.
customSchemas

value (Value format)

Custom fields of the user. The key is a schemaName and its values are 'fieldName': 'field_value'.

  • customSchemas.(key) is a nested object.
  • customSchemas.(key).(key) can be any value.
isEnrolledIn2Sv

boolean

Output only. Is enrolled in 2-step verification (Read-only)
isEnforcedIn2Sv

boolean

Output only. Is 2-step verification enforced (Read-only)
archived

boolean

Indicates if user is archived.
orgUnitPath

string

The full path of the parent organization associated with the user. If the parent organization is the top-level, it is represented as a forward slash (/).
recoveryEmail

string

Recovery email of the user.
recoveryPhone

string

Recovery phone of the user. The phone number must be in the E.164 format, starting with the plus sign (+). Example: +16506661212.

UserName

JSON representation 
{
  "fullName": string,
  "familyName": string,
  "givenName": string,
  "displayName": string
}
Fields
fullName

string

The user's full name formed by concatenating the first and last name values.
familyName

string

The user's last name. Required when creating a user account.
givenName

string

The user's first name. Required when creating a user account.
displayName

string

The user's display name. Limit: 256 characters.

Methods

delete

 Deletes a user.

get

 Retrieves a user.

insert

 Creates a user.

list

 Retrieves a paginated list of either deleted users or all users in a domain.

makeAdmin

 Makes a user a super administrator.

patch

 Updates a user using patch semantics.

signOut

 Signs a user out of all web and device sessions and reset their sign-in cookies.

undelete

 Undeletes a deleted user.

update

 Updates a user.

watch

 Watches for changes in users list.