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 Req. Description
email string yes Email — must be unique across all employees in the Bitrix24 account. A basic syntax check happens on the Vibecode side
name string no First name
lastName string no Last name
secondName string no Middle name
workPosition string no Position
workPhone string no Work phone
workCompany string no Company name
personalPhone string no Personal phone
personalMobile string no Mobile phone
personalBirthday string no Date of birth (ISO 8601)
personalGender string no Gender: M — male, F — female
personalCity string no City
departmentId number[] no Array of department IDs. Defaults to [1] (root department) for intranet employees. List: GET /v1/departments
extranet string no "Y" to invite an external user. In this case departmentId is ignored and sonetGroupId is required
sonetGroupId number[] conditional Array of workgroup IDs — required with extranet: "Y". List: GET /v1/workgroups
active boolean no Activity 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
success boolean Always true on success
data.id number ID of the created employee
data.user object Full 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
400 EMAIL_REQUIRED The request body has no email (or EMAIL)
400 EMAIL_INVALID Email failed the Vibecode syntax check
400 SONET_GROUP_ID_REQUIRED sonetGroupId is not passed when extranet: "Y"
400 BITRIX_ERROR (wrong_email) Bitrix24 rejected the creation: email already taken, domain forbidden by Bitrix24 portal policy, or another email error
401 TOKEN_MISSING The API key has no configured tokens
403 SCOPE_DENIED The 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