Create a sub-user

posthttps://api.chat-data.com/api/v2/sub-users/sub-users

Workspace keyWorkspace key only

Create a new sub-user for your company. Sub-users can log in to a branded portal on your custom domain and access their assigned chatbots.

Requires the SSO Login add-on (see plans) and a workspace API key; without the add-on, or with a chatbot-scoped key, the request gets a 403.

Your workspace's SSO company must exist and have a login domain before you can create sub-users. The sub-user's email must be unique within the company. Creating a sub-user sends no email.

Request body

Sending 2 of 7 fields

Required

emailstring

The sub-user's email address, stored in lowercase. It must be unique within the company, and for a sub-user without a password (who signs in by magic link) the mailbox must accept mail.

chatbotIdsarray of string

Array of chatbot IDs to assign to this sub-user. All IDs must belong to chatbots in your workspace. Duplicates are automatically removed.

Only these fields are sent (application/json).

Try it · POST /sub-users

curl 'https://api.chat-data.com/api/v2/sub-users' \  -H "Authorization: Bearer $CHAT_DATA_API_KEY" \  -H 'Content-Type: application/json' \  -d '{  "email": "[email protected]",  "chatbotIds": [    "6650f1c2a9e4b83d2c7a1f05",    "6650f1c2a9e4b83d2c7a1f06"  ]}'

Loading…

{  "_id": "6650f1c2a9e4b83d2c7a1f9a",  "company": "6650f1c2a9e4b83d2c7a1f3c",  "email": "[email protected]",  "name": "Jane Doe",  "avatar": "",  "chatbotIds": [    {      "_id": "6650f1c2a9e4b83d2c7a1f05",      "name": "Support Bot"    },    {      "_id": "6650f1c2a9e4b83d2c7a1f06",      "name": "Sales Assistant"    }  ],  "permissions": [    "read",    "train"  ],  "analyticsDashboardSections": [    "Overview",    "Messages Timeline",    "Chats"  ],  "hasPassword": true,  "hasGoogle": false,  "createdAt": "2026-10-14T09:30:00.000Z"}

Responses

Sub-user created successfully.

Content type: application/json

Field	Type	Description
_idstring	string	The unique identifier of the sub-user.
companystring	string	The ID of the company this sub-user belongs to.
emailstring	string	The sub-user's email address.
namestring	string	The sub-user's display name.
avatarstring	string	URL of the sub-user's avatar image, or an empty string if none is set.
chatbotIdsarray of object	array of object	The assigned chatbots, each with its `_id` and `name`.
chatbotIds[]._idstring	string	The chatbot ID.
chatbotIds[].namestring	string	The chatbot name.
permissionsarray of string	array of string	Permissions granted to this sub-user.
analyticsDashboardSectionsarray of string	array of string	Analytics dashboard sections visible to this sub-user.
hasPasswordboolean	boolean	Whether the sub-user has a password configured (the actual password is never returned).
hasGoogleboolean	boolean	Whether the sub-user has signed in with a linked Google account (the Google ID is never returned). It stays `false` when Google sign-in is only enabled.
createdAtstring	string	Timestamp when the sub-user was created.
lastLoginAtstring	string	Timestamp of the sub-user's last sign-in. Absent until they first sign in.

Example

{  "_id": "6650f1c2a9e4b83d2c7a1f9a",  "company": "6650f1c2a9e4b83d2c7a1f3c",  "email": "[email protected]",  "name": "Jane Doe",  "avatar": "",  "chatbotIds": [    {      "_id": "6650f1c2a9e4b83d2c7a1f05",      "name": "Support Bot"    },    {      "_id": "6650f1c2a9e4b83d2c7a1f06",      "name": "Sales Assistant"    }  ],  "permissions": [    "read",    "train"  ],  "analyticsDashboardSections": [    "Overview",    "Messages Timeline",    "Chats"  ],  "hasPassword": true,  "hasGoogle": false,  "createdAt": "2026-10-14T09:30:00.000Z"}

Last updated October 14, 2026