[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-sign-b2e\u002Fsend-document":3,"docs-tabs-sign-b2e\u002Fsend-document":6},{"content":4,"lastmod":5},"# Send a file for signature\n\n`POST \u002Fv1\u002Fsign-b2e\u002Fdocuments\u002Fsend`\n\nCreates a document from a single file and sends it to employees for signature. The key owner needs permission to create documents. Sending has legal consequences.\n\n**Scopes:** `sign.b2e`, `crm`.\n\n## Request body fields\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `fields` | object | yes | Fields object. Bitrix24 validates unknown fields and field values. |\n| `fields.company` | object \\| null | yes | Your own company: crmId or uuid. |\n| `fields.company.crmId` | number \\| string \\| boolean \\| null | no | Your own company ID from the [list of companies](\u002Fdocs\u002Fentities\u002Fcompanies). |\n| `fields.company.uuid` | string \\| null | no | HCM Link company UUID; requires humanresources.hcmlink. |\n| `fields.members` | array \\| null | yes | Members: at least one signer and one representative. Bitrix24 checks the composition and roles. |\n| `fields.members[].userId` | number \\| string \\| boolean \\| null | no | User ID from the [list of users](\u002Fdocs\u002Fentities\u002Fusers). |\n| `fields.members[].employeeId` | number \\| string \\| boolean \\| null | no | Numeric HCM Link employee ID; null for a regular user. |\n| `fields.members[].employeeCode` | number \\| string \\| boolean \\| null | no | HCM Link employee code; null for a regular user. |\n| `fields.members[].role` | number \\| string \\| boolean \\| null | no | Role: signer, assignee, reviewer or editor. |\n| `fields.responsible` | object \\| null | yes | Responsible person; the default role is assignee. |\n| `fields.responsible.userId` | number \\| string \\| boolean \\| null | no | User ID from the [list of users](\u002Fdocs\u002Fentities\u002Fusers). |\n| `fields.responsible.employeeId` | number \\| string \\| boolean \\| null | no | Numeric HCM Link employee ID; null for a regular user. |\n| `fields.responsible.employeeCode` | number \\| string \\| boolean \\| null | no | HCM Link employee code; null for a regular user. |\n| `fields.responsible.role` | number \\| string \\| boolean \\| null | no | Role: signer, assignee, reviewer or editor. |\n| `fields.companyProviderUid` | number \\| string \\| boolean \\| null | yes | Provider UID from the [list of company providers](.\u002Flist-company-providers.md). This is not the numeric external provider ID. |\n| `fields.files` | array \\| null | yes | Array of exactly one file. PDF, DOCX, DOC, RTF, ODT, JPG, JPEG and PNG are allowed; Bitrix24 checks the file. |\n| `fields.files[].fileName` | number \\| string \\| boolean \\| null | no | File name with extension. |\n| `fields.files[].fileType` | number \\| string \\| boolean \\| null | no | MIME type matching the extension. |\n| `fields.files[].fileContent` | number \\| string \\| boolean \\| null | no | File bytes in Base64. |\n| `fields.regionDocumentType` | number \\| string \\| boolean \\| null | no | Regional document type. Whether it is allowed depends on the license region. |\n| `fields.externalSettings` | object \\| null | yes | External system settings; null is allowed when sending from a template. |\n| `fields.externalSettings.externalId` | number \\| string \\| boolean \\| null | yes | Document ID in the external system, up to 255 characters. |\n| `fields.externalSettings.externalDateCreate` | number \\| string \\| boolean \\| null | yes | Creation date in the external system in ISO 8601. Sending from a template requires the ATOM format with a numeric time zone offset. |\n| `fields.language` | number \\| string \\| boolean \\| null | no | Language of state names, en by default; an unknown language is replaced with en. Inside fields it is accepted but does not affect the document. |\n| `fields.message` | number \\| string \\| boolean \\| null | no | Invitation text for the employee. Bitrix24 checks the limits. |\n| `fields.signers` | array \\| null | no | Accepted but not used to define members; use members instead. |\n| `fields.signers[].userId` | number \\| string \\| boolean \\| null | no | User ID from the [list of users](\u002Fdocs\u002Fentities\u002Fusers). |\n| `fields.signers[].employeeId` | number \\| string \\| boolean \\| null | no | Numeric HCM Link employee ID; null for a regular user. |\n| `fields.signers[].employeeCode` | number \\| string \\| boolean \\| null | no | HCM Link employee code; null for a regular user. |\n| `fields.signers[].role` | number \\| string \\| boolean \\| null | no | Role: signer, assignee, reviewer or editor. |\n| `fields.representatives` | array \\| null | no | Accepted but not used to define members; use members instead. |\n| `fields.representatives[].userId` | number \\| string \\| boolean \\| null | no | User ID from the [list of users](\u002Fdocs\u002Fentities\u002Fusers). |\n| `fields.representatives[].employeeId` | number \\| string \\| boolean \\| null | no | Numeric HCM Link employee ID; null for a regular user. |\n| `fields.representatives[].employeeCode` | number \\| string \\| boolean \\| null | no | HCM Link employee code; null for a regular user. |\n| `fields.representatives[].role` | number \\| string \\| boolean \\| null | no | Role: signer, assignee, reviewer or editor. |\n| `fields.reviewer` | object \\| null | no | Accepted but not used to define members; use members instead. |\n| `fields.reviewer.userId` | number \\| string \\| boolean \\| null | no | User ID from the [list of users](\u002Fdocs\u002Fentities\u002Fusers). |\n| `fields.reviewer.employeeId` | number \\| string \\| boolean \\| null | no | Numeric HCM Link employee ID; null for a regular user. |\n| `fields.reviewer.employeeCode` | number \\| string \\| boolean \\| null | no | HCM Link employee code; null for a regular user. |\n| `fields.reviewer.role` | number \\| string \\| boolean \\| null | no | Role: signer, assignee, reviewer or editor. |\n| `fields.editor` | object \\| null | no | Accepted but not used to define members; use members instead. |\n| `fields.editor.userId` | number \\| string \\| boolean \\| null | no | User ID from the [list of users](\u002Fdocs\u002Fentities\u002Fusers). |\n| `fields.editor.employeeId` | number \\| string \\| boolean \\| null | no | Numeric HCM Link employee ID; null for a regular user. |\n| `fields.editor.employeeCode` | number \\| string \\| boolean \\| null | no | HCM Link employee code; null for a regular user. |\n| `fields.editor.role` | number \\| string \\| boolean \\| null | no | Role: signer, assignee, reviewer or editor. |\n| `language` | string | no | Language of state names, en by default; an unknown language is replaced with en. Inside fields it is accepted but does not affect the document. |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST 'https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fsign-b2e\u002Fdocuments\u002Fsend' \\\n  -H 'X-Api-Key: YOUR_API_KEY' \\\n  -H 'Content-Type: application\u002Fjson' \\\n  -d '{\"fields\": {\"company\": {\"crmId\": 7}, \"companyProviderUid\": \"DUMMY_PROVIDER_UID\", \"members\": [{\"userId\": 7, \"role\": \"signer\"}, {\"userId\": 8, \"role\": \"assignee\"}], \"responsible\": {\"userId\": 8, \"role\": \"assignee\"}, \"files\": [{\"fileName\": \"VIBE-PROBE.pdf\", \"fileType\": \"application\u002Fpdf\", \"fileContent\": \"BASE64_FILE_BYTES\"}], \"externalSettings\": {\"externalId\": \"VIBE-PROBE-document-001\", \"externalDateCreate\": \"2026-11-13T12:00:00+00:00\"}}}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST 'https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fsign-b2e\u002Fdocuments\u002Fsend' \\\n  -H 'X-Api-Key: YOUR_APP_KEY' \\\n  -H 'Authorization: Bearer USER_SESSION_TOKEN' \\\n  -H 'Content-Type: application\u002Fjson' \\\n  -d '{\"fields\": {\"company\": {\"crmId\": 7}, \"companyProviderUid\": \"DUMMY_PROVIDER_UID\", \"members\": [{\"userId\": 7, \"role\": \"signer\"}, {\"userId\": 8, \"role\": \"assignee\"}], \"responsible\": {\"userId\": 8, \"role\": \"assignee\"}, \"files\": [{\"fileName\": \"VIBE-PROBE.pdf\", \"fileType\": \"application\u002Fpdf\", \"fileContent\": \"BASE64_FILE_BYTES\"}], \"externalSettings\": {\"externalId\": \"VIBE-PROBE-document-001\", \"externalDateCreate\": \"2026-11-13T12:00:00+00:00\"}}}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fsign-b2e\u002Fdocuments\u002Fsend', {\n  \"method\": \"POST\",\n  \"headers\": {\n    \"X-Api-Key\": \"YOUR_API_KEY\",\n    \"Content-Type\": \"application\u002Fjson\"\n  },\n  body: JSON.stringify({\"fields\": {\"company\": {\"crmId\": 7}, \"companyProviderUid\": \"DUMMY_PROVIDER_UID\", \"members\": [{\"userId\": 7, \"role\": \"signer\"}, {\"userId\": 8, \"role\": \"assignee\"}], \"responsible\": {\"userId\": 8, \"role\": \"assignee\"}, \"files\": [{\"fileName\": \"VIBE-PROBE.pdf\", \"fileType\": \"application\u002Fpdf\", \"fileContent\": \"BASE64_FILE_BYTES\"}], \"externalSettings\": {\"externalId\": \"VIBE-PROBE-document-001\", \"externalDateCreate\": \"2026-11-13T12:00:00+00:00\"}}})\n});\nconst result = await response.json();\nif (!response.ok || !result.success) throw new Error(result.error?.message);\nconsole.log(result.data);\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst response = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fsign-b2e\u002Fdocuments\u002Fsend', {\n  \"method\": \"POST\",\n  \"headers\": {\n    \"X-Api-Key\": \"YOUR_APP_KEY\",\n    \"Authorization\": \"Bearer USER_SESSION_TOKEN\",\n    \"Content-Type\": \"application\u002Fjson\"\n  },\n  body: JSON.stringify({\"fields\": {\"company\": {\"crmId\": 7}, \"companyProviderUid\": \"DUMMY_PROVIDER_UID\", \"members\": [{\"userId\": 7, \"role\": \"signer\"}, {\"userId\": 8, \"role\": \"assignee\"}], \"responsible\": {\"userId\": 8, \"role\": \"assignee\"}, \"files\": [{\"fileName\": \"VIBE-PROBE.pdf\", \"fileType\": \"application\u002Fpdf\", \"fileContent\": \"BASE64_FILE_BYTES\"}], \"externalSettings\": {\"externalId\": \"VIBE-PROBE-document-001\", \"externalDateCreate\": \"2026-11-13T12:00:00+00:00\"}}})\n});\nconst result = await response.json();\nif (!response.ok || !result.success) throw new Error(result.error?.message);\nconsole.log(result.data);\n```\n\n## Response fields\n\n| Field | Type | Description |\n|---|---|---|\n| `success` | boolean | Whether the request succeeded. |\n| `data` | object | Operation data. |\n| `data.uid` | string \\| null | Document UID. |\n| `data.state` | object \\| null | Object state. |\n| `data.state.code` | string \\| null | Machine-readable code. |\n| `data.state.name` | string \\| null | Localized signing state name. |\n| `data.members` | array | Document members. |\n| `data.members[].uid` | string \\| null | Signing member UID. |\n| `data.members[].role` | string \\| null | Member role. |\n| `data.members[].state` | object \\| null | Object state. |\n| `data.members[].state.code` | string \\| null | Machine-readable code. |\n| `data.members[].state.name` | string \\| null | Localized signing state name. |\n| `data.members[].user` | object \\| null | The member's user. |\n| `data.members[].party` | integer \\| null | The member's signing party number. |\n| `data.members[].user.employeeCode` | string \\| null | HCM Link employee code; null for a regular user. |\n| `data.members[].user.employeeId` | integer \\| null | Numeric HCM Link employee ID; null for a regular user. |\n| `data.members[].user.userId` | integer \\| null | User ID. |\n| `meta.redacted` | array\u003Cstring> | Present when credentials are hidden; contains the paths of the replaced values. |\n\n## Response example\n\nShape of a successful response; the data depends on the Bitrix24 account and the request.\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"uid\": \"DUMMY_DOCUMENT_UID\",\n    \"state\": {\n      \"code\": \"ready\",\n      \"name\": \"Ready\"\n    },\n    \"members\": []\n  }\n}\n```\n\n## Error response example\n\n403 — the key lacks a required scope:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"SCOPE_DENIED\",\n    \"message\": \"This endpoint requires 'sign.b2e' scope\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Reason |\n|---|---|---|\n| 400 | `INVALID_PARAMS` | Invalid request shape: types, required fields or an unknown query string parameter. |\n| 401 | `TOKEN_MISSING` | No credentials for the Bitrix24 connection. |\n| 403 | `SCOPE_DENIED` | One of the required scopes is not granted. |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the operation; the code is in error.b24Code, the text in error.message. |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only. |\n\n[Common API errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\nThe signers, representatives, reviewer and editor fields are parsed by the DTO, but the send operation does not use them. HCM Link is checked only for company.uuid, members and responsible; the legacy fields do not select HCM employees and require no additional scope. Specify participants through members with the required role.\n\nBitrix24 checks user permissions, HR e-signature availability, business rules, page sizes and field contents. Values are passed through without local correction. Bitrix24 checks the fields marked as required; a missing business field results in a Bitrix24 rejection. Scalar fields accept numeric, boolean and null values; Bitrix24 converts them by its own rules. Response text is JSON-encoded; credential-bearing links are hidden.\n\nThe operation is not retried automatically. If the outcome is unknown, check the state in the Bitrix24 account first; resending can create another document.\n\nThe request body is limited to 40 MiB including Base64. The preliminary admission check for a large body can return 413 or 429. Participants are taken only from members; signers, representatives, reviewer and editor are not used for this.\n\n## See also\n\n- [Employee signatures](\u002Fdocs\u002Fsign-b2e)\n- [API errors](\u002Fdocs\u002Ferrors)\n","2026-11-18",{},1795344085198]