Overview

The document_packs API allows you to create multiple child documents and merge them into a single document_pack. This enables you to:

• Merge templates, syntax documents, or form field documents into a single pack.
• Assign fields and signers to each document.
• Customise email notifications and the signer experience.
• Manage all child documents in a single API request.

This allows templates, syntax documents, and form field documents to be combined into a single request while controlling how the document pack behaves during the signing process and after completion.

Migration Reminder

For migrating from v0 to v1, see: Migrating from V0 to V1

🎥 Demo Watch the walkthrough: Creating a Document Pack Using an Existing Template

Document Pack Structure

A document_pack consists of several sections. Each section manages a different part of the document workflow including recipients, signers, documents, and signing behaviour.

CC Recipients

Optional. Specifies recipients who should receive a final completed copy of the document pack.

Multiple CC recipients can be configured.

Properties

Example

"cc_recipients": [
  {
    "email": "[email protected]",
    "mobile_number": "+27000000000",
    "name": "Joe Soaps Brother",
    "can_track_progress": false
  }
]

Document Pack Name

Sets the name for the document pack. Each child document will retain its own name but will belong to this pack.

Example

"document_pack_name": "my first document_pack"

Signatories

Defines the users who will sign documents in the pack.

Properties

If the uuid is not specified, the system will generate one automatically.

Note: Mobile numbers must be in international format and include the dialing code (e.g. +27XXXXXXXXX). Numbers without a country code may fail for SMS or WhatsApp delivery.

Communication Channel Permissions

The primary_communication_channel field supports email, sms, and whatsapp.

Access to sms and whatsapp must be enabled on your account before use.

If you would like to send signing requests via SMS or WhatsApp, please contact [email protected] to have these channels enabled.

Example

"signatories": [
  {
    "name": "Joe Soap",
    "email": "[email protected]",
    "mobile_number": "+27000000000",
    "role": "signer-1",
    "primary_communication_channel": "whatsapp"
  },
  {
    "name": "Joe Soaps Brother",
    "email": "[email protected]",
    "role": "signer-2"
  }
]

Note: If primary_communication_channel is not specified, it will default to email. You only need to include this field when using sms or whatsapp.

Mail Settings

Optional. Controls how emails are sent to signers.

Properties

Note The default wording of system-generated emails cannot be modified. Only the subject, custom message, sender name, and reply email can be configured.

Example

"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",
  "reply_email": "[email protected]",
  "sender_name": "Example Name"
}

Documents

This is where the child documents are added to the document pack.

Each document can be created using a template, a syntax document, or a form field PDF.

Properties

Document Creation Settings

Template Document

"create_from_template_key": "<template_key>"

Note: When creating a document from a template, do not include apply_extracted_fields in document_creation_settings.

Template fields are already configured on the template and should be managed through the QuicklySign front end before the template is used through the API.

The apply_extracted_fields flag is intended for documents where fields are being extracted from the uploaded document, such as form field PDFs. Including this flag when creating from a template may prevent the document from moving from setup to awaiting_signatures.

Correct template example:

{
  "document_name": "Document Name",
  "document_creation_settings": {
    "create_from_template_key": "<template_key>"
  }
}

Do not use:

{
  "document_name": "Document Name",
  "document_creation_settings": {
    "create_from_template_key": "<template_key>",
    "apply_extracted_fields": true
  }
}

Syntax Document (Base64)

The document must be supplied as a Base64 encoded file.

Required flag:

"extract_fields_by_tag": true

Form Field Document

The document can be supplied using either:

• base_64_document
• document_url

Required flags:

"extract_fields_from_form_fields_with_metadata": true,
"apply_extracted_fields": true

These flags instruct the API to extract and apply fields from the PDF.

Workspace Default Document Settings

Optional. Allows child documents to automatically inherit the default document settings configured on the workspace.

This is useful when your workspace already has predefined signing settings, mail settings, branding, or document behaviour that should automatically apply to newly created document packs.

When enabled, the API will apply the workspace defaults after processing any document-specific overrides supplied in the request.

Requirements

To use workspace default document settings:

• team_key must be supplied in the request
• use_workspace_default_document_settings must be set to true inside document_creation_settings

Behaviour

When enabled:

• Workspace-level default document settings will automatically be applied to the child documents
• Explicit values supplied in the API request will be overwritten by inherited workspace defaults
• Each child document can not independently choose whether to inherit workspace defaults

When disabled or omitted:

• Only the settings explicitly supplied in the API request will be used

Example

{
  "document_pack_name": "Default Settings Example",
  "team_key": "<workspace_key>",
  "documents": [
    {
      "document_creation_settings": {
        "base_64_document": "<base_64_string>",
        "use_workspace_default_document_settings": true
      },
      "document_name": "Example Child Document"
    }
  ],
  "signatories": [
    {
      "name": "Joe Soap",
      "email": "[email protected]",
      "role": "signer-1"
    }
  ]
}

Note: If team_key is omitted, the API will use the authenticated user's personal workspace. In this case, workspace default document settings will pulled from the personal workspace.

Data Fields

The data_fields section allows fields within documents to be:

• Pre-filled with data
• Assigned to specific signers

Properties

For example, if a document contains a field with custom_id first_name, you can pre-populate it using:

{
  "custom_id": "first_name",
  "data": "Joe"
}

Note: For more information regarding data_fields please click here.

Example

"documents": [
  {
    "document_creation_settings": {
      "base_64_document": "<base_64_string>",
      "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"
  }
]

Signing Settings

Controls the behaviour of the signing process.

Properties

Example

"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
}

Retrieve Document Packs

All retrieval requests require a valid access_token.

Get All Document Packs

GET /v1/document_packs

Example:

https://sandboxapi.quicklysign.com/v1/document_packs

Get a Specific Document Pack

GET /v1/document_packs/<document_pack_key>

Get Document Packs for a Team / Workspace

GET /v1/document_packs?team_key=<team_key>

Get Template Document Packs

You can retrieve only document packs that were created as templates by using the document_type filter.

GET /v1/document_packs?document_type=template

Example:

https://sandboxapi.quicklysign.com/v1/document_packs?document_type=template

This will return only document packs where the document_type is template.

Note: Templates are not a separate resource. They are stored and managed as document packs with a document_type of template.

Download Completed Document

Once a document pack has been fully signed and completed, the completed PDF can be downloaded using the serve_pdf_url.

The serve_pdf_url may be included in the API response before the document pack is complete. However, the completed PDF will only be available once the document pack has been completed and finalised.

Important Notes

• The serve_pdf_url is linked to the document pack key.
• When retrieving the document pack, use the document pack key, not the child document key.
• If the child document key is used with the document pack endpoint, the response will not return a serve_pdf_url.
• The temp_access_token included in the serve_pdf_url expires after 10 minutes.
• If the document pack is not complete yet, the serve_pdf_url will not return the completed PDF.
• If the temp_access_token has expired, the document can still be downloaded by authenticating the request with a valid account access_token.
• Authentication does not change whether the completed PDF is available. The document pack must still be completed before the completed PDF can be downloaded.

Method 1 - Retrieve from Creation Response

After creating and sending a document pack, the API response will include a serve_pdf_url for each child document.

Once the document pack is complete, this URL can be used to download the completed document.

If the temp_access_token in the URL has expired, the same serve_pdf_url can still be used, but the request must be authenticated using a valid account access_token.

Method 2 - Retrieve via Document Pack Endpoint

GET /v1/document_packs/<document_pack_key>

The request must use the document pack key.

The response will include serve_pdf_url. Once the document pack is complete, this URL can be used to download the completed document.

If you use the serve_pdf_url before the document pack is complete, the completed PDF will not be available yet and the API will return an error similar to the following:

{
    "data": {},
    "status": {
        "errors": [
            {
                "code": "not_found",
                "message": "There is currently no pdf available on this document. "
            }
        ],
        "status_code": 400
    }
}

This means the document pack has not yet been completed and finalised. Please wait until the document pack is complete before trying to download the completed PDF.

If the temp_access_token in the URL has expired, the document can still be downloaded by authenticating the request with a valid account access_token.

Delete Document Pack

To delete a document pack you must provide the document_pack_key.

Important: The API requires the DOCUMENT_PACK_KEY, not the child document key.

DELETE /v1/document_packs/<document_pack_key>

Example:

https://sandboxapi.quicklysign.com/v1/document_packs/<document_pack_key>

Advanced Signing Settings

If the first signer needs permission to edit document data (for example an advisor or preparer role), enable:

"signing_settings": {
  "first_signer_has_multi_edit_role": true
}

This allows the first signer to:

• Edit multiple fields
• Correct information before the client signs the document

Advanced Data Field Placement

Optional. Used when fields need to be positioned manually.

Field positioning uses pixel coordinates relative to the top-left corner of the document (page 0).

If each page is 800px high and the document has 10 pages, the final page fields will have y values between 7200 and 8000 pixels.

Fields can be positioned by:

• manually specifying coordinates, or
• extracting fields from another document with the same layout.

(See image below)