Create Box Sign Request
Create Box Sign Request
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.
curl -i -X POST "https://api.box.com/2.0/sign_requests" \
-H "authorization: Bearer <ACCESS_TOKEN>" \
-d '{
"signers": [
{
"role": "signer",
"email": "example_email@box.com"
}
],
"source_files": [
{
"type": "file",
"id": "123456789"
}
],
"parent_folder":
{
"type": "folder",
"id": "0987654321"
}
}'
await client.signRequests.createSignRequest({
signers: [
{
email: signer1Email,
signerGroupId: 'user',
} satisfies SignRequestCreateSigner,
{
email: signer2Email,
signerGroupId: 'user',
} satisfies SignRequestCreateSigner,
],
parentFolder: new FolderMini({ id: destinationFolder.id }),
sourceFiles: [new FileBase({ id: fileToSign.id })],
} satisfies SignRequestCreateRequest);
client.sign_requests.create_sign_request(
[
SignRequestCreateSigner(email=signer_1_email, signer_group_id="user"),
SignRequestCreateSigner(email=signer_2_email, signer_group_id="user"),
],
source_files=[FileBase(id=file_to_sign.id)],
parent_folder=FolderMini(id=destination_folder.id),
)
await client.SignRequests.CreateSignRequestAsync(requestBody: new SignRequestCreateRequest(signers: Array.AsReadOnly(new [] {new SignRequestCreateSigner() { Email = signer1Email, SignerGroupId = "user" },new SignRequestCreateSigner() { Email = signer2Email, SignerGroupId = "user" }}), parentFolder: new FolderMini(id: destinationFolder.Id), sourceFiles: Array.AsReadOnly(new [] {new FileBase(id: fileToSign.Id)})));
try await client.signRequests.createSignRequest(requestBody: SignRequestCreateRequest(signers: [SignRequestCreateSigner(email: signer1Email, signerGroupId: "user"), SignRequestCreateSigner(email: signer2Email, signerGroupId: "user")], parentFolder: FolderMini(id: destinationFolder.id), sourceFiles: [FileBase(id: fileToSign.id)]))
List<BoxSignRequestFile> files = new ArrayList<BoxSignRequestFile>();
BoxSignRequestFile file = new BoxSignRequestFile("12345");
files.add(file);
// you can also use specific version of the file
BoxFile file = new BoxFile(api, "12345");
List<BoxFileVersion> versions = file.getVersions();
BoxFileVersion firstVersion = versions.get(0);
BoxSignRequestFile file = new BoxSignRequestFile(firstVersion.getFileID(), firstVersion.getVersionID());
List<BoxSignRequestSigner> signers = new ArrayList<BoxSignRequestSigner>();
BoxSignRequestSigner newSigner = new BoxSignRequestSigner("signer@mail.com");
signers.add(newSigner);
String destinationParentFolderId = "55555";
BoxSignRequest.Info signRequestInfo = BoxSignRequest.createSignRequest(api, files,
signers, destinationParentFolderId);
source_file = {
'id': '12345',
'type': 'file'
}
files = [source_file]
signer = {
'name': 'John Doe',
'email': 'signer@mail.com'
}
signers = [signer]
parent_folder_id = '123456789'
new_sign_request = client.create_sign_request_v2(signers, files=files, parent_folder_id=parent_folder_id)
print(f'(Sign Request ID: {new_sign_request.id})')
var sourceFiles = new List<BoxSignRequestCreateSourceFile>
{
new BoxSignRequestCreateSourceFile()
{
Id = "12345"
}
};
var signers = new List<BoxSignRequestSignerCreate>
{
new BoxSignRequestSignerCreate()
{
Email = "example@gmail.com"
}
};
var parentFolder = new BoxRequestEntity()
{
Id = "12345",
Type = BoxType.folder
};
var request = new BoxSignRequestCreateRequest
{
SourceFiles = sourceFiles,
Signers = signers,
ParentFolder = parentFolder
};
BoxSignRequest signRequest = await client.SignRequestsManager.CreateSignRequestAsync(request);
const signRequest = await client.signRequests.create({
signers: [
{
role: 'signer',
email: 'user@example.com',
},
],
source_files: [
{
type: 'file',
id: '12345',
},
],
parent_folder: {
type: 'folder',
id: '1234567',
},
});
console.log(`Created a new sign request id ${signRequest.id}`);
let signers = [SignRequestCreateSigner(email: "signer@mail.com", role: .approver)]
let sourceFiles = [SignRequestCreateSourceFile(id: "12345"), SignRequestCreateSourceFile(id: "34567")]
let parentFolder = SignRequestCreateParentFolder(id: "234")
client.signRequests.create(signers: signers, sourceFiles: sourceFiles, parentFolder: parentFolder) { (result: Result<SignRequest, BoxSDKError>) in
guard case let .success(signRequest) = result else {
print("Error creating sign request")
return
}
print("Sign request \(signRequest.id) was created")
}
Document preparation
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.
Files
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.
Supported file types include:
- All documents
- All presentations
- Images:
png
,jpg
,jpeg
,tiff
only - Text-based files:
.csv
,.txt
only
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.
Parent folder
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
.
Signers
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.
Inputs
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.
Templates
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.
Redirects
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.
Multiple signers and signing order
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.
Request status
converting
: The file is converted to a.pdf
for the signing process once the sign request is sent.error_converting
: An issue was encountered while converting the file to a.pdf
.created
: Ifdocument_preparation_is_needed
is set totrue
, but theprepare_url
has not yet been visited.sent
: The request was successfully sent, but no signer has interacted with it.error_sending
: An issue was encountered while sending the request.viewed
: Once the first, or only, signer clicks on Review document in the signing email or visits the signing URL.downloaded
: The signing document was downloaded by signer.signed
: All signers completed the request.signed and downloaded
: The signing document was signed and downloaded by signer.declined
: If any signer declines the request.cancelled
: If the request is cancelled via UI or API.expired
: The date of expiration has passed with outstanding, incomplete signatures.finalizing
: If all signers have signed the request, but the final document with signatures and the signing log has not been generated yet.error_finalizing
: If thefinalizing
phase did not complete successfully.
Encountering an error status requires creating a new sign request to retry.