## Address fields `GET /v1/addresses/fields` Returns the address field schema — a list of all valid fields with their types, required flags, and whether they are writable. ## Examples ### curl — personal key ```bash curl "https://vibecode.bitrix24.com/v1/addresses/fields" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth application ```bash curl "https://vibecode.bitrix24.com/v1/addresses/fields" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" ``` ### JavaScript — personal key ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/addresses/fields', { headers: { 'X-Api-Key': 'YOUR_API_KEY', }, }) const { success, data } = await res.json() const fieldNames = Object.keys(data.fields) ``` ### JavaScript — OAuth application ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/addresses/fields', { headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', }, }) const { success, data } = await res.json() ``` ## Response fields | Field | Bitrix24 | Type | RO | Description | |------|-----------|-----|----|---------| | `typeId` | `TYPE_ID` | number | — | Address type. Required, immutable after creation | | `entityTypeId` | `ENTITY_TYPE_ID` | number | — | Address owner type. Required, immutable after creation | | `entityId` | `ENTITY_ID` | number | — | Address owner ID. Required, immutable after creation | | `address1` | `ADDRESS_1` | string | — | Street, building, block, structure | | `address2` | `ADDRESS_2` | string | — | Apartment, office | | `city` | `CITY` | string | — | City | | `postalCode` | `POSTAL_CODE` | string | — | Postal code | | `region` | `REGION` | string | — | District | | `province` | `PROVINCE` | string | — | Province | | `country` | `COUNTRY` | string | — | Country | | `countryCode` | `COUNTRY_CODE` | string | — | Country code | | `locAddrId` | `LOC_ADDR_ID` | number | — | Location address identifier | | `anchorTypeId` | `ANCHOR_TYPE_ID` | number | yes | Type of the entity the address is linked to | | `anchorId` | `ANCHOR_ID` | number | yes | ID of the entity the address is linked to | RO — the field is read-only. The "Bitrix24" column shows the name of the same field in Bitrix24. Every field in `data.fields` is described by an object. Besides the `type`, `isRequired`, `isReadOnly`, `isImmutable`, `isMultiple` and `isDynamic` flags, it carries three text keys: | Key | Description | |-----|-------------| | `title` | Short field label. Most labels come from Bitrix24 and arrive in the language of the Bitrix24 account. Where Bitrix24 returns the field name instead of a label, for example `TYPE_ID` or `COUNTRY_CODE`, Vibecode supplies the label and it comes in English | | `label` | The same label as `title`. It arrives alongside it because every other entity puts the label under `label` — so labels can be read the same way on any entity | | `description` | Extended description in English: what the field is for, the meaning of its codes, write-time behaviour. Present on the fields that have something to add to the label | Request headers do not switch the language of labels and descriptions. ## Response example ```json { "success": true, "data": { "fields": { "typeId": { "type": "integer", "isRequired": true, "isReadOnly": false, "isImmutable": true, "isMultiple": false, "isDynamic": false, "title": "Address type", "label": "Address type", "description": "Address type code. Bitrix24 defines twelve, 1 through 12: 1 — actual address (the English portal UI labels it Street address), 2 — second, 3 — third, 4 — registered, 5 — work, 6 — legal, 7 — additional, 8 — postal, 9 — beneficiary, 10 — bank, 11 — delivery, 12 — billing. Which of them an account may use depends on its country zone, so a given account may never return some of these. Part of the composite address key and immutable after creation." }, "entityTypeId": { "type": "integer", "isRequired": true, "isReadOnly": false, "isImmutable": true, "isMultiple": false, "isDynamic": false, "title": "Owner type", "label": "Owner type", "description": "Owner entity type code: 1 — lead, 3 — contact, 4 — company, 8 — requisite. Part of the composite address key and immutable after creation." }, "entityId": { "type": "integer", "isRequired": true, "isReadOnly": false, "isImmutable": true, "isMultiple": false, "isDynamic": false, "title": "Owner ID", "label": "Owner ID", "description": "Identifier of the entity that owns the address. Part of the composite address key and immutable after creation." }, "address1": { "type": "string", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Street, building, block, structure", "label": "Street, building, block, structure" }, "address2": { "type": "string", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Apartment / office", "label": "Apartment / office" }, "city": { "type": "string", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "City", "label": "City" }, "postalCode": { "type": "string", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Postal code", "label": "Postal code" }, "region": { "type": "string", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "District", "label": "District" }, "province": { "type": "string", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Province", "label": "Province" }, "country": { "type": "string", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Country", "label": "Country" }, "countryCode": { "type": "string", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Country code", "label": "Country code", "description": "Two-letter country code. Bitrix24's own REST documentation marks this field as unused and kept for backward compatibility — the value is stored as passed, so do not rely on it affecting anything." }, "locAddrId": { "type": "integer", "isRequired": false, "isReadOnly": false, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Location address identifier", "label": "Location address identifier" }, "anchorTypeId": { "type": "integer", "isRequired": false, "isReadOnly": true, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Anchor entity type", "label": "Anchor entity type", "description": "Type code of the entity the address is anchored to: 3 — contact, 4 — company. Read-only." }, "anchorId": { "type": "integer", "isRequired": false, "isReadOnly": true, "isImmutable": false, "isMultiple": false, "isDynamic": false, "title": "Anchor entity ID", "label": "Anchor entity ID", "description": "Identifier of the entity the address is anchored to. Read-only." } } } } ``` ## Error response example 403 — the API key lacks the `crm` scope: ```json { "success": false, "error": { "code": "SCOPE_DENIED", "message": "This endpoint requires 'crm' scope" } } ``` ## Errors | HTTP | Code | Description | |------|-----|---------| | 403 | `SCOPE_DENIED` | The API key lacks the `crm` scope | | 401 | `TOKEN_MISSING` | The API key has no configured tokens | Full list of common API errors — [Errors](/docs/errors). ## Known specifics **The fields `typeId`, `entityTypeId`, `entityId` are immutable.** The `isImmutable: true` flag means these fields cannot be changed after the address is created. They form the composite key and are not passed in the body of update requests. ## See also - [Get address](/docs/entities/addresses/get) - [List addresses](/docs/entities/addresses/list) - [Requisite fields](/docs/entities/requisites/fields) - [Addresses](/docs/entities/addresses)