Box Developer Documentation
Log in

Create a sign request

A request to create a sign request object

boolean
true

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

boolean
truetrue

Disables the usage of signatures generated by typing (text).

integer
20730

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

string
https://declined-redirect.com

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

string
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.

string
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.

string
123

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

boolean
true

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

boolean
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.

string
name

Name of the sign request.

Folder (Mini) object

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 array

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.

boolean
true

Checkbox prefill value

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

Date prefill value

string
1234

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

string
text

Text prefill value

string
https://www.example.com

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

string
blue

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

Value is one of blue,black,red

object array

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

string
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.

string
example@gmail.com

Email address of the signer

string
1234

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

boolean
true

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

boolean
true

If set to true, signer will need to login to a Box account before signing the request. If the signer does not have an existing account, they will have an option to create a free Box account.

integer
20

Order of the signer

string
SecretPassword123

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

string
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.

string
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

string
6314578901

If set, this phone number is be used to verify the signer via two factor authentication before they are able to sign the document.

File (Mini) array
110

List of files to create a signing document from. This is currently limited to 10 files. Only the ID and type fields are required for each file. The array will be empty if the source_files are deleted.

Response Example

{
  "are_reminders_enabled": true,
  "are_text_signatures_enabled": true,
  "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,
  "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-26T08:12:13.982Z"
    }
  ],
  "redirect_url": "https://www.example.com",
  "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"
    }
  ],
  "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"
      }
    }
  ]
}