Sign Request

A Sign Request Object

This resource has a few variations that can be encountered when using the API.

The fields that are part of the standard variant are generally returned when the resource is requested via its own API endpoints. For example, when retrieving a file by ID, it will return these fields unless the fields parameter has been specified.

string
12345

Sign request ID

string
sign-request

object type

Value is always sign-request

true

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

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

https://declined-redirect.com

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

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.

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.

123

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

true

Indicates if the sender should receive a prepare_url in the response to complete document preparation via 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.

string
name

Name of the sign request.

The destination folder to place final, signed document and signing log.

When this value was not passed in when the signature request was created, 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 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.

true

Checkbox prefill value

2021-04-26

Date prefill value

1234

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

text

Text prefill value

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.

https://www.example.com

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

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.

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.

blue

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

object array

Array of signers for the sign request

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.

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.

https://example.com

URL to direct a signer to for signing

1234

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

true

Set to true if the signer views the document

https://app.box.com/embed/sign/document/gfhr4222-a331-494b-808b-79bc7f3992a3/f14d7098-a331-494b-808b-79bc7f3992a4

This URL is specifically designed for signing documents within an HTML iframe tag. It will be returned in the response only if the embed_url_external_user_id parameter was passed in the create sign request call.

object array
text

Type of input

Value is one of signature,date,text,checkbox,radio,dropdown

true

Checkbox prefill value

signature

Content type of input

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

string / date
2021-04-26

Date prefill value

1234

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

4

Index of page that the input is on

true

Whether this input was defined as read-only(immutable by signers) or not

text

Text prefill value

true

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

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.

20

Order of the signer

SecretPassword123

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

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.

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

Final decision made by the signer

signed

Type of decision made by the signer

Value is one of signed,declined

Requesting changes before signing.

Additional info about the decision, such as the decline reason from the signer

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

Date and Time that the decision was made

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.

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.

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

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.

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,finalizing,error_finalizing

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