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

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
typeId number yes Address type. List: GET /v1/addresses/fields (field TYPE_ID). Examples: 1 — registered, 8 — delivery, 9 — actual, 11 — beneficiary
entityTypeId number yes Address owner type. 8 — requisite. Other values are possible for contacts, companies, leads
entityId number yes ID of the address owner. For a requisite — the ID from GET /v1/requisites
address1 string no Street and building
address2 string no Additional address line
city string no City
region string no District or region
province string no Province or state
postalCode string no Postal code
country string no Country (text name)
countryCode string no Country code (ISO 3166-1 alpha-2, e.g. US)

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 app

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 app

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
success boolean Always true on success
data object The three key values of the created address: typeId, entityTypeId, entityId
data.typeId number Address type from the request
data.entityTypeId number Owner type from the request
data.entityId number Owner 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
400 MISSING_COMPOSITE_KEY One or more of the key parameters typeId, entityTypeId, entityId is missing
400 INVALID_REQUEST The request body is not an object
422 BITRIX_ERROR Bitrix24 rejected the request — invalid typeId, non-existent entityId or another error on the Bitrix24 side
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 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