For AI agents: markdown of this page — /docs-content-en/mail/recipients/employees.md documentation index — /llms.txt

Search account employees

POST /v1/mail/recipients/employees

Searches Bitrix24 account employees to populate the email recipients field. When there are no matches, an empty items array is returned.

Request fields (body)

Field Type Required Description
Fieldquery Typestring Requiredyes DescriptionSearch string matched against the employee name or email address. Minimum 1 character

Examples

curl — personal key

Terminal 
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Man"}' \
  https://vibecode.bitrix24.com/v1/mail/recipients/employees

curl — OAuth application

Terminal 
curl -X POST \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "Man"}' \
  https://vibecode.bitrix24.com/v1/mail/recipients/employees

JavaScript — personal key

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/mail/recipients/employees',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query: 'Man' }),
  }
)
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
console.log(body.data.items)

JavaScript — OAuth application

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/mail/recipients/employees',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query: 'Man' }),
  }
)
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
console.log(body.data.items)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata.items Typearray DescriptionArray of matching employees. Empty array when there are no matches
Fielddata.items[].id Typenumber DescriptionEmployee identifier
Fielddata.items[].email Typestring DescriptionEmail address
Fielddata.items[].name Typestring DescriptionEmployee display name

Response example

JSON 
{
  "success": true,
  "data": {
    "items": [
      { "id": 1, "email": "manager@example.com", "name": "Manager" }
    ]
  }
}

Error response example

400 — required query not provided:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Request object validation failed",
    "validation": [
      {
        "field": "MISSING_QUERY",
        "message": "Parameter \"query\" is required."
      }
    ]
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS Descriptionquery missing or empty — validation[].field equals MISSING_QUERY
HTTP422 CodeBITRIX_ERROR DescriptionOther Bitrix24 errors
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not provided
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP401 CodeKEY_INACTIVE DescriptionThe key is deactivated
HTTP401 CodeKEY_EXPIRED DescriptionThe key has expired
HTTP401 CodeTOKEN_MISSING DescriptionThe key is not bound to a Bitrix24 portal
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the mail scope
HTTP429 CodeRATE_LIMITED DescriptionRequest rate limit exceeded
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable

Full list of common API errors — Errors.

See also