We are excited to introduce new extensibility features that enable developers to leverage the power of Box Sign within custom applications! Developers can now leverage Box Sign reusable template capabilities within custom applications with reusable template APIs.
With template APIs , developers can enable the following capabilities for senders when integrating Box Sign with custom applications:
- Provide a list of all their Box Sign reusable templates
- Obtain template details via associated template IDs
- Initiate signature requests using specific templates
The first step to leveraging this capability is to create the reusable template within the Box Sign native web application within Box.
From there, senders can send a sign request using the template they just created, and pre-populate the full name placeholders.
First, users need a ‘template_id’ to identify which template they will be using.
We can list all the available templates using the ‘/sign_templates’ end point:
curl --location 'https://api.box.com/2.0/sign_templates' \
--header 'Authorization: Bearer cR...nX'
In the example Rui Barbosa used in his “Using Templates with box Sign APIs” blog post, he gave the following example response (simplified):
...
"entries":
{
"id": "6ae28666-03c4-4ac1-80db-06a90d3b1361",
"name": "Scholarship-Contract.pdf",
"parent_folder": {
"id": "157064745449",
"etag": "0",
"type": "folder",
"sequence_id": "0",
"name": "My Sign Requests"
},
"source_files": r
{
"id": "1216382236853",
"etag": "0",
"type": "file",
"sequence_id": "0",
"sha1": "ca9c75cda0d5e3c3c9b0a1e6d42cb5e29a211ab6",
"file_version": {
"id": "1327286673653",
"type": "file_version",
"sha1": "ca9c75cda0d5e3c3c9b0a1e6d42cb5e29a211ab6"
}
}
"signers": ...]
...
}
]
Note that the template itself points to a document.
A few more details to mention:
A document may have multiple signers with different roles, in the example:
"signers": >
{
"email": "",
"label": null,
"public_id": "4Z8QZZV4",
"role": "final_copy_reader",
"is_in_person": false,
"order": 1,
"inputs": ...]
},
{
"email": "",
"label": "Student",
"public_id": "13VK8794",
"role": "signer",
"is_in_person": false,
"order": 1,
"inputs": ...]
},
{
"email": "",
"label": "Teacher",
"public_id": "13VK77Z4",
"role": "signer",
"is_in_person": false,
"order": 1,
"inputs": ...]
]
‘final_copy_reader’ is the person who gets the signed document at the end of the request.
‘Student’ and ‘teacher’ are the recipients who will actually sign the document.
Each signer also has multiple inputs/fields associated with them. These represent the different placeholders in the document the the user can interact with and add data.
These can also have a ‘document_tag_id’ which will allow you to pre-populate with data when you create the sign request:
...
{
"email": "",
"label": "Student",
"public_id": "13VK8794",
"role": "signer",
"is_in_person": false,
"order": 1,
"inputs": ,
{
"document_tag_id": "student_full_name",
"id": "da431975-55c5-4629-86ae-3fb12dda1386",
"type": "text",
"text_value": null,
"is_required": true,
"content_type": "full_name",
...
},
{
"document_tag_id": null,
"id": "b5a76a22-8d48-456e-a012-22a12fc91eb7",
"type": "signature",
...
},
{
"document_tag_id": null,
"id": "7e0cc4ee-b878-4739-afde-acbf69b117b2",
"type": "date",
"date_value": null,
...
}
]
},
In the example above, there are three placeholders or inputs:
- ‘full_name’
- ‘signature’
- ‘date’
‘full_name’ as a ‘document_tag_id’ which will allow us to pre-populate the fields with data once the signature request has been created.
Finally we can use the ‘/sign_request’ end point to create a signature request. Let’s start with the ‘template_id’:
{
"template_id": "6ae28666-03c4-4ac1-80db-06a90d3b1361",
"parent_folder": {
"id": "157064745449",
"etag": "0",
"type": "folder",
"sequence_id": "0",
"name": "My Sign Requests"
},
...
}
‘parent_folder’ will be the folder to store the completed, signed, and sealed documents and audit logs.
The signers will be:
{
"template_id": "6ae28666-03c4-4ac1-80db-06a90d3b1361",
"parent_folder": {
"id": "157064745449",
"etag": "0",
"type": "folder",
"sequence_id": "0",
"name": "My Sign Requests"
},
"signers":
{
"email": "barduinor+teacher@gmail.com",
"role": "signer"
},
{
"email": "barduinor+student@gmail.com",
"role": "signer"
},
]
}
And the pre-fill tags will be:
{
"template_id": "6ae28666-03c4-4ac1-80db-06a90d3b1361",
"parent_folder": {
"id": "157064745449",
"etag": "0",
"type": "folder",
"sequence_id": "0",
"name": "My Sign Requests"
},
"signers":
{
"email": "barduinor+student@gmail.com",
"role": "signer"
},
{
"email": "barduinor+teacher@gmail.com",
"role": "signer"
}
],
"prefill_tags": /
{
"document_tag_id": "student_full_name",
"text_value": "Mileva Maric"
},
{
"document_tag_id": "teacher_full_name",
"text_value": "Albert Einstein"
}
]
}
Make sure the signer order is the same as the one displayed on the template. In the template we had the student first and then the teacher, and in the POST request we need to respect the same order to assign the proper signers.
Once you POST the request, the API returns a ‘sign_request’ object (simplified):
{
"is_document_preparation_needed": false,
...
"signers": o
{
"email": "barduinor@gmail.com",
"role": "final_copy_reader",
},
{
"email": "barduinor+student@gmail.com",
"role": "signer",
},
{
"email": "barduinor+teacher@gmail.com",
"role": "signer",
}
],
"id": "d02fefd2-15fa-431f-a127-2b4525616ae6",
"prefill_tags": f
{
"document_tag_id": "student_full_name",
"text_value": "Mileva Maric",
},
{
"document_tag_id": "teacher_full_name",
"text_value": "Albert Einstein",
}
],
"source_files": r],
"parent_folder": {
"id": "157064745449",
"type": "folder",
"name": "My Sign Requests"
},
"name": "Scholarship-Contract (5).pdf",
"type": "sign-request",
"status": "created",
"sign_files": {
"files": e
{
"id": "1217421927592",
"type": "file",
"name": "Scholarship-Contract (5).pdf",
}
],
"is_ready_for_download": true
},
"template_id": "6ae28666-03c4-4ac1-80db-06a90d3b1361"
}
Here is what it will look like once the signature request process is completed:
To learn more about Box Sign APIs, please visit the Box Sign API Reference Documentation: Create a Signature Request