Skip to content
Last updated

Tags are text markers you add to documents before uploading to Signable. The platform detects these markers and converts them to interactive signature fields at the specified locations.

To put a tag together without writing it by hand, use the tag builder.

Tag syntax

Tags follow this format:

{WHAT:WHO:NAME}

The tag structure contains three colon-separated components:

  • WHAT– Specifies the field type: signature, qes, text, date, date-signed, split, check, or upload
  • WHO – Identifies the party: signer1, signer2, signer3
  • NAME – Sets the field label displayed to the signer

Syntax requirements

Follow these rules when writing tags:

  • Enclose tags in curly braces {}
  • Use lowercase for field types and party identifiers
  • Replace spaces with plus signs + in field names
  • Keep the entire tag on a single line
  • Use only alphanumeric characters (A-Z, a-z, 0-9)

Valid example:

{signature:signer1:Please+Sign+Here}

Invalid examples:

{Signature:Signer1:Please+Sign+Here}  // Uppercase not allowed
{text:signer1:Name
}                                      // Tag split across lines
{text:signer1:My/Name}                // Special characters not allowed

Reduce font size if a tag breaks across lines in your document editor. Tags must remain on a single line to function correctly.

Field types

Signature

Creates a signature field where the party draws or types their signature.

{signature:signer1:Employee+Signature}

QES

Creates a Qualified Electronic Signature field where the party draws or types their signature.

Find out more about QES QES

{qes:signer1:Employee+Signature}

Text

Creates a text input field for freeform text entry.

{text:signer1:Full+Name}

Date

Creates a date field that auto-populates with the current date when the party signs.

{date:signer1:Signature+Date}

Signing date

Creates a signing date field that fills itself with the date the party signed. The signer cannot edit it.

{date-signed:signer1:Signed+Date}

Available from 20 October 2026. See Signing date fields for the formats available.

Split

Creates a split field, one value entered across a row of cells that line up with the printed boxes on a form.

{split,l=4-4-4-4:signer1:Card+Number}

Available from 10 November 2026. See Split fields for how to set the layout.

Checkbox

Creates a checkbox field for yes/no selections.

{check:signer1:I+Agree}

File upload

Creates a file upload field where the party can attach documents.

{upload:signer1:Upload+ID}

Make fields optional

Add a question mark ? after the field type to make the field optional:

{text?:signer1:Middle+Name}
{check?:signer2:Optional+Consent}

Optional fields appear in the envelope but parties can complete signing without filling them.

Assign fields to parties

Assign fields to different parties by incrementing the signer number:

{signature:signer1:Employee+Signature}
{date:signer1:Employee+Date}
{signature:signer2:Manager+Signature}
{date:signer2:Manager+Date}
{signature:signer3:Witness+Signature}

The signer number corresponds to the party order in your API request. Signer1 receives fields tagged with signer1, signer2 receives fields tagged with signer2, and so on.

Adjust field dimensions

Change font size

Increase the tag's font size in your document editor before uploading. Larger font sizes create proportionally larger fields.

Add padding with plus signs

Add plus signs to the start and end of the tag to increase width:

{++text:signer1:Name++}        // Slightly wider
{++++text:signer1:Name++++}    // Much wider

This method increases width only. Height remains unchanged.

Set explicit dimensions

Specify exact width and height in PDF units:

{text,w100:signer1:Name}           // Set width to 100 units
{text,h10:signer1:Name}            // Set height to 10 units
{text,w100,h10:signer1:Name}       // Set width to 100 and height to 10

When setting both dimensions, always specify width before height. The default field size is 10 units high by 100 units wide.

Explicit dimensions work reliably for text and signature fields only. Other field types may not render correctly when resized.

Create checkbox groups

Group checkboxes to allow only one selection per group. Append a hyphen and group name to the field type:

{check-payment:signer1:Credit+Card}
{check-payment:signer1:Bank+Transfer}
{check-payment:signer1:Cash}

This creates a group named "payment" where the signer can select only one option. Create multiple groups by using different group names:

{check-delivery:signer1:Standard+Shipping}
{check-delivery:signer1:Express+Shipping}
{check-contact:signer1:Email}
{check-contact:signer1:Phone}

The first group ("delivery") and second group ("contact") operate independently.

Signing date fields

Signing date fields are available from 20 October 2026. Before then, a date-signed tag is not recognised and is left in the document as ordinary text.

A date-signed field fills itself with the date its party signed:

{date-signed:signer1:Signed+Date}

The signer cannot edit it, so it is always completed and the optional marker ? has no effect.

Write the field type exactly. Tags such as {date-signature:signer1:Signed+Date} or {dateco-signed:signer1:Signed+Date} are not recognised as signing dates.

Set the date format

Add the f= option followed by a preset to choose how the date is written:

{date-signed,f=mm/dd/yyyy:signer1:Signed+Date}

The following presets are available, shown as they would appear for 31 January 2026:

PresetExample
dd31
mm01
yyyy2026
dd/mm/yyyy31/01/2026
mm/dd/yyyy01/31/2026
dd-mm-yyyy31-01-2026
mm-dd-yyyy01-31-2026
yyyy/mm/dd2026/01/31
yyyy/dd/mm2026/31/01

Follow these rules when setting a format:

  • The option is not case-sensitive, so f= and F= are the same
  • The format value is case-sensitive and must match a preset exactly, so f=dd/mm/yyyy is accepted but f=dd/mm/YYYY is not recognised
  • A preset we do not recognise, including one in the wrong case, falls back to dd/mm/yyyy rather than failing the upload
  • Place f= anywhere among the other options
{date-signed,f=dd-mm-yyyy,w140,h40:signer1:Signed+Date}
{date-signed,w140,h40,f=dd-mm-yyyy:signer1:Signed+Date}

Formats apply to signing dates only. A format added to an ordinary date isn't supported at this moment in time, but will be in the future.

Adding a format makes the tag longer, and a field is sized from the tag it replaces. Set an explicit width and height on tags using f= so the field matches the space you have.

Split fields

Split fields are available from 10 November 2026. Before then, a split tag is not recognised and is left in the document as ordinary text.

A split field collects one value across a row of cells, such as the boxes printed on a form for a card number or sort code. Each cell holds one character.

Cells are grouped into runs. A card number printed as 1234 5678 9012 3456 has four runs of 4 cells. A field can have up to 20 runs, with between 1 and 25 cells in each.

Set the layout

Add the l= option with the number of cells in each run, joined by -:

{split,l=9:signer1:Reference}           // One run of 9 cells
{split,l=4-4-4-4:signer1:Card+Number}   // Four runs of 4 cells

Set the gaps

Add cg= to set the gap between cells and rg= to set the gap between runs, in PDF units. Both default to 0, so cells touch and runs sit next to each other:

{split,l=4-4-4-4,cg=2,rg=4:signer1:Card+Number}

The cell gap is shared by every run. Match both gaps to the spacing of the printed boxes.

Use a preset

Add the p= option to apply a preset, which sets the layout and what the signer can enter in one go:

{split,p=card_number:signer1:Card+Number}
{split,p=sort_code:signer1:Sort+Code}

Add l=, cg= or rg= alongside p= to override the preset's layout or gaps.

Follow these rules when writing split tags:

  • A split tag needs l= or p=
  • l= takes cell counts only. Write gaps with cg= and rg=, not inside l=
  • Gaps must be whole numbers of 0 or more
  • Use each option once per tag, in any order
  • l=, cg=, rg= and p= work on split fields only
  • Make a split field optional with ?, as with other fields: {split?,l=9:signer1:Reference}

A tag that breaks one of these rules, or uses a preset we do not recognise, is ignored and no field is created. If a split field you expect is missing after upload, check its tag against these rules.

A field is sized from the tag it replaces, and split tags are long. Set an explicit width with w so the cells line up with the printed boxes, and reduce the font size if the tag wraps.

The tag builder below lists every preset.

Use numbered placeholders

Where a full tag won't fit, such as a narrow table cell or a fixed-length form field, type a short numbered placeholder such as {#1} instead. You then describe the field in your API request. See Numbered placeholders.

Edit fields after upload

After uploading a tagged document, you can modify fields in the Signable web application:

  • Resize fields by dragging their edges
  • Reposition fields anywhere on the page
  • Change field properties and settings
  • Add new fields manually
  • Delete unwanted fields
  • Update field labels and names

These changes apply only to the current envelope and do not modify your original document.

Build a tag

Select a field type, configure it, then copy the tag into your document. Use Reset to start again.

1. Select a field type