User Object

User operations are exposed by the users sub-api (clerkClient.users)

getUserList(params?: UserListParams)

Retrieves user list:

1
const users = await clerkClient.users.getUserList();

1
const users = await clerkClient.users.getUserList();

Retrieves user list that is ordered and filtered by the number of results. More params can be found at the UserListParams definition.

1
const sessions = await clerkClient.users.getUserList({
2
  orderBy: '-created_at',
3
  limit: 10,
4
});

1
const sessions = await clerkClient.users.getUserList({
2
  orderBy: '-created_at',
3
  limit: 10,
4
});

Retrieves user list that is filtered by the given email addresses and phone numbers:

1
const emailAddress = ['email1@clerk.dev', 'email2@clerk.dev'];
2
const phoneNumber = ['+12025550108'];
3
const sessions = await clerkClient.users.getUserList({ emailAddress, phoneNumber });

If these filters are included, the response will contain only users that own any of these emails and/or phone numbers.

To do a broader match through a list of fields you can use the query parameter which partially matches the fields: userId, emailAddress, phoneNumber, username, web3Wallet, firstName and lastName.

// Matches users with the string `test` matched in multiple user attributes.1
const usersMatchingTest = await clerkClient.users.getUserList({
2
  query: 'test',
3
});

getUser(userId)

Retrieves a single user by their id, if the id is valid. Throws an error otherwise.

1
const userId = 'my-user-id';
2
const user = await clerkClient.users.getUser(userId);

getCount(params?: UserCountParams)

Retrieves the total number of users.

1
const totalUsers = await clerkClient.users.getCount();

This can also be flitered down by adding parameters of the type UserCountParams

const totalUsersMatchingTest = await clerkClient.users.getCount({ query: 'test' });

createUser(params)

Creates a user. Your user management settings determine how you should setup your user model.

Any email address and phone number created using this method will be automatically marked as verified.

Available parameters are:

Name	Type	Description
externalId	string	The ID of the user you use in in your external systems. Must be unique across your instance.
emailAddress[]	string	Email addresses to add to the user. Must be unique across your instance. The first email address will be set as the users primary email address.
phoneNumber[]	string	Phone numbers that will be added to the user. Must be unique across your instance. The first phone number will be set as the users primary phone number.
username	string	The username to give to the user. Must be unique across your instance.
password	string	The plaintext password to give the user.
firstName	string	User's first name.
lastName	string	User's last name.
publicMetadata	Record<string, unknown>	Metadata saved on the user, that is visible to both your Frontend and Backend APIs.
privateMetadata	Record<string, unknown>	Metadata saved on the user that is only visible to your Backend API.
unsafeMetadata	Record<string, unknown>	Metadata saved on the user, that can be updated from both the Frontend and Backend APIs. Note: Since this data can be modified from the frontend, it is not guaranteed to be safe.

updateUser(userId, params)

Updates a user with a given id with attribute values provided in a params object.

The provided id must be valid, otherwise an error will be thrown.

1
const userId = 'my-user-id';
2
const params = { firstName: 'John', lastName: 'Wick' }; 
3
// See table below for all supported attributes
4
const user = await clerkClient.users.updateUser(userId, params);

Supported user attributes for update are:

Name	Type	Description
firstName	string	User's first name.
lastName	string	User's last name.
password	string	The plaintext password to give the user.
primaryEmailAddressID	string	Email address that will replays user's current primary email address. Must be unique across your instance.
primaryPhoneNumberID	string	Phone number that will replace user's current primary phone number. Must be unique across your instance.
publicMetadata	Record<string, unknown>	Metadata saved on the user, that is visible to both your Frontend and Backend APIs.
privateMetadata	Record<string, unknown>	Metadata saved on the user, that is only visible to your Backend API.

deleteUser(userId)

Deletes a user given a valid id. Throws an error otherwise.

1
const userId = 'my-user-id';
2
const user = await clerkClient.users.deleteUser(userId);