Create a user account
A user account can be added to any of your Google Workspace account's domains, including the account's primary domain. And before adding a user account, confirm the domain ownership.
If you upgraded your personal Gmail account to a business email account with your own domain name, you won’t be able create new user accounts until you unlock additional Google Workspace settings. For details, see Create business emails for your team.
To create a user account using one of your domains, use the following POST
request and include the authorization described in Authorize requests. For the request query string properties, see the API Reference.
POST https://admin.googleapis.com/admin/directory/v1/users
All create requests require you to submit the information needed to fulfill the request. If you are using client libraries, they convert the data objects from your chosen language into JSON data formatted objects.
JSON request
The following JSON shows a sample request to create a user. For the full list of request and response properties, see the API Reference.
{
"primaryEmail": "liz@example.com",
"name": {
"givenName": "Elizabeth",
"familyName": "Smith"
},
"suspended": false,
"password": "new user password",
"hashFunction": "SHA-1",
"changePasswordAtNextLogin": false,
"ipWhitelisted": false,
"ims": [
{
"type": "work",
"protocol": "gtalk",
"im": "liz_im@talk.example.com",
"primary": true
}
],
"emails": [
{
"address": "liz@example.com",
"type": "home",
"customType": "",
"primary": true
}
],
"addresses": [
{
"type": "work",
"customType": "",
"streetAddress": "1600 Amphitheatre Parkway",
"locality": "Mountain View",
"region": "CA",
"postalCode": "94043"
}
],
"externalIds": [
{
"value": "12345",
"type": "custom",
"customType": "employee"
}
],
"relations": [
{
"value": "Mom",
"type": "mother",
"customType": ""
},
{
"value": "manager",
"type": "referred_by",
"customType": ""
}
],
"organizations": [
{
"name": "Google Inc.",
"title": "SWE",
"primary": true,
"type": "work",
"description": "Software engineer"
}
],
"phones": [
{
"value": "+1 nnn nnn nnnn",
"type": "work"
}
],
"orgUnitPath": "/corp/engineering",
"includeInGlobalAddressList": true
}
If your query rate for creation requests is too high, you might receive HTTP 503
responses from the API server indicating that your quota has been exceeded. If you get these responses, use an exponential back-off algorithm to retry your requests.
Things to note about a new account are:
- If the Google account has purchased mail licenses, the new user account is automatically assigned a mailbox. This assignment may take a few minutes to be completed and activated.
- Editing a read-only field in a request, such as
isAdmin
, is silently ignored by the API service. - The maximum number of domains allowed in an account is 600 (1 primary domain + 599 additional domains)
- If a user was not assigned to a specific organizational unit when the user account was created, the account is in the top-level organizational unit. A user's organizational unit determines which Google Workspace services the user has access to. If the user is moved to a new organization, the user's access changes. For more information about organization structures, see the administration help center. For more infomation about moving a user to a different organization, see Update a user.
- A
password
is required for new user accounts. If ahashFunction
is specified, the password must be a valid hash key. For more information, see the API Reference. - For users on a flexible plan for Google Workspace, creating users using this API will have monetary impact, and will result in charges to your customer billing account. For more information, see the API billing information.
- A Google Workspace account can include any of your domains. In a multiple domain account, users in one domain can share services with users in other account domains. For more information about users in multiple domains, see the API multiple domain information.
- There might be conflicting accounts. Check to see if anyone you plan to add already has a Google Account. Then follow steps to avoid conflicts with those accounts. See Find and resolve conflicting accounts.
- There might be visitor accounts. If users invite people outside your organization who don't have Google Accounts to collaborate on Drive, they'll receive visitor accounts, in the format visitor's_username@your_domain.com. If you add a user with the same username as a visitor account, the account will be converted to a full Google Workspace account. The account will keep its current Drive file permissions. See Share documents with visitors.
A successful response returns an HTTP 200 status code. Along with the status code, the response returns the properties for the new user account.
Update a user account
To update a user account, use the following PUT
request and include the authorization described in Authorize requests. The userKey
can be the user's primary email address, the unique user id
, or one of the user's alias email addresses. For the request and response properties, see the API Reference.
PUT https://admin.googleapis.com/admin/directory/v1/users/userKey
In general, Google recommends to not use the user email address as a key for persistent data since the email address is subject to change.
JSON request
In the example below, the user's givenName
was Elizabeth when the user account was created. The givenName
has been updated from Elizabeth to Liz which is also is her name in the email address, liz@example.com:
PUT https://admin.googleapis.com/admin/directory/v1/users/liz@example.com
{
"primaryEmail": "liz@example.com",
"name": {
"givenName": "Liz",
"familyName": "Smith"
},
"suspended": false,
"password": "updated password",
"hashFunction": "SHA-1",
"changePasswordAtNextLogin": true,
"ipWhitelisted": false,
"ims": [
{
"type": "work",
"protocol": "gtalk",
"im": "newim@talk.example.com",
"primary": true
},
{
"type": "home",
"protocol": "aim",
"im": "newaim@aim.example.com",
"primary": false
}
],
"emails": [
{
"address": "liz@example.com",
"type": "home",
"customType": "",
"primary": true
}
],
"addresses": [
{
"type": "work",
"customType": "",
"streetAddress": "1600 Amphitheatre Parkway",
"locality": "Mountain View",
"region": "CA",
"postalCode": "94043"
}
],
"externalIds": [
{
"value": "12345",
"type": "custom",
"customType": "employee"
}
],
"relations": [
{
"value": "susan",
"type": "friend",
"customType": ""
}
],
"organizations": [
{
"name": "Google Inc.",
"title": "SWE",
"primary": true,
"type": "work",
"description": "Software engineer"
}
],
"phones": [
{
"value": "+1 206 555 nnnn",
"type": "work"
},
{
"value": "+1 602 555 nnnn",
"type": "home"
}
],
"orgUnitPath": "/corp/engineering",
"includeInGlobalAddressList": true
}
All update requests require you to submit the information needed to fulfill the request. For an update request, you only need to submit the updated information in your request. Even though this example is verbose, you do not need to enter all of the user's properties.
Things to note when updating a user's account name are:
- Renaming a user account changes the user's primary email address and the domain used when retrieving this user's information. Before renaming a user, we recommend that you log out the user from all browser sessions and services. For instance, you can get the user on your support desk telephone line during the rename process to ensure they have logged out.
- The process of renaming a user account can take up to 10 minutes to propagate across all services.
- When a user is renamed, the old user name is retained as a alias to ensure continuous mail delivery in the case of email forwarding settings and will not be available as a new user name.
- In general, we also recommend to not use the user email address as a key for persistent data since the email address is subject to change.
- For a full list of the effects of renaming a user across several Google services, see the administration help center.
A successful response returns an HTTP 200 status code. Along with the status code, the response returns the updated properties for the user account.
Make a user an administrator
To make user into a super administrator, use the following POST
request and include the authorization described in Authorize requests. The userKey
can be the user's primary email address, the unique user id
, or one of the user's alias email addresses. For the request and response properties, see API Reference. For more information about a super administrator, see the administration help center.
POST https://admin.googleapis.com/admin/directory/v1/users/userKey/makeAdmin
JSON request
In this example, user whose userKey
is liz@example.com has become a super administrator:
POST https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/makeAdmin
{ "status": true }
A successful response returns an HTTP 200 status code.
Retrieve a user
To retrieve a user, use the following GET
request and include the authorization described in Authorize requests. The userKey
can be the user's primary email address, the unique user id
, or one of the user's alias email addresses. For the request and response properties, see the API Reference.
GET https://admin.googleapis.com/admin/directory/v1/users/userKey
This example returns the user account properties for the user whose primary or alias email address is liz@example.com:
GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com
JSON response
A successful response returns an HTTP 200 status code. Along with the status code, the response returns the properties for the user account.
{ "kind": "directory#user", "id": "the unique user id", "primaryEmail": "liz@example.com", "name": { "givenName": "Liz", "familyName": "Smith", "fullName": "Liz Smith" }, "isAdmin": true, "isDelegatedAdmin": false, "lastLoginTime": "2013-02-05T10:30:03.325Z", "creationTime": "2010-04-05T17:30:04.325Z", "agreedToTerms": true, "hashFunction": "SHA-1", "suspended": false, "changePasswordAtNextLogin": false, "ipWhitelisted": false, "ims": [ { "type": "work", "protocol": "gtalk", "im": "lizim@talk.example.com", "primary": true } ], "emails": [ { "address": "liz@example.com", "type": "home", "customType": "", "primary": true } ], "addresses": [ { "type": "work", "customType": "", "streetAddress": "1600 Amphitheatre Parkway", "locality": "Mountain View", "region": "CA", "postalCode": "94043" } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "relations": [ { "value": "susan", "type": "friend", "customType": "" } ], "organizations": [ { "name": "Google Inc.", "title": "SWE", "primary": true, "customType": "", "description": "Software engineer" } ], "phones": [ { "value": "+1 nnn nnn nnnn", "type": "work" } ], "aliases": [ "lizsmith@example.com", "lsmith@example.com" ], "nonEditableAliases": [ "liz@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "corp/engineering", "isMailboxSetup": true, "includeInGlobalAddressList": true }
Retrieve all users in a domain
To retrieve all users in the same domain, use the following GET
request and include the authorization described in Authorize requests. For readability, this example uses line returns:
GET https://admin.googleapis.com/admin/directory/v1/users ?domain=primary domain name&pageToken=token for next results page &maxResults=max number of results per page &orderBy=email, givenName, or familyName &sortOrder=ascending or descending &query=email, givenName, or familyName:the query's value*
For the request and response properties, see the API Reference.
JSON response
In this example, all users in the example.com domain are returned with a maximum of 2 user domains per response page. There is a nextPageToken
for the follow-on list of users in this response. By default, the system returns a list of 100 users in the alphabetical order of the user's email address:
GET https://admin.googleapis.com/admin/directory/v1/users?domain=example.com&maxResults=2
A successful response returns an HTTP 200 status code. Along with the status code, the response returns 2 user accounts in the example.com domain (maxResults=2
):
{ "kind": "directory#users", "users": [ { "kind": "directory#user", "id": "the unique user id", "primaryEmail": "liz@example.com", "name": { "givenName": "Liz", "familyName": "Smith", "fullName": "Liz Smith" }, "isAdmin": true, "isDelegatedAdmin": false, "lastLoginTime": "2013-02-05T10:30:03.325Z", "creationTime": "2010-04-05T17:30:04.325Z", "agreedToTerms": true, "hashFunction": "SHA-1", "suspended": false, "changePasswordAtNextLogin": false, "ipWhitelisted": false, "ims": [ { "type": "work", "protocol": "gtalk", "im": "lizim@talk.example.com", "primary": true } ], "emails": [ { "address": "liz@example.com", "type": "work", "customType": "", "primary": true } ], "addresses": [ { "type": "work", "customType": "", "streetAddress": "1600 Amphitheatre Parkway", "locality": "Mountain View", "region": "CA", "postalCode": "94043" } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "relations": [ { "value": "susan", "type": "friend", "customType": "" } ], "organizations": [ { "name": "Google Inc.", "title": "SWE", "primary": true, "customType": "", "description": "Software engineer" } ], "phones": [ { "value": "+1 nnn nnn nnnn", "type": "work" } ], "aliases": [ "lizsmith@example.com", "lsmith@example.com" ], "nonEditableAliases": [ "liz@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "corp/engineering", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "user unique ID", "primaryEmail": "admin2@example.com", "name": { "givenName": "admin", "familyName": "two", "fullName": "admin two" }, "isAdmin": true, "isDelegatedAdmin": true, "lastLoginTime": "2013-02-05T10:30:03.325Z", "creationTime": "2010-04-05T17:30:04.325Z", "agreedToTerms": true, "hashFunction": "SHA-1", "suspended": true, "suspensionReason": "ADMIN", "changePasswordAtNextLogin": false, "ipWhitelisted": false, "emails": [ { "address": "admin2@example.com", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "contractor license number", "type": "custom", "customType": "work" } ], "relations": [ { "value": "liz", "type": "friend", "customType": "" } ], "aliases": [ "second_admin@example.com" ], "nonEditableAliases": [ "admin@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "corp/engineering", "isMailboxSetup": true, "includeInGlobalAddressList": true } ], "nextPageToken": "next page token" }
Retrieve all account users
To retrieve all users in an account which can consist of multiple domains, use the following GET
request and include the authorization described in Authorize requests. For readability, this example uses line returns:
GET https://admin.googleapis.com/admin/directory/v1/users ?customer=my_customer or customerId&pageToken=token for next results page &maxResults=max number of results per page &orderBy=email, givenName, or familyName &sortOrder=ascending or descending &query=user attributes
- The
customer
query string is themy_customer
or thecustomerId
value. - Use the string
my_customer
to represent your account'scustomerId
. - As a reseller administrator, use the resold customer's
customerId
. For thecustomerId
, use the account's primary domain name in the Retrieve all users in a domain operation's request. The resulting response has thecustomerId
value. - The optional
orderBy
query string determines whether the list is sorted by the user's primary email address, family name or given name. When usingorderBy
, you can also use thesortOrder
query string to list the results in ascending or descending order. - The optional
query
query string allows searching over many fields in a user profile, including both core and custom fields. See Search for Users for examples.
For the request and response properties, see the API Reference.
In this example, an account administrator is requesting all users in the account be returned with one user entry on each response page. The nextPageToken
goes to the follow-on page of results:
GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&maxResults=1
In this example, a reseller administrator is requesting all users in a resold account which has the customerId
value of C03az79cb
.
GET https://admin.googleapis.com/admin/directory/v1/users?customer=C03az79cb&maxResults=1
JSON response
A successful response returns an HTTP 200 status code. Along with the status code, the response returns all the users in this account:
{ "kind": "directory#users", "users": [ { "kind": "directory#user", "id": "the unique user id", "username": "admin2@example.com", "name": { "givenName": "admin", "familyName": "two", "fullName": "admin two" }, "isAdmin": true, "isDelegatedAdmin": true, "lastLoginTime": "2013-02-05T10:30:03.325Z", "creationTime": "2010-04-05T17:30:04.325Z", "agreedToTerms": true, "hashFunction": "SHA-1", "suspended": false, "changePasswordAtNextLogin": false, "ipWhitelisted": false, "emails": [ { "address": "admin2@example.com", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "relations": [ { "value": "liz", "type": "friend", "customType": "" } ], "aliases": [ "second_admin@example.com" ], "nonEditableAliases": [ "another_admin@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "/", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "the unique user id", "username": "liz@example.com", "name": { "givenName": "Elizabeth", "familyName": "Smith", "fullName": "Elizabeth Smith" }, "isAdmin": false, "isDelegatedAdmin": false, "lastLoginTime": "1336509883546", "creationTime": "1404802800000", "agreedToTerms": false, "hashFunction": "SHA-1", "suspended": false, "changePasswordAtNextLogin": false, "ipWhitelisted": false, "emails": [ { "address": "liz@example.com", "type": "home", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "bank" } ], "relations": [ { "value": "liz", "type": "friend", "customType": "" } ], "aliases": [ "lizsmith@example.com", "lsmith@example.com" ], "nonEditableAliases": [ "liz@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "/", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "the unique user id", "username": "test3@example.com", "name": { "givenName": "Tester", "familyName": "Three", "fullName": "Tester Three" }, "isAdmin": false, "isDelegatedAdmin": false, "lastLoginTime": "1336509883546", "creationTime": "1404802800000", "agreedToTerms": true, "hashFunction": "SHA-1", "suspended": false, "changePasswordAtNextLogin": false, "ipWhitelisted": false, "emails": [ { "address": "test@example.com", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "relations": [ { "value": "liz", "type": "friend", "customType": "" } ], "aliases": [ "tester3@example.com" ], "nonEditableAliases": [ "third@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "/", "isMailboxSetup": true, "includeInGlobalAddressList": true }, { "kind": "directory#user", "id": "the unique user id", "username": "work_admin@example.com", "name": { "givenName": "Admin", "familyName": "Work", "fullName": "Admin Work" }, "isAdmin": true, "isDelegatedAdmin": true, "lastLoginTime": "1336509883546", "creationTime": "1404802800000", "agreedToTerms": true, "hashFunction": "SHA-1", "suspended": false, "changePasswordAtNextLogin": false, "ipWhitelisted": false, "emails": [ { "address": "work_admin@example.com", "type": "work", "customType": "", "primary": true } ], "externalIds": [ { "value": "employee number", "type": "custom", "customType": "office" } ], "relations": [ { "value": "liz", "type": "friend", "customType": "" } ], "aliases": [ "my_alias@example.com" ], "nonEditableAliases": [ "other_alias@test.com" ], "customerId": "C03az79cb", "orgUnitPath": "/", "isMailboxSetup": true, "includeInGlobalAddressList": true } ], "nextPageToken": "NNNNN" }
Retrieve users deleted in last 5 days
To retrieve all users deleted within the span of the last 5 days from an account or from one of the account's domains, use the following GET
requests and include the authorization described in Authorize requests. To undelete a user, see Undelete a user.
To retrieve users deleted within the span of the last 5 days from the account's primary domain or a subdomain, use the following GET
request. The domain
query string is the domain's primary domain name. For the user request and response properties, see the API Reference. And, for readability, this example uses line returns:
GET https://admin.googleapis.com/admin/directory/v1/users ?domain=primary domain name&pageToken=token for next results page &maxResults=max number of results per page &showDeleted=trueIf an account has multiple domains, you can retrieve users deleted within the span of the last 5 days from the whole account, use the following
GET
request. For readability, this example uses line returns:
GET https://admin.googleapis.com/admin/directory/v1/users ?customer=my_customer or customerId&pageToken=token for next results page &maxResults=max number of results per page&showDeleted=true
- The
customer
query string is themy_customer
or thecustomerId
value. - As an account administrator, use the string
my_customer
to represent your account'scustomerId
. - As a reseller administrator, use the resold customer's
customerId
. For thecustomerId
, use the account's primary domain name in the Retrieve all users in a domain operation's request. The resulting response has thecustomerId
value.
For the request and response properties, see the API Reference.
In this example, an account administrator is requesting all deleted users in the account:
GET https://admin.googleapis.com/admin/directory/v1/users?customer=my_customer&showDeleted=true
JSON response
A successful response returns an HTTP 200 status code. Along with the status code, the response returns all the account users deleted within the last 5 days:
{ "kind": "directory#users", "users": [ { "kind": "directory#user", "id": "the unique user id", "primaryEmail": "user1@example.com" }, { "kind": "directory#user", "id": "the unique user id", "primaryEmail": "user3@example.com" } ], "nextPageToken": "token for next page of deleted users" }
Retrieve a user's photo
The API retrieves one photo thumbnail, the lastest Gmail Chat profile photo. To retrieve the user's lastest photo, use the following GET
request and include the authorization described in Authorize requests. The userKey
can be the user's primary email address, the user id
, or any of the user's alias emails. For the request and response properties, see the API Reference.
GET https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail
In this example, the latest photo of liz@example.com is returned:
GET https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/photos/thumbnail
JSON Response
A successful response returns an HTTP 200 status code.
{ "kind": "directory#user#photo", "id": "the unique user id", "primaryEmail": "liz@example.com", "mimeType": "the photo mime type", "height": "the photo height in pixels", "width": "the photo width in pixels", "photoData": "web safe base64 encoded photo data" }
The API's web safe base64 encoding of your photos is similar to the RFC 4648 'base64url'. This means:
- The slash (/) character is replaced with the underscore (_) character.
- The plus sign (+) character is replaced with the hyphen (-) character.
- The equals sign (=) character is replaced with the asterisk (*).
- For padding, the period (.) character is used instead of the RFC-4648 baseURL definition which uses the equals sign (=) for padding. This is done to simplify URL-parsing.
- Whatever the size of the photo being uploaded, the API downsizes it proportionally to 96x96 pixels.
If you need to create compatible links from JavaScript, the Google Closure Library includes Base64 encoding and decoding functions which are released under the Apache license.
Retrieve a user as a non-administrator
While user accounts can only be modified by administrators, any user on the domain can read user
profiles. A non-admin user can make a
users.get
or
users.list
request with
the viewType
parameter equal to domain_public
to retrieve a user's
public profile. The scope
https://www.googleapis.com/auth/admin.directory.user.readonly
is ideal for this use
case.
The domain_public
view permits a non-admin user to access a standard set of core
fields. For a custom field, you can choose whether it should be public or private when defining
the schema.
Update a user's photo
To update a user's photo, use the following PUT
request and include the authorization described in Authorize requests. The userKey
can be the user's primary email address, the user id
, or any of the user aliases' emails. For the request and response properties, see the API Reference.
PUT https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail
In this example, liz@example.com photo is updated:
PUT https://admin.googleapis.com/admin/directory/v1/users/liz@example.com/photos/thumbnail
{
"photoData": "web safe base64 encoded photo data"
}
When updating a photo, the height
and width
are ignored by the API.
JSON Response
A successful response returns an HTTP 200 status code.
{ "kind": "directory#user#photo", "id": "the unique user id", "primaryEmail": "liz@example.com", "mimeType": "the photo mime type", "height": "the photo height in pixels", "width": "the photo width in pixels", "photoData": "web safe base64 encoded photo data" }
Delete a user's photo
To delete a user's photo, use the following DELETE
request and include the authorization described in Authorize requests. The userKey
can be the user's primary email address, the user id
, or any of the user aliases' emails. For the request and response properties, see the API Reference.
DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey/photos/thumbnail
Once deleted, the user's photo is not shown. Wherever a user's photo is required, a silhouette will be shown instead.
Delete a user account
To delete a user account, use the following DELETE
request and include the authorization described in Authorize requests. The userKey
can be the user's primary email address, the unique user id
, or one of the user's alias email addresses. For the request and response properties, see the API Reference.
DELETE https://admin.googleapis.com/admin/directory/v1/users/userKey
In this example, the liz@example.com user account is deleted:
DELETE https://admin.googleapis.com/admin/directory/v1/users/liz@example.com
A successful response only returns an HTTP 200 status code.
Important things to consider before deleting a user:
- The deleted user will no longer be able to log in.
- For more information about user account deletion, please refer to the administration help center.
Undelete a user account
A user deleted in the last 5 days must meet certain conditions before the user's account can be restored.
To undelete a user account, use the following POST
request and include the authorization described in Authorize requests. The userKey
is the unique user id
found in the response of the Retrieve users deleted within the past 5 days operation. The user's primary email address or one of the user's alias email addresses cannot be used in the userKey
for this operation. For the request and response properties, see the API Reference.
POST https://admin.googleapis.com/admin/directory/v1/users/userKey/undelete
In this example, the user, liz@example.com, is undeleted. All of this user's previous account properties are restored:
POST https://admin.googleapis.com/admin/directory/v1/users/12309329403209438205/undelete
A successful response only returns an HTTP 204 status code. To see the undeleted user's account, use the Retrieve a user operation.