Manage Users
There may be cases where you want to provide users with either direct or Single Sign On access to the Yext platform. For example, you may want to give a franchisee owner direct access to his or her Location data. However, you may also want to customize the kind of access users have — perhaps they should only be able to access data for the locations they manage, or maybe they should only be able to use certain sections of the dashboard. Fortunately, the User API can help you to accomplish both of these tasks.

NOTE: This API requires working with your Yext Account Manager to create custom User Roles.

Retrieve Available Roles

Before we work with the User API, let us see what Roles are available for your App using the Roles: Get request. Roles dictate what features a User can use and access. They can be applied to a User on an Account level, Location level, or Folder level.

GEThttps://api.yext.com/v2/accounts/{accountId}/roles?v=YYYYMMDD&api_key=API_KEY

If successful, the response will return a count and a list of Role objects. If you have no Roles defined, then the Role list will be empty. Please speak with your Yext representative to see if you can have custom Roles added to your account.

If you have Roles, the response field will return something like this:
{
	"count": 1,
	"roles": [{
		"id": 1,
		"name": "Full Control"
	}]
}

Create a User

Now that we know what Roles are available for your Account, let’s create a new User with the User: Create Request.

POSThttps://api.yext.com/v2/accounts/{accountId}/users?v=YYYYMMDD&api_key=API_KEY

{
	"id": "testUser",
	"firstName": "John",
	"lastName": "Doe",
	"username": "johnDoeSuperTest",
	"emailAddress": "john.doe@emails.com",
	"phoneNumber": "201-888-8888",
	"password": "aljnt23q;ob5t",
	"acl": [{
		"roleId": "1",
		"roleName": "Full Control",
		"on": "Your account id",
		"accountId": "You account id",
		"onType": "ACCOUNT"
	}]
}
If the request is successful, you will get a 201 response containing the User id you provided.

Retrieve Users

Let’s confirm the User you created with the User: Get request.

GEThttps://api.yext.com/v2/accounts/[accountId]/users/[userId]?v=YYYYMMDD&api_key=API_KEY

The response will return a User object with the data you submitted earlier.
{
	"id": "testUser",
	"firstName": "John",
	"lastName": "Doe",
	"username": "johnDoeSuperTest",
	"emailAddress": "john.doe@emails.com",
	"phoneNumber": "201-888-8888",
	"password": "aljnt23q;ob5t",
	"acl": [{
		"roleId": "1",
		"roleName": "Full Control",
		"on": "Your account id",
		"accountId": "[YOUR ACCOUNT ID]",
		"onType": "ACCOUNT"
	}],
	"sso": false
}

Update a User’s Information

Let’s try editing the User you created. In the request below, we will update the User’s phone number to a new one. Note you must include the id, firstName, lastName, username, emailAddress, and phone fields when editing a User.

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

{ 
	"id": "testUser",
	"firstName": "John",
	"lastName": "Doe",
	"username": "johnDoeSuperTest",
	"emailAddress": "john.doe@emails.com",
	"phoneNumber": "2013230000" 
}
Similar to the User: Create request, the response will return a 200 response with the User id in the response body like this:
{
        "id": "testUser"
}
Try making a few more update calls to see what other User details you can edit.

Update a User’s Password

You may have noticed during your testing that the User: Update call does not let you update the User’s password. For security purposes, you must send the following request to assign a new password to a User:

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

{
        "newPassword": "myNewPassword"
}
The request should return a 200 response with no response body. Now try updating the password to something a bit more secure and harder to guess.

Delete a User

While it’s great that you can add and edit Users via the API, there may be times when you need to remove a User. For example, if someone is no longer associated with your business, you probably don’t want them to be able to edit or view your businesses’ Location data. You can remove the User’s access with the User: Delete request:

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

This request will return a 200 response with an empty response body and is not reversible, so please be careful when removing Users!