Bulk User Invitation

Our bulk invitation API is here to simplify bulk migration, sending invitations to members of large organizations or adding users with specific roles in large quantities. The API allows you to effortlessly invite up to 1000 users , thus simplifying the process and enhancing your efficiency.

Frontegg's Bulk Invitation API allows vendors to create up to 1000 users under a single tenant. If users overlap with an existing (different) tenant - they will be added to the new tenant, and the user properties will not be overridden by the new request (i.e., their user name, phone number, etc., will be copied as is under the new tenant).

Use Cases

There are multiple instances where you may need to invite a large number of users to join your account. Common use cases include inviting users from an organization or users holding a specific role. While the single user invitation API is limited by rate limits, the Bulk Invitation API allows you to add up to 1000 users simultaneously, silently or with invitations. Thus, allowing you to invite members of an organization or a group of users holding a specific role in one go.

Supported user attributes

The following user attributes are supported for this feature:

🚧

Note: User Duplicates

• If a user you invite is already associated with another tenant, the API will then add them to the new tenant with their existing properties.
• If a user already exists under the tenant you are trying to add them to, an error will be triggered and displayed in the invitation details status.

Inviting Users in Bulk

📘

User Creation Flow

Note that a Bulk Invitation call will trigger a User Created webhook for every user invited as part of the bulk request (If you are subscribed to receive this webhook).

To add users in bulk to a tenant, you will need to obtain a Vendor Token by following these steps; Then, send the POST request with up to 1000 users per batch:

    "users": [
        {
            "name": "Test",
            "email": "[email protected]",
            "roleIds": [
                "xxxxxxxx"
            ],
            "provider": "local",
            "skipInviteEmail": true
        },
        {
            "name": "Test2",
            "email": "[email protected]",
            "roleIds": [
                "xxxxxxxx"
            ],
            "provider": "local",
            "skipInviteEmail": true
        }
    ]

Error: Users added under an existing tenant

Check the status of the request via GET request. If some of the invited users already exist under the tenant you are trying to add them to, an error will be thrown:

{
    "id": "<<id>>",
    "totalItems": 2,
    "completedItems": 2,
    "errors": [
        {
            "message": "User Already Exist Exception",
            "payload": {
                "userEmails": [
                    "[email protected]",
                    "[email protected]"
                ]
            }
        }
    ],
    "status": "CompletedWithErrors"
}

🚧

Cache time

Note that requests are being cached on Frontegg's side for 5 minutes. If your invite request failed for a specific reason, please make sure to wait for at least 5 minutes before sending the request for the same users again.