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

Get address

GET /v1/addresses/:typeId/:entityTypeId/:entityId

Returns a single address by a composite key of three parameters: address type, owner type and owner ID.

Parameters

Parameter Type Required Description
typeId (path) number yes Address type, codes 1 through 12: 1 — actual address (the English Bitrix24 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 a Bitrix24 account may use depends on its country zone, so a given account may never return some of these codes
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
select (query) string no Comma-separated field names: city, postalCode and the rest from the response table below. Bitrix24 source names are accepted too — CITY maps to city. The value * returns every field. Without select the full record is returned. The composite key typeId, entityTypeId, entityId is always returned, even when it was not listed

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/addresses/1/3/9" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth app

Terminal 
curl "https://vibecode.bitrix24.com/v1/addresses/1/3/9" \
  -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/1/3/9', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('City:', data.city, 'Postal code:', data.postalCode)

JavaScript — OAuth app

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/addresses/1/3/9', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

Field Type Description
success boolean Always true on success
data object Address object
data.typeId number Address type
data.entityTypeId number Owner type
data.entityId number Owner ID
data.address1 string | null Street, building, block, structure
data.address2 string | null Apartment, office
data.city string | null City
data.postalCode string | null Postal code
data.region string | null District
data.province string | null Province
data.country string | null Country
data.countryCode string | null Country code
data.locAddrId number Location address identifier
data.anchorTypeId number Type of the entity the address is linked to (read-only)
data.anchorId number ID of the entity the address is linked to (read-only)
meta.warnings array Returned when a name that is absent from the address schema is listed alongside * in select: the record comes back without that field. Each warning is an object with code, field and message, and the code is UNKNOWN_SELECT_FIELD. Without *, such a name causes the whole request to be rejected

Response example

JSON 
{
  "success": true,
  "data": {
    "typeId": 1,
    "entityTypeId": 3,
    "entityId": 9,
    "address1": null,
    "address2": null,
    "city": null,
    "postalCode": null,
    "region": null,
    "province": null,
    "country": null,
    "countryCode": null,
    "locAddrId": 0,
    "anchorTypeId": 3,
    "anchorId": 9
  }
}

Error response example

404 — address not found:

JSON 
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Address (typeId=1, entityTypeId=3, entityId=99999999) not found"
  }
}

Errors

HTTP Code Description
404 NOT_FOUND An address with this composite key was not found
400 INVALID_COMPOSITE_KEY One of the path parameters is not a positive integer
400 UNKNOWN_SELECT_FIELD select carried a name that is absent from the address schema. The request is rejected before the record is read, and message lists the accepted names after the word Available. Available names — Address fields
403 SCOPE_DENIED The API key lacks the crm scope
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

Here the select name id returns the composite key, while in the list and the search Bitrix24 rejects it. Getting an address by its composite key reads the whole record and picks the fields on the Vibecode side, so select=id returns typeId, entityTypeId and entityId. The list and the search pass id on, and 422 BITRIX_ERROR comes back from there with an Unknown field definition message. A name that is absent from the address schema altogether is rejected the same way by all three endpoints — 400 UNKNOWN_SELECT_FIELD before the Bitrix24 call.

See also