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, the selection is by record type and its identifier.

Parameters

Parameter Type Required Default Description
entityTypeId (query) number yes — CRM record type. Allowed values are in the "CRM record types" list below
entityId (query) number no — Record ID. Without it, documents of all records of the given type are returned. Where to get the ID by type is in the "CRM record types" list below
select (query) string no — Field selection: ?select=id,title,number
order (query) object no — Sorting: ?order[updateTime]=desc. Direction — asc or desc
start (query) number no 0 Offset for paging

A single call returns up to 50 documents. For the next page, pass the meta.next value into 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. The entityTypeId value — from GET /v1/smart-processes, the record ID — from GET /v1/items/:entityTypeId

Examples

curl — personal key

Terminal 
curl "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 "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 ready 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 Download link for the application
data[].pdfUrlMachine string PDF link for the application
data[].imageUrlMachine string Image link for the application
data[].stampsEnabled boolean Whether signature and stamp 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://example.bitrix24.com/rest/1/APP_TOKEN/crm.documentgenerator.document.download/?id=405",
      "pdfUrlMachine": "https://example.bitrix24.com/rest/1/APP_TOKEN/crm.documentgenerator.document.getPdf/?id=405",
      "imageUrlMachine": "https://example.bitrix24.com/rest/1/APP_TOKEN/crm.documentgenerator.document.getImage/?id=405",
      "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://example.bitrix24.com/rest/1/APP_TOKEN/crm.documentgenerator.document.download/?id=406",
      "pdfUrlMachine": "https://example.bitrix24.com/rest/1/APP_TOKEN/crm.documentgenerator.document.getPdf/?id=406",
      "imageUrlMachine": "https://example.bitrix24.com/rest/1/APP_TOKEN/crm.documentgenerator.document.getImage/?id=406",
      "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_ID entityId was provided but is not a positive integer
400 INVALID_START start was provided but is not an integer 0 or greater
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 called 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.

See also