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

List addresses

GET /v1/addresses

Returns a list of CRM entity addresses with support for filtering, sorting and auto-pagination. An address has no separate numeric id: to get a single address, use the three values — typeId, entityTypeId and entityId.

Parameters

Parameter Type Default Description
select string — Comma-separated field names: typeId, entityTypeId, entityId, address1, address2, city, postalCode, region, province, country, countryCode, locAddrId, anchorTypeId, anchorId. Bitrix24 source names are accepted too — CITY maps to city. The value * returns every field. Next to *, an unknown name is not rejected — a 200 arrives with an UNKNOWN_SELECT_FIELD warning in meta.warnings, and the field is missing from the records. Without select, full records are returned
limit number 50 Number of records (up to 5000). When limit > 50, Vibecode automatically requests several pages from Bitrix24
offset number 0 Skip N records. When offset ≥ 2500, limit ≤ 500 is recommended
sort / order string / object — Sorting: ?sort=typeId or ?order[typeId]=desc
filter object — Filtering by the fields of GET /v1/addresses/fields.
Filtering syntax. Example: ?filter[entityTypeId]=8&filter[entityId]=42.
Pass the whole filter in one form — either bracket notation or a single JSON object: two spellings destroy each other during query-string parsing, so a mixture is refused with 400 INVALID_FILTER. An empty ?filter= still means "no filter"

Examples

curl — personal key

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/addresses?filter[entityTypeId]=8&filter[entityId]=42" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/addresses?filter[entityTypeId]=8&filter[entityId]=42" \
  -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?filter[entityTypeId]=8&filter[entityId]=42',
  {
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
    },
  }
)

const { success, data, meta } = await res.json()
console.log(`Found ${meta.total} addresses`)

JavaScript — OAuth application

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/addresses?filter[entityTypeId]=8&filter[entityId]=42',
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)

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

Response fields

Field Type Description
success boolean Always true on success
data array Array of addresses (all fields — see Address fields)
meta.total number Total number of records matching the filter
meta.hasMore boolean Whether there are more records beyond limit

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
    },
    {
      "typeId": 1,
      "entityTypeId": 3,
      "entityId": 17,
      "address1": null,
      "address2": null,
      "city": null,
      "postalCode": null,
      "region": null,
      "province": null,
      "country": null,
      "countryCode": null,
      "locAddrId": 0,
      "anchorTypeId": 3,
      "anchorId": 17
    }
  ],
  "meta": {
    "total": 185,
    "hasMore": true
  }
}

Error response example

403 — no scope:

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

Errors

HTTP Code Description
403 SCOPE_DENIED The API key lacks the crm scope
401 TOKEN_MISSING The API key has no configured tokens
400 INVALID_FILTER An error in the filter syntax, or a condition spelled in filter that did not survive query-string parsing. The second case covers three spellings: both forms mixed (in either order), one name spelled at two different nesting levels (?filter[city]=Berlin&filter[city][eq]=Berlin), nesting deeper than two levels. The message names which one. The whole request is rejected before Bitrix24 is called: previously such a filter was silently dropped and the response covered the portal's entire address book
400 UNKNOWN_SELECT_FIELD select carried a name that is absent from the address schema. The request is rejected before the Bitrix24 call, and message lists the accepted names after the word Available. Available names — Address fields
422 BITRIX_ERROR select carried id. The address schema accepts that name, Bitrix24 does not know it, so the whole call is rejected with an Unknown field definition message. The composite key comes from getting a single address

Full list of common API errors — Errors.

Known specifics

An address has no separate numeric id. Each address is identified by three values: typeId (address type), entityTypeId (owner type) and entityId (owner ID). To get a single address, use GET /v1/addresses/:typeId/:entityTypeId/:entityId.

The composite key stays in a narrowed record. With select, the fields typeId, entityTypeId and entityId arrive in the response even when they were not listed. Without them a row cannot be told apart from its neighbour, and the request path for an update or a delete cannot be assembled.

Auto-pagination. When limit > 50, Vibecode automatically requests several pages from Bitrix24 and returns all records in a single response.

See also