لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/addresses.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

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

Create address

POST /v1/addresses

Creates an address and links it to an owner. The three values — typeId, entityTypeId and entityId — are passed in the request body together with the address fields.

Request fields (body)

Field Type Required Description
FieldtypeId Typenumber Requiredyes DescriptionAddress type. List: GET /v1/addresses/fields (field typeId). Examples: 1 — actual, 6 — legal, 8 — postal, 11 — delivery
FieldentityTypeId Typenumber Requiredyes DescriptionAddress owner type. 8 — requisite. Other values are possible for contacts, companies, leads
FieldentityId Typenumber Requiredyes DescriptionID of the address owner. For a requisite — the ID from GET /v1/requisites
Fieldaddress1 Typestring Requiredno DescriptionStreet and building
Fieldaddress2 Typestring Requiredno DescriptionAdditional address line
Fieldcity Typestring Requiredno DescriptionCity
Fieldregion Typestring Requiredno DescriptionDistrict or region
Fieldprovince Typestring Requiredno DescriptionProvince or state
FieldpostalCode Typestring Requiredno DescriptionPostal code
Fieldcountry Typestring Requiredno DescriptionCountry (text name)
FieldcountryCode Typestring Requiredno DescriptionTwo-letter country code (e.g. US). 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

Full list of fields — GET /v1/addresses/fields.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/addresses" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "typeId": 11,
    "entityTypeId": 8,
    "entityId": 1,
    "city": "Springfield",
    "address1": "Main St, 10",
    "postalCode": "12345"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/addresses" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "typeId": 11,
    "entityTypeId": 8,
    "entityId": 1,
    "city": "Springfield",
    "address1": "Main St, 10"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/addresses', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    typeId: 11,
    entityTypeId: 8,
    entityId: 1,
    city: 'Springfield',
    address1: 'Main St, 10',
    postalCode: '12345',
  }),
})

const { success, data } = await res.json()
console.log('Created address:', data.typeId, data.entityTypeId, data.entityId)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/addresses', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    typeId: 11,
    entityTypeId: 8,
    entityId: 1,
    city: 'Springfield',
    address1: 'Main St, 10',
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe three key values of the created address: typeId, entityTypeId, entityId
Fielddata.typeId Typenumber DescriptionAddress type from the request
Fielddata.entityTypeId Typenumber DescriptionOwner type from the request
Fielddata.entityId Typenumber DescriptionOwner ID from the request

The response returns only the key. Address fields — city, address1, postalCode and others — are not included in the response. To read the saved address — GET /v1/addresses/:typeId/:entityTypeId/:entityId.

Response example

HTTP status: 201 Created

JSON 
{
  "success": true,
  "data": {
    "typeId": 11,
    "entityTypeId": 8,
    "entityId": 1
  }
}

Error response example

400 — one of the key parameters is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_COMPOSITE_KEY",
    "message": "POST /v1/addresses requires typeId, entityTypeId and entityId in the body. Example: { \"typeId\": 1, \"entityTypeId\": 8, \"entityId\": 42, \"city\": \"...\" }"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_COMPOSITE_KEY DescriptionOne or more of the key parameters typeId, entityTypeId, entityId is missing
HTTP400 CodeINVALID_REQUEST DescriptionThe request body is not an object
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request — invalid typeId, non-existent entityId or another error on the Bitrix24 side
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope. This endpoint requires 'crm' scope
HTTP401 CodeTOKEN_MISSING DescriptionX-Api-Key is missing or the key has no configured tokens

Full list of common API errors — Errors.

Known specifics

The key goes in the body, not in the path. Unlike update and delete, on create the three values — typeId, entityTypeId, entityId — are passed in the request body, not in the URL.

The response is the key only. The 201 response returns only the passed typeId, entityTypeId and entityId. The saved address fields are not in it.

See also