# Numbered placeholders

A numbered placeholder is a short marker such as `{#1}` that you type into a document where a field should go. You then describe the field in your `POST /v1/envelopes` request: its type, which party fills it in, its name and its size.

Use placeholders where a full [tag](/tags) won't fit, such as fixed-length form fields and narrow table cells on forms. `{#1}` takes up far less room than `{signature:signer1:Applicant+Signature}`.

Placeholders work on uploaded documents only. They can't be used when you send an envelope from a template.

## How placeholders work

1. Type a placeholder such as `{#1}` into your document where the field should start.
2. Add a `placeholders` object to that document's entry in `envelope_documents`, with a definition keyed by the same number.
3. When the document is processed, Signable places the field where the placeholder was written and removes the placeholder from the document.


## Write a placeholder

Placeholders follow this format:

```text
{#n}
```

Follow these rules when writing placeholders:

- Use a number from 1 to 999, with no leading zeros. `{#01}` and `{#1000}` are not placeholders.
- Put a `#` before the number. `{1}` is not a placeholder.
- Write one placeholder per word, with a space either side of it. Text joined to a placeholder without a space counts as part of it, so the field starts where that text starts.
- Keep the placeholder on a single line.


The top-left corner of the field sits where the placeholder starts. Its size comes from the `width` and `height` in its definition, not from the size of the placeholder text.

### Add padding with plus signs

You can add plus signs inside the braces to take up more room in the document, for example to line the placeholder up with the space you have. Padding does not change the field's size or where it starts.

```text
{+++#1+++}
{++#2}
{#3+++}
```

Plus signs go inside the braces. In a tag they go inside too, as in `{++text:signer1:Name++}`.

### Number placeholders per document

Placeholder numbers belong to the document they are written in. Two documents in the same envelope can both use `{#1}`, and each is matched to the definition on its own document.

You don't have to number placeholders in order or use every number. A document can have up to 100 placeholder definitions.

You can write the same placeholder more than once. Each one becomes its own field, built from the same definition. For example, write `{#3}` at the bottom of every page to collect initials on each page.

## Describe placeholders in the request

Add a `placeholders` object to each document entry in `envelope_documents` that has placeholders. Each key is a placeholder number written in that document, and each value describes the field:

```json
{
  "envelope_title": "Change of address",
  "envelope_parties": [
    {
      "party_name": "Alex Mitchell",
      "party_email": "alex@example.com",
      "party_role": "signer1"
    }
  ],
  "envelope_documents": [
    {
      "document_title": "Change of address form",
      "document_url": "https://www.example.com/change-of-address.pdf",
      "placeholders": {
        "1": {
          "type": "text",
          "role": "signer1",
          "name": "Full name",
          "width": 200,
          "height": 20
        },
        "2": {
          "type": "signature",
          "role": "signer1",
          "name": "Signature",
          "width": 150,
          "height": 40
        }
      }
    }
  ]
}
```

You can send `placeholders` as an object or as a JSON string, the same as `envelope_parties` and `envelope_documents`.

### Properties

| Property | Required | Applies to | Description |
|  --- | --- | --- | --- |
| `type` | Yes | All | The field type: `text`, `signature`, `date`, `date-signed`, `checkbox`, `upload` or `split`. See [Field types](#field-types). |
| `role` | Yes | All | The `party_role` of a signer in `envelope_parties`, such as `signer1`. A `copy` party can't be given fields. |
| `name` | Yes | All | The field label shown to the signer, up to 255 characters. Spaces are allowed. |
| `required` | No | All | `true` or `false`. Defaults to `true`. Set it to `false` to make the field optional. A signing date is always required, so it has no effect on `date-signed`. |
| `width` | Yes, except on a checkbox | All except `checkbox` | The field width in PDF units, as a whole number from 1 to 675. |
| `height` | Yes, except on a checkbox | All except `checkbox` | The field height in PDF units, as a whole number from 1 to 875. |
| `format` | Yes, on `date-signed` | `date-signed` | How the signing date is written. Uses the same presets as a [signing date tag](/tags#set-the-date-format), such as `dd/mm/yyyy`. |
| `group` | No | `checkbox` | Groups checkboxes together, the same as a [checkbox group](/tags#create-checkbox-groups) in a tag. Letters, numbers, hyphens and underscores only, up to 50 characters. |
| `preset` | See [Split](#split) | `split` | A split field [preset](/field-types/split#presets), such as `card_number`. |
| `layout` | See [Split](#split) | `split` | The number of cells in each run, as an array of whole numbers, such as `[4, 4, 4, 4]`. Up to 20 runs of up to 25 cells. |
| `cell_gap` | No | `split` | The gap between cells in PDF units, from 0 to 100. Defaults to 0. |
| `run_gap` | No | `split` | The gap between runs in PDF units, from 0 to 100. Defaults to 0. |


Every page is treated as 675 PDF units wide and 875 PDF units high, whatever its real size or orientation, so a width of 675 always spans the full page. These are the same units used by `w` and `h` in [tags](/tags#set-explicit-dimensions).

A property that doesn't apply to the field's type is rejected. For example, a `group` on a text field returns error 10710.

## Field types

The examples below show one definition of each type. Each would sit inside a document's `placeholders` object, keyed by its placeholder number.

### Text

A text field the signer types into.

```json
"1": {
  "type": "text",
  "role": "signer1",
  "name": "Full name",
  "width": 200,
  "height": 20
}
```

### Signature

A signature field.

```json
"2": {
  "type": "signature",
  "role": "signer1",
  "name": "Applicant signature",
  "width": 150,
  "height": 40
}
```

### Date

A date the signer enters.

```json
"3": {
  "type": "date",
  "role": "signer1",
  "name": "Date of birth",
  "width": 100,
  "height": 20
}
```

### Signing date

A date that fills itself with the date its party signed. The signer can't edit it. A `format` is required.

```json
"4": {
  "type": "date-signed",
  "role": "signer1",
  "name": "Date signed",
  "format": "dd/mm/yyyy",
  "width": 100,
  "height": 20
}
```

### Checkbox

A checkbox. A checkbox is always 15 units wide and its height follows the size of the placeholder text, so a checkbox definition takes no `width` or `height`.

```json
"5": {
  "type": "checkbox",
  "role": "signer1",
  "name": "I agree",
  "group": "consent",
  "required": false
}
```

The type is `checkbox` here. In a tag it is written `check`.

### File upload

A field where the signer attaches a file.

```json
"6": {
  "type": "upload",
  "role": "signer1",
  "name": "Proof of address",
  "width": 150,
  "height": 40
}
```

### Split

A [split field](/field-types/split) collects one value across a row of cells. Give it a `layout`, a preset that has its own layout, or both. The `numeric`, `alphabetical` and `alphanumeric` presets only limit which characters can be entered, so they need a `layout`. A `layout` used with any other preset must have the same number of cells in total as the preset's own layout. The `width` and `height` cover the whole field.

A split field can have up to 20 runs, with up to 25 cells in each, and each gap can be up to 100 units.

```json
"7": {
  "type": "split",
  "role": "signer1",
  "name": "National Insurance number",
  "preset": "national_insurance",
  "width": 189,
  "height": 18,
  "cell_gap": 2,
  "run_gap": 10
}
```

A `layout` sets the cells in each run, the same as `l=` in a tag. This one is a 9-cell reference number:

```json
"8": {
  "type": "split",
  "role": "signer1",
  "name": "Reference",
  "preset": "numeric",
  "layout": [9],
  "width": 180,
  "height": 18
}
```

See the [split field](/field-types/split) page for the limits on runs, cells and gaps, and what each preset accepts.

## Placeholders that don't match

Placeholders and definitions are matched by number when the document is processed.

- **A placeholder with no definition** is left in the document as text, and no field is created.
- **A definition with no placeholder** in the document is ignored.
- **A document with no `placeholders` object** is processed as before, and anything that looks like a placeholder is left as text.


The envelope is still created in each case, so check that every placeholder in the document has a definition.

## Use placeholders with tags

A document can contain both placeholders and [tags](/tags). Tags are processed as usual, and each placeholder is replaced using its definition.

## Errors

The request is rejected with a `400` response if a definition is invalid. Error codes 10700 to 10711 cover placeholders. See [Envelope errors](/errors/envelope-errors) for the full list.

## Related documentation

- [Tags](/tags) place fields with full tags written in the document
- [Split field](/field-types/split) covers layouts, gaps and presets for split fields
- [Send an envelope with an uploaded document](/guides/send-envelope/send-envelope-uploaded-document) shows how to send the document your placeholders are written in