Sign in

v1

latestOpenAPI 3.0.2Apache-2.02026-07-142963051.0 MB
Box Sign requests

Cancel Box Sign request

Cancels a sign request.

post/sign_requests/{sign_request_id}/cancel

Path parameters

sign_request_idstring required

The ID of the signature request.

Request body

reasonstring

An optional reason for cancelling the sign request.

Example request

{
  "reason": "Project cancelled"
}

Response

Returns a Sign Request object.

is_document_preparation_neededboolean

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

redirect_urlstring nullable

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

declined_redirect_urlstring nullable

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

are_text_signatures_enabledboolean

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

email_subjectstring nullable

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

email_messagestring nullable

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.

are_reminders_enabledboolean

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

namestring

Name of the signature request.

days_validinteger nullable

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.

external_idstring nullable

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

template_idstring nullable

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

external_system_namestring nullable

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.

request_flowstring nullable

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.

type'sign-request'

The value will always be sign-request.

signature_colorstring nullable

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

idstring

Box Sign request ID.

prepare_urlstring nullable

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.

status'converting' | 'created' | 'sent' | 'viewed' | 'signed' | 'cancelled' | 'declined' | 'error' | 'error_converting' | 'error_sending' | 'expired' | 'finalizing' | 'error_finalizing'

Describes the status of the signature request.

auto_expire_atstring date-time nullable

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

collaborator_levelstring nullable

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

short_idstring

Short identifier for the sign request.

created_atstring date-time

Timestamp marking when the sign request was created.

finished_atstring date-time nullable

Timestamp indicating when all signing actions completed.

error_codestring nullable

When the sign request is in an error state, identifies the specific reason. Null when no error code applies.

sender_emailstring nullable

The email address of the sender of the sign request.

sender_idinteger nullable

The user ID of the sender of the sign request.

Example response

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