Users

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.

For a list of methods for this resource, see the end of this page.

Resource representations

The following JSON template is used for Users resources in the Directory API:

{
  "kind": "admin#directory#user",
  "id": string,
  "etag": etag,
  "primaryEmail": string,
  "name": {
    "givenName": string,
    "familyName": string,
    "fullName": string
  },
  "isAdmin": boolean,
  "isDelegatedAdmin": boolean,
  "lastLoginTime": datetime,
  "creationTime": datetime,
  "deletionTime": datetime,
  "agreedToTerms": boolean,
  "password": string,
  "hashFunction": string,
  "suspended": boolean,
  "suspensionReason": string,
  "archived": boolean,
  "changePasswordAtNextLogin": boolean,
  "ipWhitelisted": boolean,
  "ims": [
    {
      "type": string,
      "customType": string,
      "protocol": string,
      "customProtocol": string,
      "im": string,
      "primary": boolean
    }
  ],
  "emails": [
    {
      "address": string,
      "type": string,
      "customType": string,
      "primary": boolean
    }
  ],
  "externalIds": [
    {
      "value": string,
      "type": string,
      "customType": string
    }
  ],
  "relations": [
    {
      "value": string,
      "type": string,
      "customType": string
    }
  ],
  "addresses": [
    {
      "type": string,
      "customType": string,
      "sourceIsStructured": boolean,
      "formatted": string,
      "poBox": string,
      "extendedAddress": string,
      "streetAddress": string,
      "locality": string,
      "region": string,
      "postalCode": string,
      "country": string,
      "primary": boolean,
      "countryCode": string
    }
  ],
  "organizations": [
    {
      "name": string,
      "title": string,
      "primary": boolean,
      "type": string,
      "customType": string,
      "department": string,
      "symbol": string,
      "location": string,
      "description": string,
      "domain": string,
      "costCenter": string,
      "fullTimeEquivalent": integer
    }
  ],
  "phones": [
    {
      "value": string,
      "primary": boolean,
      "type": string,
      "customType": string
    }
  ],
  "languages": [
    {
      "languageCode": string,
      "customLanguage": string
    }
  ],
  "posixAccounts": [
    {
      "username": string,
      "uid": unsigned long,
      "gid": unsigned long,
      "homeDirectory": string,
      "shell": string,
      "gecos": string,
      "systemId": string,
      "primary": boolean,
      "accountId": string,
      "operatingSystemType": string
    }
  ],
  "sshPublicKeys": [
    {
      "key": string,
      "expirationTimeUsec": long,
      "fingerprint": string
    }
  ],
  "aliases": [
    string
  ],
  "nonEditableAliases": [
    string
  ],
  "notes": {
    "value": string,
    "contentType": string
  },
  "websites": [
    {
      "value": string,
      "primary": boolean,
      "type": string,
      "customType": string
    }
  ],
  "locations": [
    {
      "type": string,
      "customType": string,
      "area": string,
      "buildingId": string,
      "floorName": string,
      "floorSection": string,
      "deskCode": string
    }
  ],
  "keywords": [
    {
      "type": string,
      "customType": string,
      "value": string
    }
  ],
  "gender": {
    "type": string,
    "customGender": string,
    "addressMeAs": string
  },
  "customerId": string,
  "orgUnitPath": string,
  "recoveryEmail": string,
  "recoveryPhone": string,
  "isMailboxSetup": boolean,
  "isEnrolledIn2Sv": boolean,
  "isEnforcedIn2Sv": boolean,
  "includeInGlobalAddressList": boolean,
  "thumbnailPhotoUrl": string,
  "thumbnailPhotoEtag": etag,
  "customSchemas": {
    (key): {
      (key): (value)
    }
  }
}

Property name	Value	Description	Notes
addresses[]	list	A list of the user's addresses. The maximum allowed data size for this field is 10Kb.
addresses[].country	string	Country.	writable
addresses[].countryCode	string	The country code. Uses the ISO 3166-1 standard.	writable
addresses[].customType	string	If the address type is custom, this property contains the custom value.	writable
addresses[].extendedAddress	string	For extended addresses, such as an address that includes a sub-region.	writable
addresses[].formatted	string	A full and unstructured postal address. This is not synced with the structured address fields.	writable
addresses[].locality	string	The town or city of the address.	writable
addresses[].poBox	string	The post office box, if present.	writable
addresses[].postalCode	string	The ZIP or postal code, if applicable.	writable
addresses[].primary	boolean	If this is the user's primary address. The addresses list may contain only one primary address.	writable
addresses[].region	string	The abbreviated province or state.	writable
addresses[].sourceIsStructured	boolean	Indicates if the user-supplied address was formatted. Formatted addresses are not currently supported.	writable
addresses[].streetAddress	string	The street address, such as 1600 Amphitheatre Parkway. Whitespace within the string is ignored; however, newlines are significant.	writable
addresses[].type	string	The address type. Acceptable values are: "custom" "home" "other" "work"	writable
agreedToTerms	boolean	This property is true if the user has completed an initial login and accepted the Terms of Service agreement.
aliases[]	list	List of the user's alias email addresses.
archived	boolean	Indicates if user is archived.	writable
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.	writable
creationTime	datetime	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.
customSchemas	object	Custom fields of the user.
customSchemas.(key)	nested object
customSchemas.(key).(key)	any value
customerId	string	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.
deletionTime	datetime	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.
emails[]	list	A list of the user's email addresses. The maximum allowed data size for this field is 10Kb.
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.	writable
emails[].customType	string	If the value of type is custom, this property contains the custom type string.	writable
emails[].primary	boolean	Indicates if this is the user's primary email. Only one entry can be marked as primary.	writable
emails[].type	string	The type of the email account. Acceptable values are: "custom" "home" "other" "work"	writable
etag	etag	ETag of the resource.
externalIds[]	list	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.
externalIds[].customType	string	If the external ID type is custom, this property holds the custom type.	writable
externalIds[].type	string	The type of the ID. Acceptable values are: "account" "custom" "customer" "login_id" "network" "organization"	writable
externalIds[].value	string	The value of the ID.	writable
gender	nested object	The user's gender. The maximum allowed data size for this field is 1Kb.
gender.addressMeAs	string	AddressMeAs. 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	Custom gender.	writable
gender.type	string	Gender. Acceptable values are: "female" "male" "other" "unknown"	writable
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 hash format.	writable
id	string	The unique ID for the user. A user id can be used as a user request URI's userKey.
ims[]	list	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.
ims[].customProtocol	string	If the protocol value is custom_protocol, this property holds the custom protocol's string.	writable
ims[].customType	string	If the IM type is custom, this property holds the custom type string.	writable
ims[].im	string	The user's IM network ID.	writable
ims[].primary	boolean	If this is the user's primary IM. Only one entry in the IM list can have a value of true.	writable
ims[].protocol	string	An IM protocol identifies the IM network. The value can be a custom network or the standard network. Acceptable values are: "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	writable
ims[].type	string	The type must be one of these values: custom home other work Acceptable values are: "custom" "home" "other" "work"	writable
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.	writable
ipWhitelisted	boolean	If true, the user's IP address is white listed.	writable
isAdmin	boolean	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	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.
isEnforcedIn2Sv	boolean	Is 2-step verification enforced (Read-only)
isEnrolledIn2Sv	boolean	Is enrolled in 2-step verification (Read-only)
isMailboxSetup	boolean	Indicates if the user's Google mailbox is created. This property is only applicable if the user has been assigned a Gmail license.
keywords[]	list	The user's keywords. The maximum allowed data size for this field is 1Kb.
keywords[].customType	string	Custom Type.	writable
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. Such types should have the CUSTOM value as type and also have a customType value. Acceptable values are: "custom" "mission" "occupation" "outlook"	writable
keywords[].value	string	Keyword.	writable
kind	string	The type of the API resource. For Users resources, the value is admin#directory#user.
languages[]	list	The user's languages. The maximum allowed data size for this field is 1Kb.
languages[].customLanguage	string	Other language. A user can provide their own language name if there is no corresponding Google III language code. If this is set, LanguageCode can't be set	writable
languages[].languageCode	string	Language Code. Should be used for storing Google III LanguageCode string representation for language. Illegal values cause SchemaException.	writable
lastLoginTime	datetime	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.
locations[]	list	The user's locations. The maximum allowed data size for this field is 10Kb.
locations[].area	string	Textual location. This is most useful for display purposes to concisely describe the location. For example, "Mountain View, CA", "Near Seattle".	writable
locations[].buildingId	string	Building identifier.	writable
locations[].customType	string	If the location type is custom, this property contains the custom value.	writable
locations[].deskCode	string	Most specific textual code of individual desk location.	writable
locations[].floorName	string	Floor name/number.	writable
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.	writable
locations[].type	string	The location type. Acceptable values are: "custom" "default" "desk"	writable
name	nested object	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.	writable
name.familyName	string	The user's last name. Required when creating a user account.	writable
name.fullName	string	The user's full name formed by concatenating the first and last name values.
name.givenName	string	The user's first name. Required when creating a user account.	writable
nonEditableAliases[]	list	List of the user's non-editable alias email addresses. These are typically outside the account's primary domain or sub-domain.
notes	nested object	Notes for the user.
notes.contentType	string	Content type of note, either plain text or HTML. Default is plain text. Possible values are: text_plain text_html	writable
notes.value	string	Contents of notes.	writable
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 (/).	writable
organizations[]	list	A list of organizations the user belongs to. The maximum allowed data size for this field is 10Kb.
organizations[].costCenter	string	The cost center of the user's organization.	writable
organizations[].customType	string	If the value of type is custom, this property contains the custom type.	writable
organizations[].department	string	Specifies the department within the organization, such as 'sales' or 'engineering'.	writable
organizations[].description	string	The description of the organization.	writable
organizations[].domain	string	The domain the organization belongs to.	writable
organizations[].fullTimeEquivalent	integer	The full-time equivalent millipercent within the organization (100000 = 100%).	writable
organizations[].location	string	The physical location of the organization. This does not need to be a fully qualified address.	writable
organizations[].name	string	The name of the organization.	writable
organizations[].primary	boolean	Indicates if this is the user's primary organization. A user may only have one primary organization.	writable
organizations[].symbol	string	Text string symbol of the organization. For example, the text symbol for Google is GOOG.	writable
organizations[].title	string	The user's title within the organization, for example 'member' or 'engineer'.	writable
organizations[].type	string	The type of organization. Acceptable values are: "domain_only" "school" "unknown" "work"	writable
password	string	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.	writable
phones[]	list	A list of the user's phone numbers. The maximum allowed data size for this field is 1Kb.
phones[].customType	string	If the value of type is custom, this property contains the custom type.	writable
phones[].primary	boolean	Indicates if this is the user's primary phone number. A user may only have one primary phone number.	writable
phones[].type	string	The type of phone number. Acceptable values are: "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"	writable
phones[].value	string	A human-readable phone number. It may be in any telephone number format.	writable
posixAccounts[]	list	A list of POSIX account information for the user.
posixAccounts[].accountId	string	A POSIX account field identifier.	writable
posixAccounts[].gecos	string	The GECOS (user information) for this account.	writable
posixAccounts[].gid	unsigned long	The default group ID.	writable
posixAccounts[].homeDirectory	string	The path to the home directory for this account.	writable
posixAccounts[].operatingSystemType	string	The operating system type for this account. Acceptable values are: "linux" "unspecified" "windows"	writable
posixAccounts[].primary	boolean	If this is user's primary account within the SystemId.	writable
posixAccounts[].shell	string	The path to the login shell for this account.	writable
posixAccounts[].systemId	string	System identifier for which account Username or Uid apply to.	writable
posixAccounts[].uid	unsigned long	The POSIX compliant user ID.	writable
posixAccounts[].username	string	The username of the account.	writable
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.	writable
recoveryEmail	string	Recovery email of the user.	writable
recoveryPhone	string	Recovery phone of the user. The phone number must be in the E.164 format, starting with the plus sign (+). Example: [phone].	writable
relations[]	list	A list of the user's relationships to other users. The maximum allowed data size for this field is 2Kb.
relations[].customType	string	If the value of type is custom, this property contains the custom type.	writable
relations[].type	string	The type of relation. Acceptable values are: "admin_assistant" "assistant" "brother" "child" "custom" "domestic_partner" "dotted_line_manager" "exec_assistant" "father" "friend" "manager" "mother" "parent" "partner" "referred_by" "relative" "sister" "spouse"	writable
relations[].value	string	The name of the person the user is related to.	writable
sshPublicKeys[]	list	A list of SSH public keys.
sshPublicKeys[].expirationTimeUsec	long	An expiration time in microseconds since epoch.	writable
sshPublicKeys[].fingerprint	string	A SHA-256 fingerprint of the SSH public key. (Read-only)
sshPublicKeys[].key	string	An SSH public key.	writable
suspended	boolean	Indicates if user is suspended.	writable
suspensionReason	string	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. Acceptable values are: "ABUSE": The user has violated a Google abuse rule and has been suspended by Google. This user's suspension status cannot be changed by the administrator. The API service returns an error. For more information about the Google Acceptable Use Policy, see the administration help center. "ADMIN": Suspended by an administrator. "UNDER13": The user is under 13 years of age and has been suspended by Google. This user's suspension status cannot be changed by an administrator. The API service returns an error. For more information about the Google age requirements, see the administration help center. "WEB_LOGIN_REQUIRED": A new account is automatically suspended by Google until the initial administrator login which activates the account. After the account is activated, the account is no longer suspended.
thumbnailPhotoEtag	etag	ETag of the user's photo (Read-only)
thumbnailPhotoUrl	string	Photo Url of the user (Read-only)
websites[]	list	The user's websites. The maximum allowed data size for this field is 2Kb.
websites[].customType	string	The custom type. Only used if the type is custom.	writable
websites[].primary	boolean	If this is user's primary website or not.	writable
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. Custom types must have a customType value. Acceptable values are: "app_install_page" "blog" "custom" "ftp" "home" "home_page" "other" "profile" "reservations" "resume" "work"	writable
websites[].value	string	The URL of the website.	writable

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. The update method should be used instead, since it also supports patch semantics and has better performance.

This method is unable to clear fields that contain repeated objects (addresses, phones, etc). Use the update method instead.

undelete

Undeletes a deleted user.

update

Updates a user.

This method supports patch semantics, meaning you only need to include the fields you wish to update. Fields that are not present in the request will be preserved, and fields set to null will be cleared.

watch

Watch for changes in users list