At minimum, to create Box Sign request you need
the a file you want to be signed, a destination folder for the signed
document/signing log, and signers.
Preparing a document prior to sending a Box Sign request allows developers to
add date, text, checkbox, and/or signature placeholders for signers. This can be
done with UI or tags directly in the document. If this is not done,
signers receive an unprepared document and can place signatures and fields at
their own discretion. However, developers can leverage controls in the request
that allow them to turn features for the unprepared document on and off.Setting is_document_preparation_needed to true provides a prepare_url in
the response. Visiting this link in your browser allows you to complete document
preparation and send the request in the UI.To learn more about document tags, please see our support article.
Prefill tags created in a template with the Box web app cannot be accessed from
the API.
Each Box Sign request begins with a file that needs to be signed. If the file
does not already exist in Box, it must be uploaded, in a separate
API call, prior to creating the request. Multiple files can be signed in one
request. File ID of the first file in a request is specified in the
source_files body parameter.
The requester must have download privileges to the file in Box. Review
our collaboration levels to ensure this requirement is met.
All file types are converted to .pdf for the signature process. This converted
document can be found in the parent_folder upon successfully sending a
request. This means that the final, signed document is a .pdf, regardless of
the original file type. As each signer completes the request, Box Sign will
automatically add a new file version.File size limits are determined by your account type. Please see our
uploads guide for more information.
The folder ID specified in the parent_folder body parameter determines the
destination of the final signed document and signing log. This folder
cannot be the All Files or root level, which is represented by folder ID 0.
Each signer must be assigned a role: signer, approver, or final copy_reader.If the requester is not given a role, a signer with the role final_copy_reader
is automatically created. This means they only receive a copy of the final,
signed document and signing log.Signers do not need to have an existing Box account, nor create one, in order to
sign documents. Unlike other API endpoints, signers are invited by email address
and not Box user_id.If necessary, signers can log in to Box before signing the request. In such
case set the parameter login_required to true for signers. If the signer
does not have an existing account, they will have an option to create a free
Box account.
Box Sign will only attempt to send signing emails to the email addresses
provided for signers in the request. For Box users, this does not include email
aliases unless specified. Please double check to ensure all provided signer
email addresses are valid.
The inputs parameter represents placeholders that the user can interact with.
The document_tag_id parameter can be populated with data you want to
pass when creating a sign request.
You can create a sign request using a template.
To do so, you must provide the template_id parameter.
See this guide to learn more about using templates
when creating sign requests.
The URLs specified in the redirect_url and declined_redirect_url
allow you to redirect signers to a custom landing page
after signing or declining the sign request.
For example, if you integrate your application with Box Sign,
you can redirect signers back to your application
or to a custom landing page.
You can set redirect URLs globally for all signers
as well as for specific signers only.
This means that Box Sign will use specific URLs
for signers of your choice, and global
settings for the rest.
If you don’t configure any redirect URLs
Box Sign will redirect signers to a default page.
The default page includes the following note:
“Once the document has been completed by all parties,
a limited-time link to a finalized copy will be be emailed to you,
and, if you have a Box account, a copy will be placed in your account.”
If you decide to redirect the signers to a different page, this information
will not be available to signers.
Signing order is determined by ordering the provided order numbers from
smallest to largest. If two numbers are the same, signers will receive the
request at the same time.Initially, only the signer(s) with the lowest assigned order number will
receive a Box Sign request email. Once they sign, the following user(s) will
an email and so on. Box Sign automatically adds a new version of the
document to the parent_folder as each user signs.If any signer declines, any remaining signers will not receive a Box Sign
request email. The overall request is declined.
