A Sign Request Object
12345
Sign request ID
sign-request
object type
Value is always sign-request
true
If set, signers receive reminders to sign a document on day 3, 8, 13 and 18. Reminders are only sent to any outstanding signers.
true
true
Disables the usage of signatures generated by typing (text).
2021-04-26T08:12:13.982Z
Uses days_valid
to calculate the date and time, in GMT, the sign request will expire if unsigned.
signature
Content type of input
Value is one of initial
,stamp
,signature
,company
,title
,email
,full_name
,first_name
,last_name
,text
,date
,checkbox
,attachment
2
0
730
Number of days after which this request will automatically expire if not completed
https://declined-example.com
The URL that a signer will be redirected to after declining to sign a document. Defining this URL overrides the default redirect URL for all signers.
Hello! Please sign the document below
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.
Sign Request from Acme
Subject of sign request email. This is cleaned by sign request. If this field is not passed, a default subject will be used.
123
This can be used to reference an ID in an external system that the sign request is related to.
text
Type of input
Value is one of signature
,date
,text
,checkbox
true
Checkbox prefill value
signature
Content type of input
Value is one of initial
,stamp
,signature
,company
,title
,email
,full_name
,first_name
,last_name
,text
,date
,checkbox
,attachment
2021-04-26T08:12:13.982Z
Date prefill value
1234
This references the ID of a specific tag contained in a file of the sign request.
4
Index of page that the input is on
text
Text prefill value
true
If set, the sender receives a prepare_url
in the response for completed
document preparation via UI.
true
If set, signers must complete a two factor authentication text message prior to viewing the document. A verification_phone_number
must be specified for a signer for this setting to apply.
document sign request
The name of the sign request.
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.
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.
true
Checkbox prefill value
2021-04-26T08:12:13.982Z
Date prefill value
1234
This references the ID of a specific tag contained in a file of the sign request.
text
Text prefill value
https://prepareurl.com
This URL is returned if is_document_preparation_needed
is
set to true
in the request. It is used to prepare the sign request
via UI. The sign request is not sent until preparation is complete.
https://example.com
The URL that a signer will be redirected to after signing a document. Defining this URL overrides the default redirect URL for all signers. If no declined redirect URL is specified, this URL will be used for decline actions as well.
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.
true
Indicates 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.
blue
Specific signature color.
Value is one of blue
,black
,red
,blue
,black
,red
Array of signers for the sign request
https://declined-example.com
The 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.
example@gmail.com
Email address of the signer
https://example.com
URL to direct a signer to for signing
1234
User ID for the signer in an external application responsible for authentication when accessing the embed URL.
true
Set to true
if the signer views the document
text
Type of input
Value is one of signature
,date
,text
,checkbox
true
Checkbox prefill value
signature
Content type of input
Value is one of initial
,stamp
,signature
,company
,title
,email
,full_name
,first_name
,last_name
,text
,date
,checkbox
,attachment
2021-04-26T08:12:13.982Z
Date prefill value
1234
This references the ID of a specific tag contained in a file of the sign request.
4
Index of page that the input is on
text
Text prefill value
true
Used in combination with an embed URL for a sender. After the
sender signs, they are redirected to the next in_person
signer.
true
If set to true, signer will need to login to a Box account before signing the request. If the signer does not have an existing account, they will have an option to create a free Box account.
2
0
Order of the signer
SecretPassword123
If set, the signer is required to enter the password before they are able to sign a document. This field is write only.
https://example.com
The 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.
signer
"signer"
Defines the role of the signer in the sign 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
,approver
,final_copy_reader
Final decision made by the signer
signed
Type of decision made by the signer
Value is one of signed
,declined
2021-04-26T08:12:13.982Z
Date and Time that the decision was made
6314578901
If set, this phone number is be used to verify the signer via two factor authentication before they are able to sign the document.
Reference to a file that holds a log of all signer activity for
the request. Null
if the signing log is deleted.
List of files to create a signing document from. This is currently limited to one file. Only the ID and type fields are required for each file. The array will be empty if the source_files
are deleted.
converting
Describes the status of the sign request
Value is one of converting
,created
,sent
,viewed
,signed
,cancelled
,declined
,error_converting
,error_sending
,expired
,downloaded
,signed and downloaded
{
"id": 12345,
"type": "sign-request",
"are_reminders_enabled": true,
"are_text_signatures_enabled": true,
"auto_expire_at": "2021-04-26T08:12:13.982Z",
"days_valid": 2,
"declined_redirect_url": "https://declined-example.com",
"email_message": "Hello! Please sign the document below",
"email_subject": "Sign Request from Acme",
"external_id": 123,
"is_document_preparation_needed": true,
"is_phone_verification_required_to_view": true,
"name": "document sign request",
"parent_folder": {
"id": 12345,
"type": "folder",
"etag": 1,
"name": "Contracts",
"sequence_id": 3
},
"prefill_tags": [
{
"document_tag_id": 1234,
"text_value": "text",
"checkbox_value": true,
"date_value": "2021-04-26T08:12:13.982Z"
}
],
"prepare_url": "https://prepareurl.com",
"redirect_url": "https://example.com",
"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
},
"signature_color": "blue",
"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",
"has_viewed_document": true,
"signer_decision": {
"type": "signed",
"finalized_at": "2021-04-26T08:12:13.982Z"
},
"inputs": [
{
"document_tag_id": 1234,
"text_value": "text",
"checkbox_value": true,
"date_value": "2021-04-26T08:12:13.982Z",
"type": "text",
"content_type": "signature",
"page_index": 4
}
],
"embed_url": "https://example.com"
}
],
"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": [
{
"id": 12345,
"etag": 1,
"type": "file"
}
],
"status": "converting"
}