Create Users

Create up to 50 users in a single request, either by registering them directly with a password or by sending them an invitation email.

POST

/api/public/users

Headers

Key	Value
Content-Type	application/json
Authorization	Bearer <Account API Key>

Modes

Mode	Behavior
pre_register: true	Users are created and activated immediately with the supplied user_password and added to the given groups. No email is sent.
pre_register: false (or omitted)	Users receive an invitation email and set their own password from the activation link. They are added to the given groups on activation.

caution

Pre-registering users with preset passwords should only be used where invitation emails cannot be delivered. See Adding users to your account for guidance.

Request body

Field	Type	Description
pre_register (optional)	Boolean	Selects the mode described above. Default false.
invitee_user (required)	Array	1 to 50 user objects to create (see below).
admin_id (invite mode)	Integer	User id of the administrator sending the invitation.
admin_name (invite mode)	String	Name of the administrator, shown in the invitation email.

invitee_user object

Field	Type	Description
user_name (required)	String	Full name of the user.
user_email (required)	String	Email address. Must not already exist in the account.
user_group_name (required)	Array of String	Names of existing groups to add the user to. Pass an empty array for none.
user_password (pre-register mode)	String	Initial password for the user.

Example cURL

Pre-register a user:

curl --location --request POST '<BUILDER_URL>/api/public/users' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXX' \
--data-raw '{
    "pre_register": true,
    "invitee_user": [
        {
            "user_name": "Jane Doe",
            "user_email": "jane@example.com",
            "user_password": "Str0ngPassw0rd!",
            "user_group_name": ["Sales", "Support"]
        }
    ]
}'

Invite users by email:

curl --location --request POST '<BUILDER_URL>/api/public/users' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXX' \
--data-raw '{
    "pre_register": false,
    "admin_id": 1,
    "admin_name": "Admin",
    "invitee_user": [
        {
            "user_name": "Jane Doe",
            "user_email": "jane@example.com",
            "user_group_name": ["Sales"]
        },
        {
            "user_name": "John Smith",
            "user_email": "john@example.com",
            "user_group_name": []
        }
    ]
}'

Responses

Status Code	Description	Response
200	Request processed. The body lists the users that could not be created; an empty array means every user was created.	application/json
401	Unauthorized, or invitee_user is empty	application/json
500	Internal Server Error	application/json

Sample response

200 : All users created

[]

200 : Some users could not be created

[
    {
        "user_email": "jane@example.com",
        "error_code": "3",
        "error_detail": "User already exists in the channel"
    },
    {
        "user_email": "john@example.com",
        "error_code": "6",
        "error_detail": "Licence expired"
    }
]

Error codes

error_code	Description
3	A user with this email already exists in the account.
6	The account's user licence has expired or no seats are available.