## Search Bitrix24 users

`GET /v1/infra/servers/:id/b24-users`

Searches for users in the Bitrix24 account by first name, last name, or email — returns `userId`, name, position, and photo for each match. Used to populate the `NAMED_USERS` list via [`POST /access`](./access-add.md) when a person's name is known but not their Bitrix24 account ID. Works through the server's Bitrix24 credentials: the webhook key from [apiKey.webhookUrl](/docs/keys-auth), or — when the server key is an OAuth app without a user token — an automatic fallback to the linked application's personal key. If neither source yields credentials (the app is not yet authorized on the account, or the key was revoked), the endpoint returns an empty `data` together with a `hint` field explaining why.

## Parameters

| Parameter | In | Type | Req. | Description |
|----------|---|-----|:-----:|----------|
| `id` | path | string (UUID) | yes | Server ID |
| `search` | query | string | **yes** | Search string, minimum 2 characters. Searches by first name, last name, and email |

## Examples

### curl — personal key

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/b24-users?search=John"
```

### curl — OAuth application

```bash
curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/b24-users?search=John"
```

### JavaScript — personal key

```javascript
const q = encodeURIComponent('John')
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/b24-users?search=${q}`,
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const { data: users } = await res.json()
users.forEach(u => console.log(`${u.id}: ${u.name} — ${u.position ?? 'no position'}`))
```

### JavaScript — OAuth application

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/b24-users?search=${q}`,
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | Always `true` on success |
| `data` | array | Array of found users |
| `data[].id` | string | Bitrix24 user ID — pass it in `userId` for [`POST /access`](./access-add.md) |
| `data[].name` | string | Full name (first name + last name) |
| `data[].photo` | string \| null | Avatar URL (may be `null`) |
| `data[].position` | string \| null | Position (may be `null`) |
| `hint` | string | Optional. Present only when `data` is empty because no Bitrix24 credentials resolved (the app is not authorized on the account, or the key was revoked). Absent on a populated response |

## Response example

```json
{
  "success": true,
  "data": [
    {
      "id": "243",
      "name": "Kate Smith",
      "photo": null,
      "position": null
    }
  ]
}
```

## Error response example

400 — search string shorter than 2 characters:

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "search query required (min 2 chars)"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `VALIDATION_ERROR` | `search` is missing or shorter than 2 characters |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not provided |
| 401 | `INVALID_API_KEY` | Invalid or expired API key |
| 404 | `NOT_FOUND` | The server does not exist, was deleted, or belongs to another API key |
| 429 | `RATE_LIMITED` | The platform's overall request limit was exceeded |

The full list of common API errors — [Errors](/docs/errors).

## Known specifics

- **Empty `data` with a `hint` field when no Bitrix24 credentials resolve.** If the server key is an OAuth app without a user token, the platform first tries the linked application's personal key (fallback). If that is also unavailable (no application, key revoked/expired, or owner blocked), the endpoint returns `data: []` and a `hint` string with the reason — instead of a mute empty array. The client can show the `hint` to the user or switch to an alternative tool.
- **The search runs through the `user.search` method in the Bitrix24 account.** That means matching follows the Bitrix24 account UI — the same rules for first name/last name/email.
- **Non-ASCII characters in the URL — via `encodeURIComponent`.** In JS: `encodeURIComponent('Müller')`. In curl: `?search=M%C3%BCller`.
- **Independent of the server mode.** The search works for any server — both BLACKHOLE and OPEN. Logically it is needed for `NAMED_USERS`, but the endpoint does not restrict the call by `mode`.

## See also

- [Add user/department](./access-add.md) — add a found user to the access list.
- [Access list](./access-list.md) — see the users and departments already added.
- [Access policy](./access-policy.md) — switch to `NAMED_USERS`.