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 application

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 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
FieldtypeId Bitrix24TYPE_ID Typenumber RO— DescriptionAddress type. Required, immutable after creation
FieldentityTypeId Bitrix24ENTITY_TYPE_ID Typenumber RO— DescriptionAddress owner type. Required, immutable after creation
FieldentityId Bitrix24ENTITY_ID Typenumber RO— DescriptionAddress owner ID. Required, immutable after creation
Fieldaddress1 Bitrix24ADDRESS_1 Typestring RO— DescriptionStreet, building, block, structure
Fieldaddress2 Bitrix24ADDRESS_2 Typestring RO— DescriptionApartment, office
Fieldcity Bitrix24CITY Typestring RO— DescriptionCity
FieldpostalCode Bitrix24POSTAL_CODE Typestring RO— DescriptionPostal code
Fieldregion Bitrix24REGION Typestring RO— DescriptionDistrict
Fieldprovince Bitrix24PROVINCE Typestring RO— DescriptionProvince
Fieldcountry Bitrix24COUNTRY Typestring RO— DescriptionCountry
FieldcountryCode Bitrix24COUNTRY_CODE Typestring RO— DescriptionCountry code
FieldlocAddrId Bitrix24LOC_ADDR_ID Typenumber RO— DescriptionLocation address identifier
FieldanchorTypeId Bitrix24ANCHOR_TYPE_ID Typenumber ROyes DescriptionType of the entity the address is linked to
FieldanchorId Bitrix24ANCHOR_ID Typenumber ROyes DescriptionID 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
Keytitle DescriptionShort 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
Keylabel DescriptionThe 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
Keydescription DescriptionExtended 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
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe 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