Document packs
The all you need to know guide about how to setup and create documents VIA the API.
Our Document_packs API will allow you to create multiple customizable child documents and merge them into a single document_pack, this way we can easily merge our templates, syntax document and/or form field documents into a single document pack, assign their respective field and signer details, customize our mail settings as well as how the request will look, feel and behave when received by our signers as well as once completed, all in one simple request. Lets get started!
Migration guide for v0 to v1:
To skip the reading and watch our walkthrough DEMO explaining the below, you can begin here Creating a document pack using an existing template
Document pack structure
The key sections of our document pack structure are as follows:
cc_recipients
This section is located at a top level within the document_pack, it's possible to add multiple cc_recipients if need be, we can setup the follow:
- email - email of the cc_recipient, a final completed document will be sent to this email if specified.
- mobile number - mobile_number of the cc_recipient, a final completed document will be sent to this number if specified
- name - simply the name of the cc_recipient you are configuring
"cc_recipients": [ //not mandatory, this can be left out if you do not want to setup cc_recipients to recieve a completed document
{
"email": "[email protected]",
"mobile_number": "+27736615278",
"name": "Joe Soaps Brother"
}
],
document_pack_name
- document_pack_name -This will set the document_pack name, each child document (which will have it's own unique name) will sit within this document_pack.
"document_pack_name": "my first document_pack",
signatories
In this section we can setup the following:
- email - this will be used as their primary communication by default, unless stated otherwise using primary_communication_channel (explained below)
- name - the name of the signer. He/she will be referred to by this within their notifications.
- mobile_number - OTPs will be sent to the number specified, as well as notifications if primary_communication_channel is set to 'whatsapp' OR 'SMS'
- primary_communication_channel - This is used to let the API which channel to use for communication between the system and the signer, if 'SMS' is specified for example, his/her signing notifications and OTP will be sent VIA SMS.
- role - This can be used to match your role for the signers setup within your template, can be ignored if using syntax or form field documents.
- uuid - this can be generated by the system if left out OR you can manually assign this and match it to the signatory_uuid of the data_fields section (explained below) for a specified field. That will then assign that data_field to this signer.
"signatories": [
{
"name": "Joe Soap",
"email": "[email protected]",
"mobile_number": "+27736615278",
"role": "signer-1",
"primary_communication_channel": "whatsapp"
},
{
"name": "Joe Soaps Brother",
"email": "[email protected]",
"role": "signer-2",
"primary_communication_channel": "email"
}
],
mail_settings
In this section we can setup the following:
- exclude_created_by_from_final_mail - flag to indicate whether the user who created this document receives a final copy email once the document has been signed and finalized
- include_attachments_in_final_mail - flag to include or exclude the completed document as an attachment when document has been signed and finalized
- message - custom body to reflect in the email body
- subject - subject to reflect for the email received by the signer
"mail_settings": { //not mandatory, this can be left out if you do not want to setup custom mail settings
"exclude_created_by_from_final_mail": false,
"include_attachments_in_final_mail": false,
"message": "Custom email body message",
"subject": "My First Document Pack"
},
documents
In this section we can setup the following:
-
NOTE. This is where we add our document/s to our document_pack, as well as specify any data we want to place in pre-defined custom_id fields, including the assigning of fields to their signers if need be.
-
document_creation_settings - This contains the document type you're going to be using as a child document, as well as the necessary flags based on the type of document you're using.
-
when using a template we use - create_from_template_key (this should already contains the necessary flags)
-
when using a form field document - we require the document to be either in a base_64 format or if the
document is hosted you can specify the document_url. Important to note that when working with form field
documents you should specify two flags to notify the API to extract the form fields and apply them to the
document_pack using "extract_fields_from_form_fields_with_metadata": true as well as
"apply_extracted_fields": true. -
when using a syntax document - we require the document to be either in a base_64 format or if the
document is hosted you can specify the document_url. Important to note that when working with syntax
documents we require "extract_fields_by_tag": true.
Following the document_creation_settings is document_name, this is to specify each name of the child document you're adding.
Once your document_creation_settings and document name have been specified, the next section is data_fields, this section is not mandatory as templates could already be defined with their respective data, this goes for form field/syntax documents as well.
Within data_fields we can set the follow:
- custom_id - this will match up against the custom_id that you've set under your fields using your form field, syntax
field as well as fields you've setup under your template. - data - this is the value data that will be applied to the field in question, for example if it's a form field PDF that
contains a field explicitly called first_name we can then point to this field using "custom_id": "first_name" and
then provide a first_name. eg: "data": "Joe Soap". This will then pre-populate this field when received by the signer.
This concept applies to syntax document fields that have their custom_id's applied as well as template fields added
within QuicklySign.
"documents": [
{
"document_creation_settings": { //syntax form converted to base_64 example, containg 2 text fields called first_name, last_name and a signature field employee_signature which we pre-populate and assign to signer_1
"base_64_document": "<base_64 value of your document>",
"extract_fields_by_tag": true
},
"document_name": "my base_64 syntax child document",
"data_fields":[{"custom_id":"first_name", "data":"Joe", "signatory_uuid":"signer_1"},
{"custom_id":"last_name", "data":"Soap", "signatory_uuid":"signer_1"},
{"custom_id":"employee_signature", "signatory_uuid":"signer_1"}]
},
{
"document_creation_settings": { //hosted form field document containing metadata, 3 fields with the custom ID's of company_name, registration_number and employer_signature. Assign them to signer_2
"document_url": "https://www.quicklysign.com/s/example_form_field.pdf",
"extract_fields_from_form_fields_with_metadata": true,
"apply_extracted_fields": true
},
"document_name": "my hosted form field child document",
"data_fields":[{"custom_id":"company_name", "data":"QuicklySign", "signatory_uuid":"signer_2"},
{"custom_id":"registration_number", "signatory_uuid":"signer_2"},
{"custom_id":"employer_signature", "signatory_uuid":"signer_2"}]
},
{
"document_creation_settings": { //QuicklySign template example
"create_from_template_key": "<template_key>"
},
"document_name": "my template child document"
}
],
signing_settings
In this section we can setup the following:
- attachments_visible_to_all_signers - flag stating whether all users can see attachments provided in
the document. - branding_key - please see branding tutorial process Using custom branding VIA the API
- can_use_drawn_signature - allow the singer to draw their signature.
- can_use_one_click_initial - if an existing user, their pre-defined initial will auto populate within the
initial field. - can_use_one_click_signature - if an existing user, their pre-defined signature will auto populate
within the signature field. - can_use_typed_signature - if an existing user, their pre-defined signature will auto populate
within the signature field. - can_use_uploaded_signature - flag to allow signer to upload an image of their signature.
- post_signing_url - this can be populated with a URL that the user will be sent to once signing has
been completed. - sequential_signing - once the first signer has completed his/her fields, the second signer will then
be prompt to complete his/her fields. If false, both signers will be sent a request to sign the
document at the same time. - use_signing_wizard - use_signing_wizard will direct the user to each field required for them to
complete. - use_two_factor_authentication - user will be prompt to enter in their OTP via email(if not mobile
number provided) or SMS/Whatsapp
"signing_settings": {
"attachments_visible_to_all_signers": true,
"branding_key": null,
"can_use_drawn_signature": true,
"can_use_one_click_initial": true,
"can_use_one_click_signature": true,
"can_use_typed_signature": true,
"can_use_uploaded_signature": true,
"post_signing_url": "",
"sequential_signing": true,
"use_signing_wizard": true,
"use_two_factor_authentication": true
}
Now to show the final JSON body structure with all of the above in place:
{
"cc_recipients": [
{
"email": "[email protected]",
"mobile_number": "+27736615278",
"name": "Joe Soaps Brother"
}
],
"document_pack_name": "my first document_pack",
"document_type": "document",
"documents": [
{
"document_creation_settings": {
"base_64_document": "<base_64 value of your document>",
"extract_fields_by_tag": true
},
"document_name": "my base_64 syntax child document",
"data_fields":[{"custom_id":"first_name", "data":"Joe", "signatory_uuid":"signer_1"},
{"custom_id":"last_name", "data":"Soap", "signatory_uuid":"signer_1"},
{"custom_id":"employee_signature", "signatory_uuid":"signer_1"}]
},
{
"document_creation_settings": {
"document_url": "https://www.quicklysign.com/s/example_form_field.pdf",
"extract_fields_from_form_fields_with_metadata": true,
"apply_extracted_fields": true
},
"document_name": "my hosted form field child document",
"data_fields":[{"custom_id":"company_name", "data":"QuicklySign", "signatory_uuid":"signer_2"},
{"custom_id":"registration_number", "signatory_uuid":"signer_2"},
{"custom_id":"employer_signature", "signatory_uuid":"signer_2"}]
},
{
"document_creation_settings": {
"create_from_template_key": "<template_key>"
},
"document_name": "my template child document"
}
],
"mail_settings": {
"exclude_created_by_from_final_mail": false,
"include_attachments_in_final_mail": false,
"message": "Custom email body message",
"subject": "My First Document Pack"
},
"signatories": [
{
"name": "Joe Soap",
"email": "[email protected]",
"mobile_number": "+27736615278",
"role": "signer-1",
"primary_communication_channel": "whatsapp"
},
{
"name": "Joe Soaps Brother",
"email": "[email protected]",
"role": "signer-2",
"primary_communication_channel": "email"
}
],
"signing_settings": {
"attachments_visible_to_all_signers": true,
"branding_key": null,
"can_use_drawn_signature": true,
"can_use_one_click_initial": true,
"can_use_one_click_signature": true,
"can_use_typed_signature": true,
"can_use_uploaded_signature": true,
"post_signing_url": "",
"sequential_signing": true,
"use_signing_wizard": true,
"use_two_factor_authentication": true
}
}
Get Document Packs
Note! It is expected that you provide the below mentioned calls with the access_token set within the header. Below calls are made using the GET verb
To retrieve document_packs with their relevant data you can simply use the below API, this will return all document_packs associated with your account:
<base_URL>/document_packs
In order to retrieve a specific document pack you can provide the above API a document key:
<base_URL>/document_packs/<document_pack_key>
- eg: https://sandboxapi.quicklysign.com/v1/document_packs/<document_pack_key>
If you'd like to get all document_packs that are part of a specific workspace/team, use the below API call, you'll notice it requires a new parameter called team_key:
<base_URL>/document_packs?team_key=<team_key>
Download a completed document
In order to download a document once it has been signed and completed by all parties, you can simply use the provided "serve_pdf_url" value.
You can retrieve the "serve_pdf_url" value in two ways:
Method 1 - Retrieve the "serve_pdf_url" once creating and sending document off for signatures.
Once a document has been created and sent off for signatures VIA the API, our automatic 200 response json will contain the "serve_pdf_url" value, you simply have you wait for the document to be finalized and then use this URL to download the document.
Method 2 - Retrieve the "serve_pdf_url" using the <base_URL>/document_packs/<document_pack_key> endpoint
The return json response value for this call will generate a "serve_pdf_url" that can be used to download the document once completed.
Delete Document
In order to DELETE a document_pack please note you need to provide the API call with your access_token, also important to note that the API requires a DOCUMENT_PACK_KEY and NOT a CHILD_DOCUMENT_KEY
<base_URL>/document_packs/<document_pack_key>
- eg: https://sandboxapi.quicklysign.com/v1/document_packs/<document_pack_key> using a DELETE verb.
Advanced data_field placement (This should be used as a last resort to customize your field positioning).
Extra notes regarding data_fields:
Setting up data fields
Positioning can either be done manually, by specifying the x and y positions as detailed below, or it they can be extracted from your pdf.
Manually setting up data fields
Setting up data_fields (these are the blocks for signing, entering text etc) can either by done manually or by copying them from another document with the same layout. The positions shown are in pixels from the top left point from page 0 (so if each page is 800px and there are 10 pages, then the last page data fields will have a y position in the range 7200 to 8000px). See the figure below for further explanation.
Data field positioning.
Updated almost 2 years ago