Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.dev

User Object

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

getUserList(params?: UserListParams)

Retrieves user list:

1

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

1

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

1

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

getUser(userId)

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

1

getCount(params?: UserCountParams)

Retrieves the total number of users.

1

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

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:

NameTypeDescription
externalIdstring

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.

usernamestring

The username to give to the user. Must be unique across your instance.

passwordstring

The plaintext password to give the user.

firstNamestring

User's first name.

lastNamestring

User's last name.

publicMetadataRecord<string, unknown>

Metadata saved on the user, that is visible to both your Frontend and Backend APIs.

privateMetadataRecord<string, unknown>

Metadata saved on the user that is only visible to your Backend API.

unsafeMetadataRecord<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

Supported user attributes for update are:

NameTypeDescription
firstNamestring

User's first name.

lastNamestring

User's last name.

passwordstring

The plaintext password to give the user.

primaryEmailAddressIDstring

Email address that will replays user's current primary email address. Must be unique across your instance.

primaryPhoneNumberIDstring

Phone number that will replace user's current primary phone number. Must be unique across your instance.

publicMetadataRecord<string, unknown>

Metadata saved on the user, that is visible to both your Frontend and Backend APIs.

privateMetadataRecord<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

Was this helpful?

Clerk © 2022