Templates

The API works with published templates — the ones your team has prepared and published in the app's Templates area. Drafts and archived templates are not visible to the API.

Templates are authored in the app, not through the API: someone uploads the document, reviews the fields and publishes it once, and your integration sends from it many times. So an empty list means nothing has been published in this workspace yet — not that your key lacks access. If you expect a template and don't see it, check it is published rather than archived or still a draft.

List templates

curl "https://api.instaspace.ai/api/v1/esign/templates?search=nda" \
  -H "Authorization: Bearer isk_live_..."

search is optional and filters by name.

{
  "templates": [
    {
      "id": "0b9f6f2e-…",
      "name": "Mutual NDA",
      "description": "Standard two-party NDA",
      "fillMode": "flow",
      "submitterRoles": ["First Party", "Second Party"],
      "fields": [{ "name": "Signature", "type": "signature", "required": true, "submitterRole": "First Party" }],
      "variables": [{ "key": "client_name", "label": "Client Name", "type": "text", "required": true }],
      "version": 3
    }
  ]
}

Get one template

curl https://api.instaspace.ai/api/v1/esign/templates/{id} \
  -H "Authorization: Bearer isk_live_..."

For a coordinate-positioned template, the response includes each field's available placement rectangles in fields[].areas:

{
  "id": "0b9f6f2e-8a7d-4c31-9e42-6d28f4ab7310",
  "name": "Mutual NDA",
  "description": "Standard two-party NDA",
  "fillMode": "coordinate",
  "submitterRoles": ["First Party", "Second Party"],
  "fields": [
    {
      "name": "First Party Signature",
      "type": "signature",
      "required": true,
      "submitterRole": "First Party",
      "areas": [{ "page": 3, "x": 0.1, "y": 0.78, "w": 0.34, "h": 0.08 }]
    },
    {
      "name": "Second Party Signature",
      "type": "signature",
      "required": true,
      "submitterRole": "Second Party",
      "areas": [{ "page": 3, "x": 0.56, "y": 0.78, "w": 0.34, "h": 0.08 }]
    }
  ],
  "variables": [],
  "version": 3
}

Each area describes one field rectangle. page is 1-based. x and y are the rectangle's normalized horizontal and vertical position on that page; w and h are its normalized width and height. All four coordinates use the 0..1 range. areas is present for coordinate-positioned fields when placement data is available, and is otherwise omitted.

Apart from these detail-only field positions, the response has the same shape as one list entry. Requesting a draft or archived template returns 404, the same as an unknown id.

Reading the shape

Two things on the template drive what you send in a signature request:

• submitterRoles — the signing parties. A signature request must name exactly one recipient per role.
• fillMode decides what the request's values mean:
  • flow — the template is a document with fillable variables (client name, fee, dates…). Your values are keyed by variables[].key, and instaSpace writes them into the document text itself before sending.
  • coordinate — the template has positioned fields. Your values are keyed by field name and prefill those fields; anything you leave out is completed by the signer. Signature fields can never be prefilled.