لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/documents/crm-upload.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Upload a CRM document

POST /v1/crm-documents/upload

Attaches a ready-made document file, produced outside Bitrix24 without a template, to a CRM record. The file is sent as a base64 string, and the fields go inside the fields object.

Request fields (body)

Field Type Required Description
Fieldfields.entityTypeId Typenumber Requiredyes DescriptionCRM record type, a positive integer: 2 — deal, 3 — contact, 4 — company. Other types are in the "CRM record types" list on the GET /v1/crm-documents page
Fieldfields.entityId Typenumber Requiredyes DescriptionRecord ID, a positive integer. The source depends on the type: deals — GET /v1/deals, contacts — GET /v1/contacts, companies — GET /v1/companies
Fieldfields.title Typestring Requiredyes DescriptionDocument title
Fieldfields.number Typestring Requiredyes DescriptionDocument number. A number instead of a string is rejected
Fieldfields.region Typestring Requiredyes DescriptionDocument region, for example uk or de
Fieldfields.fileContent Typestring Requiredyes DescriptionDOCX file content as a base64 string, at most 2 MiB after decoding
Fieldfields.pdfContent Typestring Requiredno DescriptionPDF version of the document as a base64 string, at most 2 MiB after decoding
Fieldfields.imageContent Typestring Requiredno DescriptionDocument image as a base64 string, at most 2 MiB after decoding

The whole request body is at most 3 MiB. The id, fileId, pdfId, imageId, moduleId, providerClassName and value fields are set by Bitrix24: a request with any of them is rejected with 400 READONLY_FIELD.

Examples

In the examples, contract.docx is your document file. The request body is assembled into a document.json file and then sent.

curl — personal key

Terminal 
printf '{"fields":{"entityTypeId":2,"entityId":8781,"title":"Supply agreement","number":"VD-1","region":"uk","fileContent":"%s"}}' \
  "$(base64 < contract.docx | tr -d '\n')" > document.json

curl -X POST "https://vibecode.bitrix24.com/v1/crm-documents/upload" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @document.json

curl — OAuth application

Terminal 
printf '{"fields":{"entityTypeId":2,"entityId":8781,"title":"Supply agreement","number":"VD-1","region":"uk","fileContent":"%s"}}' \
  "$(base64 < contract.docx | tr -d '\n')" > document.json

curl -X POST "https://vibecode.bitrix24.com/v1/crm-documents/upload" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @document.json

JavaScript — personal key

javascript 
import { readFile } from 'node:fs/promises'

const fileContent = (await readFile('contract.docx')).toString('base64')

const res = await fetch('https://vibecode.bitrix24.com/v1/crm-documents/upload', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: {
      entityTypeId: 2,
      entityId: 8781,
      title: 'Supply agreement',
      number: 'VD-1',
      region: 'uk',
      fileContent,
    },
  }),
})

const { success, data } = await res.json()
console.log('Document:', data.id)

JavaScript — OAuth application

javascript 
import { readFile } from 'node:fs/promises'

const fileContent = (await readFile('contract.docx')).toString('base64')

const res = await fetch('https://vibecode.bitrix24.com/v1/crm-documents/upload', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: {
      entityTypeId: 2,
      entityId: 8781,
      title: 'Supply agreement',
      number: 'VD-1',
      region: 'uk',
      fileContent,
    },
  }),
})

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

Response fields

Returns HTTP status 201 Created and the created document. The full description of document fields is on the Get a CRM document page.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typestring DescriptionDocument ID
Fielddata.title Typestring DescriptionTitle from fields.title
Fielddata.number Typestring DescriptionNumber from fields.number
Fielddata.entityTypeId Typestring DescriptionCRM record type
Fielddata.entityId Typestring DescriptionCRM record ID
Fielddata.templateId Typestring DescriptionInternal template used for uploaded documents. It does not appear in template lists
Fielddata.createdBy Typestring DescriptionID of the user who uploaded the document. List: GET /v1/users
Fielddata.downloadUrlMachine Typestring DescriptionURL of /v1/crm-documents/:id/download. Requires X-Api-Key with the crm scope
Fielddata.pdfUrlMachine Typestring DescriptionURL of /v1/crm-documents/:id/pdf. Present in the response right away if fields.pdfContent was sent

Response example

The main fields are shown. Full list: Get a CRM document.

JSON 
{
  "success": true,
  "data": {
    "downloadUrl": "https://example.bitrix24.com/bitrix/services/main/ajax.php?action=crm.documentgenerator.document.download&SITE_ID=s1&id=1985",
    "publicUrl": null,
    "title": "Supply agreement",
    "number": "VD-1",
    "id": "1985",
    "createTime": "2026-10-08T17:59:45+00:00",
    "createdBy": "1317",
    "stampsEnabled": false,
    "isTransformationError": false,
    "templateId": "275",
    "entityId": "8781",
    "entityTypeId": "2",
    "downloadUrlMachine": "https://vibecode.bitrix24.com/v1/crm-documents/1985/download"
  }
}

Error response example

400 — fileContent is not a base64 string:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "fileContent must be base64"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe fields object is missing. Message: fields is required
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionA required field is missing or empty. The message names the fields: Empty required fields: number
HTTP400 CodeREADONLY_FIELD Descriptionfields contains a field set by Bitrix24, for example id
HTTP400 CodeINVALID_PARAMS DescriptionentityTypeId or entityId is not a positive integer
HTTP400 CodeINVALID_PARAMS Descriptiontitle, number or region is not a string
HTTP400 CodeINVALID_PARAMS DescriptionfileContent, pdfContent or imageContent is not a base64 string. The message names the field
HTTP400 CodeINVALID_PARAMS DescriptionThe CRM record type in entityTypeId is not supported for documents, for example 999. Message: Wrong "entityTypeId" field value
HTTP413 CodePAYLOAD_TOO_LARGE DescriptionA file exceeds 2 MiB after decoding. The message names the field: fileContent must not exceed 2 MiB
HTTP413 CodePAYLOAD_TOO_LARGE DescriptionThe request body exceeds 3 MiB. Message: Request body too large
HTTP429 CodeLARGE_BODY_BACKEND_BUSY DescriptionThe body exceeds 1 MiB and the platform is already processing the maximum volume of large bodies. Retry the request after Retry-After seconds
HTTP502 CodeBITRIX_INVALID_RESPONSE DescriptionBitrix24 responded without a document
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the crm scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionNo tokens are mapped to the key — an OAuth application key was called without a user session

Full list of common API errors — Errors.

Known specifics

The file format is not checked. The only check is that fileContent is a valid base64 string. The file is stored as sent, even if it is not a DOCX, and the DOCX download returns the same bytes.

The record's existence is not checked. A document is created even for an entityId that does not exist among records of this type: the response is 201, including for a contact — unlike creating from a template. A document attached to a non-existent contact cannot be read or deleted afterwards: all methods return 403 BITRIX_ACCESS_DENIED. Check the record beforehand, for example with GET /v1/contacts/:id.

Without pdfContent, the PDF is generated later. If no PDF version is sent, the PDF is generated from the DOCX after the upload, and until then the PDF download returns 409 DOCUMENT_NOT_READY.

See also