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 Req. Description
query string yes Search string by 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 app

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 app

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' }),
  }
)

Response fields

Field Type Description
success boolean true on success
data.items array Array of found employees. Empty array when there are no matches
data.items[].id number Employee identifier
data.items[].email string Email address
data.items[].name string Employee 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
400 INVALID_PARAMS query missing or empty — validation[].field equals MISSING_QUERY
422 BITRIX_ERROR Other Bitrix24 errors
403 SCOPE_DENIED The key lacks the mail scope
401 TOKEN_MISSING The key is not bound to a Bitrix24 portal
429 RATE_LIMITED Request rate limit exceeded
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable
401 MISSING_API_KEY The X-Api-Key header was not provided
401 INVALID_API_KEY Invalid or expired key
401 KEY_INACTIVE The key is deactivated
401 KEY_EXPIRED The key has expired

Full list of common API errors — Errors.

See also