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
ParameterentityTypeId (query) Typenumber Requiredyes Default— DescriptionCRM 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
ParameterentityId (query) Typenumber Requiredno Default— DescriptionRecord 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
Parameterselect (query) Typestring Requiredno Default— DescriptionField selection: ?select=id,title,number
Parameterorder (query) Typeobject Requiredno Default— DescriptionSorting: ?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
Parameterstart (query) Typenumber Requiredno Default0 DescriptionOffset 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

The generic filter parameter is not applied by this endpoint. By default, the API preserves the previous HTTP 200 response and data, adds Warning: 299 - "filter is not supported on this endpoint and was ignored", and records unsupported-filter use in the server log.

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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of documents
Fielddata[].id Typestring DescriptionDocument identifier
Fielddata[].title Typestring DescriptionDocument title
Fielddata[].number Typestring DescriptionDocument number
Fielddata[].templateId Typestring DescriptionTemplate identifier. Source — GET /v1/doc-templates
Fielddata[].entityTypeId Typestring DescriptionType of the CRM record the document is attached to
Fielddata[].entityId Typestring DescriptionID of the CRM record the document is attached to
Fielddata[].fileId Typestring DescriptionIdentifier of the generated file
Fielddata[].pdfId Typestring DescriptionIdentifier of the PDF version
Fielddata[].imageId Typestring DescriptionIdentifier of the preview image
Fielddata[].downloadUrl Typestring DescriptionFile download link for the user
Fielddata[].pdfUrl Typestring DescriptionPDF link for the user
Fielddata[].imageUrl Typestring DescriptionPreview image link for the user
Fielddata[].downloadUrlMachine Typestring DescriptionVibe API URL; requires X-Api-Key with crm scope
Fielddata[].pdfUrlMachine Typestring DescriptionVibe API URL; requires X-Api-Key with crm scope
Fielddata[].imageUrlMachine Typestring DescriptionVibe API URL; requires X-Api-Key with crm scope
Fielddata[].stampsEnabled Typeboolean DescriptionWhether stamps and signatures are enabled
Fielddata[].values Typeobject DescriptionValues for the template's label fields
Fielddata[].createTime Typestring DescriptionCreation date in ISO 8601 format
Fielddata[].updateTime Typestring DescriptionModification date in ISO 8601 format
Fielddata[].createdBy Typestring DescriptionCreator ID. Source — GET /v1/users
Fielddata[].updatedBy Typestring | null DescriptionLast editor ID. Source — GET /v1/users
Fieldmeta.total Typenumber DescriptionNumber of documents on the record
Fieldmeta.start Typenumber DescriptionOffset of the current page
Fieldmeta.next Typenumber | null DescriptionOffset 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
HTTP200 CodeWarning: 299 DescriptionThe filter is ignored by default; previous data is preserved and the warning is sent in the Warning header.
HTTP400 (strict mode only) CodeUNSUPPORTED_FILTER DescriptionThe server mode is disabled by default; until it is enabled, the endpoint preserves HTTP 200 and the previous data.
HTTP400 CodeMISSING_PARAMS DescriptionentityTypeId not provided, or its value is not a positive integer
HTTP400 CodeINVALID_ENTITY_TYPE DescriptionThe 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
HTTP400 CodeINVALID_ENTITY_ID DescriptionentityId was provided but is not a positive integer
HTTP400 CodeINVALID_ENTITY_ID DescriptionThe 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
HTTP400 CodeINVALID_START Descriptionstart was provided but is not an integer 0 or greater
HTTP400 CodeINVALID_START DescriptionThe 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
HTTP400 CodeINVALID_ORDER DescriptionA 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. Syntax the parser cannot parse at all — order=desc, order[]=desc, a third bracket level — still leaves the listing unsorted rather than failing
HTTP403 CodeSCOPE_DENIED DescriptionThe key is missing the crm scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not provided
HTTP401 CodeTOKEN_MISSING DescriptionThe authorization key has no tokens assigned — an OAuth application key was used without a user session
HTTP422 CodeBITRIX_ERROR DescriptionThe 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