Sign Request

A Sign Request Object

id string

example12345

Sign request ID

type string

examplesign-request

object type

Value is always sign-request

are_reminders_enabled boolean

exampletrue

If set, signers receive reminders to sign a document on day 3, 8, 13 and 18. Reminders are only sent to any outstanding signers.

are_text_signatures_enabled boolean

exampletruedefaulttrue

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

auto_expire_at string / date-time

example2021-04-26T08:12:13.982Z

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

content_type string

examplesignature

Content type of input

Value is one of initial,stamp,signature,company,title,email,full_name,first_name,last_name,text,date,checkbox,attachment

days_valid integer

example2min value0max value730

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

declined_redirect_url string

examplehttps://declined-example.com

The URL that a signer will be redirected to after declining to sign a document. Defining this URL overrides the default redirect URL for all signers.

email_message string

exampleHello! 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.

email_subject string

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

external_id string

example123

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

inputs object array

[inputs].type string

exampletext

Type of input

Value is one of signature,date,text,checkbox

[inputs].checkbox_value boolean

exampletrue

Checkbox prefill value

[inputs].content_type string

examplesignature

Content type of input

Value is one of initial,stamp,signature,company,title,email,full_name,first_name,last_name,text,date,checkbox,attachment

[inputs].date_value string / date-time

example2021-04-26T08:12:13.982Z

Date prefill value

[inputs].document_tag_id string

example1234

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

[inputs].page_index integer

example4

Index of page that the input is on

[inputs].text_value string

exampletext

Text prefill value

is_document_preparation_needed boolean

exampletrue

If set, the sender receives a prepare_url in the response for completed document preparation via UI.

is_phone_verification_required_to_view boolean

exampletrue

If set, signers must complete a two factor authentication text message prior to viewing the document. A verification_phone_number must be specified for a signer for this setting to apply.

name string

exampledocument sign request

The name of the sign request.

parent_folderFolder (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.

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

[prefill_tags].checkbox_value boolean

exampletrue

Checkbox prefill value

[prefill_tags].date_value string / date-time

example2021-04-26T08:12:13.982Z

Date prefill value

[prefill_tags].document_tag_id string

example1234

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

[prefill_tags].text_value string

exampletext

Text prefill value

prepare_url string

examplehttps://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.

redirect_url string

examplehttps://example.com

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

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

sign_files.filesFile (Mini) array

sign_files.is_ready_for_download boolean

exampletrue

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.

signature_color string

exampleblue

Specific signature color.

Value is one of blue,black,red,blue,black,red

signers object array

Array of signers for the sign request

[signers].declined_redirect_url string

examplehttps://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.

[signers].email string

exampleexample@gmail.com

Email address of the signer

[signers].embed_url string

examplehttps://example.com

URL to direct a signer to for signing

[signers].embed_url_external_user_id string

example1234

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

[signers].has_viewed_document boolean

exampletrue

Set to true if the signer views the document

[signers].inputs object array

[inputs].type string

exampletext

Type of input

Value is one of signature,date,text,checkbox

[inputs].checkbox_value boolean

exampletrue

Checkbox prefill value

[inputs].content_type string

examplesignature

Content type of input

Value is one of initial,stamp,signature,company,title,email,full_name,first_name,last_name,text,date,checkbox,attachment

[inputs].date_value string / date-time

example2021-04-26T08:12:13.982Z

Date prefill value

[inputs].document_tag_id string

example1234

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

[inputs].page_index integer

example4

Index of page that the input is on

[inputs].text_value string

exampletext

Text prefill value

[signers].is_in_person boolean

exampletrue

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

[signers].login_required boolean

exampletrue

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.

[signers].order integer

example2min value0

Order of the signer

[signers].password string

exampleSecretPassword123

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

[signers].redirect_url string

examplehttps://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.

[signers].role string

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

[signers].signer_decision object

Final decision made by the signer

signer_decision.type string

examplesigned

Type of decision made by the signer

Value is one of signed,declined

signer_decision.finalized_at string / date-time

example2021-04-26T08:12:13.982Z

Date and Time that the decision was made

[signers].verification_phone_number string

example6314578901

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

signing_logFile (Mini) object

Reference to a file that holds a log of all signer activity for the request. Null if the signing log is deleted.

source_filesFile (Base) 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. The array will be empty if the source_files are deleted.

status string

exampleconverting

Describes the status of the sign request

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

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-example.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": "document sign request",
  "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",
  "redirect_url": "https://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",
      "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",
          "content_type": "signature",
          "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"
    }
  ],
  "status": "converting"
}