The Directory API provides programmatic methods for creating, updating, anddeleting users. You can also get information about individualusers or lists of users who meet specified criteria. Following are examples ofsome basic user operations.

Create a user account

You can add a user account to any of your Google Workspace account's domains. Before adding a user account, confirm thedomain ownership.

If you upgraded your personal Gmail account to a business email account with your own domain name, you can't create new user accounts until you unlock additional Google Workspace settings. For details, seeG Suite business email accounts updated to G Suite Basic.

To create a user account using one of your domains, use the followingPOST request and include the authorization described inLearn about authentication and authorization. You can view the available scopes for the Directory API in theOAuth 2.0 scopes list. For the request query string properties, see theusers.insert() method.

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 theAPI 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"}],"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 HTTP503 responses from the API server indicating that your quota has been exceeded. If you get these responses, use anexponential 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 asisAdmin, 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 theadministration help center. For more infomation about moving a user to a different organization, seeUpdate a user.
• Apassword is required for new user accounts. If ahashFunction is specified, the password must be a valid hash key. If it's not specified, the password should be in clear text and between 8–100 ASCII characters. For more information, see theAPI 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 theAPI 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 theAPI 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. SeeFind 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. SeeShare documents with visitors.

A successful response returns anHTTP 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 followingPUT request and include theauthorization described inAuthorize requests. TheuserKey can be the user's primary email address, the unique userid, or oneof the user's alias email addresses.

PUT https://admin.googleapis.com/admin/directory/v1/users/userKey

Both the request and response body contain an instance ofUser. However, theDirectory API supportspatch semantics, so youonly need to submit the updated fields in your request.

{"name":{"givenName":"Elizabeth","familyName":"Smith"},"emails":[{"address":"liz@example.com","type":"work","primary":true}]}

{"name":{"givenName":"Liz",},"emails":[{"address":"liz@example.com","type":"work","primary":true},{"address":"liz@home.com","type":"home"}]}

A successful response returns anHTTP 200 status codeand aUserresource with the updated fields.

Be aware of the following when updating a user's account name:

• Renaming a user account changes the user's primary email address and thedomain used when retrieving this user's information. Before renaming a user,we recommend that you sign out the user from all browser sessions andservices.
• The process of renaming a user account can take up to 10 minutes to propagateacross all services.
• When you rename a user, the old user name is retained as an alias to ensurecontinuous mail delivery in the case of email forwarding settings, and is notavailable as a new user name.
• In general, we also recommend not using the user email address as a key forpersistent data because the email address is subject to change.
• For a full list of the effects of renaming a user across Google Workspaceapps, see theAdmin help center.

Make a user an administrator

To make user into a super administrator, use the followingPOST request and include the authorization described inAuthorize requests. TheuserKey can be the user's primary email address, the unique userid, or one of the user's alias email addresses. For the request and response properties, seeAPI Reference. For more information about a super administrator, see theadministration help center.

POST https://admin.googleapis.com/admin/directory/v1/users/userKey/makeAdmin

JSON request

In this example, user whoseuserKey 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 anHTTP 200 status code.

Manage user relationships

The Directory API uses therelations field to define different typesof relationships between users. In a business setting, people commonly usethis field for manager-employee and assistant relationships, but the fieldsupports many other types as well. The relationship displays inthe "Related people" card of the user in any Google Workspace application thatsupports the card. For examples of where the card is visible, seeAdd information to a user’s Directory profile.

Create a relationship between users

You can define a relationship in only one direction, starting fromthe "owning" user, whose record includes therelations field. Thetypedescribes the relationship of the other person to the owning user. Forexample, in a manager-employee relationship, the employee is the owning user andyou add arelations field to their account with themanager type. Forallowed types, see theUser object reference.

Set up the relationship bycreating orupdatingthe owning user with a JSON request body that includes therelations field.You can create multiple relationships in one request.

{"relations":[{"value":"EMAIL_ADDRESS_RELATION_1","type":"manager"},{"value":"EMAIL_ADDRESS_RELATION_2","type":"dotted_line_manager"}]}

Update or delete a relationship

You can only updated therelations field can only be updated as a whole—youcan't address the individual people listed to change the relationship type orto remove them. In the example above, to remove the existing managerrelationship and make the dotted-line manager the owning user's manager, updatethe owning user's account with all of the field's values as you now want them.

{"relations":[{"value":"EMAIL_ADDRESS_RELATION_2","type":"manager"}]}

To remove all of the owning user's relationships, setrelations to be empty:

{"relations":[]}

Retrieve a user

To retrieve a user, use the followingGET request and include the authorization described inAuthorize requests. TheuserKey can be the user's primary email address, the unique userid, or one of the user's alias email addresses. For the request and response properties, see theAPI 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 anHTTP 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"}],"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 followingGET request and include the authorization described inAuthorize 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 theAPI 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 anextPageToken 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 anHTTP 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"}],"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"}],"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 followingGET request and include the authorization described inAuthorize 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

• Thecustomer query string is themy_customer or thecustomerId value.
• Use the stringmy_customer to represent your account'scustomerId.
• As a reseller administrator, use the resold customer'scustomerId. For thecustomerId, use the account's primary domain name in theRetrieve all users in a domain operation's request. The resulting response has thecustomerId value.
• The optionalorderBy 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 optionalquery query string allows searching over many fields in a userprofile, including both core and custom fields. SeeSearch for Users for examples.

For the request and response properties, see theAPI Reference.

In this example, an account administrator is requesting all users in the account be returned with one user entry on each response page. ThenextPageToken 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 thecustomerId value ofC03az79cb.

GET https://admin.googleapis.com/admin/directory/v1/users?customer=C03az79cb&maxResults=1

JSON response

A successful response returns anHTTP 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"}],"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"}],"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"}],"aliases":["my_alias@example.com"],"nonEditableAliases":["other_alias@test.com"],"customerId":"C03az79cb","orgUnitPath":"/","isMailboxSetup":true,"includeInGlobalAddressList":true}],"nextPageToken":"NNNNN"}

Retrieve recently deleted users

To retrieve all users deleted within the span of the last 20 days from an account or from one of the account's domains, use the followingGET requests and include the authorization described inAuthorize requests. To undelete a user, seeUndelete a user.

To retrieve users deleted within the span of the last 20 days from the account's primary domain or a subdomain, use the followingGET request. Thedomain query string is the domain's primary domain name. For the user request and response properties, see theAPI 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=true

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

• Thecustomer query string is themy_customer or thecustomerId value.
• As an account administrator, use the stringmy_customer to represent your account'scustomerId.
• As a reseller administrator, use the resold customer'scustomerId. For thecustomerId, use the account's primary domain name in theRetrieve all users in a domain operation's request. The resulting response has thecustomerId value.

For the request and response properties, see theAPI 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 anHTTP 200 status code. Along with the status code, the response returns all the account users deleted within the last 20 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 latest Google profile photo. To retrieve the user's lastest photo, use the followingGET request and include the authorization described inAuthorize requests. TheuserKey can be the user's primary email address, the userid, or any of the user's alias emails. For the request and response properties, see theAPI 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 anHTTP 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 theRFC 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, theGoogle Closure Library includesBase64 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 ausers.get orusers.list request with theviewType parameter equal todomain_public to retrieve a user's public profile. The scopehttps://www.googleapis.com/auth/admin.directory.user.readonly is ideal for this use case.

Thedomain_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 followingPUT request and include the authorization described inAuthorize requests. TheuserKey can be the user's primary email address, the userid, or any of the user aliases' emails. For the request and response properties, see theAPI 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, theheight andwidth are ignored by the API.

JSON Response

A successful response returns anHTTP 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 followingDELETE request and include the authorization described inAuthorize requests. TheuserKey can be the user's primary email address, the userid, or any of the user aliases' emails. For the request and response properties, see theAPI 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 followingDELETE request and include the authorization described inAuthorize requests. TheuserKey can be the user's primary email address, the unique userid, or one of the user's alias email addresses. For the request and response properties, see theAPI 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 anHTTP 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 theadministration help center.

Note: If the user you're trying to delete is under legal hold using Google Vault, you can't delete them and the API returns an error: "Could not delete user due to legal hold. Please contact your Vault administrator."

Undelete a user account

A user deleted in the last 20 days must meet certainconditions before the user's account can be restored.

To undelete a user account, use the followingPOST request and include the authorization described inAuthorize requests. TheuserKey is the unique userid found in the response of theRetrieve users deleted within the past 20 days operation. The user's primary email address or one of the user's alias email addressescannot be used in theuserKey for this operation. For the request and response properties, see theAPI Reference.

POST https://admin.googleapis.com/admin/directory/v1/users/userKey/undelete

POST https://admin.googleapis.com/admin/directory/v1/users/12309329403209438205/undelete

A successful response only returns anHTTP 204 status code. To see the undeleted user's account, use theRetrieve a user operation.