# Addresses

Addresses of CRM entities: actual, legal, postal, delivery. Most often linked to a requisite, but the same endpoint works for contacts, companies and leads. An address has no separate numeric `id`: a specific address is identified by three values — address type `typeId`, owner type `entityTypeId` and owner ID `entityId`.

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

## Operations

- [Create address](./addresses/create.md) — `POST /v1/addresses`
- [List addresses](./addresses/list.md) — `GET /v1/addresses`
- [Get address](./addresses/get.md) — `GET /v1/addresses/:typeId/:entityTypeId/:entityId`
- [Update address](./addresses/update.md) — `PATCH /v1/addresses/:typeId/:entityTypeId/:entityId`
- [Delete address](./addresses/delete.md) — `DELETE /v1/addresses/:typeId/:entityTypeId/:entityId`
- [Search addresses](./addresses/search.md) — `POST /v1/addresses/search`
- [Address fields](./addresses/fields.md) — `GET /v1/addresses/fields`

## Key fields

| Field | Description |
|------|---------|
| `typeId` | Address type, codes `1` through `12`. Actual — `1`, legal — `6`, postal — `8`, delivery — `11`. Full reference — [Get address](./addresses/get.md) |
| `entityTypeId` | Owner type: `8` — requisite (also contact, company, lead) |
| `entityId` | ID of the address owner |
| `address1` | Street, building |
| `city` | City |
| `postalCode` | Postal code |

Full list of fields — [`GET /v1/addresses/fields`](./addresses/fields.md).

## What to know before you start

1. **An address has no separate numeric `id`.** An address is identified by three values: `typeId`, `entityTypeId`, `entityId`. The get, update and delete operations use them in the path. The create operation passes them in the request body.
2. **`typeId` is the address type, `entityTypeId` is the owner type.** A single owner can have several addresses of different types. For a requisite, `entityTypeId` equals `8`.
3. **The set of available types depends on the country zone of the Bitrix24 account.** There are twelve codes in total, but a given account will never return some of them — its country determines the set. Pick the type you need from what the response actually returns rather than relying on a fixed number. For a legal address that is `typeId` `6`; if it is not available, fall back to `1`, the actual address.
4. **Field names are camelCase everywhere.** The list and get operations return `address1`, `city`, `postalCode`. The `GET /v1/addresses/fields` schema returns the same names: `typeId`, `address1`, `postalCode`. Pass those same names in `filter` and in the request body.
5. **Addresses have their own routes.** The composite key does not fit the common Entity API shape, so operations go through `/v1/addresses/...` paths — one call per address. The `addresses` entity does not participate in the combined [`POST /v1/batch`](/docs/batch): such a call is rejected before it reaches Bitrix24, with the code `ENTITY_CUSTOM_ROUTES` in `data.errors` under the call identifier. If the batch contains other working calls, the response stays `200`, and `400` is returned only when all of them are rejected.

## Related entities

| Entity | Endpoint | Purpose |
|----------|----------|-----------|
| Requisites | `GET /v1/requisites` | Address owner: `entityTypeId` equals `8`, and `entityId` is the requisite `id`. |
| Requisite presets | `GET /v1/requisite-presets` | Field-set template of the owner requisite. |
| Bank details | `GET /v1/bank-details` | Bank accounts of the same requisite. |

## Typical scenario

1. Find the company requisite: [`GET /v1/requisites?filter[entityTypeId]=4&filter[entityId]=15`](./requisites/list.md).
2. Create an address for it: [`POST /v1/addresses`](./addresses/create.md) with `typeId`, `entityTypeId: 8` and the requisite `entityId`.
3. Read or update the address by its composite key: [`GET /v1/addresses/:typeId/:entityTypeId/:entityId`](./addresses/get.md).

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Auto-pagination | enabled when `limit > 50` |
| `offset` on large result sets | `limit ≤ 500` recommended when `offset ≥ 2500` |
| Rate limit | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Company requisites for document generation](/docs/recipes/document-requisites)
- [Entity API](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)
- [API reference](/docs/api-reference)

## Available address types

Find `typeId` values in [address types](./crm-enums/address-types.md): `GET /v1/crm-enums/address-types`.