# Contacts

CRM contact management: create, retrieve, update, delete, filter.

Bitrix24 API: `crm.item.*`
Scope: `crm`

## Operations

- [Create contact](./contacts/create.md) — `POST /v1/contacts`
- [List contacts](./contacts/list.md) — `GET /v1/contacts`
- [Get contact](./contacts/get.md) — `GET /v1/contacts/:id`
- [Update contact](./contacts/update.md) — `PATCH /v1/contacts/:id`
- [Delete contact](./contacts/delete.md) — `DELETE /v1/contacts/:id`
- [Search contacts](./contacts/search.md) — `POST /v1/contacts/search`
- [Contact fields](./contacts/fields.md) — `GET /v1/contacts/fields`
- [Aggregate contacts](./contacts/aggregate.md) — `POST /v1/contacts/aggregate`
- [List contact companies](./contacts/companies-list.md) — `GET /v1/contacts/:id/companies`
- [Replace contact companies](./contacts/companies-set.md) — `PUT /v1/contacts/:id/companies`
- [Link a company to a contact](./contacts/companies-create.md) — `POST /v1/contacts/:id/companies`
- [Unlink a company from a contact](./contacts/companies-delete-delete.md) — `DELETE /v1/contacts/:id/companies/:relatedId`
- [Unlink all companies from a contact](./contacts/companies-delete.md) — `DELETE /v1/contacts/:id/companies`
- [Import records](../import.md) — `POST /v1/contacts/import`

## Key fields

| Field | Description |
|------|----------|
| `id` | Contact ID. Source: [List contacts](./contacts/list.md) |
| `name` | First name |
| `lastName` | Last name |
| `secondName` | Middle name |
| `companyId` | The contact's primary company. Source: [List companies](./companies/list.md) |
| `assignedById` | Assignee. Source: [List employees](./users/list.md) |
| `phone` | Phone numbers |
| `email` | Email addresses |

Full field list — [Contact fields](./contacts/fields.md).

## What to know before you start

1. On create and update, pass the fields at the root of the JSON, without a `fields` wrapper. Phone and email formats are described on the [Create contact](./contacts/create.md) and [Update contact](./contacts/update.md) pages.
2. A contact can be linked to several companies. The `companyId` field points to the primary company. The rules for linking a contact to companies — the primary company, repeated calls, limits — are described on the [Contact companies](./contacts/companies.md) page.
3. To read and change the links, use [List contact companies](./contacts/companies-list.md), [Link a company to a contact](./contacts/companies-create.md) and [Replace contact companies](./contacts/companies-set.md).

## Typical scenario

1. Find the contact with [List contacts](./contacts/list.md) or [Search contacts](./contacts/search.md).
2. If the contact does not exist, [create a contact](./contacts/create.md) with the customer's name and contact details.
3. Find the company with [List companies](./companies/list.md) and [link it to the contact](./contacts/companies-create.md).
4. Check the contact with [Get contact](./contacts/get.md), and the links with [List contact companies](./contacts/companies-list.md).

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Automatic pagination | enabled when `limit > 50` |
| `offset` on large result sets | `limit ≤ 500` recommended when `offset ≥ 2500` |
| Batch requests | up to 50 operations in [Batch calls](/docs/batch) |
| Request rate | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Contact companies](./contacts/companies.md)
- [Companies](./companies.md)
- [Deals](./deals.md)
- [Import records](../import.md)
- [Filtering syntax](/docs/filtering)