Box Developer Documentation
Log in

Box Sign

A standard representation of a sign request, as returned from any Box Sign API endpoints by default.

string
12345

Sign request ID

string
sign-request

Value is always sign-request

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)

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

Uses days_valid to calculate the date and time, in GMT, the sign request will expire if unsigned.

integer
21-730

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

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.

Box Sign array
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.

integer / int64
1000

The limit that was used for these entries. This will be the same as the limit query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API.

integer / int64
3000

The marker for the start of the next page of results.

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://prepareurl.com

This URL is returned if is_document_preparation_needed is set to true in the request. It is used to prepare the sign request via UI. The sign request is not sent until preparation is complete.

integer / int64
1000

The marker for the start of the previous page of results.

object

List of files that will be signed, which are copies of the original source files. A new version of these files are created as signers sign and can be downloaded at any point in the signing process.

File (Mini) array
boolean
true

Indicates whether the sign_files documents are processing and the PDFs may be out of date. A change to any document requires processing on all sign_files. We recommended waiting until processing is finished (and this value is true) before downloading the PDFs.

object array

Array of signers for the sign request

string
example@gmail.com

Email address of the signer

string
https://example.com

URL to direct a signer to for signing

string
1234

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

boolean
true

Set to true if the signer views the document

object array
string
text

Type of input

Value is one of signature,date,text,checkbox

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.

integer
4

Index of page that the input is on

string
text

Text prefill value

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

integer
2

Order of the signer

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,signer,approver,final_copy_reader

object

Final decision made by the signer

string
signed

Type of decision made by the signer

Value is one of signed,declined

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

Date and Time that the decision was made

File (Mini) object

Reference to a file that holds a log of all signer activity for the request

File (Mini) array

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.

string
converting

Describes the status of the sign request

Value is one of converting,created,sent,viewed,signed,cancelled,declined,error_converting,error_sending,expired

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"
}