Guides›Working with the API

Templates

Templates are made and published in the app. The API lists them, describes the data they take, previews them, and sends envelopes from them in one call.

Find a template and its data

GET /v1/templates lists your templates with their roles and latest published version (paginated); GET /v1/templates/{id} shows the published one in full. GET /v1/templates/{id}/data_schema returns a JSON Schema (2020-12) of the data it takes — handy for code generators:

• Text, date and number tags are strings; the tag’s type is in x-skanything-type.
• Yes / No tags are booleans (the text "yes", "no", "true" and "false" is accepted too).
• Tables and API-filled checkbox or radio groups are objects.
• required lists the keys you must send.

Templates need a plan that includes them (402 feature_not_included). Reading them needs templates:read.

Send from a template

POST /v1/envelopes with template_id, the data for its tags and one entry in recipients per role (role, name, email). Add send: true to send it in the same call; without it you get a draft to check first. signing_order (parallel, serial or groups) overrides the template’s. Each recipient can also carry the recipient options (phone, delivery, require_text_code, access_pin, language, signing_capacity, allow_reassign).

curl https://api.skanything.io/v1/envelopes \
  -H "Authorization: Bearer $SA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lease-1042" \
  -d '{
    "template_id": "tpl_8d2b6f0a3c9e4b7d1a5f2c8e6b0d4a9f",
    "send": true,
    "external_ref": "lease-1042",
    "data": { "tenant_name": "Sam Rivera", "monthly_rent": "$1,850.00", "pets_allowed": false },
    "recipients": [
      { "role": "Tenant", "name": "Sam Rivera", "email": "sam@example.com", "delivery": "both", "phone": "+15125550142" },
      { "role": "Landlord", "name": "Jordan Ellis", "email": "jordan@example.com" }
    ]
  }'

The call is one outcome: if anything fails — data, a recipient, your plan — no envelope is left behind, and a retry with the same Idempotency-Key starts clean. Common errors: 404 not_published, 422 missing_data, invalid_data, unknown_role, duplicate_role, missing_recipient, and with send: true everything send can return. Senders can’t add or change fields a template locks (403 template_locked).

Preview with your data

POST /v1/templates/{id}/preview returns a watermarked PDF of one document (document, from 1; version, the latest when left out) filled with the data you send and sample values for the rest. Nothing is stored. Needs templates:write.

curl -X POST -o preview.pdf https://api.skanything.io/v1/templates/tpl_8d2b6f0a3c9e4b7d1a5f2c8e6b0d4a9f/preview \
  -H "Authorization: Bearer $SA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "tenant_name": "Sam Rivera" } }'