Skip to main content
POST
/
sign_requests
cURL
curl -i -X POST "https://api.box.com/2.0/sign_requests" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
       "signers": [
          {
            "role": "signer",
            "email": "example_email@box.com"
          }
        ],
       "source_files": [
          {
            "type": "file",
            "id": "123456789"
          }
       ],
       "parent_folder":
          {
            "type": "folder",
            "id": "0987654321"
          }
     }'
{
  "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",
  "type": "sign-request",
  "source_files": [
    {
      "id": "12345",
      "type": "file",
      "etag": "1"
    }
  ],
  "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",
      "signer_group_id": "cd4ff89-8fc1-42cf-8b29-1890dedd26d7",
      "suppress_notifications": false,
      "has_viewed_document": true,
      "signer_decision": {
        "type": "signed",
        "finalized_at": "2021-04-26T08:12:13.982Z",
        "additional_info": "Requesting changes before signing."
      },
      "inputs": [
        {
          "page_index": 4,
          "document_tag_id": "1234",
          "text_value": "text",
          "checkbox_value": true,
          "date_value": "2021-04-26",
          "type": "text",
          "content_type": "signature",
          "read_only": true,
          "validation": {
            "validation_type": "email"
          }
        }
      ],
      "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",
    "type": "file",
    "etag": "1",
    "sequence_id": "3",
    "name": "Contract.pdf",
    "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
    "file_version": {
      "id": "12345",
      "type": "file_version",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    }
  },
  "status": "converting",
  "sign_files": {
    "files": [
      {
        "id": "12345",
        "type": "file",
        "etag": "1",
        "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",
    "type": "folder",
    "etag": "1",
    "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",
  "sender_email": "sender@box.com",
  "sender_id": 12345
}
This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

Creates a Box Sign request object. A standard representation of a signature request object.

​
signers
Signer fields used to create a Box Sign request object. · object[]
required

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

Note: It may happen that some signers belong to conflicting segments (user groups). This means that due to the security policies, users are assigned to segments to prevent exchanges or communication that could lead to ethical conflicts. In such a case, an attempt to send the sign request will result in an error.

Read more about segments and ethical walls.

​
is_document_preparation_needed
boolean

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

Example:

true

​
redirect_url
string | null

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

Example:

"https://www.example.com"

​
declined_redirect_url
string | null

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

Example:

"https://declined-redirect.com"

​
are_text_signatures_enabled
boolean
default:true

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

Example:

true

​
email_subject
string | null

Subject of sign request email. This is cleaned by sign request. If this field is not passed, a default subject will be used.

Example:

"Sign Request from Acme"

​
email_message
string | null

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.

Example:

"Hello! Please sign the document below"

​
are_reminders_enabled
boolean

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

Example:

true

​
name
string

Name of the signature request.

Example:

"name"

​
prefill_tags
Sign request prefill tag · 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.

​
days_valid
integer | null

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.

Required range: 0 <= x <= 730
Example:

2

​
external_id
string | null

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

Example:

"123"

​
template_id
string | null

When a signature request is created from a template this field will indicate the id of that template.

Example:

"123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb"

​
external_system_name
string | null

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.

Example:

"Box"

​
source_files
(File (Base) · object | null)[] | null

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.

Maximum array length: 10

The bare basic representation of a file, the minimal amount of fields returned when using the fields query parameter.

​
signature_color
enum<string> | null

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

Available options:
blue,
black,
red
Example:

"blue"

​
parent_folder
Folder (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 and can also not be null.

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

Response

Returns a Box Sign request object.

A Box Sign request object. A standard representation of a signature request object.

​
is_document_preparation_needed
boolean

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

Example:

true

​
redirect_url
string | null

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

Example:

"https://www.example.com"

​
declined_redirect_url
string | null

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

Example:

"https://declined-redirect.com"

​
are_text_signatures_enabled
boolean
default:true

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

Example:

true

​
email_subject
string | null

Subject of sign request email. This is cleaned by sign request. If this field is not passed, a default subject will be used.

Example:

"Sign Request from Acme"

​
email_message
string | null

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.

Example:

"Hello! Please sign the document below"

​
are_reminders_enabled
boolean

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

Example:

true

​
name
string

Name of the signature request.

Example:

"name"

​
prefill_tags
Sign request prefill tag · 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.

​
days_valid
integer | null

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.

Required range: 0 <= x <= 730
Example:

2

​
external_id
string | null

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

Example:

"123"

​
template_id
string | null

When a signature request is created from a template this field will indicate the id of that template.

Example:

"123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb"

​
external_system_name
string | null

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.

Example:

"Box"

​
type
enum<string>

The value will always be sign-request.

Available options:
sign-request
Example:

"sign-request"

​
source_files
(File (Base) · object | null)[]

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.

The bare basic representation of a file, the minimal amount of fields returned when using the fields query parameter.

​
signers
Signer fields for Box Sign request response · object[]

Array of signers for the signature request.

​
signature_color
string | null

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

Example:

"blue"

​
id
string

Box Sign request ID.

Example:

"12345"

​
prepare_url
string | null

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.

Example:

"https://prepareurl.com"

​
signing_log
File (Mini) · object

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

​
status
enum<string>

Describes the status of the signature request.

Available options:
converting,
created,
sent,
viewed,
signed,
cancelled,
declined,
error_converting,
error_sending,
expired,
finalizing,
error_finalizing
Example:

"converting"

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

​
auto_expire_at
string<date-time> | null

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

Example:

"2021-04-26T08:12:13.982Z"

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

​
collaborator_level
string | null

The collaborator level of the user to the sign request. Values can include "owner", "editor", and "viewer".

Example:

"owner"

​
short_id
string

Short identifier for the sign request.

Example:

"SR-12345"

​
created_at
string<date-time>

Timestamp marking when the sign request was created.

Example:

"2025-02-01T12:00:00Z"

​
finished_at
string<date-time> | null

Timestamp indicating when all signing actions completed.

Example:

"2025-02-02T12:00:00Z"

​
sender_email
string | null

The email address of the sender of the sign request.

Example:

"sender@box.com"

​
sender_id
integer | null

The user ID of the sender of the sign request.

Example:

12345