For AI agents: markdown of this page — /docs-content-en/entities/addresses/fields.md documentation index — /llms.txt

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

Terminal 
curl "https://vibecode.bitrix24.com/v1/addresses/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth app

Terminal 
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 app

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.

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