For AI agents: markdown of this page — /docs-content-en/entities/users/invite.md documentation index — /llms.txt

Invite employee

POST /v1/users/invite

Creates a new employee or invites an external user to the Bitrix24 account. Accepts fields in camelCase and UPPER_SNAKE_CASE, sets sensible defaults, and validates email before the Bitrix24 call — returning clear error codes (EMAIL_REQUIRED, EMAIL_INVALID, SONET_GROUP_ID_REQUIRED) instead of the generic wrong_email.

Request fields (body)

Parameter Type Required Description
Parameteremail Typestring Requiredyes DescriptionEmail — must be unique across all employees in the Bitrix24 account. A basic syntax check happens on the Vibecode side
Parametername Typestring Requiredno DescriptionFirst name
ParameterlastName Typestring Requiredno DescriptionLast name
ParametersecondName Typestring Requiredno DescriptionMiddle name
ParameterworkPosition Typestring Requiredno DescriptionPosition
ParameterworkPhone Typestring Requiredno DescriptionWork phone
ParameterworkCompany Typestring Requiredno DescriptionCompany name
ParameterpersonalPhone Typestring Requiredno DescriptionPersonal phone
ParameterpersonalMobile Typestring Requiredno DescriptionMobile phone
ParameterpersonalBirthday Typestring Requiredno DescriptionDate of birth (ISO 8601)
ParameterpersonalGender Typestring Requiredno DescriptionGender: M — male, F — female
ParameterpersonalCity Typestring Requiredno DescriptionCity
ParameterpersonalPhoto Type[string, string] Requiredno DescriptionPhoto for writing: a [fileName, base64Content] pair. A URL returned by read endpoints is not accepted here
ParameterxmlId Typestring Requiredno DescriptionExternal employee identifier for integrations
ParametertimeZone Typestring Requiredno DescriptionTime zone, for example Europe/Berlin
ParameterpersonalWww Typestring Requiredno DescriptionPersonal website URL
ParameterpersonalProfession Typestring Requiredno DescriptionProfession
Parametertitle Typestring Requiredno DescriptionTitle or form of address
ParameterpersonalIcq Typestring Requiredno DescriptionICQ number
ParameterpersonalFax Typestring Requiredno DescriptionPersonal fax number
ParameterpersonalPager Typestring Requiredno DescriptionPager number
ParameterpersonalStreet Typestring Requiredno DescriptionStreet in the residential address
ParameterdepartmentId Typenumber[] Requiredno DescriptionArray of department IDs. Defaults to [1] (root department) for intranet employees. List: GET /v1/departments
Parameterextranet Typestring Requiredno Description"Y" to invite an external user. In this case departmentId is ignored and sonetGroupId is required
ParametersonetGroupId Typenumber[] Requiredconditional DescriptionArray of workgroup IDs — required with extranet: "Y". List: GET /v1/workgroups
Parameteractive Typeboolean Requiredno DescriptionActivity flag (defaults to true)

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/users/invite" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.brown@example.com",
    "name": "John",
    "lastName": "Brown",
    "workPosition": "Manager"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/users/invite" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.brown@example.com",
    "name": "John",
    "lastName": "Brown",
    "workPosition": "Manager"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/users/invite', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'john.brown@example.com',
    name: 'John',
    lastName: 'Brown',
    workPosition: 'Manager',
  }),
})

const { success, data } = await res.json()
console.log('Created employee ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/users/invite', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'john.brown@example.com',
    name: 'John',
    lastName: 'Brown',
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typenumber DescriptionID of the created employee
Fielddata.user Typeobject DescriptionFull record of the just-created employee — the same fields as GET /v1/users/:id

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 1331,
    "user": {
      "id": 1331,
      "xmlId": "74668002",
      "active": true,
      "name": "John",
      "lastName": "Brown",
      "email": "john.brown@example.com",
      "lastLogin": null,
      "dateRegister": "2026-05-06T00:00:00.000Z",
      "isOnline": false,
      "timestampX": {},
      "personalGender": null,
      "departmentId": [1],
      "workPosition": "Manager",
      "userType": "employee"
    }
  }
}

The HTTP response status is 201 Created.

Error response example

400 — email not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "EMAIL_REQUIRED",
    "message": "EMAIL (or `email`) is required to invite a user."
  }
}

Errors

HTTP Code Description
HTTP400 CodeEMAIL_REQUIRED DescriptionThe request body has no email (or EMAIL)
HTTP400 CodeEMAIL_INVALID DescriptionEmail failed the Vibecode syntax check
HTTP400 CodePERSONAL_PHOTO_INVALID DescriptionpersonalPhoto is not a [fileName, base64Content] pair
HTTP400 CodeSONET_GROUP_ID_REQUIRED DescriptionsonetGroupId is not passed when extranet: "Y"
HTTP400 CodeBITRIX_ERROR (wrong_email) DescriptionBitrix24 rejected the creation: email already taken, domain forbidden by Bitrix24 portal policy, or another email error
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the user scope

Full list of common API errors — Errors.

Known specifics

Why the departmentId: [1] default. Without UF_DEPARTMENT Bitrix24 returns a generic wrong_email without stating the reason — a missing department for an intranet employee is one of the most frequent pitfalls. Substituting the root department [1] eliminates it for the typical "inviting an employee, the specific department is unknown" case. If the department structure matters — pass departmentId explicitly.

Email uniqueness in the Bitrix24 account. Email is checked across all employees including previously deactivated ones — on a duplicate Bitrix24 returns BITRIX_ERROR: wrong_email. Before inviting — search via GET /v1/users?filter[EMAIL]=john.brown@example.com. If a deactivated one is found, bring it back with PATCH /v1/users/:id { active: true } — this preserves history and relations, unlike creating a duplicate.

Best-effort re-read. After a successful creation the wrapper re-reads the record and puts it into data.user. If the helper call fails, data.id is still returned — the employee is already created, and a repeated request GET /v1/users/:id will load the record.

See also