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

Update address

PATCH /v1/addresses/:typeId/:entityTypeId/:entityId

Updates the fields of an existing address. Pass only the fields you want to change. Full list of fields — GET /v1/addresses/fields.

Parameters

Parameter Type Required Description
ParametertypeId (path) Typenumber Requiredyes DescriptionAddress type. Examples: 1 — actual, 6 — legal, 8 — postal, 11 — delivery
ParameterentityTypeId (path) Typenumber Requiredyes DescriptionOwner type: 8 — requisite, 3 — contact, 4 — company, 1 — lead
ParameterentityId (path) Typenumber Requiredyes DescriptionID of the address owner. For a requisite — the ID from GET /v1/requisites

Request fields (body)

Field Type Description
Fieldaddress1 Typestring DescriptionStreet and building
Fieldaddress2 Typestring DescriptionAdditional address line
Fieldcity Typestring DescriptionCity
Fieldregion Typestring DescriptionDistrict or region
Fieldprovince Typestring DescriptionProvince or state
FieldpostalCode Typestring DescriptionPostal code
Fieldcountry Typestring DescriptionCountry (text name)
FieldcountryCode Typestring 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

The fields typeId, entityTypeId, entityId in the request body are ignored — the key is set only in the path.

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

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

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

JavaScript — OAuth application

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

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionUpdate confirmation with an echo of the key
Fielddata.typeId Typenumber DescriptionAddress type from the path
Fielddata.entityTypeId Typenumber DescriptionOwner type from the path
Fielddata.entityId Typenumber DescriptionOwner ID from the path
Fielddata.updated Typeboolean DescriptionAlways true on successful update

Response example

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

Error response example

403 — no crm scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_COMPOSITE_KEY DescriptionOne or more of the path parameters typeId, entityTypeId, entityId is not a positive integer
HTTP400 CodeINVALID_REQUEST DescriptionThe request body is not an object
HTTP404 CodeNOT_FOUND DescriptionAn address with this composite key was not found
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the update of an existing address
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 is in the path, not in the body. An address is identified by the triple /:typeId/:entityTypeId/:entityId in the URL. If you pass typeId, entityTypeId or entityId in the body, they are ignored — the path values take precedence.

A company's or contact's address is stored on its requisite. For a company (4) and a contact (3), the address is attached to their requisite. An update by the company or contact composite key is automatically applied to the matching requisite, so you can update the address by the same key you created and read it with. For a requisite (8) and a lead (1), the key matches the storage location.

Address not found — 404. If no address exists for the composite key, the endpoint returns 404 NOT_FOUND and does not perform the update.

See also