Fields & placeholders

A template carries two distinct kinds of variable. Knowing which is which is the key to automating contracts cleanly.

The two kinds

Fields are boxes a signer (or a lead form) fills — a signature, an initial, a date, or a short text. They live at fixed x/y/w/h coordinates on the rendered PDF and are placed visually in the editor.

Placeholders are inline {{tokens}} woven into the body text. They're merge variables: at instantiate time the literal {{token}} is replaced with a value. No coordinates — they reflow with the text.

Both share one field_key namespace (snake_case, e.g. client_name). The same field_values map you send at instantiate fills a placeholder and any positioned text field with the same key.

Placeholder sources: lead vs API

Every placeholder declares who fills it:

A template that uses only lead placeholders can be sent through Present (the no-code lead form). A template that uses api placeholders is filled programmatically — see below.

API objects (line-item collections)

Some data is a list, not a single value — order lines, deliverables, services rendered. A collection is an inline table whose row is repeated once per item.

In field_values, a collection key maps to an array of row objects; every other key maps to a string:

POST /api/templates/{templateId}/instantiate
Authorization: Bearer lsk_live_…
Content-Type: application/json

{
  "recipients": [
    { "slot": 1, "email": "buyer@acme.ch", "name": "Sara Buyer" }
  ],
  "field_values": {
    "client_name": "Acme AG",
    "order_total": "CHF 1,240.00",
    "line_items": [
      { "description": "Design sprint", "qty": "1", "unit_price": "900.00", "amount": "900.00" },
      { "description": "Hosting (yr)",  "qty": "1", "unit_price": "340.00", "amount": "340.00" }
    ]
  }
}

The column keys in each row object (description, qty, …) match the column keys defined on the table in the template.

Reusable definitions & preview examples

Admins curate a workspace catalog of fields and API objects in Settings → API → Fields & API objects. Each definition carries:

• a key + label + type (text, email, currency, date, collection, …),
• a source (lead or api),
• an example value (and per-column examples for collections).

Authors then insert known tokens from the editor's placeholder menu instead of retyping them, and the example values render in the template preview — so a draft shows “Acme AG” and real line items rather than {{client_name}}.

A definition that a template already uses is locked: its key can't be renamed or deleted until it's removed from the template, so live integrations never break.

Enum fields are validated

If a definition has type enum, its value is checked against the allowed options. Sending an out-of-vocabulary value to instantiate returns a 400 with code: "invalid-enum" and the list of allowed values:

{
  "error": "Invalid value \"Platinum\" for \"Plan tier\". Allowed: Gold, Silver, Bronze.",
  "code": "invalid-enum",
  "field": "plan_tier",
  "allowed": ["Gold", "Silver", "Bronze"]
}

Which should I use?

• Need a signature, initials, or a value a person types as they sign → field.
• Need to merge a value you already have into the prose → placeholder (api source).
• Collecting from a prospect via a shared link → placeholder (lead source) + Present.
• A repeating list (invoice lines, deliverables) → collection.