Skip to main content
Docs

Organization invitation methods

These methods on the Organization object allow you to manage the invitations to an organization.

The following examples assume:

getInvitations()

Retrieves the list of invitations for the currently active organization.

function getInvitations(params?: GetInvitationsParams): Promise<ClerkPaginatedResponse<OrganizationInvitation>>;
  • Name
    initialPage?
    Type
    number
    Description

    A number that can be used to skip the first n-1 pages. For example, if initialPage is set to 10, it is will skip the first 9 pages and will fetch the 10th page.

  • Name
    pageSize?
    Type
    number
    Description

    A number that indicates the maximum number of results that should be returned for a specific page.

  • Name
    status?
    Type
    'pending' | 'accepted' | 'revoked'
    Description

    The status an invitation can have.

getInvitations() returns

TypeDescription
Promise<ClerkPaginatedResponse<OrganizationInvitation>>This method returns a Promise that resolves to a ClerkPaginatedResponse of OrganizationInvitation objects.

getInvitations() example

main.js
import Clerk from '@clerk/clerk-js';

// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('YOUR_PUBLISHABLE_KEY');
await clerk.load();

if (clerk.user) {
  // Check for an active organization
  if (clerk.organization) {
    await clerk.organization.getInvitations()
      .then((res) => console.log(res))
      .catch((error) => console.log("An error occurred:", error.errors));
  } else {
    // If there is no active organization,
    // mount Clerk's <OrganizationSwitcher />
    // to allow the user to set an organization as active
    document.getElementById("app").innerHTML = `
      <h2>Select an organization to set it as active</h2>
      <div id="org-switcher"></div>
    `;

    const orgSwitcherDiv = document.getElementById("org-switcher");

    clerk.mountOrganizationSwitcher(orgSwitcherDiv);
  }
} else {
  document.getElementById("app").innerHTML = `
    <div id="sign-in"></div>
  `;

  const signInDiv = document.getElementById("sign-in");

  clerk.mountSignIn(signInDiv);
}

Caution

This method is deprecated in favor of getInvitations().

Retrieves a list of organization invitations that have not yet been accepted.

function getPendingInvitations(params?: GetPendingInvitationsParams): Promise<OrganizationInvitation[]>;
  • Name
    limit
    Type
    number
    Description

    Limit of the results returned.

  • Name
    offset
    Type
    number
    Description

    The offset of results to start the retrieval.

getPendingInvitations() returns

TypeDescription
Promise<OrganizationInvitation[]>This method returns a Promise which resolves with a list of OrganizationInvitation objects.

inviteMember()

Creates and sends an invitation to the target email address for becoming a member with the role passed on the function parameters.

function inviteMember(params: InviteMemberParams): Promise<OrganizationInvitation>;
  • Name
    emailAddress
    Type
    string
    Description

    The email address to invite.

  • Name
    role
    Type
    string
    Description

    The role of the new member.

inviteMember() returns

TypeDescription
Promise<OrganizationInvitation>This method returns a Promise that resolves to the OrganizationInvitation for the created invitation.

inviteMember() example

main.js
import Clerk from '@clerk/clerk-js';

// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('YOUR_PUBLISHABLE_KEY');
await clerk.load();

if (clerk.user) {
  // Check for an active organization
  if (clerk.organization) {
    const emailAddress = "test@test.com";
    const role = "org:member";

    await clerk.organization.inviteMember({ emailAddress, role })
      .then((res) => console.log(res))
      .catch((error) => console.log("An error occurred:", error.errors));
  } else {
    // If there is no active organization,
    // mount Clerk's <OrganizationSwitcher />
    // to allow the user to set an organization as active
    document.getElementById("app").innerHTML = `
      <h2>Select an organization to set it as active</h2>
      <div id="org-switcher"></div>
    `;

    const orgSwitcherDiv = document.getElementById("org-switcher");

    clerk.mountOrganizationSwitcher(orgSwitcherDiv);
  }
} else {
  document.getElementById("app").innerHTML = `
    <div id="sign-in"></div>
  `;

  const signInDiv = document.getElementById("sign-in");

  clerk.mountSignIn(signInDiv);
}

inviteMembers()

Creates and sends an invitation to the target email addresses for becoming a member with the role passed in the parameters.

function inviteMembers(params: InviteMembersParams): Promise<OrganizationInvitation[]>;
  • Name
    emailAddresses
    Type
    string[]
    Description

    The email addresses to invite.

  • Name
    role
    Type
    string
    Description

    The role of the new members.

inviteMembers() returns

TypeDescription
Promise<OrganizationInvitation[]>This method returns a Promise that resolves to an array of OrganizationInvitation objects for the created invitations.

inviteMembers() example

main.js
import Clerk from '@clerk/clerk-js';

// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('YOUR_PUBLISHABLE_KEY');
await clerk.load();

if (clerk.user) {
  // Check for an active organization
  if (clerk.organization) {
    const emailAddresses = ["test@test.com", "test2@test.com", "test3@test.com"];
    const role = "org:member";

    await clerk.organization.inviteMembers({ emailAddresses, role })
      .then((res) => console.log(res))
      .catch((error) => console.log("An error occurred:", error.errors));
  } else {
    // If there is no active organization,
    // mount Clerk's <OrganizationSwitcher />
    // to allow the user to set an organization as active
    document.getElementById("app").innerHTML = `
      <h2>Select an organization to set it as active</h2>
      <div id="org-switcher"></div>
    `;

    const orgSwitcherDiv = document.getElementById("org-switcher");

    clerk.mountOrganizationSwitcher(orgSwitcherDiv);
  }
} else {
  document.getElementById("app").innerHTML = `
    <div id="sign-in"></div>
  `;

  const signInDiv = document.getElementById("sign-in");

  clerk.mountSignIn(signInDiv);
}

Feedback

What did you think of this content?