Warning: The Notifications API is deprecated and will be shutdown soon.

Users: insert

Creates a user. Try it now.


HTTP request

POST https://www.googleapis.com/admin/directory/v1/users


This request requires authorization with the following scope:


For more information, see the authentication and authorization page.

Request body

In the request body, supply a Users resource with the following properties:

Property name Value Description Notes
Required Properties
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.givenName string The user's first name. Required when creating a user account. 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.
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
Optional Properties
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"
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
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"
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": IDs of this type map to employee ID in the Admin Console
externalIds[].value string The value of the ID. writable
gender.customGender string Custom gender. writable
gender.type string Gender.

Acceptable values are:
  • "female"
  • "male"
  • "other"
  • "unknown"
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
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
ims[].type string The type must be one of these values:
  • custom
  • home
  • other
  • work

Acceptable values are:
  • "custom"
  • "home"
  • "other"
  • "work"
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
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"
keywords[].value string Keyword. writable
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
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"
notes.contentType string Content type of note, either plain text or HTML. Default is plain text. Possible values are:
  • text_plain
  • text_html
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[].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"
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"
phones[].value string A human-readable phone number. It may be in any telephone number format. 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"
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
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[].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"
relations[].value string The name of the person the user is related to. writable
sshPublicKeys[].expirationTimeUsec long An expiration time in microseconds since epoch. writable
sshPublicKeys[].key string An SSH public key. writable
suspended boolean Indicates if user is suspended. writable
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"
websites[].value string The URL of the website. writable


If successful, this method returns a Users resource in the response body.

Try it!

Use the APIs Explorer below to call this method on live data and see the response.