Admin SDK

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,
  "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
    }
  ],
  "phones": [
    {
      "value": string,
      "primary": boolean,
      "type": string,
      "customType": string
    }
  ],
  "aliases": [
    string
  ],
  "nonEditableAliases": [
    string
  ],
  "customerId": string,
  "orgUnitPath": string,
  "isMailboxSetup": boolean,
  "includeInGlobalAddressList": boolean,
  "thumbnailPhotoUrl": string
}
Property name Value Description Notes
addresses[] list A list of the user's addresses.
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.
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. Allowed values are:
  • custom
  • home
  • other
  • work


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.
changePasswordAtNextLogin boolean Indicates if the user is forced to change their password at next login. 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.
customerId string The customer ID to retrieve all account users.
As an account administrator, you can use the alias my_customerto 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.
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 Idicates 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. Valid values are:
  • custom
  • home
  • other
  • work


    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.
    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. Allowed values are:
    • account
    • custom
    • customer
    • network
    • organization


    Acceptable values are:
    • "account":
    • "custom":
    • "customer":
    • "network":
    • "organization":
    writable
    externalIds[].value string The value of the ID. writable
    hashFunction string Stores the hash format of the password property. We recommend sending the password property value as a base 16 bit 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, except in Undelete a user account operations.
    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.
    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. The values are:
    • custom_protocol: A custom IM network protocol
    • aim: AOL Instant Messenger 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


    Acceptable values are:
    • "aim":
    • "custom_protocol":
    • "gtalk":
    • "icq":
    • "jabber":
    • "msn":
    • "net_meeting":
    • "qq":
    • "skype":
    • "yahoo":
    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 Google Apps 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.
    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.
    kind string The type of the API resource. For Users resources, the value is admin#directory#user.
    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.
    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), dashers(-), forward slashes (/), and periods (.). For more information about character usage rules, see the administration help center. 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.
    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.
    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[].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. Possible values are:
    • unknown
    • school
    • work
    • domain_only
    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 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.
    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. Allowed values are:
    • custom
    • home
    • work
    • other
    • home_fax
    • work_fax
    • mobile
    • pager
    • other_fax
    • compain_main
    • assistant
    • car
    • radio
    • isdn
    • callback
    • telex
    • tty_tdd
    • work_mobile
    • work_pager
    • main
    • grand_central


    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
    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
    relations[] list A list of the user's relationships to other users.
    relations[].customType string If the value of type is custom, this property contains the custom type. writable
    relations[].type string The type of relation. Possible values are:
    • custom
    • spouse
    • child
    • mother
    • father
    • parent
    • brother
    • sister
    • friend
    • relative
    • domestic_partner
    • manager
    • assistant
    • referred_by
    • partner


    Acceptable values are:
    • "assistant":
    • "brother":
    • "child":
    • "custom":
    • "domestic_partner":
    • "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
    suspended boolean Indicates if the 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. Possible values include:
    • 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.
    • 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.


    Acceptable values are:
    • "ABUSE":
    • "ADMIN":
    • "UNDER13":
    • "WEB_LOGIN_REQUIRED":
    thumbnailPhotoUrl string Photo Url of the user (Read-only)

    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. This method supports patch semantics.
    undelete
    Undeletes a deleted user.
    update
    Updates a user.
    watch
    Watch for changes in users list

    Authentication required

    You need to be signed in with Google+ to do that.

    Signing you in...

    Google Developers needs your permission to do that.