Numbered placeholders will be released on **11 November 2026**. Until then, `placeholders` in a request is ignored, and a placeholder such as `{#1}` is left in the document as ordinary text.

You can now place fields with **numbered placeholders**. Type a short marker such as `{#1}` into your document where a field should go, then describe the field in your `POST /v1/envelopes` request. Use them where a full [tag](/tags) won't fit, such as fixed-length form fields and narrow table cells on forms.

Nothing changes for existing documents, templates or tags.

## How placeholders work

Write `{#n}` in your document, with a number from 1 to 999. Then add a `placeholders` object to that document in `envelope_documents`, keyed by the same numbers:

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

The field starts where the placeholder is written, and its size comes from `width` and `height`. The placeholder is removed from the document.

Placeholders support the `text`, `signature`, `date`, `date-signed`, `checkbox`, `upload` and `split` field types. They work on uploaded documents only, not on templates.

You can find the full list of properties, an example for each field type and the rules in [Numbered placeholders](/placeholders). Error codes 10700 to 10711 are listed in [Envelope errors](/errors/envelope-errors).