API documentation

Authentication

Create a key under API keys. Send it on every request as X-Auth-Token. All responses are JSON; errors look like {"error":"…"} with a 4xx/5xx status.

curl https://sign.airosofts.com/api/v1/me -H "X-Auth-Token: as_live_…"

Templates

• GET/api/v1/templatesList templates (?archived=true to include archived)
• GET/api/v1/templates/:idTemplate with documents + fields
• POST/api/v1/templates/htmlCreate from HTML with field tags
• POST/api/v1/templates/pdfCreate from a PDF (JSON base64 or multipart) with field geometry
• PUT/api/v1/templates/:idRename / replace fields
• POST/api/v1/templates/:id/cloneDuplicate
• GET/api/v1/templates/:id/documentDownload the source PDF
• DELETE/api/v1/templates/:idArchive

POST /api/v1/templates/html
{
  "name": "Subcontractor Agreement",
  "html": "<p>Name: <text-field name=\"Contractor Name\" role=\"Contractor\" required=\"true\" style=\"width:220px\"></text-field></p>
           <signature-field name=\"Signature\" role=\"Contractor\" required=\"true\" style=\"width:240px;height:60px\"></signature-field>"
}

Field geometry uses page fractions: { page: 0, x: 0.1, y: 0.82, w: 0.3, h: 0.06 } — the same coordinates the builder saves, so a template made in the UI and one posted via API are interchangeable.

Submissions (send for signature)

• POST/api/v1/submissionsCreate from a template and email signers
• POST/api/v1/submissions/htmlOne call: render HTML → template → send
• GET/api/v1/submissionsList (?status=&template_id=&external_id=&after=)
• GET/api/v1/submissions/:idDetail incl. submitters, documents, audit events
• GET/api/v1/submissions/:id/documentsSigned PDF (?kind=source for the original)
• DELETE/api/v1/submissions/:idArchive

POST /api/v1/submissions
{
  "template_id": "…",
  "order": "sequential",                // or "parallel" (default)
  "send_email": true,
  "completed_redirect_url": "https://southerninvestment.co/work-with-us/done",
  "bcc_completed": "office@southerninvestment.co",
  "expire_at": "2026-10-01T00:00:00Z",
  "external_id": "monday-item-123",
  "submitters": [
    { "role": "Contractor", "email": "jo@example.com", "name": "Jo Ortiz",
      "fields": [ { "name": "Contractor Name", "default_value": "Jo Ortiz", "readonly": true } ] },
    { "role": "Company", "email": "roland@southerninvestment.co", "send_email": false }
  ]
}

→ 201 { "id": "…", "status": "pending",
        "submitters": [ { "id": "…", "slug": "…", "embed_src": "https://…/s/<token>", "status": "sent" }, … ] }

Use embed_src to open the signing page yourself (redirect, iframe, or the web component below) instead of emailing.

Submitters

• GET/api/v1/submittersList (?submission_id=&status=&email=)
• GET/api/v1/submitters/:idOne submitter with values
• PUT/api/v1/submitters/:idChange email/name, prefill values, send_email:true to re-send

Embedding the signing form

<script src="https://sign.airosofts.com/embed.js"></script>
<airosign-form data-src="https://sign.airosofts.com/s/TOKEN"></airosign-form>
<script>
  document.querySelector("airosign-form").addEventListener("completed", (e) => {
    console.log("signed", e.detail); // { submitter_id, submission_id, all_completed }
  });
</script>

<docuseal-form> is registered as an alias, so existing DocuSeal embeds keep working. Events: load, completed, declined.

Webhooks

Events: form.viewed · form.started · form.completed · form.declined · submission.created · submission.completed · submission.expired · submission.archived · template.created · template.updated · template.archived. Payload: { event_type, timestamp, data }. Headers webhook-id, webhook-timestamp, webhook-signature (v1,base64(hmac_sha256(secret, id.ts.body))). Non-2xx responses retry at 1, 5, 15, 60, 240 and 720 minutes.

Verification

Every completed document has a public page at /verify/:submission_id (also printed on the certificate page) that re-computes the audit hash chain and lets anyone compare a PDF’s SHA-256 against the sealed original. GET /api/verify/:id returns the same as JSON.

Signer-side API

The signing page is driven by /api/sign/:token/* (state, document, values, signature, complete, decline, otp). These accept only the signed link token — no API key — so you can build a fully custom signing UI if you need one.