Box Sign request - Box Dev Docs

API version 2024.0 A Box 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

example: 12345Box Sign request ID.

type

string

example: sign-requestThe value will always be sign-request.Value is always sign-request

are_reminders_enabled

boolean

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

are_text_signatures_enabled

boolean

example: trueDisables the usage of signatures generated by typing (text).

auto_expire_at

string(date-time)

example: 2021-04-26T08:12:13.982ZUses days_valid to calculate the date and time, in GMT, the sign request will expire if unsigned.

collaborator_level

string

example: ownerThe collaborator level of the user to the sign request. Values can include “owner”, “editor”, and “viewer”.

days_valid

integer

example: 2Set 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.comThe uri that a signer will be redirected to after declining to sign a document.

email_message

string

example: Hello! Please sign the document belowMessage 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 AcmeSubject 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: 123This can be used to reference an ID in an external system that the sign request is related to.

external_system_name

string

example: BoxUsed as an optional system name to appear in the signature log next to the signers who have been assigned the embed_url_external_id.

is_document_preparation_needed

boolean

example: trueIndicates if the sender should receive a prepare_url in the response to complete document preparation using the UI.

name

string

example: nameName of the signature request.

parent_folder

Folder (Mini)object

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

prefill_tags

object[]

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.

Show child attributes

checkbox_value

boolean

example: trueCheckbox prefill value.

date_value

string(date)

example: 2021-04-26Date prefill value.

document_tag_id

string

example: 1234This references the ID of a specific tag contained in a file of the signature request.

text_value

string

example: textText prefill value.

prepare_url

string

example: https://prepareurl.comThis URL is returned if is_document_preparation_needed is set to true in the request. The parameter is used to prepare the signature request using the UI. The signature request is not sent until the preparation phase is complete.

redirect_url

string

example: https://www.example.comWhen specified, the signature request will be redirected to this url when a document is signed.

sender_email

string

example: [email protected]The email address of the sender of the sign request.

sender_id

integer

example: 12345The user ID of the sender of the sign request.

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.

Show child attributes

files

File (Mini)array

is_ready_for_download

boolean

example: trueIndicates 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

example: blueForce a specific color for the signature (blue, black, or red).

signers

object[]

Array of signers for the signature request.

Show child attributes

declined_redirect_url

string

example: https://declined-example.comThe 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: [email protected]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.

embed_url

string

example: https://example.comURL to direct a signer to for signing.

embed_url_external_user_id

string

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

has_viewed_document

boolean

example: trueSet to true if the signer views the document.

iframeable_embed_url

string

example: https://app.box.com/embed/sign/document/gfhr4222-a331-494b-808b-79bc7f3992a3/f14d7098-a331-494b-808b-79bc7f3992a4This 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 Box Sign request call.

inputs

object[]

Show child attributes

type

string

example: textType of input.Value is one of signature,date,text,checkbox,radio,dropdown

checkbox_value

boolean

example: trueCheckbox prefill value.

content_type

string

example: signatureContent 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

date_value

string(date)

example: 2021-04-26Date prefill value.

document_tag_id

string

example: 1234This references the ID of a specific tag contained in a file of the signature request.

page_index

integer

example: 4Index of page that the input is on.

read_only

boolean

example: trueWhether this input was defined as read-only(immutable by signers) or not.

text_value

string

example: textText prefill value.

is_in_person

boolean

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

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

order

integer

example: 2Order of the signer.

password

string

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

redirect_url

string

example: https://example.comThe 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.

role

string

example: signerDefines the role of the signer in the signature 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_decision

object

Final decision made by the signer.

Show child attributes

type

string

example: signedType of decision made by the signer.Value is one of signed,declined

additional_info

string

example: Requesting changes before signing.Additional info about the decision, such as the decline reason from the signer.

finalized_at

string(date-time)

example: 2021-04-26T08:12:13.982ZDate and Time that the decision was made.

signer_group_id

string

example: cd4ff89-8fc1-42cf-8b29-1890dedd26d7If 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.

suppress_notifications

boolean

example: falseIf true, no emails about the sign request will be sent.

verification_phone_number

string

example: 6314578901If set, this phone number will be used to verify the signer via two-factor authentication before they are able to sign the document. Cannot be selected in combination with login_required.

signing_log

File (Mini)object

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

source_files

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

status

string

example: convertingDescribes the status of the signature request.Value is one of converting,created,sent,viewed,signed,cancelled,declined,error_converting,error_sending,expired,finalizing,error_finalizing

template_id

string

example: 123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cbWhen a signature request is created from a template this field will indicate the id of that template.

{
  "id": "12345",
  "type": "sign-request",
  "are_reminders_enabled": true,
  "are_text_signatures_enabled": true,
  "auto_expire_at": "2021-04-26T08:12:13.982Z",
  "collaborator_level": "owner",
  "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",
  "external_system_name": "Box",
  "is_document_preparation_needed": true,
  "name": "name",
  "parent_folder": {
    "id": "12345",
    "type": "folder",
    "etag": "1",
    "name": "Contracts",
    "sequence_id": "3"
  },
  "prefill_tags": [
    {
      "checkbox_value": true,
      "date_value": "2021-04-26",
      "document_tag_id": "1234",
      "text_value": "text"
    }
  ],
  "prepare_url": "https://prepareurl.com",
  "redirect_url": "https://www.example.com",
  "sender_email": "[email protected]",
  "sender_id": 12345,
  "sign_files": {
    "files": [
      {
        "etag": "1",
        "id": "12345",
        "type": "file",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        },
        "name": "Contract.pdf",
        "sequence_id": "3",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37"
      }
    ],
    "is_ready_for_download": true
  },
  "signature_color": "blue",
  "signers": [
    {
      "declined_redirect_url": "https://declined-example.com",
      "email": "[email protected]",
      "embed_url_external_user_id": "1234",
      "is_in_person": true,
      "login_required": true,
      "order": 2,
      "password": "SecretPassword123",
      "redirect_url": "https://example.com",
      "role": "signer",
      "signer_group_id": "cd4ff89-8fc1-42cf-8b29-1890dedd26d7",
      "suppress_notifications": false,
      "verification_phone_number": "6314578901",
      "embed_url": "https://example.com",
      "has_viewed_document": true,
      "iframeable_embed_url": "https://app.box.com/embed/sign/document/gfhr4222-a331-494b-808b-79bc7f3992a3/f14d7098-a331-494b-808b-79bc7f3992a4",
      "inputs": [
        {
          "checkbox_value": true,
          "date_value": "2021-04-26",
          "document_tag_id": "1234",
          "text_value": "text",
          "content_type": "signature",
          "page_index": 4,
          "read_only": true,
          "type": "text"
        }
      ],
      "signer_decision": {
        "additional_info": "Requesting changes before signing.",
        "finalized_at": "2021-04-26T08:12:13.982Z",
        "type": "signed"
      }
    }
  ],
  "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": [
    {
      "etag": "1",
      "id": "12345",
      "type": "file"
    }
  ],
  "status": "converting",
  "template_id": "123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb"
}