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

Documents by CRM record

GET /v1/crm-documents

Returns documents attached to a specific CRM record — a deal, contact, company, lead, quote, invoice, or smart process item. Unlike the list of all documents in the Bitrix24 account, documents are filtered by record type and record ID.

Parameters

Parameter Type Required Default Description
entityTypeId (query) number yes — CRM record type — a single positive integer passed once. Allowed values are in the "CRM record types" list below. The entityTypeID spelling is accepted too, but only one of the two
entityId (query) number no — Record ID — a single positive integer passed at most once. The entityID spelling is accepted too, but only one of the two. Without the parameter, and also with a single empty value entityId=, documents of all records of the given type are returned. See the "CRM record types" list below for where to get the ID for each type
select (query) string no — Field selection: ?select=id,title,number
order (query) object no — Sorting: ?order[updateTime]=desc. Direction — asc or desc. One bracket level: the value of an entry is a direction, and a second level under the field name returns 400 INVALID_ORDER
start (query) number no 0 Offset for pagination — a single integer 0 or greater, passed at most once. An empty value start= is the same as 0. The parameter has no alternative spellings

A single call returns up to 50 documents. For the next page, pass the meta.next value as the start parameter. When there are no more documents, meta.next is null.

CRM record types

The entityTypeId value and the endpoint to get entityId from:

  • 1 — lead. Record ID: GET /v1/leads
  • 2 — deal. Record ID: GET /v1/deals
  • 3 — contact. Record ID: GET /v1/contacts
  • 4 — company. Record ID: GET /v1/companies
  • 7 — quote. Record ID: GET /v1/quotes
  • 31 — invoice. Record ID: GET /v1/invoices
  • 128 and above — smart process item. Take the entityTypeId value from GET /v1/smart-processes and the record ID from GET /v1/items/:entityTypeId

Examples

curl — personal key

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/crm-documents?entityTypeId=2&entityId=15&order[updateTime]=desc" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/crm-documents?entityTypeId=2&entityId=15&order[updateTime]=desc" \
  -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/crm-documents?entityTypeId=2&entityId=15&order[updateTime]=desc', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`The record has ${meta.total} documents`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-documents?entityTypeId=2&entityId=15&order[updateTime]=desc', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

Identifiers are returned as strings.

Field Type Description
success boolean Always true on success
data array Array of documents
data[].id string Document identifier
data[].title string Document title
data[].number string Document number
data[].templateId string Template identifier. Source — GET /v1/doc-templates
data[].entityTypeId string Type of the CRM record the document is attached to
data[].entityId string ID of the CRM record the document is attached to
data[].fileId string Identifier of the generated file
data[].pdfId string Identifier of the PDF version
data[].imageId string Identifier of the preview image
data[].downloadUrl string File download link for the user
data[].pdfUrl string PDF link for the user
data[].imageUrl string Preview image link for the user
data[].downloadUrlMachine string Vibe API URL; requires X-Api-Key with crm scope
data[].pdfUrlMachine string Vibe API URL; requires X-Api-Key with crm scope
data[].imageUrlMachine string Vibe API URL; requires X-Api-Key with crm scope
data[].stampsEnabled boolean Whether stamps and signatures are enabled
data[].values object Values for the template's label fields
data[].createTime string Creation date in ISO 8601 format
data[].updateTime string Modification date in ISO 8601 format
data[].createdBy string Creator ID. Source — GET /v1/users
data[].updatedBy string | null Last editor ID. Source — GET /v1/users
meta.total number Number of documents on the record
meta.start number Offset of the current page
meta.next number | null Offset of the next page. null if there are no more documents

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": "405",
      "title": "Invoice A-161",
      "number": "A-161",
      "templateId": "1",
      "entityTypeId": "2",
      "entityId": "15",
      "fileId": "1369",
      "pdfId": "1373",
      "imageId": "1371",
      "downloadUrl": "https://example.bitrix24.com/bitrix/services/main/ajax.php?action=crm.documentgenerator.document.download&id=405",
      "pdfUrl": "https://example.bitrix24.com/bitrix/services/main/ajax.php?action=crm.documentgenerator.document.getPdf&id=405",
      "imageUrl": "https://example.bitrix24.com/bitrix/services/main/ajax.php?action=crm.documentgenerator.document.getImage&id=405",
      "downloadUrlMachine": "https://vibecode.bitrix24.com/v1/crm-documents/405/download",
      "pdfUrlMachine": "https://vibecode.bitrix24.com/v1/crm-documents/405/pdf",
      "imageUrlMachine": "https://vibecode.bitrix24.com/v1/crm-documents/405/image",
      "stampsEnabled": false,
      "values": { "_creationMethod": "public" },
      "createTime": "2026-01-18T11:10:00+00:00",
      "updateTime": "2026-01-18T11:10:00+00:00",
      "createdBy": "29",
      "updatedBy": null
    },
    {
      "id": "406",
      "title": "Act A-162",
      "number": "A-162",
      "templateId": "4",
      "entityTypeId": "2",
      "entityId": "15",
      "fileId": "1402",
      "pdfId": "1404",
      "imageId": "1403",
      "downloadUrl": "https://example.bitrix24.com/bitrix/services/main/ajax.php?action=crm.documentgenerator.document.download&id=406",
      "pdfUrl": "https://example.bitrix24.com/bitrix/services/main/ajax.php?action=crm.documentgenerator.document.getPdf&id=406",
      "imageUrl": "https://example.bitrix24.com/bitrix/services/main/ajax.php?action=crm.documentgenerator.document.getImage&id=406",
      "downloadUrlMachine": "https://vibecode.bitrix24.com/v1/crm-documents/406/download",
      "pdfUrlMachine": "https://vibecode.bitrix24.com/v1/crm-documents/406/pdf",
      "imageUrlMachine": "https://vibecode.bitrix24.com/v1/crm-documents/406/image",
      "stampsEnabled": false,
      "values": { "_creationMethod": "public" },
      "createTime": "2026-01-19T09:30:00+00:00",
      "updateTime": "2026-01-19T09:30:00+00:00",
      "createdBy": "29",
      "updatedBy": null
    }
  ],
  "meta": { "total": 2, "start": 0, "next": null }
}

Error response example

400 — entityTypeId is missing or invalid. A value of 0, a fraction, or a non-numeric value returns the same code:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "Query parameter `entityTypeId` (positive integer) is required. Common values: 1=LEAD, 2=DEAL, 3=CONTACT, 4=COMPANY, 7=QUOTE, 31=INVOICE, 128+ for smart processes."
  }
}

Errors

HTTP Code Description
400 MISSING_PARAMS entityTypeId not provided, or its value is not a positive integer
400 INVALID_ENTITY_TYPE The record type is not passed as a single value: the parameter is repeated, both spellings entityTypeId and entityTypeID are passed together, or a bracket form is used — entityTypeId[]=2, entityTypeId[0]=2. The request is rejected even when the values are identical
400 INVALID_ENTITY_ID entityId was provided but is not a positive integer
400 INVALID_ENTITY_ID The record ID is not passed as a single value: the parameter is repeated, both spellings entityId and entityID are passed together, or a bracket form is used — entityId[]=7, entityId[0]=7. The request is rejected even when the values are identical
400 INVALID_START start was provided but is not an integer 0 or greater
400 INVALID_START The offset is not passed as a single value: the parameter is repeated, or a bracket form is used — start[]=1, start[0]=1. The request is rejected even when the values are identical
400 INVALID_ORDER A sorting entry carries a nested structure instead of a direction: a second bracket level sits under the field name — order[updateTime][x]=desc, order[updateTime][]=desc, order[updateTime][0]=desc. A spelling the parser cannot place at all — order=desc, order[]=desc, a third bracket level — still leaves the listing unsorted rather than failing
403 SCOPE_DENIED The key is missing the crm scope
401 MISSING_API_KEY The X-Api-Key header was not provided
401 TOKEN_MISSING The authorization key has no tokens assigned — an OAuth application key was used without a user session
422 BITRIX_ERROR The document generator module is not installed on the portal

Full list of common API errors — Errors.

Known specifics

The select parameter limits the field set, but the file links downloadUrl, pdfUrl, imageUrl together with their machine variants, as well as stampsEnabled and values, are always returned even when absent from the selection.

The single-occurrence check on entityId and start counts parameter occurrences, not their values, and does not protect against parameter smuggling: an unencoded value can introduce any extra parameter into the query string, including ones that pass the check. Encode user input when building query strings.

See also