Sample - Box Platform API
POST/sign_requests

Create a Box Sign request

Creates a signature request from one or more source files and sends it to the specified signers. Supply signers and, when applicable, configure the source files, expiration, signature appearance, reminders, redirects, and signing flow; a 201 response returns the created request.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

18 body fields

Signature request details, including signers and the files or template used to create the signing request.

is_document_preparation_neededbooleanoptional
Indicates if the sender should receive a `prepare_url` in the response to complete document preparation using the UI.
redirect_urlstringoptional
When specified, the signature request will be redirected to this url when a document is signed.
declined_redirect_urlstringoptional
The uri that a signer will be redirected to after declining to sign a document.
are_text_signatures_enabledbooleanoptional
Disables the usage of signatures generated by typing (text).
Default:true
email_subjectstringoptional
Subject of sign request email. This is cleaned by sign request. If this field is not passed, a default subject will be used.
email_messagestringoptional
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_enabledbooleanoptional
Reminds signers to sign a document on day 3, 8, 13 and 18. Reminders are only sent to outstanding signers.
namestringoptional
Name of the signature request.
prefill_tagsarray<SignRequestPrefillTag>optional
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_validintegeroptional
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_idstringoptional
This can be used to reference an ID in an external system that the sign request is related to.
template_idstringoptional
When a signature request is created from a template this field will indicate the id of that template.
external_system_namestringoptional
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_flowstringoptional
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.
source_filesarray<FileBase>optional
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.
signature_colorstringoptional
Force a specific color for the signature (blue, black, or red).
Allowed:blueblackred
signersarray<SignerFieldsUsedToCreateABoxSignRequestObject>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](https://developer.box.com/reference/resources/shield-information-barrier-segment-member) (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](https://support.box.com/hc/en-us/articles/9920431507603-Understanding-Information-Barriers#h_01GFVJEHQA06N7XEZ4GCZ9GFAQ).
parent_folderobjectoptional
The folder where the signing request's files are stored.

2 status codes
201Returns the created Box Sign request object, including its signers, source files, status, signing information, and generated identifiers.
is_document_preparation_neededbooleanoptional
Indicates if the sender should receive a `prepare_url` in the response to complete document preparation using the UI.
redirect_urlstringoptional
When specified, the signature request will be redirected to this url when a document is signed.
declined_redirect_urlstringoptional
The uri that a signer will be redirected to after declining to sign a document.
are_text_signatures_enabledbooleanoptional
Disables the usage of signatures generated by typing (text).
Default:true
email_subjectstringoptional
Subject of sign request email. This is cleaned by sign request. If this field is not passed, a default subject will be used.
email_messagestringoptional
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_enabledbooleanoptional
Reminds signers to sign a document on day 3, 8, 13 and 18. Reminders are only sent to outstanding signers.
namestringoptional
Name of the signature request.
prefill_tagsarray<SignRequestPrefillTag>optional
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_validintegeroptional
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_idstringoptional
This can be used to reference an ID in an external system that the sign request is related to.
template_idstringoptional
When a signature request is created from a template this field will indicate the id of that template.
external_system_namestringoptional
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_flowstringoptional
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.
typestringoptional
The value will always be `sign-request`.
Allowed:sign-request
source_filesarray<FileBase>optional
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.
signersarray<SignerFieldsForBoxSignRequestResponse>optional
Array of signers for the signature request.
signature_colorstringoptional
Force a specific color for the signature (blue, black, or red).
idstringoptional
Box Sign request ID.
prepare_urlstringoptional
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.
signing_logobjectoptional
statusstringoptional
Describes the status of the signature request.
Allowed:convertingcreatedsentviewedsignedcancelleddeclinederrorerror_convertingerror_sendingexpiredfinalizing
sign_filesobjectoptional
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_atstringoptional
Uses `days_valid` to calculate the date and time, in GMT, the sign request will expire if unsigned.
parent_folderobjectoptional
collaborator_levelstringoptional
The collaborator level of the user to the sign request. Values can include "owner", "editor", and "viewer".
short_idstringoptional
Short identifier for the sign request.
created_atstringoptional
Timestamp marking when the sign request was created.
finished_atstringoptional
Timestamp indicating when all signing actions completed.
error_codestringoptional
When the sign request is in an error state, identifies the specific reason. Null when no error code applies.
sender_emailstringoptional
The email address of the sender of the sign request.
sender_idintegeroptional
The user ID of the sender of the sign request.
defaultReturned when an unexpected client error occurs. The response contains an error type, status, code, message, context information, help URL, and request identifier.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.

Error handling

signers is required, and source_files can contain no more than 10 files. days_valid must be between 0 and 730, signature_color must be blue, black, or red, and each source file must include id and type.