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 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.

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.

Placeholders follow this format:

{#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.

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.

{+++#1+++}
{++#2}
{#3+++}

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

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.

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:

{
  "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.

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.

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

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

A text field the signer types into.

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

A signature field.

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

A date the signer enters.

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

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

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

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.

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

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

A field where the signer attaches a file.

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

A split field 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.

"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:

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

See the split field page for the limits on runs, cells and gaps, and what each preset accepts.

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.

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

The request is rejected with a 400 response if a definition is invalid. Error codes 10700 to 10711 cover placeholders. See Envelope errors for the full list.

• Tags place fields with full tags written in the document
• Split field covers layouts, gaps and presets for split fields
• Send an envelope with an uploaded document shows how to send the document your placeholders are written in