Split field

A split field collects a single value across a row of cells. Use it where a printed form breaks one answer into boxes, such as a card number, a sort code or a National Insurance number. You place one field over the boxes instead of one text field per box, and the value can be validated as a whole.

A split field is made of cells, runs and gaps.

• A cell holds one character.
• A run is a group of cells that sit together. A field has between 1 and 20 runs, and each run has between 1 and 25 cells.
• The cell gap is the space between cells. It is one value shared by every run.
• The run gap is the space between runs. It is one value for the whole field.

A card number printed as 1234 5678 9012 3456 has four runs of 4 cells:

 run 1          run 2          run 3          run 4
[1][2][3][4]   [5][6][7][8]   [9][0][1][2]   [3][4][5][6]
           |<->|
          run gap

Describe the printed form from left to right, then set the gaps to match the spacing between its boxes. Where boxes touch, use a cell gap of 0.

The card_number preset sets this layout for you and checks the value is 16 digits. See Presets.

A preset sets a validation rule and, for most presets, a layout. Presets are for UK references.

numeric, alphabetical and alphanumeric only limit which characters a signer can enter, so use them with l=. For example, {split,p=numeric,l=8:signer1:Reference}.

You can override a preset's layout or gaps. See Combine options.

Validation restricts what a signer can enter. It comes from the preset, and there is no separate validation option. The whole value must match, not part of it. An empty value is not validated unless the field is required.

• A split field without a preset accepts any characters.
• The value is checked without separators, one character per cell.
• Overriding a preset's layout keeps its validation. A layout that cannot fit the preset, such as p=card_number,l=4, is accepted. The signer will never be able to enter a valid value, so check the layout still fits the preset.
• Custom regular expressions are not supported.

Split tags use the same {WHAT:WHO:NAME} format as other tags. Add options after split, separated by commas. Options can appear in any order.

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

Gaps are measured in PDF units, the same as w and h. The tag-level g option used for other fields is unrelated to cg=.

Use the tag builder and choose Split to put a tag together, then copy it into your document.

l= takes run cell counts only. Gaps are set separately with cg= and rg=.

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

The first gives one run of 9 cells. The second gives two runs sharing a cell gap of 2. The third gives four runs of four cells with a cell gap of 2 and a run gap of 4.

{split,p=card_number:signer1:Card+Number}
{split?,p=utr,w200:signer1:UTR}

Use l= with p= to override the preset's layout. The preset's validation still applies.

{split,p=card_number,l=16,cg=2:signer1:Card+Number}

This keeps the card number check but lays the 16 cells out as one run, for a form that prints the boxes without breaks.

Using cg= or rg= with p= overrides the preset's gaps.

A split tag with any of these problems is ignored, so no field is created. If a field you expect is missing after upload, check its tag against this list.

If your integration validates field_type against a fixed list, add the new type before 10 November 2026.

• Tags – The full tag syntax
• Send an envelope with an uploaded document – Use tags when uploading a document