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
typeId (path) number yes Address type. Examples: 1 — registered, 8 — delivery, 9 — actual, 11 — beneficiary
entityTypeId (path) number yes Owner type: 8 — requisite, 3 — contact, 4 — company, 1 — lead
entityId (path) number yes ID of the address owner. For a requisite — the ID from GET /v1/requisites

Request fields (body)

Field Type Description
address1 string Street and building
address2 string Additional address line
city string City
region string District or region
province string Province or state
postalCode string Postal code
country string Country (text name)
countryCode string Country code (ISO 3166-1 alpha-2, e.g. US)

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 app

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 app

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
success boolean Always true on success
data object Update confirmation with an echo of the key
data.typeId number Address type from the path
data.entityTypeId number Owner type from the path
data.entityId number Owner ID from the path
data.updated boolean Always 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
400 INVALID_COMPOSITE_KEY One or more of the path parameters typeId, entityTypeId, entityId is not a positive integer
400 INVALID_REQUEST The request body is not an object
404 NOT_FOUND An address with this composite key was not found
422 BITRIX_ERROR Bitrix24 rejected the update of an existing address
403 SCOPE_DENIED The key lacks the crm scope. This endpoint requires 'crm' scope
401 TOKEN_MISSING X-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