Box Developer Documentation
Log in

Create sign request

post
https://api.box.com/2.0
/sign_requests/

Creates a sign request. This involves preparing a document for signing and sending the sign request to signers.

Request

Bearer [ACCESS_TOKEN]
application/json

Request Body

booleanin bodyoptional
true

Reminds signers to sign a document on day 3, 8, 13 and 18. Reminders are only sent to outstanding signers.

booleanin bodyoptional
truetrue

Disables the usage of signatures generated by typing (text)

integerin bodyoptional
21-730

Number of days after which this request will automatically expire if not completed

stringin bodyoptional
Hello! Please sign the document below

Message to include in sign request email. The field is cleaned through sanitization of specific characters. However, some html tags are allowed. Links included in the message are also converted to hyperlinks in the email. The message may contain the following html tags including a, abbr, acronym, b, blockquote, code, em, i, ul, li, ol, and strong. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. If this field is not passed, a default message will be used.

stringin bodyoptional
Sign Request from Acme

Subject of sign request email. This is cleaned by sign request. If this field is not passed, a default subject will be used.

stringin bodyoptional
123

This can be used to reference an ID in an external system that the sign request is related to.

booleanin bodyoptional
true

Indicates if the sender should receive a prepare_url in the response to complete document preparation via UI.

Folder (Mini) objectin body

The destination folder to place final, signed document and signing log. Only ID and type fields are required. The root folder, folder ID 0, cannot be used.

object arrayin bodyoptional

When a document contains sign related tags in the content, you can prefill them using this prefill_tags by referencing the 'id' of the tag as the external_id field of the prefill tag.

booleanin bodyoptional
true

Checkbox prefill value

string / date-timein bodyoptional
2021-04-26T08:12:13.982Z

Date prefill value

stringin bodyoptional
1234

This references the ID of a specific tag contained in a file of the sign request.

stringin bodyoptional
text

Text prefill value

object arrayin bodyrequired

Array of signers for the sign request. 35 is the max number of signers permitted.

stringin bodyrequired
example@gmail.com

Email address of the signer

stringin bodyoptional
1234

User ID for the signer in an external application responsible for authentication when accessing the embed URL.

booleanin bodyoptional
true

Used in combination with an embed URL for a sender. After the sender signs, they will be redirected to the next in_person signer.

integerin bodyoptional
2

Order of the signer

stringin bodyoptional
signer"signer"

Defines the role of the signer in the sign request. A signer must sign the document and an approver must approve the document. A final_copy_reader only receives the final signed document and signing log.

Value is one of signer,approver,final_copy_reader

File (Mini) arrayin bodyrequired

List of files to create a signing document from. This is currently limited to one file. Only the ID and type fields are required for each file.

Response

application/jsonBox Sign

Returns a Sign Request object.

application/jsonClient error

An unexpected client error.

post
Create sign request
You can now try out some of our APIs live, right here in the documentation.
Log in

Request Example

cURL
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"
          }
     }'
Java
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);
Python
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(files, signers, parent_folder_id)
print('(Sign Request ID: {0})'.format(new_sign_request.id))
Node
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}`);

Response Example

{
  "id": 12345,
  "type": "sign-request",
  "are_reminders_enabled": true,
  "are_text_signatures_enabled": true,
  "auto_expire_at": "2021-04-26T08:12:13.982Z",
  "days_valid": 2,
  "email_message": "Hello! Please sign the document below",
  "email_subject": "Sign Request from Acme",
  "external_id": 123,
  "is_document_preparation_needed": true,
  "parent_folder": {
    "id": 12345,
    "type": "folder",
    "etag": 1,
    "name": "Contracts",
    "sequence_id": 3
  },
  "prefill_tags": [
    {
      "document_tag_id": 1234,
      "text_value": "text",
      "checkbox_value": true,
      "date_value": "2021-04-26T08:12:13.982Z"
    }
  ],
  "prepare_url": "https://prepareurl.com",
  "sign_files": {
    "files": [
      {
        "id": 12345,
        "etag": 1,
        "type": "file",
        "sequence_id": 3,
        "name": "Contract.pdf",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "file_version": {
          "id": 12345,
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        }
      }
    ],
    "is_ready_for_download": true
  },
  "signers": [
    {
      "email": "example@gmail.com",
      "role": "signer",
      "is_in_person": true,
      "order": 2,
      "embed_url_external_user_id": 1234,
      "has_viewed_document": true,
      "signer_decision": {
        "type": "signed",
        "finalized_at": "2021-04-26T08:12:13.982Z"
      },
      "inputs": [
        {
          "document_tag_id": 1234,
          "text_value": "text",
          "checkbox_value": true,
          "date_value": "2021-04-26T08:12:13.982Z",
          "type": "text",
          "page_index": 4
        }
      ],
      "embed_url": "https://example.com"
    }
  ],
  "signing_log": {
    "id": 12345,
    "type": "file",
    "etag": 1,
    "file_version": {
      "id": 12345,
      "type": "file_version",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    },
    "name": "Contract.pdf",
    "sequence_id": 3,
    "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37"
  },
  "source_files": [
    {
      "id": 12345,
      "etag": 1,
      "type": "file",
      "sequence_id": 3,
      "name": "Contract.pdf",
      "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
      "file_version": {
        "id": 12345,
        "type": "file_version",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
      }
    }
  ],
  "status": "converting"
}