Box Sign requests resources

Box Sign requests are used to submit a file for signature.

Box Sign request

A Box Sign request object.

Attributes and example

Property	Type	Required	Description
`is_document_preparation_needed`	`boolean`	No	Indicates if the sender should receive a `prepare_url` in the response to complete document preparation using the UI.
`redirect_url`	`string`	No	When specified, the signature request will be redirected to this url when a document is signed. Can be `null`.
`declined_redirect_url`	`string`	No	The uri that a signer will be redirected to after declining to sign a document. Can be `null`.
`are_text_signatures_enabled`	`boolean`	No	Disables the usage of signatures generated by typing (text).
`email_subject`	`string`	No	Subject of sign request email. This is cleaned by sign request. If this field is not passed, a default subject will be used. Can be `null`.
`email_message`	`string`	No	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. Can be `null`.
`are_reminders_enabled`	`boolean`	No	Reminds signers to sign a document on day 3, 8, 13 and 18. Reminders are only sent to outstanding signers.
`name`	`string`	No	Name of the signature request.
`prefill_tags`	array of `Sign request prefill tag`	No	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.
`days_valid`	`integer`	No	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. Can be `null`.
`external_id`	`string`	No	This can be used to reference an ID in an external system that the sign request is related to. Can be `null`.
`template_id`	`string`	No	When a signature request is created from a template this field will indicate the id of that template. Can be `null`.
`external_system_name`	`string`	No	Used as an optional system name to appear in the signature log next to the signers who have been assigned the `embed_url_external_id`. Can be `null`.
`request_flow`	`string`	No	The flow type of the sign request. Values can include `standard` or `cfr11`. When not specified during creation, a default is chosen based on admin settings. Can be `null`.
`type`	`enum<string>`	No	The value will always be `sign-request`. Available options: `sign-request`.
`source_files`	array of File (Base)	No	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.
`signers`	array of `Signer fields for Box Sign request response`	No	Array of signers for the signature request.
`signature_color`	`string`	No	Force a specific color for the signature (blue, black, or red). Can be `null`.
`id`	`string`	No	Box Sign request ID.
`prepare_url`	`string`	No	This 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. Can be `null`.
`signing_log`	File (Mini)	No	Reference to a file that holds a log of all signer activity for the request.
`status`	`enum<string>`	No	Describes the status of the signature request. Available options: `converting`, `created`, `sent`, `viewed`, `signed`, `cancelled`, `declined`, `error`, `error_converting`, `error_sending`, `expired`, `finalizing`, `error_finalizing`.
`sign_files`	`object`	No	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.
`auto_expire_at`	`string`	No	Uses `days_valid` to calculate the date and time, in GMT, the sign request will expire if unsigned. Can be `null`.
`parent_folder`	Folder (Mini)	No	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”.
`collaborator_level`	`string`	No	The collaborator level of the user to the sign request. Values can include “owner”, “editor”, and “viewer”. Can be `null`.
`short_id`	`string`	No	Short identifier for the sign request.
`created_at`	`string`	No	Timestamp marking when the sign request was created.
`finished_at`	`string`	No	Timestamp indicating when all signing actions completed. Can be `null`.
`error_code`	`string`	No	When the sign request is in an error state, identifies the specific reason. Null when no error code applies. Read-only. Can be `null`.
`sender_email`	`string`	No	The email address of the sender of the sign request. Can be `null`.
`sender_id`	`integer`	No	The user ID of the sender of the sign request. Can be `null`.

Example

{
  "is_document_preparation_needed": true,
  "redirect_url": "https://www.example.com",
  "declined_redirect_url": "https://declined-redirect.com",
  "are_text_signatures_enabled": true,
  "email_subject": "Sign Request from Acme",
  "email_message": "Hello! Please sign the document below",
  "are_reminders_enabled": true,
  "name": "name",
  "prefill_tags": [
    {
      "document_tag_id": "1234",
      "text_value": "text",
      "checkbox_value": true,
      "date_value": "2021-04-26"
    }
  ],
  "days_valid": 2,
  "external_id": "123",
  "template_id": "123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb",
  "external_system_name": "Box",
  "request_flow": "standard",
  "type": "sign-request",
  "source_files": [
    {
      "id": "12345",
      "etag": "1",
      "type": "file"
    }
  ],
  "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",
      "suppress_notifications": false,
      "language": "en",
      "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,
          "validation": {
            "validation_type": "email"
          },
          "reason": "I read and approve this document",
          "is_validated": 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",
      "attachments": [
        {
          "id": "12345",
          "name": "proof_of_identity.pdf"
        }
      ]
    }
  ],
  "signature_color": "blue",
  "id": "12345",
  "prepare_url": "https://prepareurl.com",
  "signing_log": {
    "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",
  "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
  },
  "auto_expire_at": "2021-04-26T08:12:13.982Z",
  "parent_folder": {
    "id": "12345",
    "etag": "1",
    "type": "folder",
    "sequence_id": "3",
    "name": "Contracts"
  },
  "collaborator_level": "owner",
  "short_id": "SR-12345",
  "created_at": "2025-02-01T12:00:00Z",
  "finished_at": "2025-02-02T12:00:00Z",
  "error_code": "cfr11_validation_failed",
  "sender_email": "sender@box.com",
  "sender_id": 12345
}

Box Sign requests

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

Attributes and example

Property	Type	Required	Description
`limit`	`integer`	No	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.
`next_marker`	`string`	No	The marker for the start of the next page of results. Can be `null`.
`entries`	array of Box Sign request	No	A list of Box Sign requests.

Example

{
  "limit": 1000,
  "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
  "entries": [
    {
      "is_document_preparation_needed": true,
      "redirect_url": "https://www.example.com",
      "declined_redirect_url": "https://declined-redirect.com",
      "are_text_signatures_enabled": true,
      "email_subject": "Sign Request from Acme",
      "email_message": "Hello! Please sign the document below",
      "are_reminders_enabled": true,
      "name": "name",
      "prefill_tags": [
        {
          "document_tag_id": "1234",
          "text_value": "text",
          "checkbox_value": true,
          "date_value": "2021-04-26"
        }
      ],
      "days_valid": 2,
      "external_id": "123",
      "template_id": "123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb",
      "external_system_name": "Box",
      "request_flow": "standard",
      "type": "sign-request",
      "source_files": [
        {
          "id": "12345",
          "etag": "1",
          "type": "file"
        }
      ],
      "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",
          "suppress_notifications": false,
          "language": "en",
          "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,
              "validation": {
                "validation_type": "email"
              },
              "reason": "I read and approve this document",
              "is_validated": 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",
          "attachments": [
            {
              "id": "12345",
              "name": "proof_of_identity.pdf"
            }
          ]
        }
      ],
      "signature_color": "blue",
      "id": "12345",
      "prepare_url": "https://prepareurl.com",
      "signing_log": {
        "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",
      "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
      },
      "auto_expire_at": "2021-04-26T08:12:13.982Z",
      "parent_folder": {
        "id": "12345",
        "etag": "1",
        "type": "folder",
        "sequence_id": "3",
        "name": "Contracts"
      },
      "collaborator_level": "owner",
      "short_id": "SR-12345",
      "created_at": "2025-02-01T12:00:00Z",
      "finished_at": "2025-02-02T12:00:00Z",
      "error_code": "cfr11_validation_failed",
      "sender_email": "sender@box.com",
      "sender_id": 12345
    }
  ]
}

API reference

v2025.0

v2026.0

Box Sign requests resources

Box Sign request

Box Sign requests

​Box Sign request

​Box Sign requests

Box Sign request

Box Sign requests