Create user metadata

These methods on the User object help you create data for the user, such as createEmailAddress() and createPhoneNumber().

The following examples assume that you have followed the quickstart in order to add Clerk to your JavaScript application.

`createEmailAddress()`

Adds an email address for the user. A new EmailAddress will be created and associated with the user.

Email address must be enabled as an identifier in your Clerk settings for this method to work. See the Identifiers section to learn more.


function createEmailAddress: (params: CreateEmailAddressParams) => Promise<EmailAddress>;

`CreateEmailAddressParams`

Name	Type	Description
`email`	`string`	The value of the email address

`createEmailAddress()` returns

Type	Description
`Promise<EmailAddress>`	This method returns a `Promise` which resolves to the email address created for the user.

`createEmailAddress()` example

The following example adds test@test.com as an email address for the user. If the user is not signed in, the user will be prompted to sign in.

main.js
import Clerk from '@clerk/clerk-js';
 
// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('{{pub_key}}');
await clerk.load();
 
if (clerk.user) {
  const email = "test@test.com";
 
  clerk.user.createEmailAddress({ email })
    .then((response) => console.log(response))
    .catch((error) => console.log("An error occurred:", error.errors));
} else {
  document.getElementById("app").innerHTML = `
    <div id="sign-in"></div>
  `;
 
  const signInDiv = document.getElementById("sign-in");
 
  clerk.mountSignIn(signInDiv);
}

index.html
  <div id="app"></div>
 
  <!-- Initialize Clerk with your
  Clerk Publishable key and Frontend API URL -->
  <script
    async
    crossorigin="anonymous"
    data-clerk-publishable-key="{{pub_key}}"
    src="https://{{fapi_url}}/npm/@clerk/clerk-js@latest/dist/clerk.browser.js"
    type="text/javascript"
  ></script>
 
  <script>
    window.addEventListener("load", async function () {
      await Clerk.load();
 
      if (Clerk.user) {
        const email = "test@test.com";
 
        Clerk.user.createEmailAddress({ email })
          .then((response) => console.log(response))
          .catch((error) => console.log("An error occurred:", error.errors));
      } else {
        document.getElementById("app").innerHTML = `
            <div id="sign-in"></div>
          `;
 
        const signInDiv = document.getElementById("sign-in");
 
        Clerk.mountSignIn(signInDiv);
      }
    });
  </script>

`createPhoneNumber()`

Adds a phone number for the user. A new PhoneNumber will be created and associated with the user.

Phone number must be enabled as an identifier in your Clerk settings for this method to work. See the Identifiers section to learn more.


function createPhoneNumber: (params: CreatePhoneNumberParams) => Promise<PhoneNumber>;

`CreatePhoneNumberParams`

Name	Type	Description
`phoneNumber`	`string`	The value of the phone number, in E.164(opens in a new tab) format.

`createPhoneNumber()` returns

Type	Description
`Promise<PhoneNumber>`	This method returns a `Promise` which resolves to the `PhoneNumber` created for the user.

`createPhoneNumber()` example

The following example adds 15551234567 as a phone number for the user. If the user is not signed in, the user will be prompted to sign in.

main.js
import Clerk from '@clerk/clerk-js';
 
// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('{{pub_key}}');
await clerk.load();
 
if (clerk.user) {
  const phoneNumber = "15551234567";
 
  clerk.user.createPhoneNumber({ phoneNumber })
    .then((response) => console.log(response))
    .catch((error) => console.log("An error occurred:", error.errors));
} else {
  document.getElementById("app").innerHTML = `
    <div id="sign-in"></div>
  `;
 
  const signInDiv = document.getElementById("sign-in");
 
  clerk.mountSignIn(signInDiv);
}

index.html
  <div id="app"></div>
 
  <!-- Initialize Clerk with your
  Clerk Publishable key and Frontend API URL -->
  <script
    async
    crossorigin="anonymous"
    data-clerk-publishable-key="{{pub_key}}"
    src="https://{{fapi_url}}/npm/@clerk/clerk-js@latest/dist/clerk.browser.js"
    type="text/javascript"
  ></script>
 
  <script>
    window.addEventListener("load", async function () {
      await Clerk.load();
 
      if (Clerk.user) {
        const phoneNumber = "15551234567";
 
        Clerk.user.createPhoneNumber({ phoneNumber })
          .then((response) => console.log(response))
          .catch((error) => console.log("An error occurred:", error.errors));
      } else {
        document.getElementById("app").innerHTML = `
            <div id="sign-in"></div>
          `;
 
        const signInDiv = document.getElementById("sign-in");
 
        Clerk.mountSignIn(signInDiv);
      }
    });
  </script>

`createWeb3Wallet()`

Adds a web3 wallet for the user. A new Web3Wallet< will be created and associated with the user.

A Web3 provider must be enabled in your Clerk settings for this method to work. See the Web3 authentication section to learn more.


function createWeb3Wallet: (params: CreateWeb3WalletParams) => Promise<Web3Wallet>;

`CreateWeb3WalletParams`

Name	Type	Description
`web3Wallet`	`string`	In Ethereum(opens in a new tab), the address is made up of `0x + 40` hexadecimal characters.

`createWeb3Wallet()` returns

Type	Description
`Promise<Web3Wallet>`	This method returns a `Promise` which resolves to the `Web3Wallet` created for the user.

`createWeb3Wallet()` example

The following example adds 0x0123456789ABCDEF0123456789ABCDEF01234567 as a web3 wallet for the user. If the user is not signed in, the user will be prompted to sign in.

main.js
import Clerk from '@clerk/clerk-js';
 
// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('{{pub_key}}');
await clerk.load();
 
if (clerk.user) {
  const web3Wallet = "0x0123456789ABCDEF0123456789ABCDEF01234567";
 
  clerk.user.createWeb3Wallet({ web3Wallet })
    .then((response) => console.log(response))
    .catch((error) => console.log("An error occurred:", error.errors));
} else {
  document.getElementById("app").innerHTML = `
    <div id="sign-in"></div>
  `;
 
  const signInDiv = document.getElementById("sign-in");
 
  clerk.mountSignIn(signInDiv);
}

index.html
  <div id="app"></div>
 
  <!-- Initialize Clerk with your
  Clerk Publishable key and Frontend API URL -->
  <script
    async
    crossorigin="anonymous"
    data-clerk-publishable-key="{{pub_key}}"
    src="https://{{fapi_url}}/npm/@clerk/clerk-js@latest/dist/clerk.browser.js"
    type="text/javascript"
  ></script>
 
  <script>
    window.addEventListener("load", async function () {
      await Clerk.load();
 
      if (Clerk.user) {
        const web3Wallet = "0x0123456789ABCDEF0123456789ABCDEF01234567";
 
        Clerk.user.createWeb3Wallet({ web3Wallet })
          .then((response) => console.log(response))
          .catch((error) => console.log("An error occurred:", error.errors));
      } else {
        document.getElementById("app").innerHTML = `
            <div id="sign-in"></div>
          `;
 
        const signInDiv = document.getElementById("sign-in");
 
        Clerk.mountSignIn(signInDiv);
      }
    });
  </script>

`createExternalAccount()`

Adds an external account for the user. A new ExternalAccount will be created and associated with the user. This method is useful if you want to allow an already signed-in user to connect their account with an external provider, such as Facebook, GitHub, etc., so that they can sign in with that provider in the future.

The social provider that you want to connect to must be enabled in your Clerk settings for this method to work. See the Social connections (OAuth) section to learn more.


function createExternalAccount: (params: CreateExternalAccountParams) => Promise<ExternalAccount>;

`CreateExternalAccountParams`

Name	Type	Description
`strategy`	`OAuthStrategy`	The strategy corresponding to the OAuth provider. For example: `oauth_facebook`, `oauth_github`, etc.
`redirectUrl?`	`string`	The URL to redirect back to once the OAuth flow has succeeded or failed.
`additionalScopes?`	`string[]`	Any additional scopes you would like your user to be prompted to approve.

`createExternalAccount()` returns

Type	Description
`Promise<ExternalAccount>`	This method returns a `Promise` which resolves to the `ExternalAccount` created for the user.

`createExternalAccount()` example

After calling createExternalAccount, the initial state of the returned ExternalAccount will be unverified. To initiate the connection with the external provider, redirect the user to the externalAccount.verification.externalVerificationRedirectURL contained in the result of createExternalAccount.

Upon return, inspect within the user.externalAccounts the entry that corresponds to the requested strategy:

If the connection succeeded, then externalAccount.verification.status will be verified.
If the connection failed, then the externalAccount.verification.status will not be verified and the externalAccount.verification.error will contain the error encountered, which you can present to the user. To learn more about the properties available on verification, see the verification reference.

The following example demonstrates how to add a Notion account as an external account for the user. When the user selects the "Add Notion as a social connection" button, the user will be redirected to Notion to connect their account. After connecting their account, they will be redirected to the / route of your application, and the status of the connection will be displayed.

For the following example, your HTML file should look like this:

index.html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Clerk + JavaScript App</title>
  </head>
  <body>
    <div id="app"></div>
 
    <p>
      Notion verification status:
      <span id="notion-status"></span>
    </p>
    <button id="add-notion">Add Notion as a social connection</button>
 
    <script type="module" src="/main.js"></script>
  </body>
</html>

And your JavaScript file should look like this:

main.js
import Clerk from '@clerk/clerk-js';
 
// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('{{pub_key}}');
await clerk.load();
 
if (clerk.user) {
  // Find the external account for the provider
  const externalAccount = clerk.user.externalAccounts.find(
    (p) => p.provider === "notion"
  );
  // If the external account exists, display its status
  document.getElementById("notion-status").innerHTML =
    externalAccount.verification.status;
 
  // When the button is clicked, initiate the connection with the provider
  document.getElementById("add-notion").addEventListener("click", async () => {
    clerk.user
      .createExternalAccount({ strategy: "oauth_notion", redirect_url: "/" })
      .then((externalAccount) => {
        window.location.href =
          externalAccount.verification.externalVerificationRedirectURL;
      })
      .catch((error) => {
        console.log("An error occurred:", error.errors);
      });
  });
} else {
  document.getElementById("app").innerHTML = `
    <div id="sign-in"></div>
  `;
 
  const signInDiv = document.getElementById("sign-in");
 
  clerk.mountSignIn(signInDiv);
}

index.html
  <div id="app"></div>
  <p>
    Notion verification status:
    <span id="notion-status"></span>
  </p>
  <button id="add-notion">Add Notion as a social connection</button>
 
  <!-- Initialize Clerk with your
  Clerk Publishable key and Frontend API URL -->
  <script
    async
    crossorigin="anonymous"
    data-clerk-publishable-key="{{pub_key}}"
    src="https://{{fapi_url}}/npm/@clerk/clerk-js@latest/dist/clerk.browser.js"
    type="text/javascript"
  ></script>
 
  <script>
    window.addEventListener("load", async function () {
      await Clerk.load();
 
      if (Clerk.user) {
        // Find the external account for the provider
        const externalAccount = Clerk.user.externalAccounts.find(
          (p) => p.provider === "notion"
        );
        // If the external account exists, display its status
        document.getElementById("notion-status").innerHTML =
          externalAccount.verification.status;
 
        // When the button is clicked, initiate the connection with the provider
        document.getElementById("add-notion").addEventListener("click", async () => {
          Clerk.user
            .createExternalAccount({ strategy: "oauth_notion", redirect_url: "/" })
            .then((externalAccount) => {
              window.location.href =
                externalAccount.verification.externalVerificationRedirectURL;
            })
            .catch((error) => {
              console.log("An error occurred:", error.errors);
            });
        });
      } else {
        document.getElementById("app").innerHTML = `
            <div id="sign-in"></div>
          `;
 
        const signInDiv = document.getElementById("sign-in");
 
        Clerk.mountSignIn(signInDiv);
      }
    });
  </script>

Last updated on March 26, 2024

createEmailAddress()

CreateEmailAddressParams

createEmailAddress() returns

createEmailAddress() example

createPhoneNumber()

CreatePhoneNumberParams

createPhoneNumber() returns

createPhoneNumber() example

createWeb3Wallet()

CreateWeb3WalletParams

createWeb3Wallet() returns

createWeb3Wallet() example

createExternalAccount()

CreateExternalAccountParams

createExternalAccount() returns

createExternalAccount() example