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

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

Create a CRM document

POST /v1/crm-documents

Generates a document from a CRM template for a CRM record (a deal, contact, company or smart process item) and attaches it to that record. Fields are passed at the JSON root without a fields wrapper.

Request fields (body)

Field Type Required Description
FieldtemplateId Typenumber Requiredyes DescriptionCRM template ID, a positive integer. Templates available for a record: GET /v1/crm-document-templates/available
FieldentityTypeId 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
FieldentityId 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
Fieldvalues Typeobject Requiredno DescriptionTemplate field values. For example, DocumentNumber sets the document number
FieldstampsEnabled Typeboolean Requiredno DescriptionEnable stamps and signatures. If the field is not passed, stamps are disabled. The changeStampsEnabled response field shows whether the template has stamps

The request accepts no other fields, such as title. The stamps flag is passed only at the body root, not inside values.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-documents" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": 87,
    "entityTypeId": 2,
    "entityId": 8781,
    "values": { "DocumentNumber": "VD-100" }
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-documents" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": 87,
    "entityTypeId": 2,
    "entityId": 8781,
    "values": { "DocumentNumber": "VD-100" }
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-documents', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 87,
    entityTypeId: 2,
    entityId: 8781,
    values: { DocumentNumber: 'VD-100' },
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-documents', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 87,
    entityTypeId: 2,
    entityId: 8781,
    values: { DocumentNumber: 'VD-100' },
  }),
})

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

Response fields

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

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typenumber DescriptionID of the created document. Returned as a number, unlike the GET /v1/crm-documents/:id response
Fielddata.title Typestring DescriptionDocument title generated from the template
Fielddata.number Typestring DescriptionDocument number. Set by values.DocumentNumber or by the template numerator
Fielddata.templateId Typestring DescriptionTemplate ID
Fielddata.entityTypeId Typestring DescriptionCRM record type
Fielddata.entityId Typenumber DescriptionCRM record ID
Fielddata.values Typeobject DescriptionTemplate field values as passed, along with service keys
Fielddata.stampsEnabled Typeboolean DescriptionWhether stamps and signatures are enabled
Fielddata.changeStampsEnabled Typeboolean DescriptionWhether stamps can be enabled: false if the template has none
Fielddata.createdBy Typenumber DescriptionCreator ID. List: GET /v1/users
Fielddata.downloadUrl Typestring DescriptionLink for an employee to open the DOCX file in a browser
Fielddata.downloadUrlMachine Typestring DescriptionURL of /v1/crm-documents/:id/download. Requires X-Api-Key with the crm scope

Response example

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

JSON 
{
  "success": true,
  "data": {
    "changeStampsEnabled": false,
    "downloadUrl": "https://example.bitrix24.com/bitrix/services/main/ajax.php?action=crm.documentgenerator.document.download&SITE_ID=s1&id=1981",
    "publicUrl": null,
    "title": "Addresses VD-100",
    "number": "VD-100",
    "id": 1981,
    "createTime": "2026-10-08T17:55:00+00:00",
    "createdBy": 1317,
    "stampsEnabled": false,
    "isTransformationError": false,
    "values": {
      "productsTableVariant": "",
      "stampsEnabled": false,
      "_creationMethod": "rest",
      "DocumentNumber": "VD-100"
    },
    "templateId": "87",
    "entityId": 8781,
    "entityTypeId": "2",
    "downloadUrlMachine": "https://vibecode.bitrix24.com/v1/crm-documents/1981/download"
  }
}

Error response example

404 — no template with this templateId exists:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Template not found"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe body is not a JSON object, for example an array. Message: A document body is required
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptiontemplateId, entityTypeId or entityId is missing, or the value is not a positive integer. Message: templateId, entityTypeId and entityId must be positive integers
HTTP400 CodeREADONLY_FIELD DescriptionThe body contains a field not listed in the table above, for example title
HTTP400 CodeINVALID_PARAMS Descriptionvalues is not an object, values contains stampsEnabled, or stampsEnabled is not a boolean
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo template with this templateId exists. Message: Template not found
HTTP422 CodeBITRIX_ERROR DescriptionThis entityTypeId is not supported for documents, for example 999. Message: No provider for entityTypeId
HTTP502 CodeBITRIX_INVALID_RESPONSE DescriptionBitrix24 responded without a document
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionNo access to the CRM record, including a contact that does not exist. Message: Access denied
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
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

Deal existence is not checked. With entityTypeId: 2, a document is created even for an entityId that matches no deal: the response is 201. For a contact with a nonexistent ID, 403 BITRIX_ACCESS_DENIED is returned. Check the record beforehand, for example via GET /v1/deals/:id.

PDF and image appear later. The creation response contains only DOCX links. Links to the PDF and image appear in the GET /v1/crm-documents/:id response once the files are ready. Until then, downloading the PDF returns 409 DOCUMENT_NOT_READY.

IDs can be passed as strings. "templateId": "87" is accepted the same way as 87.

See also