Sign Request (Base)

A request to create 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 base variant represent the default fields that are always returned when using the fields query parameter, additional to the fields specified in the parameter.

are_reminders_enabled boolean

exampletrue

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

are_text_signatures_enabled boolean

exampletruedefaulttrue

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

days_valid integer

example2min0max730

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.

declined_redirect_url string

example"https://declined-redirect.com"

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

email_message string

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

email_subject string

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

external_id string

example"123"

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

is_document_preparation_needed boolean

exampletrue

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

is_phone_verification_required_to_view boolean

exampletrue

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.

name string

example"name"

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

example"2021-04-26"

Date prefill value

[prefill_tags].document_tag_id string

example"1234"

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

[prefill_tags].text_value string

example"text"

Text prefill value

redirect_url string

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

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

signature_color string

example"blue"

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

Value is one of blue,black,red

signers object array

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

[signers].declined_redirect_url string

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

[signers].email string

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

[signers].embed_url_external_user_id string

example"1234"

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

[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

example2min0

Order of the signer

[signers].password string

example"SecretPassword123"

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

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

[signers].role string

example"signer"default"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

[signers].signer_group_id string

example"cd4ff89-8fc1-42cf-8b29-1890dedd26d7"

If set, signers who have the same group ID will be assigned to the same input. A signer group is expected to have more than one signer. When a group contains fewer than two signers, it will be converted to a single signer and the group will be removed.

[signers].verification_phone_number string

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

source_filesFile (Base) array

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.

template_id string

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

{
  "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-26"
    }
  ],
  "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"
    }
  ],
  "template_id": "123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb"
}