`createUser()`

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.


function createUser: (params: CreateUserParams) => Promise<User>;

`CreateUserParams`

Name	Type	Description
`externalId?`	`string`	The ID of the user you use 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`	The user's first name.
`lastName?`	`string`	The 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.

`createUser()` example

In this example, the application's instance settings have been configured to use email and password as the primary authentication method.

You can see that the returned response is the created User object, with firstName as "Test", lastName as "User", and emailAddress as an array of email addresses, which includes 'testclerk123@gmail.com'.


const response = await clerkClient.users.createUser({
  firstName: "Test",
  lastName: "User",
  emailAddress: [ "testclerk123@gmail.com" ],
  password: "password"
})
 
console.log(response);
/*
_User {
  id: 'user_2cSSCzV7948rhPJMsY601tXsEU4',
  passwordEnabled: true,
  totpEnabled: false,
  backupCodeEnabled: false,
  twoFactorEnabled: false,
  banned: false,
  createdAt: 1708103362688,
  updatedAt: 1708103362701,
  imageUrl: 'https://img.clerk.com/eyJ0eXBlIjoiZGVmYXVsdCIsImlpZCI6Imluc18yVjdKRFdyclJwRmZFZTlqQUM2dWpSMG8xSlQiLCJyaWQiOiJ1c2VyXzJjU1NDelY3OTQ4cmhQSk1zWTYwMXRYc0VVNCIsImluaXRpYWxzIjoiVFUifQ',
  hasImage: false,
  primaryEmailAddressId: 'idn_2cSSCuFhU35F5u5Labwtmj7xU6B',
  primaryPhoneNumberId: null,
  primaryWeb3WalletId: null,
  lastSignInAt: null,
  externalId: null,
  username: null,
  firstName: 'Test',
  lastName: 'User',
  publicMetadata: {},
  privateMetadata: {},
  unsafeMetadata: {},
  emailAddresses: [
    _EmailAddress {
      id: 'idn_2cSSCuFhU35F5u5Labwtmj7xU6B',
      emailAddress: 'testclerk123@gmail.com',
      verification: [_Verification],
      linkedTo: []
    }
  ],
  phoneNumbers: [],
  web3Wallets: [],
  externalAccounts: [],
  lastActiveAt: null,
  createOrganizationEnabled: true
}
*/

Backend API (BAPI) endpoint

This method in the SDK is a wrapper around the BAPI endpoint POST/users. See the BAPI reference(opens in a new tab) for more details.

Last updated on September 8, 2023

CreateUserParams

createUser() example

Backend API (BAPI) endpoint

`CreateUserParams`

`createUser()` example