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

Coordinate System

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

Origin (0,0) is the top-left corner of the 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:

Property	Type	Description
`type`	string	The type of field (signature, text, date, etc.)
`x`	number	Horizontal position from top-left
`y`	number	Vertical position from top-left
`width`	number	Field width
`height`	number	Field height
`signatory_uuid`	string	UUID of the assigned signatory
`required`	boolean	Whether the field must be completed
`custom_id`	string	Optional developer-defined identifier
`data`	string	Optional initial value for the field (text, checkbox, choice, etc.)

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:

Value	Description
`self`	Applies to the document pack creator / owner

Example:

"signatory_uuid": "self"

Supported Field Types

Type	Description
`signature`	Captures a full signature
`initial`	Captures initials
`text`	Free text input
`date`	Date input field
`check`	Checkbox
`file`	File upload
`choice`	Dropdown / selection list
`block`	Static strikethrough block
`question_text`	Signer question: text input
`question_date`	Signer question: date input
`question_signer_setup`	Captures additional signer details
`highlight`	Highlights an area
`link`	Clickable URL
`approve`	Approval document back button
`decline`	Decline document pack button
`image`	Image upload

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

Can I use data fields with templates? No. Data fields are only supported with base64 documents. Templates must contain predefined fields.
Are custom_id values required? No. They are optional and auto-generated if omitted.
How do I make radio-button style fields? Use grouped checkboxes with the same checkbox_group_id and mutually_exclusive: true.