## 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 ```bash 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 ```bash 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](/docs/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 - [List documents](/docs/entities/documents/list) - [Create document](/docs/entities/documents/create) - [Document templates](/docs/entities/doc-templates)