Create Box Sign Request

At minimum, to create Box Sign request you need the a file you want to be signed, a destination folder for the signed document/signing log, and signers.

curl -i -X POST "https://api.box.com/2.0/sign_requests" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
       "signers": [
          {
            "role": "signer",
            "email": "example_email@box.com"
          }
        ],
       "source_files": [
          {
            "type": "file",
            "id": "123456789"
          }
       ],
       "parent_folder":
          {
            "type": "folder",
            "id": "0987654321"
          }
     }'

await client.signRequests.createSignRequest({
  signers: [
    {
      email: signer1Email,
      signerGroupId: 'user',
    } satisfies SignRequestCreateSigner,
    {
      email: signer2Email,
      signerGroupId: 'user',
    } satisfies SignRequestCreateSigner,
  ],
  parentFolder: new FolderMini({ id: destinationFolder.id }),
  sourceFiles: [new FileBase({ id: fileToSign.id })],
} satisfies SignRequestCreateRequest);

client.sign_requests.create_sign_request(
    [
        SignRequestCreateSigner(email=signer_1_email, signer_group_id="user"),
        SignRequestCreateSigner(email=signer_2_email, signer_group_id="user"),
    ],
    source_files=[FileBase(id=file_to_sign.id)],
    parent_folder=FolderMini(id=destination_folder.id),
)

await client.SignRequests.CreateSignRequestAsync(requestBody: new SignRequestCreateRequest(signers: Array.AsReadOnly(new [] {new SignRequestCreateSigner() { Email = signer1Email, SignerGroupId = "user" },new SignRequestCreateSigner() { Email = signer2Email, SignerGroupId = "user" }}), parentFolder: new FolderMini(id: destinationFolder.Id), sourceFiles: Array.AsReadOnly(new [] {new FileBase(id: fileToSign.Id)})));

try await client.signRequests.createSignRequest(requestBody: SignRequestCreateRequest(signers: [SignRequestCreateSigner(email: signer1Email, signerGroupId: "user"), SignRequestCreateSigner(email: signer2Email, signerGroupId: "user")], parentFolder: FolderMini(id: destinationFolder.id), sourceFiles: [FileBase(id: fileToSign.id)]))

List<BoxSignRequestFile> files = new ArrayList<BoxSignRequestFile>();
BoxSignRequestFile file = new BoxSignRequestFile("12345");
files.add(file);
        
// you can also use specific version of the file
BoxFile file = new BoxFile(api, "12345");
List<BoxFileVersion> versions = file.getVersions();
BoxFileVersion firstVersion = versions.get(0);
BoxSignRequestFile file = new BoxSignRequestFile(firstVersion.getFileID(), firstVersion.getVersionID());

List<BoxSignRequestSigner> signers = new ArrayList<BoxSignRequestSigner>();
BoxSignRequestSigner newSigner = new BoxSignRequestSigner("signer@mail.com");
signers.add(newSigner);

String destinationParentFolderId = "55555";

BoxSignRequest.Info signRequestInfo = BoxSignRequest.createSignRequest(api, files,
        signers, destinationParentFolderId);

source_file = {
    'id': '12345',
    'type': 'file'
}
files = [source_file]

signer = {
    'name': 'John Doe',
    'email': 'signer@mail.com'
}
signers = [signer]
parent_folder_id = '123456789'

new_sign_request = client.create_sign_request_v2(signers, files=files, parent_folder_id=parent_folder_id)
print(f'(Sign Request ID: {new_sign_request.id})')

var sourceFiles = new List<BoxSignRequestCreateSourceFile>
{
    new BoxSignRequestCreateSourceFile()
    {
        Id = "12345"
    }
};

var signers = new List<BoxSignRequestSignerCreate>
{
    new BoxSignRequestSignerCreate()
    {
        Email = "example@gmail.com"
    }
};

var parentFolder = new BoxRequestEntity()
{
    Id = "12345",
    Type = BoxType.folder
};

var request = new BoxSignRequestCreateRequest
{
    SourceFiles = sourceFiles,
    Signers = signers,
    ParentFolder = parentFolder
};

BoxSignRequest signRequest = await client.SignRequestsManager.CreateSignRequestAsync(request);

const signRequest = await client.signRequests.create({
	signers: [
		{
			role: 'signer',
			email: 'user@example.com',
		},
	],
	source_files: [
		{
			type: 'file',
			id: '12345',
		},
	],
	parent_folder: {
		type: 'folder',
		id: '1234567',
	},
});
console.log(`Created a new sign request id ${signRequest.id}`);

let signers = [SignRequestCreateSigner(email: "signer@mail.com", role: .approver)]
let sourceFiles = [SignRequestCreateSourceFile(id: "12345"), SignRequestCreateSourceFile(id: "34567")]
let parentFolder = SignRequestCreateParentFolder(id: "234")

client.signRequests.create(signers: signers, sourceFiles: sourceFiles, parentFolder: parentFolder) { (result: Result<SignRequest, BoxSDKError>) in
    guard case let .success(signRequest) = result else {
        print("Error creating sign request")
        return
    }

    print("Sign request \(signRequest.id) was created")
}

Document preparation

Preparing a document prior to sending a Box Sign request allows developers to add date, text, checkbox, and/or signature placeholders for signers. This can be done with UI or tags directly in the document. If this is not done, signers receive an unprepared document and can place signatures and fields at their own discretion. However, developers can leverage controls in the request that allow them to turn features for the unprepared document on and off.

Setting is_document_preparation_needed to true provides a prepare_url in the response. Visiting this link in your browser allows you to complete document preparation and send the request in the UI.

To learn more about document tags, please see our support article.

Files

Each Box Sign request begins with a file that needs to be signed. If the file does not already exist in Box, it must be uploaded, in a separate API call, prior to creating the request. Multiple files can be signed in one request. File ID of the first file in a request is specified in the source_files body parameter.

Supported file types include:

• All documents
• All presentations
• Images: png, jpg, jpeg, tiff only
• Text-based files: .csv, .txt only

All file types are converted to .pdf for the signature process. This converted document can be found in the parent_folder upon successfully sending a request. This means that the final, signed document is a .pdf, regardless of the original file type. As each signer completes the request, Box Sign will automatically add a new file version.

File size limits are determined by your account type. Please see our uploads guide for more information.

Parent folder

The folder ID specified in the parent_folder body parameter determines the destination of the final signed document and signing log. This folder cannot be the All Files or root level, which is represented by folder ID 0.

Signers

Each signer must be assigned a role: signer, approver, or final copy_reader.

If the requester is not given a role, a signer with the role final_copy_reader is automatically created. This means they only receive a copy of the final, signed document and signing log.

Signers do not need to have an existing Box account, nor create one, in order to sign documents. Unlike other API endpoints, signers are invited by email address and not Box user_id.

If necessary, signers can log in to Box before signing the request. In such case set the parameter login_required to true for signers. If the signer does not have an existing account, they will have an option to create a free Box account.

Inputs

The inputs parameter represents placeholders that the user can interact with. The document_tag_id parameter can be populated with data you want to pass when creating a sign request.

Templates

You can create a sign request using a template. To do so, you must provide the template_id parameter. See this guide to learn more about using templates when creating sign requests.

Redirects

The URLs specified in the redirect_url and declined_redirect_url allow you to redirect signers to a custom landing page after signing or declining the sign request. For example, if you integrate your application with Box Sign, you can redirect signers back to your application or to a custom landing page. You can set redirect URLs globally for all signers as well as for specific signers only. This means that Box Sign will use specific URLs for signers of your choice, and global settings for the rest. If you don't configure any redirect URLs Box Sign will redirect signers to a default page.

Multiple signers and signing order

Signing order is determined by ordering the provided order numbers from smallest to largest. If two numbers are the same, signers will receive the request at the same time.

Initially, only the signer(s) with the lowest assigned order number will receive a Box Sign request email. Once they sign, the following user(s) will an email and so on. Box Sign automatically adds a new version of the document to the parent_folder as each user signs.

If any signer declines, any remaining signers will not receive a Box Sign request email. The overall request is declined.

Request status

• converting: The file is converted to a .pdf for the signing process once the sign request is sent.
• error_converting: An issue was encountered while converting the file to a .pdf.
• created: If document_preparation_is_needed is set to true, but the prepare_url has not yet been visited.
• sent: The request was successfully sent, but no signer has interacted with it.
• error_sending: An issue was encountered while sending the request.
• viewed: Once the first, or only, signer clicks on Review document in the signing email or visits the signing URL.
• downloaded: The signing document was downloaded by signer.
• signed: All signers completed the request.
• signed and downloaded: The signing document was signed and downloaded by signer.
• declined: If any signer declines the request.
• cancelled: If the request is cancelled via UI or API.
• expired: The date of expiration has passed with outstanding, incomplete signatures.
• finalizing: If all signers have signed the request, but the final document with signatures and the signing log has not been generated yet.
• error_finalizing: If the finalizing phase did not complete successfully.

Encountering an error status requires creating a new sign request to retry.