REST Resource: users

Resource: User

The Directory API allows you to create and manage your account's users, user aliases, and user Gmail chat 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 is optional when updating a user and should only be provided if the user is updating their account password.
A password can contain any combination of ASCII characters. A minimum of 8 characters is required. The maximum length is 100 characters.
We recommend sending the password property value as a base 16 bit, hexadecimal-encoded hash value. If a hashFunction is specified, the password must be a valid hash key.
The password value is never returned in the API's response body.

hashFunction

string

Stores the hash format of the password property. We recommend sending the password property value as a base 16 bit hexadecimal-encoded hash value. Set the hashFunction values as either the SHA-1, MD5, or [crypt](https://en.wikipedia.org/wiki/Crypt_(C)) hash format.

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 white listed.

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)

A list of the user's email addresses. The maximum allowed data size for this field is 10Kb.

externalIds

value (Value format)

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

relations

value (Value format)

A list of the user's relationships to other users. The maximum allowed data size for this field is 2Kb.

aliases[]

string

Output only. asps.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)

A list of the user's addresses. The maximum allowed data size for this field is 10Kb.

organizations

value (Value format)

A list of organizations the user belongs to. The maximum allowed data size for this field is 10Kb.

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 for this field is 1Kb.

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. Photo Url of the user (Read-only)

languages

value (Value format)

The user's languages. The maximum allowed data size for this field is 1Kb.

posixAccounts

value (Value format)

A list of POSIX account information for the user.

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

notes

value (Value format)

Notes for the user.

websites

value (Value format)

The user's websites. The maximum allowed data size for this field is 2Kb.

locations

value (Value format)

The user's locations. The maximum allowed data size for this field is 10Kb.

includeInGlobalAddressList

boolean

Indicates if the user's profile is visible in the G Suite 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 user's keywords. The maximum allowed data size for this field is 1Kb.

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)

The user's gender. The maximum allowed data size for this field is 1Kb.

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. The maximum allowed data size for this field is 2Kb.

customSchemas

value (Value format)

Custom fields of the user.

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

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

Sign 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

Watch for changes in users list