The Account Settings API lets you manage users and their access controls programmatically, so you can build integrations to create, retrieve, update, and delete users without using the Yext platform UI.

Each user is represented by a user object containing identifying information such as email address, username, and name, along with the access controls assigned to that user.

Create a User

Use the Users: Create endpoint to create a new user.

The request body requires the following fields:

• id
• firstName
• lastName
• emailAddress

To allow the new user to log into the Yext platform, include at least one Access Control (ACL) in the acl field. An Access Control consists of:

• roleId and roleName: Identify the role to assign. Retrieve available roles with GET /accounts/{accountId}/roles.
• onType: The type of object the role applies to. Set to ACCOUNT, ENTITY, or FOLDER.
• on: The ID of the object the role applies to. This matches the account ID, entity ID, or folder ID, depending on the onType value.
• accountId: The ID of the Yext account under which the user is created.

Example request: Create a user with the built-in Account Manager role applied to the full account.

POST https://api.yextapis.com/v2/accounts/{accountId}/users?v=YYYYMMDD&api_key=API_KEY
{
  "id": "testUser",
  "firstName": "John",
  "lastName": "Doe",
  "username": "johnDoeSuperTest",
  "emailAddress": "john.doe@emails.com",
  "acl": [{
    "roleId": "20",
    "roleName": "Account Manager",
    "on": "Your account id",
    "accountId": "Your account id",
    "onType": "ACCOUNT"
  }]
}

A successful request returns a 201 response containing the user id.

Retrieve Users

Retrieve users with either of the following endpoints:

• Users: List: Retrieves all users in the account.
• Users: Get: Retrieves details for a specific user.

Example request: Retrieve a specific user.

GET https://api.yextapis.com/v2/accounts/{accountId}/users/{userId}?v=YYYYMMDD&api_key=API_KEY

The response returns a user object with the account's stored data for that user, including their acl and sso status.

Update a User

Update user information

Use the Users: Update endpoint to update a user's information. Include the id, firstName, lastName, username, and emailAddress fields with each request, even for fields that aren't changing.

PUT https://api.yextapis.com/v2/accounts/{accountId}/users/{userId}?v=YYYYMMDD&api_key=API_KEY
{
  "id": "testUser",
  "firstName": "John",
  "lastName": "Doehring",
  "username": "johnDoeSuperTest",
  "emailAddress": "john.doe@emails.com"
}

A successful request returns a 200 response containing the user id.

Update a user's password

The Users: Update endpoint doesn't update a user's password. Use a separate endpoint to assign a new password:

PUT https://api.yextapis.com/v2/accounts/{accountId}/users/{userId}/password?v=YYYYMMDD&api_key=API_KEY
{
  "newPassword": "myNewPassword"
}

A successful request returns a 200 response with no response body.

Delete a User

Use the Users: Delete endpoint to remove a user's access, for example, when someone is no longer associated with your business.

DELETE https://api.yextapis.com/v2/accounts/{accountId}/users/{userId}?v=YYYYMMDD&api_key=API_KEY

This action isn't reversible. A successful request returns a 200 response with no response body.