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
ParametertypeId (path) Typenumber Requiredyes DescriptionAddress 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
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
Parameterselect (query) Typestring Requiredno DescriptionComma-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 application

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 application

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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionAddress object
Fielddata.typeId Typenumber DescriptionAddress type
Fielddata.entityTypeId Typenumber DescriptionOwner type
Fielddata.entityId Typenumber DescriptionOwner ID
Fielddata.address1 Typestring | null DescriptionStreet, building, block, structure
Fielddata.address2 Typestring | null DescriptionApartment, office
Fielddata.city Typestring | null DescriptionCity
Fielddata.postalCode Typestring | null DescriptionPostal code
Fielddata.region Typestring | null DescriptionDistrict
Fielddata.province Typestring | null DescriptionProvince
Fielddata.country Typestring | null DescriptionCountry
Fielddata.countryCode Typestring | null DescriptionCountry code
Fielddata.locAddrId Typenumber DescriptionLocation address identifier
Fielddata.anchorTypeId Typenumber DescriptionType of the entity the address is linked to (read-only)
Fielddata.anchorId Typenumber DescriptionID of the entity the address is linked to (read-only)
Fieldmeta.warnings Typearray DescriptionReturned 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
HTTP404 CodeNOT_FOUND DescriptionAn address with this composite key was not found
HTTP400 CodeINVALID_COMPOSITE_KEY DescriptionOne of the path parameters is not a positive integer
HTTP400 CodeUNKNOWN_SELECT_FIELD Descriptionselect 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
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe 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