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. 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. 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. 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`	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. 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`	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`	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`	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`	List of organizations the user belongs to. 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. 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: +16506661212.	writable
`relations[]`	`list`	A list of the user's relationships to other users. 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`	Websites of the user. 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