Get Box Sign request by ID

cURL

curl -i -X GET "https://api.box.com/2.0/sign_requests/<SIGN_REQUEST_ID>" \
     -H "authorization: Bearer <ACCESS_TOKEN>"

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

GET

sign_requests

{sign_request_id}

cURL

curl -i -X GET "https://api.box.com/2.0/sign_requests/<SIGN_REQUEST_ID>" \
     -H "authorization: Bearer <ACCESS_TOKEN>"

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

Path Parameters

sign_request_id

string

required

The ID of the signature request.

Response

Returns a signature request.

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.

Show child attributes

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.

Show child attributes

signers

Signer fields for Box Sign request response · object[]

Array of signers for the signature request.

Show child attributes

signature_color

string | null

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

Example:

"blue"

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.

Show child attributes

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.

Show child attributes

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

Show child attributes

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

Create Box Sign request

List Box Sign requests

⌘I