Box Developer Documentation

Join BoxWorks 2024 to discover what's possible with content and AI!

Register now!

Create Box Sign request

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

Creates a signature request. This involves preparing a document for signing and sending the signature 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
20730

Set the number of days after which the created signature request will automatically expire if not completed. By default, we do not apply any expiration date on signature requests, and the signature request does not expire.

stringin bodyoptional
"https://declined-redirect.com"

The uri that a signer will be redirected to after declining to sign a document.

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.

stringin bodyoptional
"Box"

Used as an optional system name to appear in the signature log next to the signers who have been assigned the embed_url_external_id.

booleanin bodyoptional
true

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

true

Forces signers to verify a text message prior to viewing the document. You must specify the phone number of signers to have this setting apply to them.

stringin bodyoptional
"name"

Name of the signature request.

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 and can also not be null.

When this value is not passed in when the signature request, then we will use a default folder which is either the parent folder of the first source file in the payload if we have the permission to upload to that folder or a folder called "My Sign Requests".

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)in bodyoptional
"2021-04-26"

Date prefill value

stringin bodyoptional
"1234"

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

stringin bodyoptional
"text"

Text prefill value

stringin bodyoptional
"https://www.example.com"

When specified, the signature request will be redirected to this url when a document is signed.

stringin bodyoptional
"blue"

Force a specific color for the signature (blue, black, or red)

Value is one of blue,black,red

object arrayin bodyrequired

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

Note: It may happen that some signers belong to conflicting segments (user groups). This means that due to the security policies, users are assigned to segments to prevent exchanges or communication that could lead to ethical conflicts. In such a case, an attempt to send the sign request will result in an error.

Read more about segments and ethical walls.

stringin bodyoptional
"https://declined-example.com"

The URL that a signer will be redirect to after declining to sign a document. Defining this URL overrides default or global declined redirect URL settings for a specific signer.

stringin bodyoptional
"example@gmail.com"

Email address of the signer. The email address of the signer is required when making signature requests, except when using templates that are configured to include emails.

"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 are redirected to the next in_person signer.

booleanin bodyoptional
true

If set to true, the signer will need to log in to a Box account before signing the request. If the signer does not have an existing account, they will have the option to create a free Box account. Cannot be selected in combination with verification_phone_number.

integerin bodyoptional
20

Order of the signer

stringin bodyoptional
"SecretPassword123"

If set, the signer is required to enter the password before they are able to sign a document. This field is write only.

stringin bodyoptional
"https://example.com"

The URL that a signer will be redirected to after signing a document. Defining this URL overrides default or global redirect URL settings for a specific signer. If no declined redirect URL is specified, this URL will be used for decline actions as well.

stringin bodyoptional
"signer""signer"

Defines the role of the signer in the signature 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

stringin bodyoptional
"cd4ff89-8fc1-42cf-8b29-1890dedd26d7"

If set, signers who have the same value will be assigned to the same input and to the same signer group. A signer group is not a Box Group. It is an entity that belongs to a Sign Request and can only be used/accessed within this Sign Request. A signer group is expected to have more than one signer. If the provided value is only used for one signer, this value will be ignored and request will be handled as it was intended for an individual signer. The value provided can be any string and only used to determine which signers belongs to same group. A successful response will provide a generated UUID value instead for signers in the same signer group.

booleanin bodyoptional
false

If true, no emails about the sign request will be sent

"6314578901"

If set, this phone number will be used to verify the signer via two-factor authentication before they are able to sign the document. Cannot be selected in combination with login_required.

File (Base) arrayin bodyoptional

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

stringin bodyoptional
"123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb"

When a signature request is created from a template this field will indicate the id of that template.

Response

application/jsonBox Sign request

Returns a Box Sign request object.

application/jsonClient error

An unexpected client error.

post
Create Box 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"
          }
     }'
TypeScript Gen
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);
Python Gen
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),
)
.NET Gen
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)})));
Swift Gen (Beta)
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)]))
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_v2(signers, files=files, parent_folder_id=parent_folder_id)
print(f'(Sign Request ID: {new_sign_request.id})')
.NET
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);
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}`);
iOS
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")
}

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,
  "declined_redirect_url": "https://declined-redirect.com",
  "email_message": "Hello! Please sign the document below",
  "email_subject": "Sign Request from Acme",
  "external_id": "123",
  "external_system_name": "Box",
  "is_document_preparation_needed": true,
  "is_phone_verification_required_to_view": true,
  "name": "name",
  "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-26"
    }
  ],
  "prepare_url": "https://prepareurl.com",
  "redirect_url": "https://www.example.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
  },
  "signature_color": "blue",
  "signers": [
    {
      "email": "example@gmail.com",
      "role": "signer",
      "is_in_person": true,
      "order": 2,
      "embed_url_external_user_id": "1234",
      "redirect_url": "https://example.com",
      "declined_redirect_url": "https://declined-example.com",
      "login_required": true,
      "verification_phone_number": "6314578901",
      "password": "SecretPassword123",
      "signer_group_id": "cd4ff89-8fc1-42cf-8b29-1890dedd26d7",
      "suppress_notifications": false,
      "has_viewed_document": true,
      "signer_decision": {
        "type": "signed",
        "finalized_at": "2021-04-26T08:12:13.982Z",
        "additional_info": "Requesting changes before signing."
      },
      "inputs": [
        {
          "document_tag_id": "1234",
          "text_value": "text",
          "checkbox_value": true,
          "date_value": "2021-04-26",
          "type": "text",
          "content_type": "signature",
          "page_index": 4,
          "read_only": true
        }
      ],
      "embed_url": "https://example.com",
      "iframeable_embed_url": "https://app.box.com/embed/sign/document/gfhr4222-a331-494b-808b-79bc7f3992a3/f14d7098-a331-494b-808b-79bc7f3992a4"
    }
  ],
  "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"
    }
  ],
  "status": "converting",
  "template_id": "123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb"
}