Migrating from V0 to V1
New features
- Support for multiple documents in a single request. We've added support for using our document pack functionality via the api. See migration details below Migrating from V0 to V1
- Event Hooks - These are custom pieces of code that can be executed when certain events are raised. These are different to webhooks in that the code is maintained on Quicklysign and can be built specifically for your usecase or you can use existing generic eventhooks.
- User Defined Attributes - These are custom attributes that can be added to a document. You would use these in cases where you want the user to enter additional data before sending the document e.g. reference number or some custom data required for an event hook.
- Generate signing url You can now generate your own signing urls that you can place in emails. These urls won't have the normal mail tracking but will track open events. Using signing urls forces an otp to be entered before signing (sent to email if no mobile number is specified.
- Create document pack from multiple templates. You can create a single document pack by specifying multiple documents (or document packs) to merge.
- Multiple upload mechanisms: We now support using a base64 encoded string to specify document to be uploaded. Also added is the ability to specify a url where Quicklysign must retrieve the document (pdf) from. Old mechanism using temporary upload url is still supported.
- Creating documents from multiple methods (e.g. from template and uploaded documents)
- Extracting data_fields from Adobe form fields which just uses fields for positioning and assigning field types
- Extracting data_fields from Adobe form fields where data_field description is defined in the Adobe form field
- Conditional signatory allocation: A signatory field can be left blank and a signer can assign who that signer must be.
Documents and Document Packs
In v0, documents were returned as a single entity.
V1 we introduce the document, which can contain multiple documents. Document pack serves as an "envelope" for the request.
{
"cc_recipients": [], //list of cc recipients
"created_by_email": "[email protected]", //not editable
"created_by_external_user_code": null, //not editable
"custom_data":null,
"date_created": 1573897936521.0,
"date_updated": 1573897937116.0,
"document_pack_name": "My Example",
"document_type": "document",
"documents": [
{
"custom_data": null, //json object of your custom data
"data_fields": [ //all data fields belonging to this document.
],
"document_name": "name of child document",
"field_enabled_conditions": [],
"key": "key of child document",
"serve_pdf_url": "url to retrieve document from"
}
// multiple documents here
],
"event_hooks": [], //list of event hooks subscribed to
"external_id": "",
"field_enabled_conditions": [], //list of conditions for enabling and disabling fields
"key": "**document pack key**",
"mail_settings": {
"exclude_created_by_from_final_mail": false, //excludes document creator from final mail
"include_attachments_in_final_mail": false,
"message": "", //Mail body
"subject": null //Mail subject
},
"organisation_key": "key of the organisation this document belongs to
"signatories": [ //List of signatoriues
{
"date_updated": 1573897936521.0,
"email": "[email protected]",
"email_send_count": 1,
"mobile_number": null,
"name": "Rob",
"role": "signer-1",
"status": "setup",
"user_key": null,
"uuid": "b89ebad9-55f5-b5e8-c918-72483ce50140"
}
],
"signatory_allocation_questions": [], //list of questions and conditions that can be asked of signer e.g. Enter Details of Spouse (which would be visible if spouse is required to co-sign).
"signing_settings": { //all the 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,
"document_can_be_used_as_form": false,
"in_app_signing_page_url": "",
"obfuscate_contact_info": false,
"post_signing_url": "",
"sequential_signing": true,
"use_signing_wizard": true,
"use_two_factor_authentication": true
},
"status": "awaiting_signatures",
"team_key": "team this document belongs to",
"user_defined_attributes": [ //custom attributes for the document that document owner/editor can view. E.g. reference number
{
"id": "callback_url",
"name": "Callback Url",
"required": true,
"value": "https://enql3ue58a9y.x.pipedream.net",
"visible_on_ui": false
}
],
"visible_to_organisation": false //applicable if this is a template. Template can be made visible to entire organisation.
}
{
"document_pack_name": "My Example",
"document_type": "document",
"documents": [
{
"document_creation_settings": {
"document_url": "url where we must retrieve file to convert",
"extract_fields_by_tag": true
}
},
{
"document_creation_settings": {
"base_64_document": "",
"extract_fields_by_tag": true
}
},
{
"document_creation_settings": {
"create_from_template_key": "Template to use"
}
},
{
"document_creation_settings": {
"base_64_document": "base 64 encoded document ",
"add_signing_page_template_to_document": "signing template"
}
},
{
"document_creation_settings": {
"base_64_document": "base 64 encoded pdf with form fields ",
"extract_fields_from_form_fields_with_metadata": true
}
},
{
"document_creation_settings": {
"base_64_document": "base 64 encoded pdf",
"apply_template_to_document": "template_key"
}
}
]
}
Structural changes
- signing_settings now encapsulates the properties to do with signing settings
- mail_settings now encapsulates the properties to do with sending mail.
- document_pack_name introduced instead of document_name for document_pack
- documents are now part of a document_pack.
Usage changes:
- documents endpoint changes to document_packs
- In v0 you had to submit entire document body when doing updates, posts etc. Now you only need to include the fields you're changing. This has implications for deleting data_fields, signatories and child_documents (which will be described later) because we can no longer just removed a field if it isn't included in the json.
- When creating document we now encapsulate all the "creation settings" in an object per child document of the document pack (See "document creation inside document pack" above). You can combine multiple creation settings to achieve different results. Creation settings aren't returned in document json, it's only used for new documents.
Subscriptions renamed to Webhooks
We initially had named our webhooks as subscriptions because you "subscribed" to events. This was confusing given that webhook is already a well know term for this kind of functionality.
See the documentation here: Subscription Webhooks
Updated almost 2 years ago