Overview

Tag Syntax allows you to define fields directly inside a document by placing formatted tags where the fields should appear.

When the document is processed, QuicklySign detects the tags and creates the corresponding fields in those positions.

Tag Syntax can be useful when documents are:

• Generated from Microsoft Word templates
• Generated by another application
• Uploaded through the QuicklySign interface
• Submitted through the API as a Base64 document

How it works

A basic tag uses double curly brackets and pipe-separated values.

{{type|signer|required}}

For example:

{{tx|1|1}}

This creates:

• A text field
• Assigned to signer 1
• Marked as required

The generated field is placed over the tag when the document is processed.

The size of the generated field is influenced by the size of the tag in the source document. You can also define explicit field dimensions when required.

Enable Tag Syntax through the API

When creating a document through the API, set extract_fields_by_tag to true inside document_creation_settings.

{
  "document_pack_name": "Employment agreement",
  "documents": [
    {
      "document_name": "Employment agreement",
      "document_creation_settings": {
        "base_64_document": "<base_64_document>",
        "extract_fields_by_tag": true
      }
    }
  ]
}

QuicklySign will detect the tags while processing the document and create the corresponding fields.

Tag Syntax structure

A complete positional Tag Syntax field supports the following structure:

{{type|signer|required|custom_id|description|group_id|field_options|mutually_exclusive}}

Values that are not required can be left blank.

When using a later position, the pipe separators for the positions before it must still be included.

For example:

{{tx|||employee_first_name}}

This creates an unassigned text field with the custom ID employee_first_name.

Supported field types

The following field types can be created using Tag Syntax:

Assigning fields to signers

The signer position uses a numerical value beginning at 1.

For example:

{{tx|1|1}}

This assigns the text field to signer 1.

{{sig|2|1}}

This assigns the signature field to signer 2.

If the signer position is left blank, the field is not assigned to a signer.

{{tx||1}}

An unassigned field can be completed during document setup before the document is sent for signature.

Required and optional fields

Use 1 in the required position to make a field required.

{{tx|1|1}}

For most field types, leaving the required position blank makes the field optional.

{{tx|1}}

Signature, initial and approve fields are required by default.

Use 0 to make a signature or initial field optional.

{{sig|1|0}}

{{in|1|0}}

A decline field cannot be required.

{{dec|1}}

Configuring fields

Text fields

Use tx to create a text field.

{{tx|1|1}}

This creates a required text field assigned to signer 1.

Prefilled text

Use .val() to provide a value for the field.

{{tx.val("Joe Soap")|1|1}}

The field will initially contain Joe Soap.

Text field with a custom ID

A custom ID can be provided in position 4.

{{tx|1|1|employee_first_name}}

The field can then be referenced using employee_first_name when working with document data through the API.

Signature and initial fields

Use sig to create a signature field.

{{sig|1|1}}

Use in to create an initial field.

{{in|1|1}}

To make either field optional, use 0 in the required position.

{{sig|1|0}}

{{in|1|0}}

Date fields

QuicklySign supports both manually completed date fields and automatically completed signing date fields.

Manual date field

Use dt when the signer should complete the date field.

{{dt|1|1}}

This creates a required date field assigned to signer 1.

Automatic signing date

Use dta when the date should be completed automatically when the signer signs.

{{dta|1}}

This creates an automatic date field assigned to signer 1.

Checkbox fields

Use cb to create a checkbox.

{{cb|1|1}}

Preselected checkbox

Use .val(checked) to create a checkbox that is selected by default.

{{cb.val(checked)|1|1}}

Checkbox groups

Position 7 can be used to place related checkboxes into the same checkbox group.

For example:

{{cb|1|1|married_checkbox|Select your marital status|personal_details|marital_status}}

{{cb|1|1|single_checkbox|Select your marital status|personal_details|marital_status}}

Both fields use marital_status as the checkbox group identifier.

Mutually exclusive checkboxes

Use 1 in position 8 when only one checkbox in the group should be selectable.

{{cb|1|1|married_checkbox|Select your marital status|personal_details|marital_status|1}}

{{cb|1|1|single_checkbox|Select your marital status|personal_details|marital_status|1}}

Because both fields belong to the same checkbox group and are mutually exclusive, only one of the options can be selected.

Dropdown fields

Use cho together with .options() to create a dropdown field.

{{cho.options(EFT,Debit Order)|1|1}}

This creates a required dropdown assigned to signer 1 with the following options:

• EFT
• Debit Order

Preselected dropdown option

Use .val() to set a default option.

{{cho.options(Yes,No).val("Yes")|1|1}}

Dropdown with a custom ID

A custom ID can also be provided.

{{cho.options(EFT,Debit Order)|1|1|payment_method}}

File and image upload fields

Use fl to create a file upload field.

{{fl|1|1||Upload a copy of your ID}}

Use im to create an image upload field.

{{im|1|1||Upload your company logo}}

The description should explain what the signer is expected to upload.

Link fields

Use lk together with .val() to create a link.

{{lk.val("https://www.quicklysign.com/")||||Visit QuicklySign}}

The value supplied to .val() is the destination URL.

The description position is used as the text displayed to the user.

The complete HTTPS URL should be provided.

Links cannot be assigned to a signer and cannot be marked as required.

A custom ID can still be provided.

{{lk.val("https://www.quicklysign.com/")|||quicklysign_link|Visit QuicklySign}}

Approve and decline fields

Use apr to create an approve field.

{{apr|1|1}}

Use dec to create a decline field.

{{dec|1}}

Button text can be set using the field-specific options position.

{{apr|1|1||||Accept}}

{{dec|1|||||Reject}}

Approve fields can be required or optional.

Decline fields cannot be required.

Advanced configuration

Custom field IDs

Position 4 can be used to provide a custom ID.

{{tx|1|1|employee_first_name}}

Custom IDs allow your application to identify and populate specific fields when working with the API.

For example:

{
  "document_creation_settings": {
    "base_64_document": "<base_64_document>",
    "extract_fields_by_tag": true
  },
  "document_name": "Employee form",
  "data_fields": [
    {
      "custom_id": "employee_first_name",
      "data": "Joe",
      "signatory_uuid": "signer_1"
    }
  ]
}

Custom IDs should normally be unique for each field.

Help text

Position 5 can be used to provide help or additional information to the signer.

{{tx|1|1|employee_number|Enter your employee number}}

Help text is particularly useful for file and image upload fields because it can explain what should be uploaded.

{{fl|1|1|identity_document|Upload a clear copy of your ID}}

Field groups

Position 6 can be used to give related fields a common group identifier.

{{tx|1|1|employee_first_name|Enter your first name|employee_details}}

{{tx|1|1|employee_last_name|Enter your last name|employee_details}}

Both fields belong to the employee_details group.

Setting field dimensions

The size of a generated field is normally influenced by the size and spacing of the tag in the source document.

You can override this by defining an explicit width and height using .w() and .h().

{{tx.w(150).h(22)|1|1}}

The dimensions are specified in pixels.

Common field dimensions are:

For example:

{{sig.w(150).h(40)|1|1}}

Adjusting field placement

Use .offx() and .offy() when a generated field needs to be moved slightly from the position of its tag.

Horizontal adjustment

A positive .offx() value moves the field to the right.

{{sig.offx(10)|1|1}}

A negative value moves the field to the left.

{{sig.offx(-10)|1|1}}

Vertical adjustment

A positive .offy() value moves the field down.

{{sig.offy(10)|1|1}}

A negative value moves the field up.

{{sig.offy(-10)|1|1}}

Both can be used together.

{{sig.offx(10).offy(-5)|1|1}}

Variables

Long tags can affect the layout of the source document.

Variables allow you to define the complete field configuration elsewhere in the document and place a shorter variable where the field should appear.

Define the variable:

{{$employee_name=tx.val("Joe Soap").w(150).h(22)|1|1|employee_name|Enter your full name|employee_details}}

Then place the variable where the field should appear:

{{$employee_name}}

Variable names must begin with $ and cannot contain spaces.

Verbose syntax

Verbose syntax provides another way to configure fields without relying on the position of each pipe-separated value.

This can make more complex fields easier to read.

Verbose syntax should generally be used together with variables.

For example:

{{$first_name=tx.value("Joe").custom_id("employee_first_name").signer(1).is_required(1).description("Enter your first name").group_id("employee_details")}}

The variable can then be placed where the field should appear:

{{$first_name}}

Available verbose properties include:

.signer()
.is_required()
.custom_id()
.description()
.group_id()
.is_mutually_exclusive()
.button_text()

Complete example

The following example creates a text field that:

• Is assigned to signer 1
• Is required
• Is prefilled with Joe
• Has the custom ID employee_first_name
• Includes help text
• Belongs to the employee_details field group
• Has a width of 150 pixels
• Has a height of 22 pixels

{{tx.val("Joe").w(150).h(22)|1|1|employee_first_name|Enter your first name|employee_details}}

For longer field configurations, variables can be used to prevent the complete Tag Syntax value from affecting the document layout.