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.

🎥 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.

Retrieving a Preview PDF

A preview PDF allows you to retrieve the current version of a document before the document pack has been completed.

This is useful when you need to display or download a document containing fields or signatures that have already been completed while other signers are still outstanding.

The final serve_pdf_url should be used once the document pack is complete. Use the preview endpoint when you need the current version before completion.

Endpoint

GET {{url}}/document_packs/{{document_pack_key}}/file/{{document_key}}?file_download_type=preview

Replace:

• {{url}} with the API base URL, including /v1
• {{document_pack_key}} with the parent document pack key
• {{document_key}} with the key of the child document you want to preview

A document pack can contain multiple child documents. The document_key must identify the individual document rather than the parent document pack.

Request headers

Include a valid access token in the request headers.

Content-Type: application/json
access_token: <your_access_token>

Example:

curl --request GET \
  --url "https://sandboxapi.quicklysign.com/v1/document_packs/<document_pack_key>/file/<document_key>?file_download_type=preview" \
  --header "access_token: <your_access_token>"

Example response

The initial response may contain a status URL while the preview file is being generated.

{
  "data": {
    "document_key": "<document_key>",
    "document_pack_key": "<document_pack_key>",
    "file_download_url": null,
    "file_status_url": "/v1/document_packs/<document_pack_key>/file/<document_key>?temp_download_key=<temporary_download_key>"
  }
}

When file_download_url is null, the preview is not ready yet.

Send a GET request to the returned file_status_url to check whether the preview has finished generating.

Check the preview status

GET {{url}}{{file_status_url}}

Include the access token header when checking the status.

curl --request GET \
  --url "https://sandboxapi.quicklysign.com/v1/document_packs/<document_pack_key>/file/<document_key>?temp_download_key=<temporary_download_key>" \
  --header "access_token: <your_access_token>"

Continue checking the status URL until a file_download_url is returned.

Your application should wait briefly between status requests rather than sending requests continuously.

Download the preview

Once the preview is ready, the response will contain a download URL.

{
  "data": {
    "document_key": "<document_key>",
    "document_pack_key": "<document_pack_key>",
    "file_download_url": "<preview_download_url>",
    "file_status_url": "<file_status_url>"
  }
}

Send a GET request to the returned file_download_url to retrieve the PDF.

GET <preview_download_url>

The returned file represents the current version of that child document at the time the preview was generated.

Example flow

The complete preview process is:

1. Retrieve the document pack and identify the required child document.
2. Copy the child document's key.
3. Send a request to the preview endpoint using the document pack key and document key.
4. Check whether file_download_url has been returned.
5. When it is null, send a GET request to file_status_url.
6. Repeat the status request until file_download_url is available.
7. Download the preview PDF from file_download_url.

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)