Send Document for Signing sign.b2e.document.send

Choose a tool for developing with an AI agent:

  • use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
  • use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation

Scope: sign.b2e, crm

Who can execute the method: a user with permission to create documents in e-Signature for HR

The method sign.b2e.document.send sends a document for signing on behalf of the company.

This method works only in the context of application authorization application.

Method Parameters

Required parameters are marked with *

Name
type

Description

fields*
object

Parameters for sending the document for signing (detailed description)

language
string

Language for localizing statuses in the response.

Defaults to en

Parameter fields

Name
type

Description

company*
object

The company on behalf of which the document is sent (detailed description)

members*
array

List of signing participants. Must contain at least one participant with the role signer and one with the role assignee (detailed description)

responsible*
object

Responsible person for the document (detailed description)

companyProviderUid*
string

Identifier of the signing provider. You can get a list of available signing providers using the sign.b2e.company.provider.list method

files*
array

File of the document being signed (detailed description)

regionDocumentType*
string

Document type for the region (detailed description)

externalSettings*
object

External parameters of the document (detailed description)

language
string

Language of the document

Parameter company

Name
type

Description

uuid*
string

UUID of the company in HCM Link.

Requires additional scope humanresources.hcmlink

crmId*
integer

Identifier of the company in CRM, connected in the integration as "my company"

Pass either the uuid or crmId parameter.

Array Element members

Name
type

Description

employeeCode*
string

Employee code in HCM Link.

Requires additional scope humanresources.hcmlink

employeeId*
integer

Employee identifier in HCM Link.

Requires additional scope humanresources.hcmlink

userId*
integer

User identifier in Bitrix24

role*
string

Role of the participant. Possible values:

  • signer — signer,
  • assignee — company representative,
  • reviewer — approver,
  • editor — editor

Pass either the employeeId, employeeCode, or userId parameter.

The employeeCode and employeeId fields are available only for companies linked to HCM Link. For companies passed through company.crmId without a connection to HCM Link, use userId.

Parameter responsible

Name
type

Description

employeeCode*
string

Employee code in HCM Link.

Requires additional scope humanresources.hcmlink

employeeId*
integer

Employee identifier in HCM Link.

Requires additional scope humanresources.hcmlink

userId*
integer

User identifier in Bitrix24

role
string

Role of the participant. Possible values:

  • signer — signer,
  • assignee — company representative, default value
  • reviewer — approver,
  • editor — editor

Pass either the employeeId, employeeCode, or userId parameter.

The employeeCode and employeeId fields are available only for companies linked to HCM Link. For companies passed through company.crmId without a connection to HCM Link, use userId.

Array Element files

Name
type

Description

fileName*
string

File name. Must include the .pdf extension

fileType*
string

MIME type of the file. Supported application/pdf

fileContent*
string

Content of the file, encoded in Base64

Parameter regionDocumentType

The document type code depends on the license region. The list of available codes is formed on the Bitrix24 side, and validation is performed based on the license region.

If you do not know the code, use the value 12.999 as a safe default. This value passes validation by default when the list of codes for the region is empty or unknown.

Parameter externalSettings

Name
type

Description

externalId*
string

External identifier. Maximum length — 255 characters

externalDateCreate*
string

Creation date of the external document in ISO 8601 format

Code Examples

How to Use Examples in Documentation

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"fields":{"company":{"crmId":12},"members":[{"userId":25,"role":"signer"},{"userId":42,"role":"assignee"}],"responsible":{"userId":7},"companyProviderUid":"d4f6b8a1-4c6d-4d8c-9c7c-2d1b1f6d0f2b","files":[{"fileName":"contract.pdf","fileType":"application/pdf","fileContent":"JVBERi0xLjQKJ..."}],"regionDocumentType":"12.999","externalSettings":{"externalId":"EXT-123","externalDateCreate":"2025-02-18T09:19:34+01:00"}},"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/sign.b2e.document.send
        
// This snippet is an ES module: top-level await requires type="module" or a bundler.
        // $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
        import { Text } from '@bitrix24/b24jssdk'
        import type { B24Frame } from '@bitrix24/b24jssdk'
        
        declare const $b24: B24Frame
        
        // Shape of the payload returned in result (match the "response handling" section of the page)
        type SendDocumentResult = {
          uid: string
          state: {
            code: string
            name: string
          }
          members: {
            uid: string
            role: string
            party: number
            user: {
              employeeCode: string
              employeeId: number
              userId: number
            }
            state: {
              code: string
              name: string
            }
          }[]
        }
        
        try {
          const response = await $b24.actions.v2.call.make<SendDocumentResult>({
            method: 'sign.b2e.document.send',
            params: {
              fields: {
                company: { crmId: 12 },
                members: [
                  { userId: 25, role: 'signer' },
                  { userId: 42, role: 'assignee' },
                ],
                responsible: { userId: 7 },
                companyProviderUid: 'd4f6b8a1-4c6d-4d8c-9c7c-2d1b1f6d0f2b',
                files: [
                  {
                    fileName: 'contract.pdf',
                    fileType: 'application/pdf',
                    fileContent: 'JVBERi0xLjQKJ...',
                  },
                ],
                regionDocumentType: '12.999',
                externalSettings: {
                  externalId: 'EXT-123',
                  externalDateCreate: '2025-02-18T09:19:34+03:00',
                },
              },
            },
            requestId: Text.getUuidRfc4122()
          })
        
          // The payload is available only on a successful response
          if (!response.isSuccess) {
            console.error(response.getErrorMessages().join('; '))
          } else {
            const result = response.getData()!.result
            console.info('Document uid:', result.uid, 'state:', result.state.code, 'members:', result.members.length)
          }
        } catch (error) {
          // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
          console.error(error)
        }
        
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
        <script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
        <script>
          async function sendDocument() {
            try {
              // Initialize the SDK inside a Bitrix24 frame
              const $b24 = await B24Js.initializeB24Frame()
        
              const response = await $b24.actions.v2.call.make({
                method: 'sign.b2e.document.send',
                params: {
                  fields: {
                    company: { crmId: 12 },
                    members: [
                      { userId: 25, role: 'signer' },
                      { userId: 42, role: 'assignee' },
                    ],
                    responsible: { userId: 7 },
                    companyProviderUid: 'd4f6b8a1-4c6d-4d8c-9c7c-2d1b1f6d0f2b',
                    files: [
                      {
                        fileName: 'contract.pdf',
                        fileType: 'application/pdf',
                        fileContent: 'JVBERi0xLjQKJ...',
                      },
                    ],
                    regionDocumentType: '12.999',
                    externalSettings: {
                      externalId: 'EXT-123',
                      externalDateCreate: '2025-02-18T09:19:34+03:00',
                    },
                  },
                },
                requestId: B24Js.Text.getUuidRfc4122()
              })
        
              // The payload is available only on a successful response
              if (!response.isSuccess) {
                console.error(response.getErrorMessages().join('; '))
                return
              }
        
              const result = response.getData().result
              console.info('Document uid:', result.uid, 'state:', result.state.code, 'members:', result.members.length)
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', sendDocument)
        </script>
        
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
        
        fields = {
            "company": {
                "crmId": 12,
            },
            "members": [
                {
                    "userId": 25,
                    "role": "signer",
                },
                {
                    "userId": 42,
                    "role": "assignee",
                },
            ],
            "responsible": {
                "userId": 7,
            },
            "companyProviderUid": "d4f6b8a1-4c6d-4d8c-9c7c-2d1b1f6d0f2b",
            "files": [
                {
                    "fileName": "contract.pdf",
                    "fileType": "application/pdf",
                    "fileContent": "JVBERi0xLjQKJ...",
                },
            ],
            "regionDocumentType": "12.999",
            "externalSettings": {
                "externalId": "EXT-123",
                "externalDateCreate": "2025-02-18T09:19:34+03:00",
            },
        }
        
        try:
            bitrix_response = client.sign.b2e.document.send(
                fields=fields,
            ).response
            result = bitrix_response.result
            print(result)
        except BitrixAPIError as error:
            print(
                "Bitrix API error",
                f"error: {error.error}",
                f"error_description: {error.error_description}",
                sep="\n",
            )
        except BitrixSDKException as error:
            print(f"Bitrix SDK error: {error.message}")
        except Exception as error:
            print(f"Unexpected error: {error}")
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'sign.b2e.document.send',
                    [
                        'fields' => [
                            'company' => [
                                'crmId' => 12
                            ],
                            'members' => [
                                [ 'userId' => 25, 'role' => 'signer' ],
                                [ 'userId' => 42, 'role' => 'assignee' ]
                            ],
                            'responsible' => [ 'userId' => 7 ],
                            'companyProviderUid' => 'd4f6b8a1-4c6d-4d8c-9c7c-2d1b1f6d0f2b',
                            'files' => [
                                [
                                    'fileName' => 'contract.pdf',
                                    'fileType' => 'application/pdf',
                                    'fileContent' => 'JVBERi0xLjQKJ...'
                                ]
                            ],
                            'regionDocumentType' => '12.999',
                            'externalSettings' => [
                                'externalId' => 'EXT-123',
                                'externalDateCreate' => '2025-02-18T09:19:34+01:00'
                            ]
                        ]
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Success: ' . print_r($result, true);
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error: ' . $e->getMessage();
        }
        
BX24.callMethod(
            'sign.b2e.document.send',
            {
                fields: {
                    company: { crmId: 12 },
                    members: [
                        { userId: 25, role: 'signer' },
                        { userId: 42, role: 'assignee' }
                    ],
                    responsible: { userId: 7 },
                    companyProviderUid: 'd4f6b8a1-4c6d-4d8c-9c7c-2d1b1f6d0f2b',
                    files: [
                        {
                            fileName: 'contract.pdf',
                            fileType: 'application/pdf',
                            fileContent: 'JVBERi0xLjQKJ...'
                        }
                    ],
                    regionDocumentType: '12.999',
                    externalSettings: {
                        externalId: 'EXT-123',
                        externalDateCreate: '2025-02-18T09:19:34+01:00'
                    }
                }
            },
            result => {
                if (result.error()) {
                    console.error(result.error());
                } else {
                    console.dir(result.data());
                }
            }
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'sign.b2e.document.send',
            [
                'fields' => [
                    'company' => [ 'crmId' => 12 ],
                    'members' => [
                        [ 'userId' => 25, 'role' => 'signer' ],
                        [ 'userId' => 42, 'role' => 'assignee' ]
                    ],
                    'responsible' => [ 'userId' => 7 ],
                    'companyProviderUid' => 'd4f6b8a1-4c6d-4d8c-9c7c-2d1b1f6d0f2b',
                    'files' => [
                        [
                            'fileName' => 'contract.pdf',
                            'fileType' => 'application/pdf',
                            'fileContent' => 'JVBERi0xLjQKJ...'
                        ]
                    ],
                    'regionDocumentType' => '12.999',
                    'externalSettings' => [
                        'externalId' => 'EXT-123',
                        'externalDateCreate' => '2025-02-18T09:19:34+01:00'
                    ]
                ]
            ]
        );
        
        if (isset($result['error'])) {
            echo 'Error: ' . $result['error_description'];
        } else {
            echo '<PRE>';
            print_r($result['result']);
            echo '</PRE>';
        }
        
// client and ctx are already created — see the Go SDK section
        res, err := client.Core().Call(ctx, "sign.b2e.document.send", b24.Params{
        	"fields": b24.Params{
        		"company": b24.Params{
        			"crmId": 12,
        		},
        		"members": []b24.Params{
        			{
        				"userId": 25,
        				"role":   "signer",
        			},
        			{
        				"userId": 42,
        				"role":   "assignee",
        			},
        		},
        		"responsible": b24.Params{
        			"userId": 7,
        		},
        		"companyProviderUid": "d4f6b8a1-4c6d-4d8c-9c7c-2d1b1f6d0f2b",
        		"files": []b24.Params{
        			{
        				"fileName":    "contract.pdf",
        				"fileType":    "application/pdf",
        				"fileContent": "JVBERi0xLjQKJ...",
        			},
        		},
        		"regionDocumentType": "12.999",
        		"externalSettings": b24.Params{
        			"externalId":         "EXT-123",
        			"externalDateCreate": "2025-02-18T09:19:34+03:00",
        		},
        	},
        })
        if err != nil {
        	return fmt.Errorf("sign.b2e.document.send: %w", err)
        }
        
        var item struct {
        	Uid string `json:"uid"`
        }
        if err := json.Unmarshal(res.Result, &item); err != nil {
        	return fmt.Errorf("parse response: %w", err)
        }
        fmt.Println(item.Uid)
        

Response Handling

HTTP Status: 200

{
            "result": {
                "uid": "b6f5f1f1-9d20-4b6b-ae0f-2f0a8a0c2b3c",
                "state": {
                    "code": "sent",
                    "name": "Sent"
                },
                "members": [
                    {
                        "uid": "f1c2d3e4",
                        "role": "signer",
                        "party": 0,
                        "user": {
                            "employeeCode": "EMP-001",
                            "employeeId": 123,
                            "userId": 25
                        },
                        "state": {
                            "code": "waiting",
                            "name": "Waiting"
                        }
                    }
                ]
            },
            "time": {
                "start": 1739860000.123,
                "finish": 1739860000.456,
                "duration": 0.333,
                "processing": 0.111,
                "date_start": "2025-02-18T09:19:34+01:00",
                "date_finish": "2025-02-18T09:19:34+01:00",
                "operating_reset_at": 1739860600,
                "operating": 0
            }
        }
        

Returned Data

Name
type

Description

result
object

Information about the document and signing participants

time
time

Information about the request execution time

Fields of the result object

Name
type

Description

uid
string

Unique identifier of the document

state
object

Current status of the document

members
array

Signing participants

Fields of the result.state object

Name
type

Description

code
string

Status code

name
string

Status name

Element of the result.members array

Name
type

Description

uid
string

Unique identifier of the participant

role
string

Role of the participant

party
integer

Signing party

user
object

User data

state
object

Status of the participant

Fields of the result.members.user object

Name
type

Description

employeeCode
string

Employee code in HCM Link.

Returned only for companies linked to HCM Link

employeeId
integer

Employee identifier in HCM Link.

Returned only for companies linked to HCM Link

userId
integer

User identifier in Bitrix24

Fields of the result.members.state object

Name
type

Description

code
string

Status code of the participant

name
string

Name of the participant's status

Error Handling

HTTP Status: 200

{
            "error": "BAD_REQUEST",
            "error_description": "[companyProviderUid] field is required"
        }
        

Name
type

Description

error
string

String error code. It consists of digits, Latin letters, and underscores. It may arrive empty — in that case only error_description shows the reason

error_description
string

Error message for the developer. Do not show it to the end user without processing

Possible Error Codes

Code

Description

When it occurs

ACCESS_DENIED

Access denied!

Insufficient permissions

WRONG_AUTH_TYPE

Current authorization type is denied for this method

Call not from application context

BAD_REQUEST

Empty request fields

fields object not provided

BAD_REQUEST

companyProviderUid field is required

companyProviderUid not provided

BAD_REQUEST

The responsible field is required

responsible not provided

BAD_REQUEST

At least one signing party with role signer is required

No participant with role signer in members

BAD_REQUEST

At least one signing party with role assignee is required

No participant with role assignee in members

BAD_REQUEST

Invalid role ...

Role provided outside of allowed values

BAD_REQUEST

Employee ID is required

employeeId/employeeCode not provided and userId not provided

BAD_REQUEST

Employee with code ... was not found

Employee with specified employeeCode not found

BAD_REQUEST

Employee with ID ... was not found

Employee with specified employeeId not found

BAD_REQUEST

Could not find employee for specified User ID

User by userId not found

BAD_REQUEST

Could not find user for specified employee

User not found for employee

BAD_REQUEST

At least one file is required to sign the document

files array not provided

BAD_REQUEST

Signing multiple files is currently not supported

More than one file provided in files

BAD_REQUEST

The specified file type is not supported

fileType other than application/pdf specified

BAD_REQUEST

Invalid file name

Invalid file name

BAD_REQUEST

Invalid file name. File extension is not specified

File extension not specified

BAD_REQUEST

The specified file extension is not supported

File extension not supported

BAD_REQUEST

Region document type is required. Use value '12.999' as a default value

regionDocumentType not provided when codes list is available

BAD_REQUEST

Region document type is not valid. Use value '12.999' as a default value

Unsupported regionDocumentType provided

BAD_REQUEST

Signing provider is not available

Provider not available for the company

BAD_REQUEST

Signing provider has expired

Signing provider has expired

BAD_REQUEST

External date create field is required

externalSettings.externalDateCreate not provided

BAD_REQUEST

External ID field is required

externalSettings.externalId not provided

BAD_REQUEST

External date create invalid field value

Invalid date format in externalSettings.externalDateCreate

BAD_REQUEST

External ID maximum length of 255 is exceeded

externalSettings.externalId length exceeded

INTERNAL_ERROR

Internal error

Error sending document or generating response

-

humanresources module is not installed

humanresources module not installed when using HCM Link fields

Statuses and System Error Codes

HTTP Status: 4xx, 5xx

The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.

Status

Code
Error Message

Description

500

INTERNAL_SERVER_ERROR
Internal server error

An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support

503

QUERY_LIMIT_EXCEEDED
Too many requests

The request intensity limit has been exceeded

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit

401

NO_AUTH_FOUND
Wrong authorization data

The request contains no authorization data: neither an access token nor a webhook code was passed

401

INVALID_REQUEST
Https required

Methods are called over the HTTPS protocol only

401

OVERLOAD_LIMIT
REST API is blocked due to overload

The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support

401

ACCESS_DENIED
REST is available only on commercial plans

REST API access is not active for this account. In Bitrix24 Cloud, check the current plan or trial status: Vibe+ plans include REST API access, while Essentials plans do not. A webhook receives a different error message — REST is available only by subscription

401

INVALID_CREDENTIALS
Invalid request credentials

No active webhook with the specified user identifier and secret code was found

404

ERROR_METHOD_NOT_FOUND
Method not found!

No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope

401

insufficient_scope
The request requires higher privileges than provided by the webhook token

The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with provided by the access token

401

expired_token
The access token provided has expired

The access token has expired

401

user_access_error
The user does not have access to the application

The application is installed, but the Bitrix24 administrator has granted access to it only to specific users

403

PORTAL_DELETED
Portal was deleted

The public part of the site is closed. To open it on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue Learning