Templates API

GET /document_templates

List templates Extension

Cursor-paginated list of the workspace's templates. total_count counts every template matching the filters so navigation badges do not need to fetch and serialize every row.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Query parameters

Responses

Example request

curl -X GET https://api.signclad.com/api/v1/document_templates \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /document_templates

Create a template

Same shape as a document, with placeholders instead of recipients and placeholder_id on fields. draft: false publishes the template; draft: true returns an embedded_edit_url for the template builder. The response carries the transient status Created in both cases. The settled status (Draft or Available) appears on the next GET, and PUT {draft: false} moves a draft to Available. fields is accepted both as an array of arrays (one inner array per file) and as an object keyed by file and field, for compatibility with clients that build it as a map.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Request body

application/json

Responses

Example request

curl -X POST https://api.signclad.com/api/v1/document_templates \
  -H "X-Api-Key: $SIGNCLAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Onboarding agreement",
  "draft": true,
  "text_tags": true,
  "metadata": {
    "s3_keys": "[\"2026/09/09/ws/files/file/originals/onboarding.pdf\"]"
  },
  "files": [
    {
      "name": "onboarding.pdf",
      "file_url": "https://files.example.com/onboarding.pdf?X-Amz-Expires=7200&X-Amz-Signature=..."
    }
  ],
  "placeholders": [
    {
      "id": "borrower",
      "name": "Borrower"
    }
  ],
  "fields": [
    [
      {
        "api_id": "borrower_signature",
        "type": "signature",
        "placeholder_id": "borrower",
        "page": 1,
        "x": 375,
        "y": 206,
        "width": 180,
        "height": 44
      }
    ]
  ]
}'

Example response (201)

{
  "id": "3f1c9a2e-6b7d-4c8e-9a0b-1c2d3e4f5a6b",
  "name": "Onboarding agreement",
  "status": "Created",
  "archived": false,
  "created_at": "2026-09-01T12:00:00Z",
  "updated_at": "2026-09-01T12:00:00Z",
  "template_link": "https://app.signclad.com/t/3f1c9a2e6b7d",
  "embedded_edit_url": "https://app.signclad.com/embed/templates/3f1c9a2e?token=eyJhbGciOi...",
  "placeholders": [
    {
      "id": "borrower",
      "name": "Borrower"
    }
  ],
  "files": [
    {
      "name": "onboarding.pdf",
      "pages_number": 0,
      "status": "processing"
    }
  ],
  "fields": [
    [
      {
        "api_id": "borrower_signature",
        "type": "signature",
        "page": 1,
        "placeholder_name": "Borrower",
        "x": 375,
        "y": 206,
        "width": "180.0",
        "height": "44.0",
        "value": ""
      }
    ]
  ]
}

GET /document_templates/{id}

Get a template

The full template, including placeholders, copied_placeholders, template_link (the public fill link, which works even while the template is still a draft) and a single-use embedded_edit_url. fields is an array of arrays, one per file, and each field carries placeholder_name — never placeholder_id. This is where a template's settled status lives; a create answered Created.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Responses

Example request

curl -X GET https://api.signclad.com/api/v1/document_templates/{id} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

Example response (200)

{
  "id": "3f1c9a2e-6b7d-4c8e-9a0b-1c2d3e4f5a6b",
  "name": "Onboarding agreement",
  "status": "Available",
  "archived": false,
  "created_at": "2026-09-01T12:00:00Z",
  "updated_at": "2026-09-08T09:31:44Z",
  "template_link": "https://app.signclad.com/t/3f1c9a2e6b7d",
  "embedded_edit_url": "https://app.signclad.com/embed/templates/3f1c9a2e?token=eyJhbGciOi...",
  "subject": "Please sign your onboarding agreement",
  "message": "<p>Welcome aboard.</p>",
  "expires_in": 30,
  "language": "en",
  "current_revision": 7,
  "placeholders": [
    {
      "id": "borrower",
      "name": "Borrower",
      "signing_order": 1
    }
  ],
  "copied_placeholders": [],
  "files": [
    {
      "name": "onboarding.pdf",
      "pages_number": 4,
      "status": "ready"
    }
  ],
  "fields": [
    [
      {
        "api_id": "borrower_date",
        "type": "date",
        "page": 1,
        "placeholder_name": "Borrower",
        "label": "Date signed",
        "x": 375,
        "y": 262,
        "width": "120.0",
        "height": "24.0",
        "lock_sign_date": true,
        "date_format": "MM/DD/YYYY",
        "value": ""
      },
      {
        "api_id": "borrower_signature",
        "type": "signature",
        "page": 1,
        "placeholder_name": "Borrower",
        "label": "Signature",
        "x": 375,
        "y": 206,
        "width": "180.0",
        "height": "44.0",
        "lock_sign_date": false,
        "value": ""
      }
    ]
  ]
}

PUT /document_templates/{id}

Update template settings

Settings only; files, placeholders, and fields are edited in the builder. labels and checkbox_groups are replaced wholesale by what the request carries. conditional_rules are upserted by id; send {"id": "...", "deleted": true} to remove one.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Request body

application/json

Responses

Example request

curl -X PUT https://api.signclad.com/api/v1/document_templates/{id} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Loan agreement (2026)",
  "subject": "Your loan agreement",
  "expires_in": 30,
  "labels": [
    "loans",
    "onboarding"
  ]
}'

PATCH /document_templates/{id}

Save a template editor snapshot

Saves fields and roles atomically with settings and a revision. Fields replace the entire field collection and address roles by placeholder_name or placeholder_id. Files are unchanged. draft true returns the template to Draft; false publishes it.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Request body

application/json

Responses

Example request

curl -X PATCH https://api.signclad.com/api/v1/document_templates/{id} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

DELETE /document_templates/{id}

Delete a template

Documents already created from the template are unaffected.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Responses

Example request

curl -X DELETE https://api.signclad.com/api/v1/document_templates/{id} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /document_templates/documents

Create a document from templates

Creates a document from one template (template_id) or several composed in order (template_ids). Exactly one of the two is required. Recipients are assigned to placeholders by placeholder_name and inherit that placeholder's fields and settings. files and fields are appended: they never replace the template's files, and each inner fields array belongs to one appended file. Signatures and initials already applied on the template are copied in as content: they stay visible, create no signing event, fire no document_signed, and do not change any recipient's status. If the request adds new unsigned signature or initials fields for the same signer, the pre-applied ones are cleared so that signer signs once. The response carries the transient status Draft whatever draft was; the settled status appears on the next GET. On a composed document a field's identity is the pair (source template, api_id). Nothing is renamed, every field in the response carries template_id, and rule and group references resolve inside their source template. A template_fields entry may be {api_id, value} when the api_id is unique across the templates, and must be {template_id, api_id, value} when it is not; an ambiguous bare reference is 422 ambiguous_field_reference and lists the candidates.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Request body

application/json

Responses

Example request

curl -X POST https://api.signclad.com/api/v1/document_templates/documents \
  -H "X-Api-Key: $SIGNCLAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "template_id": "3f1c9a2e-6b7d-4c8e-9a0b-1c2d3e4f5a6b",
  "draft": false,
  "embedded_signing": true,
  "recipients": [
    {
      "id": "signer-1",
      "placeholder_name": "Borrower",
      "name": "Jane Doe",
      "email": "[email protected]",
      "send_email": false
    }
  ],
  "exclude_placeholders": [
    "Co-borrower"
  ],
  "template_fields": [
    {
      "api_id": "borrower_full_name",
      "value": "Jane Doe"
    },
    {
      "api_id": "borrower_start_date",
      "value": "2026-07-02T00:00:00Z"
    }
  ],
  "conditional_rules_mode": "append",
  "skip_invalid_fields": true,
  "metadata": {
    "loan_id": "48213"
  }
}'

POST /document_templates/{id}/duplicate

Duplicate a template Extension

Copies files, placeholders, fields, checkbox groups, conditional rules, and settings into a new template. Field api_ids are preserved, so field mappings keep working.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Request body

application/json

Responses

Example request

curl -X POST https://api.signclad.com/api/v1/document_templates/{id}/duplicate \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /document_templates/{id}/embedded_edit_url

Regenerate a template builder URL Extension

Issues a fresh single-use embedded_edit_url for the template builder.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Request body

application/json

Responses

Example request

curl -X POST https://api.signclad.com/api/v1/document_templates/{id}/embedded_edit_url \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

PUT /document_templates/{id}/files/{position}

Replace a file on a template Extension

Swaps one file of a template and re-anchors its fields, producing a new template revision. Dry run first, then commit with the expected_revision from the dry run; a template that changed in between fails with 409 revision_mismatch.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Request body

application/json

Responses

Example request

curl -X PUT https://api.signclad.com/api/v1/document_templates/{id}/files/{position} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "file_id": "file_01J9K3P2S5N7Q8R1T2V3W4X5",
  "strategy": "anchors",
  "scale_to_page": true,
  "dry_run": false,
  "expected_revision": 7
}'

GET /document_templates/{id}/revisions

List template revisions Extension

Every saved revision, newest first, with the reason it was created and the hash of its snapshot. current_revision is the number to pass as expected_revision when replacing a file.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Responses

Example request

curl -X GET https://api.signclad.com/api/v1/document_templates/{id}/revisions \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /document_templates/{id}/revisions/{number}/restore

Restore a template revision Extension

Recreates an old snapshot as a new revision rather than rewinding history, so field layout and file always match and nothing that pinned an earlier revision changes under it.

Base URL

https://api.signclad.com/api/v1

Authentication

API key or OAuth 2.1 access token

Path parameters

Responses

Example request

curl -X POST https://api.signclad.com/api/v1/document_templates/{id}/revisions/{number}/restore \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"