API reference

Use Signa from backend systems with API keys, templates, submissions, submitters, attachments, webhooks, verification tools, and embedded signing packages.

Exhaustive OpenAPI

Use Swagger for every field

Open live API docs

Authentication

Create an API key in Settings > API and send it as X-Auth-Token. Keys inherit the active account/team scope. Store keys server-side, rotate them when team access changes, and never expose them in browser or mobile clients.

Authenticated request

curl https://signa.example.com/api/templates \
  -H "X-Auth-Token: {token}"

Common error

{
  "statusCode": 401,
  "message": "Unauthorized",
  "requestId": "9df2e9b5-4f08-4bd1-bc3e-eab7f7d05f9a"
}

Pagination

List endpoints accept limit and filter parameters where supported. Responses include pagination metadata when the endpoint returns a collection.

Errors

Errors include request IDs so API consumers can match user-facing failures with backend logs and webhook delivery logs.

Production workflow

1
Create a template in the console or with /api/templates/pdf.
2
Create a submission with roles, submitters, values, metadata, and delivery flags.
3
Open the returned /s/{submitterSlug} in hosted, React, or React Native signing.
4
Listen for submission.completed webhooks and verify the HMAC signature.
5
Download final documents and audit logs from the submission documents endpoint.
6
Verify PDFs when your workflow needs cryptographic trust-chain reporting.

Templates

Templates store source documents, generated preview pages, signer roles, field schema, folder placement, preferences, and version history.

Templates model

Name
id
Type
string
Description
Unique template identifier.
Name
slug
Type
string
Description
Public shared-link slug when enabled.
Name
name
Type
string
Description
Human-readable template name.
Name
schema
Type
array
Description
Documents and generated page schema.
Name
fields
Type
array
Description
Signer fields with type, role, page, and coordinates.
Name
submitters
Type
array
Description
Roles configured for the template.
Name
preferences
Type
object
Description
Template-level signing and delivery settings.
Name
archived_at
Type
timestamp
Description
Set when the template is archived.

GET/api/templates

List templates

List templates visible to the authenticated account or team.

Name
limit
Type
integer
Description
Maximum templates to return, up to 100.
Name
folder
Type
string
Description
Filter templates by folder name or path.
Name
archived
Type
boolean
Description
Include or filter archived templates.
Name
q
Type
string
Description
Search template names.
Name
after
Type
string
Description
Cursor for the next page.
Name
before
Type
string
Description
Cursor for the previous page.

Request

curl -G https://signa.example.com/api/templates \
  -H "X-Auth-Token: {token}" \
  -d limit=10 \
  -d include=fields

Response

{
  "data": [
    {
      "id": "12",
      "name": "Service Contract",
      "folder_name": "Default",
      "submitters": [{ "name": "Client" }],
      "fields": []
    }
  ],
  "pagination": { "count": 1, "next": null, "prev": null }
}

GET/api/templates/:id

Get a template

Retrieve a template with signer roles, fields, schema, preferences, author, and source-document URLs.

Name
id
Type
string
required
Description
Template identifier.

Request

curl https://signa.example.com/api/templates/12 \
  -H "X-Auth-Token: {token}"

Response

{
  "id": "12",
  "name": "Service Contract",
  "folder_name": "Default",
  "submitters": [{ "name": "Client" }],
  "fields": [],
  "schema": [],
  "preferences": {}
}

POST/api/templates/pdf

Create template from PDF

Create a fillable template from PDF files. Embedded {{field}} text tags are detected where possible.

Name
name
Type
string
required
Description
Template name shown in the console.
Name
documents
Type
file[]
required
Description
One or more PDF documents.
Name
folder_name
Type
string
Description
Folder name. Defaults to Default.
Name
external_id
Type
string
Description
Your app's idempotent template key.
Name
shared_link
Type
boolean
Description
Enable public /d/{slug} usage.

Request

curl https://signa.example.com/api/templates/pdf \
  -H "X-Auth-Token: {token}" \
  -F name="Service Contract" \
  -F folder_name="Default" \
  -F documents[]=@contract.pdf

Response

{
  "id": "12",
  "name": "Service Contract",
  "folder_name": "Default",
  "documents": [
    { "filename": "contract.pdf", "url": "https://signa.example.com/api/storage/blobs/..." }
  ]
}

POST/api/templates/docx

Create template from DOCX

Create a template from DOCX. Use [[variables]] for generated document text and {{fields}} for signer inputs.

Name
name
Type
string
required
Description
Template name shown in the console.
Name
document
Type
file
required
Description
DOCX template file.
Name
folder_name
Type
string
Description
Folder name. Defaults to Default.
Name
variables
Type
object
Description
Optional DOCX variable defaults.

Request

curl https://signa.example.com/api/templates/docx \
  -H "X-Auth-Token: {token}" \
  -F name="Offer Letter" \
  -F document=@offer.docx

Response

{
  "id": "18",
  "name": "Offer Letter",
  "schema": [{ "name": "offer", "attachment_uuid": "..." }]
}

PUT/api/templates/:id

Update a template

Update template metadata, roles, fields, schema, preferences, folder placement, or shared-link availability.

Name
name
Type
string
Description
New template display name.
Name
folder_name
Type
string
Description
Move the template to this folder.
Name
shared_link
Type
boolean
Description
Enable or disable its public start form.
Name
roles
Type
string[]
Description
Ordered signer role names.
Name
fields
Type
array
Description
Complete field schema with page areas.
Name
preferences
Type
object
Description
Signing, expiry, and delivery preferences.
Name
archived
Type
boolean
Description
Archive or restore the template.

Request

curl -X PUT https://signa.example.com/api/templates/12 \
  -H "X-Auth-Token: {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "2026 Service Contract",
    "shared_link": true,
    "preferences": { "default_expire_at_duration": "7_days" }
  }'

Response

{
  "id": "12",
  "name": "2026 Service Contract",
  "shared_link": true,
  "preferences": { "default_expire_at_duration": "7_days" }
}

POST/api/templates/:id/clone

Clone a template

Clone the template documents, preview attachments, roles, fields, schema, and preferences.

Name
name
Type
string
Description
Name for the cloned template.
Name
folder_name
Type
string
Description
Destination folder.
Name
external_id
Type
string
Description
Your application correlation key.

Request

curl https://signa.example.com/api/templates/12/clone \
  -H "X-Auth-Token: {token}" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Service Contract - EMEA", "folder_name": "EMEA" }'

Response

{
  "id": "19",
  "name": "Service Contract - EMEA",
  "folder_name": "EMEA"
}

DELETE/api/templates/:id

Archive or delete a template

Archive a template by default. Permanent deletion is intended for controlled cleanup and cannot be undone.

Name
permanently
Type
boolean
Description
Hard-delete instead of archiving. Defaults to false.

Submissions

Submissions are signature requests. They can be created from templates or directly from PDF, DOCX, or HTML for one-off API workflows.

Submissions model

Name
id
Type
string
Description
Unique submission identifier.
Name
slug
Type
string
Description
Submission route slug.
Name
source
Type
string
Description
invite, bulk, api, embed, link, pdf, docx, or html.
Name
status
Type
string
Description
pending, completed, declined, or expired.
Name
submitters
Type
array
Description
Recipients and their signing status/links.
Name
audit_log_url
Type
string
Description
Audit trail PDF URL.
Name
combined_document_url
Type
string
Description
Final merged completed document URL.
Name
metadata
Type
object
Description
Caller-supplied correlation data.

GET/api/submissions

List submissions

List submissions and their recipient progress for the authenticated account.

Name
template_id
Type
string
Description
Filter submissions by template.
Name
status
Type
string
Description
pending, completed, declined, or expired.
Name
email
Type
string
Description
Filter by submitter email.
Name
include
Type
string
Description
Optional related data such as fields.

Request

curl -G https://signa.example.com/api/submissions \
  -H "X-Auth-Token: {token}" \
  -d template_id=12 \
  -d status=pending

Response

{
  "data": [
    {
      "id": "36",
      "status": "pending",
      "source": "api",
      "submitters": [{ "email": "client@example.com", "status": "sent" }]
    }
  ]
}

GET/api/submissions/:id

Get a submission

Retrieve one request with its recipients, document URLs, audit URL, metadata, and current status.

Name
id
Type
string
required
Description
Submission identifier.
Name
include
Type
string
Description
Optional related data such as fields.

Request

curl https://signa.example.com/api/submissions/36?include=fields \
  -H "X-Auth-Token: {token}"

Response

{
  "id": "36",
  "status": "pending",
  "source": "api",
  "submitters": [
    { "id": "500001", "email": "client@example.com", "status": "sent" }
  ],
  "metadata": { "contract_id": "SC-1001" }
}

POST/api/submissions

Create submission from template

Create a signature request from an existing template. This is the primary API path for production apps.

Name
template_id
Type
string
required
Description
Template used to create the request.
Name
submitters
Type
array
required
Description
Recipients with role, email, phone, and values.
Name
send_email
Type
boolean
Description
Queue signature request emails.
Name
send_sms
Type
boolean
Description
Queue SMS signing links.
Name
submitters_order
Type
string
Description
preserved or random.
Name
auto_sign_owner
Type
boolean
Description
Auto-complete the configured owner role.
Name
metadata
Type
object
Description
Your app's correlation data.

Request

curl https://signa.example.com/api/submissions \
  -H "X-Auth-Token: {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "12",
    "submitters_order": "preserved",
    "send_email": true,
    "metadata": { "contract_id": "SC-1001" },
    "submitters": [
      {
        "role": "Client",
        "email": "client@example.com",
        "values": { "Client Name": "Ada Lovelace" }
      }
    ]
  }'

Response

{
  "id": "36",
  "status": "pending",
  "submitters": [
    {
      "email": "client@example.com",
      "slug": "61102d70-fc1e-4a44-894d-1ea8eeec9305",
      "url": "https://signa.example.com/s/61102d70-fc1e-4a44-894d-1ea8eeec9305"
    }
  ]
}

POST/api/submissions/pdf

Create submission from PDF

Create a one-off signing request from a PDF without saving a reusable template first.

Name
name
Type
string
required
Description
Submission name.
Name
document
Type
file
required
Description
PDF file for one-off signing.
Name
submitters
Type
array
required
Description
Recipients and roles.
Name
fields
Type
array
Description
Optional explicit field coordinates.
Name
send_email
Type
boolean
Description
Queue signature request emails.

Request

curl https://signa.example.com/api/submissions/pdf \
  -H "X-Auth-Token: {token}" \
  -F name="One-off NDA" \
  -F document=@nda.pdf \
  -F 'submitters=[{"email":"client@example.com","role":"Client"}]'

Response

{
  "id": "41",
  "source": "api",
  "status": "pending",
  "documents": [{ "name": "One-off NDA", "url": "https://signa.example.com/api/storage/blobs/..." }]
}

POST/api/submissions/html

Create submission from HTML

Render HTML into temporary signing PDFs and create a one-off signature request. Place Signa field tags directly in the HTML.

Name
documents
Type
array
required
Description
HTML documents with optional headers and footers.
Name
submitters
Type
array
required
Description
Recipients matching roles used by HTML field tags.
Name
send_email
Type
boolean
Description
Queue signature request emails.
Name
template_ids
Type
string[]
Description
Optional existing templates to append.

Request

curl https://signa.example.com/api/submissions/html \
  -H "X-Auth-Token: {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [{
      "name": "Approval",
      "html": "<h1>Approval</h1><signature-field name=\"Signature\" role=\"Approver\"></signature-field>"
    }],
    "submitters": [{ "role": "Approver", "email": "approver@example.com" }],
    "send_email": true
  }'

Response

[
  {
    "id": "500010",
    "submission_id": "42",
    "email": "approver@example.com",
    "url": "https://signa.example.com/s/4ef83a..."
  }
]

POST/api/submissions/docx

Create submission from DOCX

Expand DOCX variables, render the result to PDF, and create recipients without first saving a reusable template.

Name
documents
Type
array
required
Description
DOCX name/file entries using base64, data URL, or URL.
Name
submitters
Type
array
required
Description
Recipients and roles.
Name
variables
Type
object
Description
Values for [[variable_name]] placeholders.
Name
merge_documents
Type
boolean
Description
Combine rendered DOCX documents before signing.
Name
send_email
Type
boolean
Description
Queue signature request emails.

Request

curl https://signa.example.com/api/submissions/docx \
  -H "X-Auth-Token: {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [{ "name": "Offer.docx", "file": "UEsDBBQ..." }],
    "variables": { "candidate_name": "Ada Lovelace" },
    "submitters": [{ "role": "Candidate", "email": "ada@example.com" }],
    "send_email": true
  }'

Response

[
  {
    "id": "500011",
    "submission_id": "43",
    "email": "ada@example.com",
    "url": "https://signa.example.com/s/286b95..."
  }
]

GET/api/submissions/:id/documents

Get submission documents

Download partially filled documents or final signed documents once the submission is complete.

Name
id
Type
string
required
Description
Submission identifier.
Name
merge
Type
boolean
Description
Return one combined PDF when available.

Request

curl https://signa.example.com/api/submissions/36/documents?merge=true \
  -H "X-Auth-Token: {token}"

Response

{
  "id": "36",
  "documents": [
    {
      "name": "service-contract-client-2026-07-28.pdf",
      "url": "https://signa.example.com/api/storage/blobs/..."
    }
  ]
}

DELETE/api/submissions/:id

Archive or delete a submission

Archive a request by default. Use permanent deletion only when your retention policy permits it.

Name
permanently
Type
boolean
Description
Hard-delete instead of archiving. Defaults to false.

Submitters

Submitters represent each signer. Update submitters to prefill values, resend delivery, mark owner auto-sign flows, or inspect signing links.

Submitters model

Name
id
Type
string
Description
Unique submitter identifier.
Name
submission_id
Type
string
Description
Parent submission identifier.
Name
email
Type
string
Description
Signer email address.
Name
phone
Type
string
Description
Signer phone number.
Name
role
Type
string
Description
Template role assigned to the signer.
Name
slug
Type
string
Description
Public signer route slug.
Name
url
Type
string
Description
Public signing URL.
Name
values
Type
array
Description
Prefilled or completed field values.

GET/api/submitters

List submitters

List recipients across requests for reconciliation, completion reporting, or integration polling.

Name
submission_id
Type
string
Description
Filter by parent submission.
Name
template_id
Type
string
Description
Filter by source template.
Name
q
Type
string
Description
Search recipient name or email.
Name
completed_after
Type
timestamp
Description
Return recipients completed after this time.
Name
completed_before
Type
timestamp
Description
Return recipients completed before this time.
Name
limit
Type
integer
Description
Maximum records to return, up to 100.
Name
after
Type
string
Description
Cursor for the next page.

Request

curl -G https://signa.example.com/api/submitters \
  -H "X-Auth-Token: {token}" \
  -d template_id=12 \
  -d completed_after=2026-07-01T00:00:00.000Z

Response

{
  "data": [
    {
      "id": "500001",
      "submission_id": "36",
      "email": "client@example.com",
      "status": "completed"
    }
  ],
  "pagination": { "count": 1, "next": null, "prev": null }
}

GET/api/submitters/:id

Get submitter

Retrieve a submitter with signing URL, values, documents, and status.

Name
id
Type
string
required
Description
Submitter identifier.

Request

curl https://signa.example.com/api/submitters/500001 \
  -H "X-Auth-Token: {token}"

Response

{
  "id": "500001",
  "email": "client@example.com",
  "role": "Client",
  "status": "sent",
  "url": "https://signa.example.com/s/61102d70-fc1e-4a44-894d-1ea8eeec9305",
  "values": []
}

PUT/api/submitters/:id

Update submitter

Update recipient identity, prefilled values, delivery flags, or auto-sign completion state.

Name
email
Type
string
Description
Updated signer email.
Name
phone
Type
string
Description
E.164 phone number.
Name
values
Type
object
Description
Field values keyed by field name.
Name
readonly_fields
Type
array
Description
Field names the signer cannot edit.
Name
send_email
Type
boolean
Description
Resend email after updating.
Name
completed
Type
boolean
Description
Mark submitter completed for allowed auto-sign flows.

Request

curl -X PUT https://signa.example.com/api/submitters/500001 \
  -H "X-Auth-Token: {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "values": { "Client Name": "Ada Lovelace" },
    "send_email": true
  }'

Response

{
  "id": "500001",
  "email": "client@example.com",
  "status": "sent",
  "values": [{ "field": "Client Name", "value": "Ada Lovelace" }]
}

Attachments

The public attachment endpoint uploads file, image, and signature values for a specific signer. Template source files and completed documents are returned through their template or submission endpoints.

Attachments model

Name
uuid
Type
string
Description
Stable storage UUID used by template schema.
Name
filename
Type
string
Description
Original or generated file name.
Name
content_type
Type
string
Description
Detected MIME type.
Name
url
Type
string
Description
Time-limited or authorized storage URL.
Name
created_at
Type
timestamp
Description
Stored object timestamp.

POST/api/attachments

Upload a signer attachment

Upload a value for a signer attachment field. The returned UUID can be supplied as that field's value. The signer slug authorizes and scopes the upload.

Name
file
Type
file
required
Description
Supported file, image, or signature value.
Name
submitter_slug
Type
string
required
Description
Signer slug from the submission response.
Name
type
Type
string
Description
Attachment purpose, such as signature, image, or file.

Request

curl https://signa.example.com/api/attachments \
  -F submitter_slug=61102d70-fc1e-4a44-894d-1ea8eeec9305 \
  -F type=signature \
  -F file=@signature.png

Response

{
  "uuid": "d94e615f-76e3-46d5-8f98-36bdacb8664a",
  "filename": "signature.png",
  "content_type": "image/png",
  "created_at": "2026-07-28T10:15:30.000Z",
  "url": "https://signa.example.com/api/storage/blobs/..."
}

Tools

Tools support PDF merge and verification workflows for completed documents and imported third-party signed PDFs.

Tools model

Name
checksum_status
Type
string
Description
verified when the PDF matches a completed Signa document.
Name
cryptographic_verification
Type
boolean
Description
True when at least one CMS signature validates.
Name
byte_range_valid
Type
boolean
Description
PDF ByteRange structural validation result.
Name
cms_signature_valid
Type
boolean | null
Description
CMS signature validation result.
Name
certificate_chain_status
Type
string
Description
trusted, external, expired, invalid, or missing.
Name
signer_name
Type
string | null
Description
Signer name embedded in the signature dictionary.
Name
signature_type
Type
string | null
Description
PDF signature SubFilter such as ETSI.CAdES.detached.
Name
signing_time
Type
timestamp | null
Description
Signing time embedded in the PDF.
Name
revocation_status
Type
string
Description
good, missing, revoked, unavailable, or unknown.
Name
ltv_status
Type
string
Description
valid, missing, or invalid.

POST/api/tools/merge

Merge PDFs

Merge multiple PDF files into one document while preserving page order.

Name
files
Type
base64[]
required
Description
At least two base64-encoded PDFs in merge order.

Request

curl https://signa.example.com/api/tools/merge \
  -H "X-Auth-Token: {token}" \
  -H "Content-Type: application/json" \
  -d '{ "files": ["JVBERi0xLjQK...", "JVBERi0xLjQK..."] }'

Response

{
  "data": "JVBERi0xLjQK..."
}

POST/api/tools/verify

Verify signed PDF

Verify Signa or third-party PDF signatures. Results include byte range integrity, signer, timestamp, trust chain, and LTV evidence status.

Name
file
Type
file
required
Description
Signed PDF to verify.

Request

curl https://signa.example.com/api/tools/verify \
  -H "X-Auth-Token: {token}" \
  -F file=@signed-document.pdf

Response

{
  "checksum_status": "verified",
  "sha256": "7d865e959b2466918c9863afca942d0f...",
  "cryptographic_verification": true,
  "signatures": [
    {
      "byte_range_valid": true,
      "cms_signature_valid": true,
      "certificate_chain_status": "trusted",
      "signer_name": "client@example.com",
      "signature_type": "ETSI.CAdES.detached",
      "signing_time": "2026-07-28T10:15:30.000Z",
      "revocation_status": "good",
      "ltv_status": "valid"
    }
  ]
}