Data Fields

Overview

Data fields allow you to place interactive fields on documents that signatories may complete during the signing process.

These fields include signatures, text inputs, dates, checkboxes, file uploads, and other controls that appear directly on the document.

Data fields can be used in two ways:

• Base64 Documents – You can create new fields dynamically and position them anywhere on the document.
• Templates – You cannot add new fields, but you can populate existing template fields by referencing their custom_id and providing data.

Example (populating a template field):

"data_fields": [
    {"custom_id":"name", "data":"Joe"},
    {"custom_id":"premium", "data":"1000"}
]

Supported Document Setup Methods

Data fields are supported only when documents are uploaded using base64:

"document_creation_settings": {
    "base_64_document": "BASE64_PDF"
}

Not Supported:

"document_creation_settings": {
    "create_from_template_key": "TEMPLATE_KEY"
}

When using templates, data fields must be configured inside the template itself. You may still pass in data using their custom_id.

Adding Data Fields

Data fields are defined inside each document object using the data_fields array.

Each field specifies:

• The field type
• Its position on the page
• Its dimensions
• Which signatory must complete it
• Optional behaviour and validation rules

Basic Structure:

{
  "document_pack_name": "Example Pack",
  "documents": [
    {
      "document_creation_settings": {
        "base_64_document": "BASE64_PDF"
      },
      "document_name": "example.pdf",
      "data_fields": [
        {
          "type": "text",
          "custom_id": "customer_name",
          "data": "Joe",
          "required": true,
          "signatory_uuid": "1f3f1524-5929-fc6f-2374-64ca2c3d54ac",
          "x": 50,
          "y": 50,
          "width": 150,
          "height": 22
        }
      ]
    }
  ],
  "signatories": [
    {
      "name": "John Doe",
      "email": "[email protected]",
      "mobile_number": "0123456789",
      "role": "signer-1",
      "uuid": "1f3f1524-5929-fc6f-2374-64ca2c3d54ac"
    }
  ]
}

Extracting Data Fields

QuicklySign can extract predefined fields from an uploaded document during document creation.

The extraction option must be added to the document’s document_creation_settings object. The option you use depends on how the fields were added to the original document.

Extract Fields Using QuicklySign Tags

Use extract_fields_by_tag when the uploaded document contains fields defined using QuicklySign tag syntax.

{
  "document_creation_settings": {
    "base_64_document": "BASE64_PDF",
    "extract_fields_by_tag": true
  }
}

When enabled, QuicklySign scans the uploaded document for supported QuicklySign tags and extracts them as data fields.

Extract Form Fields From a QuicklySign Document

Use extract_fields_from_form_fields_with_metadata when the document was previously prepared in QuicklySign and then exported.

{
  "document_creation_settings": {
    "base_64_document": "BASE64_PDF",
    "extract_fields_from_form_fields_with_metadata": true
  }
}

This option allows QuicklySign form fields stored in the exported document to be extracted when the document is uploaded again.

Extract Form Fields From an External Document

Use extract_fields_from_form_fields when the PDF contains form fields that were created outside of QuicklySign.

{
  "document_creation_settings": {
    "base_64_document": "BASE64_PDF",
    "extract_fields_from_form_fields": true
  }
}

This option extracts the existing PDF form fields and adds them to the document as data fields.

Example Request

The following example uploads a PDF and extracts form fields that were created outside of QuicklySign:

{
  "document_pack_name": "Example Pack",
  "documents": [
    {
      "document_name": "example.pdf",
      "document_creation_settings": {
        "base_64_document": "BASE64_PDF",
        "extract_fields_from_form_fields": true
      }
    }
  ],
  "signatories": [
    {
      "name": "John Doe",
      "email": "[email protected]",
      "role": "signer-1"
    }
  ]
}

📘

Select the appropriate extraction option

Use the extraction option that matches how the fields were originally created:

• extract_fields_by_tag for QuicklySign tag syntax
• extract_fields_from_form_fields_with_metadata for documents prepared and exported from QuicklySign
• extract_fields_from_form_fields for PDF form fields created outside of QuicklySign

Coordinate System

All data field positions use a page-based coordinate system:

• Origin (0,0) is the top-left corner of the first page
• X increases to the right
• Y increases downward
• All measurements are in pixels
• Y coordinates are cumulative across pages (e.g., if the first page height is 800px, a field at y: 850 will appear on page 2)

Common Field Properties

Most data fields support the following properties:

custom_id is optional. If omitted, QuicklySign generates one automatically.

Example:

{
    "type": "text",
    "custom_id": "customer_name",
    "x": 50,
    "y": 100,
    "width": 150,
    "height": 22
}

Signatory Assignment

Each field is assigned to a signatory using signatory_uuid.

Example:

"signatory_uuid": "f86bf6c0-87ca-4712-b805-fec1a185cef7"

Special value:

Example:

"signatory_uuid": "self"

Supported Field Types

Field Type Examples

Signature:

{
    "type": "signature",
    "required": true,
    "signatory_uuid": "1f3f1524-5929-fc6f-2374-64ca2c3d54ac",
    "x": 50,
    "y": 50,
    "width": 150,
    "height": 40
}

Initial:

{
    "type": "initial",
    "required": true,
    "signatory_uuid": "1f3f1524-5929-fc6f-2374-64ca2c3d54ac",
    "x": 50,
    "y": 50,
    "width": 150,
    "height": 40
}

Text:

{
    "type": "text",
    "custom_id": "full_name",
    "required": false,
    "signatory_uuid": "1f3f1524-5929-fc6f-2374-64ca2c3d54ac",
    "x": 50,
    "y": 100,
    "width": 150,
    "height": 22
}

Date (manual):

{
    "type": "date",
    "auto_assign_date": false,
    "required": true,
    "signatory_uuid": "1f3f1524-5929-fc6f-2374-64ca2c3d54ac",
    "x": 50,
    "y": 150,
    "width": 150,
    "height": 22
}

Date (auto-assigned):

{
    "type": "date",
    "auto_assign_date": true,
    "required": false,
    "signatory_uuid": "1f3f1524-5929-fc6f-2374-64ca2c3d54ac",
    "x": 250,
    "y": 150,
    "width": 150,
    "height": 22
}

Checkbox:

{
    "type": "check",
    "data": "checked",
    "required": false,
    "signatory_uuid": "1f3f1524-5929-fc6f-2374-64ca2c3d54ac",
    "x": 50,
    "y": 200,
    "width": 20,
    "height": 20
}

Checkbox Groups (Mutually Exclusive):

{
  "type": "check",
  "checkbox_group_id": "payment_method",
  "mutually_exclusive": true,
  "data": "unchecked",
  "required": true,
  "signatory_uuid": "1f3f1524-5929-fc6f-2374-64ca2c3d54ac",
  "x": 50,
  "y": 200,
  "width": 20,
  "height": 20
}

Choice (Dropdown):

{
    "type": "choice",
    "options_as_csv": "Yes,No,Maybe",
    "required": true,
    "signatory_uuid": "1f3f1524-5929-fc6f-2374-64ca2c3d54ac",
    "x": 50,
    "y": 300,
    "width": 150,
    "height": 22
}

File Upload:

{
    "type": "file",
    "description": "Upload ID Document",
    "required": true,
    "signatory_uuid": "1f3f1524-5929-fc6f-2374-64ca2c3d54ac",
    "x": 50,
    "y": 350,
    "width": 150,
    "height": 45
}

Image Upload:

{
    "type": "image",
    "description": "Upload supporting image",
    "signatory_uuid": "1f3f1524-5929-fc6f-2374-64ca2c3d54ac",
    "x": 50,
    "y": 420,
    "width": 300,
    "height": 200
}

Link:

{
    "type": "link",
    "data": "https://www.google.com",
    "description": "Open Google",
    "signatory_uuid": "self",
    "x": 50,
    "y": 650,
    "width": 200,
    "height": 22
}

Validation and Completion

Before a document can be completed:

• All required fields must be filled
• All required grouped checkboxes must have a selection
• Required file and image uploads must be provided
• Required signatures and initials must be completed

If validation fails, the signer is prompted to complete missing fields unless the field was not marked as required.

Limitations

• Data fields are only supported with base64 documents
• Templates cannot receive dynamic data fields
• Coordinates must be manually calculated
• Multi-page field placement requires page-specific configuration

FAQ

1. Can I use data fields with templates? No. Data fields are only supported with base64 documents. Templates must contain predefined fields.

2. Are custom_id values required? No. They are optional and auto-generated if omitted.

3. How do I make radio-button style fields? Use grouped checkboxes with the same checkbox_group_id and mutually_exclusive: true.