ctSignature^™

Section 1

Getting Started

Platform Overview

ctSignature is a multi-tenant, API-first document signing platform. It lets you send PDFs for legally binding electronic signatures, track signer progress, and store signed documents with a full audit trail.

Key capabilities:

• Single and multi-signer documents — sequential or parallel signing order
• Reusable templates — pre-place fields once, send to many recipients
• Embedded signing — host the signing experience inside your own app via iframe
• Webhooks — get notified in real time when documents are viewed, signed, or completed
• ESIGN/UETA compliance — consent capture, OTP verification, device fingerprinting, audit log, and certificate of completion
• White-label branding — custom logo, colors, and brand name on signing pages
• Address book — save frequent signers for quick reuse

Base URLs & Environments

All API paths in this manual are relative to the base URL.

Quick Start (5 Minutes)

With your API key in hand, here’s the canonical document-signing flow:

export CTDS_KEY="ctds_live_aBcDeFgHiJkLm..."

POST /api/v1/documents
Authorization: Bearer ctds_live_aBcDeFgHiJkLm...
Content-Type: multipart/form-data

RecipientName: John Smith
RecipientEmail: john@example.com
File: contract.pdf

GET /api/documents/signed/{documentId}?token=<secureToken>

Section 2

Authentication

ctSignature supports four types of authentication, each for a different purpose.

API Keys (Programmatic Access)

API keys are the primary way to call the REST API from your backend code. Each key is tied to a single tenant and gives full read/write access to that tenant's data.

Key Format

Keys follow the pattern ctds_<random-characters>. Example:

ctds_aB3cDeFgH1iJkLmN2oPqRsT3uVwXy

How to Send

Include the key in the Authorization header using the Bearer scheme:

Authorization: Bearer ctds_aB3cDeFgH1iJkLmN2oPqRsT3uVwXy

An X-Api-Key header carrying the same key is also accepted, if that suits your HTTP client better:

X-Api-Key: ctds_aB3cDeFgH1iJkLmN2oPqRsT3uVwXy

Generating a Key

POST /api/dashboard/api-keys
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "name": "Production Server"    // optional label
}

// Response
{
  "id": 1,
  "key": "ctds_aB3cDeFgH1iJkLmN2oPqRsT3uVwXy",   // shown only once!
  "prefix": "ctds_aB3",
  "name": "Production Server",
  "createdDate": "2026-04-17T10:00:00Z"
}

Revoking a Key

DELETE /api/dashboard/api-keys/{keyId}
Authorization: Bearer <jwt-token>

Endpoints That Accept API Keys

JWT Bearer Tokens (Dashboard & User Sessions)

JWT tokens are used by the web dashboard and by applications that need user-level authentication (for example, if your app lets users log in to manage their own signing settings).

Getting a Token

Identity is managed by ctOneAuth (OIDC). ctSignature does not store passwords. Registration creates the local tenant and provisions the org in ctOneAuth in a single call; sign-in always goes through the OIDC flow at GET /api/auth/oidc/login, which redirects to ctOneAuth and finishes by minting a JWT for the dashboard.

Register a New Account

POST /api/auth/register
Content-Type: application/json

{
  "companyName": "Acme Corp",
  "name": "Jane Developer",
  "email": "jane@acme.com"
}

// Response — no password is set here; user finishes setup on ctOneAuth.
{
  "setupUrl": "https://ctoneauth.example/setup?token=...",
  "tenant": {
    "id": 1,
    "companyName": "Acme Corp",
    "email": "jane@acme.com",
    "isTrial": true
  },
  "user": {
    "id": 1,
    "name": "Jane Developer",
    "role": "Admin"
  }
}

Sign In

GET /api/auth/oidc/login
// 302 → ctOneAuth /oauth2/authorize → /signin-oidc → /api/auth/oidc/complete
// On success, a JWT is delivered to /dashboard/oidc-complete.html via URL fragment.

How to Send

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Token Details

JWT Claims

Check Current User

GET /api/auth/me
Authorization: Bearer <jwt-token>

// Response
{
  "tenant": { "id": 1, "companyName": "Acme Corp", ... },
  "user": { "id": 1, "name": "Jane Developer", "role": "Admin" }
}

Platform Admin Tokens

Platform admin tokens give access to system-wide management endpoints. These credentials are set in the server configuration, not in the database.

POST /api/admin/auth/login
Content-Type: application/json

{
  "email": "<PlatformAdmin:Email from config>",
  "password": "<PlatformAdmin:Password from config>"
}

// Response
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "email": "admin@ctsignature.com",
  "role": "platform_admin"
}

Use this token with /api/admin/* endpoints only.

Signing & Placement Tokens

These are single-use, document-specific tokens embedded in URLs. They do not require any auth header — the token in the URL is the authentication.

For multi-signer documents, each signer gets their own unique secure token and signing URL.

Section 3

Documents API

The Documents API lets you create, track, and manage documents for signing. All endpoints below use API key authentication unless noted otherwise.

Create a Document (Single Signer)

Upload a PDF or Word document and specify who should sign it. Word files (.doc/.docx) are converted to PDF on upload — the stored, placed, and signed document is always a PDF.

Request

Content-Type: multipart/form-data

Example

curl -X POST https://ctsign.io/api/v1/documents \
  -H "Authorization: Bearer ctds_yourApiKey" \
  -F "RecipientName=John Smith" \
  -F "RecipientEmail=john@example.com" \
  -F "ExpirationHours=48" \
  -F "NotificationEmail=sender@acme.com" \
  -F "File=@contract.pdf"

Response (200 OK)

{
  "documentId": 42,
  "placementUrl": "https://ctsign.io/sign/place/abc123...",
  "signingUrl": "https://ctsign.io/sign/document/xyz789...",
  "placementToken": "abc123...",
  "secureToken": "xyz789...",
  "expirationDate": "2026-05-19T10:00:00Z"
}

Inline field placement (FieldsJson)

Pass a JSON array of field objects to place fields at creation time and skip the placement page entirely. At least one signature field is required; the response then has "skippedPlacement": true and no placementUrl.

-F 'FieldsJson=[
  {"type":"signature","x":100,"y":620,"width":150,"height":32,"page":2},
  {"type":"date","x":280,"y":635,"width":100,"height":20,"page":2},
  {"type":"initials","x":480,"y":700,"width":100,"height":24,"page":1},
  {"type":"text","x":100,"y":200,"width":180,"height":28,"page":1,"isRequired":false},
  {"type":"sender_text","x":100,"y":100,"width":220,"height":30,"page":1,
   "value":"Please initial every page and sign on page 2."}
]'

Coordinates are PDF points with the origin at the top-left of each page; page is 1-based. Field types: signature, initials, date, datetime, text (signer fills in), name (auto: printed name), stamp (auto: digital stamp block), and sender_text (your own text, stamped into the PDF — requires value). All types are repeatable; isRequired defaults to true and signatures are always required.

Create a Multi-Signer Document

Create a document that requires two or more signers.

Request

Content-Type: multipart/form-data

Signer Object

Example

curl -X POST https://ctsign.io/api/v1/documents/multi-signer \
  -H "Authorization: Bearer ctds_yourApiKey" \
  -F "WorkflowType=sequential" \
  -F 'Signers=[{"SignerName":"Alice","SignerEmail":"alice@acme.com","SignOrder":1},{"SignerName":"Bob","SignerEmail":"bob@acme.com","SignOrder":2}]' \
  -F "File=@agreement.pdf"

Response (200 OK)

{
  "documentId": 43,
  "workflowType": "sequential",
  "placementUrl": "https://ctsign.io/sign/place/abc...",
  "signers": [
    {
      "signerId": 1,
      "signerName": "Alice",
      "signerEmail": "alice@acme.com",
      "signOrder": 1,
      "status": "pending",
      "signingUrl": "https://ctsign.io/sign/document/token_alice..."
    },
    {
      "signerId": 2,
      "signerName": "Bob",
      "signerEmail": "bob@acme.com",
      "signOrder": 2,
      "status": "pending",
      "signingUrl": "https://ctsign.io/sign/document/token_bob..."
    }
  ]
}

Where Signer Replies Go

Signers reply to signing emails — with questions, corrections, or "is this legitimate?". By default those replies reach ctSignature's own notification mailbox, which is almost never who the signer meant to write to.

ReplyToEmail sets the Reply-To header on every signer-facing email for that document: the signing request, the daily reminders, the next-signer notice, and the verification-code email. Point it at whoever should field the signer's question.

curl -X POST https://ctsign.io/api/v1/documents \
  -H "Authorization: Bearer ctds_yourApiKey" \
  -F "RecipientName=John Smith" \
  -F "RecipientEmail=john@example.com" \
  -F "ReplyToEmail=casemanager@youragency.com" \
  -F "File=@contract.pdf"

Binding. A plain string form field on multipart requests (ReplyToEmail=...), a plain string property on the JSON template endpoints ("replyToEmail": "..."). Not indexed, not JSON-encoded, and one value per document — it covers every signer on a multi-signer document. Invalid addresses are rejected with 400.

Resolution order

When ReplyToEmail is omitted, the first match wins:

1. ReplyToEmail on the document
2. the email of the signed-in user who created it (dashboard sends)
3. the tenant-wide Reply-To Address (Dashboard → Branding, or replyToEmail on the partner tenant API)
4. the platform default — replies come back to ctSignature

Reminders, the next-signer notice and the OTP email are always ctSignature’s, so ReplyToEmail always covers those. The invite is the one that varies — see Who Emails the Signer.

Who Emails the Signer Their Invite

Historically this depended on whether a placement step happened, which is not obvious from the outside:

SendInvite overrides all of that:

curl -X POST https://ctsign.io/api/v1/documents \
  -H "Authorization: Bearer ctds_yourApiKey" \
  -F "RecipientName=Sarah Johnson" \
  -F "RecipientEmail=sarah@example.com" \
  -F "ReplyToEmail=casemanager@youragency.com" \
  -F 'FieldsJson=[{"type":"signature","x":100,"y":620,"width":150,"height":32,"page":1}]' \
  -F "SendInvite=true" \
  -F "File=@contract.pdf"

Binding matches ReplyToEmail: plain form field on multipart, "sendInvite": true on the JSON template endpoints. It is stored on the document, so it still applies when the invite is sent later at placement time.

Owner-facing notifications — "document signed", "all signatures complete", "signing link expired", "reminder sent" — are unaffected. They already arrive with you, so their replies stay with ctSignature.

List Documents

Query Parameters

Response (200)

{
  "items": [
    {
      "id": 42,
      "originalFilename": "contract.pdf",
      "recipientName": "John Smith",
      "recipientEmail": "john@example.com",
      "status": "signed",
      "expirationDate": "2026-05-19T10:00:00Z",
      "createdDate": "2026-05-17T10:00:00Z",
      "signedDate": "2026-05-17T14:30:00Z",
      "isExpired": false,
      "hasPlacement": true
    }
  ],
  "page": 1,
  "pageSize": 20,
  "totalCount": 1,
  "hasMore": false
}

Get Document Details

Returns the document’s status, signer audit entries, and any required-initials field placements.

Response (200)

{
  "id": 42,
  "originalFilename": "contract.pdf",
  "recipientName": "John Smith",
  "recipientEmail": "john@example.com",
  "status": "signed",
  "workflowType": "single",
  "expirationDate": "2026-05-19T10:00:00Z",
  "createdDate": "2026-05-17T10:00:00Z",
  "modifiedDate": "2026-05-17T14:30:00Z",
  "signedDate": "2026-05-17T14:30:00Z",
  "isExpired": false,
  "hasPlacement": true,
  "signedPdfHash": "a1b2c3d4e5f6...",
  "sourceFileNames": ["ISP.pdf", "Goods Form.pdf"],
  "placementUrl": null,
  "signingUrl": null,
  "verifiedBadgeApplied": true,
  "initialsFields": [
    { "id": 1, "x": 450, "y": 700, "width": 60, "height": 30, "page": 2, "isRequired": true }
  ],
  "signatures": [
    {
      "id": 10,
      "signerName": "John Smith",
      "signerEmail": "john@example.com",
      "signatureFont": "Dancing Script",
      "ipAddress": "203.0.113.42",
      "platform": "Windows",
      "timezone": "America/New_York",
      "signatureHash": "a1b2c3d4e5f6...",
      "createdDate": "2026-05-17T14:30:00Z"
    }
  ],
  "signers": []
}

Each signature row names the signer who produced it (signerName / signerEmail). For multi-signer documents the response also carries a signers array — the same per-signer progress entries returned by the signers endpoint below; it is empty for single-signer documents, whose document-level status already tells the whole story.

Check Document Status

A lightweight endpoint to check the current status of a document and its signers.

Document Status Values

Expiration is not a stored status. To detect expired documents, check isExpired on the response, or pass ?status=expired to the list endpoint as a convenience filter.

Check Signer Status

The signing-progress view of one document: who has signed (and when), whose turn it is right now, and who is still waiting to be emailed. Single-signer documents return one synthesized entry for the recipient, so you can render every document the same way.

Response (200 OK)

{
  "documentId": 43,
  "workflowType": "sequential",
  "status": "partially_signed",
  "isExpired": false,
  "signedCount": 1,
  "totalSigners": 2,
  "signers": [
    {
      "signerId": 1,
      "name": "Alice",
      "email": "alice@acme.com",
      "role": "Manager",
      "signOrder": 1,
      "status": "signed",
      "signedDate": "2026-05-17T14:30:00Z",
      "isNext": false
    },
    {
      "signerId": 2,
      "name": "Bob",
      "email": "bob@acme.com",
      "role": null,
      "signOrder": 2,
      "status": "sent",
      "signedDate": null,
      "isNext": true
    }
  ]
}

• status per signer is pending (not yet emailed), sent (their signing link is out), or signed.
• isNext is true for every signer who can sign right now: in a sequential workflow that is only the next unsigned signer in the chain; in a parallel workflow it is every unsigned signer. Always false once the document is signed or voided.
• For a single-signer document, signers contains one entry with signerId: null built from the document's recipient.

Resend / Renew a Document

Get a working signing link back for a document that was sent but not yet signed — or whose link has already expired (still unsigned). The v1 API is URL-based (it never emails), so resend hands you a link to redeliver rather than sending mail.

• If the existing link is still valid, it is returned unchanged.
• If the link has expired — or the hourly cleanup job already scrubbed the token — the deadline is extended by the tenant's TokenExpirationHours (default 72h) and any missing token is regenerated. The same document is reused (documentId and publicId are unchanged); the response field renewed: true signals this happened, and the old URL stops working.

No request body is required. Returns 400 if the document is already signed, or if a single-signer document's fields were never placed; 404 if not found. For multi-signer documents the response lists the actionable pending signers (the next signer for sequential, all pending signers for parallel) each with a fresh signingUrl.

Void a Document

Retract a document that hasn’t fully signed — the first half of a correct-and-reissue loop. Optional JSON body: { "reason": "..." } (max 500 chars; recorded in the audit trail and webhook).

• Allowed while pending, sent or partially_signed — even after some signers have signed. Refused (400) once every signer has signed.
• Every outstanding signing link dies immediately. A signer clicking a stale link sees an explicit “document was voided — check for a newer signing email” page (HTTP 410, code: "document_voided").
• Emits a document.voided webhook and audit event. The document stays visible with status: "voided" — void is not delete; the trail is evidence.
• To reissue: fix the content and create/send a new document. resend and embedded-session refuse voided documents.

Delete a Document

Delete a pending document. Signed documents cannot be deleted through the API — that rule is deliberate and permanent. To get a signed document out of your lists (test runs, stale records), use archive instead.

Archive a Document

Hide a document from default lists without touching the record — the sanctioned way to declutter signed documents, which can never be deleted or voided. Typical use: integration-test documents that completed for real but have no business value.

• Any status can be archived. Nothing else changes: the record, its files, its signing links, its publicId verification, and its audit trail all keep working exactly as before. Archive is not void and not delete.
• Archived documents disappear from GET /api/v1/documents (and the dashboard list and stats) unless includeArchived=true is passed. All by-id endpoints (/documents/{id}, /download, /separate-files, …) ignore archive entirely.
• Fully reversible: unarchive puts the document back. Both calls are idempotent and return 200; archiving an already-archived document does not reset its archivedAt.
• Recorded in the audit trail as document.archived / document.unarchived. No webhook is emitted — archive is a list-level preference, not a document lifecycle change.

// Response (200)
{
  "message": "Document archived",
  "documentId": 42,
  "archivedAt": "2026-08-27T17:30:00Z"
}

Download Signed PDF

Downloads the fully signed PDF with the Certificate of Completion appended, once the document status is signed (404 with "Signed document not available yet" before that). The returned bytes are the verification artifact: their SHA-256 matches signedPdfHash from the detail endpoint. The download is logged in the audit trail.

Alternative routes for other callers:

Download as Separate Files

For a signed document that was created from two or more uploaded files (multipart files on create), returns a ZIP containing each original file as its own signed PDF — cut along the page boundaries recorded when the files were merged — plus the Certificate of Completion pages as a separate Certificate of Completion.pdf. Signature and field content is flattened onto the pages at signing time, so every split file is a complete signed document.

• The detail endpoint's sourceFileNames array tells you up front which files the ZIP will contain. An empty array means the document was sent as a single file (or predates per-file tracking) and this endpoint returns 400.
• The split files are on-demand convenience copies. The combined signed PDF from /download and its signedPdfHash remain the sole verification artifacts — split files do not carry their own hash.
• Content type is application/zip; the download is logged in the audit trail as separate_files.downloaded.

Verify a Signed Document

ctSignature provides a public verification system. Anyone with the document's public ID can verify its authenticity.

Look Up Verification Info

// Response
{
  "documentId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "signed",
  "signedPdfHash": "a1b2c3d4e5f6...",
  "signers": [
    { "name": "John Smith", "signedDate": "2026-04-17T14:30:00Z" }
  ]
}

Verify a File's Hash

Compute the SHA-256 hash of your PDF file and submit it to check whether it matches the original signed document.

POST /api/documents/verify/550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "hash": "a1b2c3d4e5f6..."
}

// Response
{
  "match": true,
  "documentId": "550e8400-e29b-41d4-a716-446655440000",
  "completedAt": "2026-04-17T14:30:00Z"
}

Embedded Signing Sessions

If your subscription includes embedded signing, you can host the signing experience inside your app using an iframe.

Step 1: Enable Embedded Signing

PUT /api/dashboard/embedded-signing
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "enabled": true,
  "allowedDomains": ["https://app.yourdomain.com"]
}

Step 2: Create an Embedded Session

// Response
{
  "signingUrl": "https://ctsign.io/sign/document/xyz...?embed=true",
  "expiresAt": "2026-04-17T11:00:00Z"
}

Step 3: Embed in Your Page

<iframe
  src="https://ctsign.io/sign/document/xyz...?embed=true"
  width="100%"
  height="800"
  frameborder="0"
></iframe>

<script>
  window.addEventListener('message', function(event) {
    // Verify origin matches your ctSignature domain
    if (event.origin !== 'https://ctsign.io') return;

    if (event.data.type === 'ctSignature:signed') {
      console.log('Document signed!', event.data.documentId, event.data.signedPdfUrl);
      // Close the modal, refresh your record, etc.
    }
    if (event.data.type === 'ctSignature:error') {
      console.warn('Signing error:', event.data.title, event.data.message);
    }
  });
</script>

The iframe posts ctSignature:ready when loaded, ctSignature:signed (with documentId and signedPdfUrl) on completion, and ctSignature:error on a blocking error.

Quick Sign (pre-authenticated users)

For signers already authenticated inside your application, append &quick=true to the embedded signing URL. The signature dialog opens immediately: the signer types their name, confirms intent, and every signature, printed-name and date field completes from that one entry. Only engaged when no field needs per-field input (a text or initials field falls back to the standard click-each flow). Use plain embed=true for a signer who should review the document before signing.

Partners can additionally attest that their application obtains ESIGN/UETA consent from its own users (hostManagedConsent on the Partner API’s embedded-signing endpoint) — signers on host-delivered documents then skip the consent disclosure entirely, and each signature’s audit trail records consent as host-asserted. Email-delivered signers always see the disclosure.

Section 4

Templates API

Templates let you upload a PDF or Word document once, position the signature fields, and then reuse it for many recipients without re-uploading or re-placing fields each time. Word files are converted to PDF on upload.

Create a Template

You can also create a template from an existing signed document:

Requires a JSON body with the new template’s name (and optional description). The original (unsigned) PDF and all field placements are copied into a new template.

{
  "name": "Standard NDA",
  "description": "Copied from doc 42"
}

Other Template Endpoints

Multi-Signer Templates

A template can require signatures from two or more parties. The template stores roles — “Client”, “Contractor”, “Witness” — not people. Each role gets its own signature, initials, date and text fields on the PDF; the actual names and email addresses are supplied at send time, along with whether the routing is sequential or parallel.

Send 2–10 roles, or an empty list to turn the template back into a single-signer one. This call replaces the whole role list: omit a role’s id to create it, include the id to keep it, and leave a role out to delete it (its placed fields go with it).

PUT /api/v1/templates/5/signers
Authorization: Bearer ctds_yourApiKey
Content-Type: application/json

{
  "signers": [
    { "roleName": "Client", "signOrder": 1 },
    { "roleName": "Contractor", "signOrder": 2 }
  ],
  "defaultWorkflowType": "sequential"
}

After defining roles, place each role’s fields. PUT /api/v1/templates/{id}/placement takes a per-role payload instead of a flat fields list; signerId is the role’s id. Every role needs at least one signature field, and sender_text boxes belong to documentFields because they are typed once by the sender, not by any signer.

PUT /api/v1/templates/5/placement

{
  "signers": [
    { "signerId": 11, "fields": [ { "type": "signature", "x": 100, "y": 620, "width": 150, "height": 32, "page": 1 } ] },
    { "signerId": 12, "fields": [ { "type": "signature", "x": 340, "y": 620, "width": 150, "height": 32, "page": 1 } ] }
  ],
  "documentFields": [
    { "type": "sender_text", "x": 100, "y": 700, "width": 220, "height": 30, "page": 1, "value": "Contract #4471" }
  ]
}

Anchored Fields (Mail-Merge Forms)

Fixed coordinates assume the form never moves. A mail-merged form does move: the amount of content above a signature line changes per document, so the line drifts down the page — sometimes onto the next page. An anchored field is positioned by finding text in each sent document instead: put an invisible marker (white ~8pt text such as [[ctsig:sc:sign]]) in your source document where the field belongs, and the field is placed wherever that marker lands in every render.

Set anchors in the dashboard template editor (Anchor panel) or in the placement payload — each field object accepts:

Anchors resolve once, at send time, against that document’s text layer. A marker that can’t be found fails the send with HTTP 400 naming the field and marker — nothing is created or billed. Scanned (image-only) PDFs cannot be anchored: they have no text to search.

Send Your Own PDF Through a Template

Send from a Template copies the template’s stored PDF — right when the document never changes. When your application generates a different PDF every time (a mail merge), use this endpoint instead: the template contributes the roles and field definitions (usually anchored), and the document travels with the request. Multipart form-data; requires a multi-role template.

ExpirationHours, RemindersEnabled, NotificationEmail and ReplyToEmail work as on other create endpoints. The response matches Send from a Template: documentId plus a signingUrl per signer.

Send from a Template

Creates a new document from the template with pre-placed fields and sends the signing link directly. No placement step needed. notificationEmail and replyToEmail (see Where Signer Replies Go) are accepted here and on batch send; on a batch, one replyToEmail applies to every document in the call.

POST /api/v1/templates/5/send
Authorization: Bearer ctds_yourApiKey
Content-Type: application/json

{
  "recipientName": "Sarah Johnson",
  "recipientEmail": "sarah@example.com",
  "expirationHours": 48,
  "replyToEmail": "casemanager@youragency.com"
}

// Response
{
  "documentId": 44,
  "signingUrl": "https://ctsign.io/sign/document/xyz...",
  "templateId": 5,
  "skippedPlacement": true
}

Sending a multi-signer template

When the template has roles, send a signers array instead of recipientName/recipientEmail, with one entry per role, plus the workflowType:

• "sequential" — one at a time. Only the first signer is emailed now; each later signer is emailed automatically as the one before them finishes. signOrder sets the running order and overrides the role’s template default.
• "parallel" — everyone is emailed immediately and can sign in any order. signOrder is ignored.

POST /api/v1/templates/5/send

{
  "workflowType": "sequential",
  "signers": [
    { "templateSignerId": 11, "signerName": "Sarah Johnson", "signerEmail": "sarah@example.com", "signOrder": 1 },
    { "templateSignerId": 12, "signerName": "Dan Reyes", "signerEmail": "dan@contractor.com", "signOrder": 2 }
  ]
}

// Response
{
  "documentId": 44,
  "workflowType": "sequential",
  "templateId": 5,
  "templateName": "Consulting Agreement",
  "signers": [
    { "signerId": 88, "roleName": "Client", "signerName": "Sarah Johnson",
      "signerEmail": "sarah@example.com", "signOrder": 1,
      "signingUrl": "https://ctsign.io/sign/document/abc...", "notified": true },
    { "signerId": 89, "roleName": "Contractor", "signerName": "Dan Reyes",
      "signerEmail": "dan@contractor.com", "signOrder": 2,
      "signingUrl": "https://ctsign.io/sign/document/def...", "notified": false }
  ]
}

Batch Send

Send a template to up to 100 recipients in a single call. One document is created per recipient.

POST /api/v1/templates/5/batch-send
Authorization: Bearer ctds_yourApiKey
Content-Type: application/json

{
  "recipients": [
    { "name": "Alice Brown", "email": "alice@acme.com" },
    { "name": "Bob Green", "email": "bob@acme.com" },
    { "name": "Carol White", "email": "carol@acme.com" }
  ]
}

// Response
{
  "templateId": 5,
  "totalSent": 3,
  "documents": [
    { "documentId": 45, "recipientEmail": "alice@acme.com", "signingUrl": "..." },
    { "documentId": 46, "recipientEmail": "bob@acme.com", "signingUrl": "..." },
    { "documentId": 47, "recipientEmail": "carol@acme.com", "signingUrl": "..." }
  ]
}

Batch sending a multi-signer template

Send signerSets instead of recipients — one entry per document, each filling every role. workflowType applies to all documents in the batch. Up to 100 documents per call. Every set is validated before anything is created, so a bad row fails the whole call rather than leaving a half-sent batch.

POST /api/v1/templates/5/batch-send

{
  "workflowType": "parallel",
  "signerSets": [
    { "signers": [
        { "templateSignerId": 11, "signerName": "Alice Brown", "signerEmail": "alice@acme.com" },
        { "templateSignerId": 12, "signerName": "Dan Reyes", "signerEmail": "dan@contractor.com" }
    ]},
    { "signers": [
        { "templateSignerId": 11, "signerName": "Bob Green", "signerEmail": "bob@acme.com" },
        { "templateSignerId": 12, "signerName": "Dan Reyes", "signerEmail": "dan@contractor.com" }
    ]}
  ]
}

Section 5

Recipients API (Address Book)

Save frequently-used signers so you don't have to re-enter their info each time. Recipients are automatically added when you create multi-signer documents from the dashboard.

Create Recipient

POST /api/v1/recipients
Authorization: Bearer ctds_yourApiKey
Content-Type: application/json

{
  "name": "John Smith",
  "email": "john@example.com",
  "company": "Example Inc",
  "role": "VP of Sales",
  "phone": "+1-555-123-4567",
  "notes": "Prefers signing on mobile"
}

// Response
{
  "id": 1,
  "name": "John Smith",
  "email": "john@example.com",
  "company": "Example Inc",
  "role": "VP of Sales",
  "phone": "+1-555-123-4567",
  "notes": "Prefers signing on mobile",
  "isActive": true,
  "createdDate": "2026-04-17T10:00:00Z"
}

Section 6

Webhooks

Webhooks let your application receive real-time notifications when events happen in ctSignature — like when a document is signed, viewed, or completed.

Setting Up Webhooks

POST /api/v1/webhooks
Authorization: Bearer ctds_yourApiKey
Content-Type: application/json

{
  "url": "https://yourapp.com/webhooks/ctsignature",
  "events": ["document.completed", "signer.signed"],
  "description": "Production webhook"
}

// Response
{
  "id": 1,
  "url": "https://yourapp.com/webhooks/ctsignature",
  "events": ["document.completed", "signer.signed"],
  "secret": "a1b2c3d4e5f6...64-hex-chars...",    // shown only once!
  "isActive": true,
  "createdDate": "2026-04-17T10:00:00Z"
}

In production, the URL must use HTTPS.

Event Types

Subscribe to any combination of these events. If you don't specify events, you receive all webhook-emitting events.

Payload Format

Webhooks are sent as HTTP POST requests with a JSON body:

{
  "id": "whd_123",
  "timestamp": "2026-05-17T14:30:00Z",
  "event": "signer.signed",
  "data": {
    "documentId": 42,
    "publicId": "550e8400-e29b-41d4-a716-446655440000",
    "filename": "contract.pdf",
    "signerName": "John Smith",
    "signerEmail": "john@example.com",
    "signedAt": "2026-05-17T14:30:00Z"
  }
}

Headers Sent

Verifying Webhook Signatures

Always verify the X-Signature header before processing a webhook.

How it works

1. Read the raw request body as a UTF-8 string (do not re-serialize the JSON — whitespace matters).
2. Read the X-Timestamp header.
3. Build the signing string: {timestamp}.{rawBody} (timestamp, a literal dot, then the body).
4. Compute HMAC-SHA256 using your webhook secret. The secret is a 64-character hex string; decode it to bytes with hex-decoding before using it as the HMAC key.
5. Hex-encode the result (lowercase) and compare to X-Signature using a constant-time comparison.
6. Reject the request if the timestamp is more than a few minutes old to prevent replay.

Node.js Example

const crypto = require('crypto');

// Use express.raw({ type: 'application/json' }) so req.body is a Buffer.
function verifyWebhook(req, secret) {
  const rawBody = req.body.toString('utf8');
  const timestamp = req.headers['x-timestamp'];
  const signature = req.headers['x-signature'];
  if (!timestamp || !signature) return false;

  const expected = crypto
    .createHmac('sha256', Buffer.from(secret, 'hex'))
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(signature, 'hex');
  const b = Buffer.from(expected, 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Python Example

import hmac, hashlib

def verify_webhook(raw_body: bytes, secret: str, timestamp: str, signature: str) -> bool:
    signing_input = f"{timestamp}.".encode('utf-8') + raw_body
    expected = hmac.new(
        bytes.fromhex(secret),
        signing_input,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature.lower())

C# Example

using System.Security.Cryptography;
using System.Text;

bool VerifyWebhook(string rawBody, string secret, string timestamp, string signature)
{
    var key = Convert.FromHexString(secret);
    using var hmac = new HMACSHA256(key);
    var input = Encoding.UTF8.GetBytes($"{timestamp}.{rawBody}");
    var expected = Convert.ToHexString(hmac.ComputeHash(input)).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(expected),
        Encoding.UTF8.GetBytes(signature.ToLowerInvariant())
    );
}

Retries & Deliveries

Each event is queued and picked up by a background dispatcher that polls every ~15 seconds. If your endpoint returns a non-2xx status code (or times out after 10 seconds), ctSignature retries with the following backoff:

After 5 failed attempts the delivery is marked as exhausted. You can view delivery history from the dashboard:

limit is clamped to 1–100 (default 25).

To test your webhook endpoint without creating a real document:

Section 7

Signing Workflow

Single-Signer Flow

This is the complete lifecycle of a single-signer document:

Multi-Signer Flow

Sequential Workflow

1. Create multi-signer document with workflowType: "sequential"
2. Place fields for all signers on the placement page
3. Signer 1 receives an email. They sign.
4. Only after Signer 1 completes does Signer 2 receive their email
5. This continues through all signers in order
6. When the last signer signs, the document status becomes signed

Parallel Workflow

1. Create multi-signer document with workflowType: "parallel"
2. Place fields for all signers
3. All signers receive emails at the same time
4. Signers can sign in any order
5. When the last remaining signer completes, the document is fully signed

Consent & OTP Verification

These features are configured per-tenant in the dashboard settings.

Consent Disclosure

When enabled, signers must accept a legal disclosure before they can sign. This is required for ESIGN Act compliance.

• Modal mode: The disclosure appears as a popup on the signing page
• Page mode: The signer is taken to a full-page disclosure before seeing the document

You can publish custom disclosure text. Each change creates a new version so you have a record of which version each signer accepted.

OTP (One-Time Password)

When enabled, signers must verify their identity by entering a 6-digit code sent to their email before they can sign. This adds an extra layer of identity verification.

• OTP codes expire after 10 minutes
• Maximum 5 verification attempts per code
• Each new code invalidates any previous unverified codes

Section 8

Billing & Subscriptions

Free Trial

New accounts start with a free trial that includes 3 documents. All features are available during the trial.

Subscription Tiers

Returns available subscription plans with pricing and included features.

// Response
[
  {
    "id": 1,
    "name": "Starter",
    "monthlyPriceCents": 2999,
    "includedDocuments": 50,
    "overagePriceCents": 150,
    "featureFlags": { "webhooks": true, "templates": true }
  },
  {
    "id": 2,
    "name": "Professional",
    "monthlyPriceCents": 7999,
    "includedDocuments": 200,
    "overagePriceCents": 100,
    "featureFlags": { "webhooks": true, "templates": true, "embedding": true }
  }
]

Check Usage

// Response
{
  "documentsUsedThisCycle": 37,
  "includedDocuments": 50,
  "trialRemaining": 0,
  "billingPeriodStart": "2026-04-01T00:00:00Z",
  "billingPeriodEnd": "2026-04-30T23:59:59Z"
}

Upgrade / Manage Subscription

To start or change a subscription:

POST /api/billing/checkout
Authorization: Bearer <jwt-token>
Content-Type: application/json

{ "tierId": 2 }

// Response
{ "checkoutUrl": "https://checkout.stripe.com/pay/cs_..." }

Redirect the user to checkoutUrl to complete payment on Stripe.

To manage payment methods, view invoices, or cancel:

Returns a Stripe Customer Portal URL.

Section 9

Partner API (OEM Provisioning)

The Partner API lives at /api/platform/v1/*. A Partner is registered by a platform operator (see Admin → Partners on the platform admin console) and gets a distinct key type — ctps_live_… — that authorizes them to create, list, update, and disable tenants, plus mint API keys, configure webhooks, and enable embedded signing on behalf of those tenants.

Ownership is enforced by a nullable Tenant.PartnerId column:

• Tenants provisioned via the Partner API are tagged with the calling partner’s id.
• Tenants that sign up directly at ctsign.io have PartnerId = null and are invisible to every partner.
• A partner can only see / act on tenants where PartnerId matches them. 404s on cross-partner IDs do not distinguish “does not exist” from “owned by someone else.”

Partner Key Authentication

Partner keys follow the pattern ctps_<random-characters> (note: ctps_, not ctds_). They are sent on the Authorization header with the Bearer scheme:

Authorization: Bearer ctps_live_aB3cDeFgH1iJkLmN2oPqRsT3uVwXy

Where keys come from

A platform operator creates a Partner row and mints keys for it from the platform admin console:

1. Sign in to the platform admin at https://ctsign.io/dashboard/admin.html.
2. Open the Partners tab.
3. Click New Partner, enter name + contact email, save.
4. Click Keys on the partner’s row, enter a label (e.g. Production), click Create Key.
5. Copy the ctps_live_… value — it is shown once.

Hand the key to the partner via a secure channel; they store it as an environment variable (e.g. CTSIGN_PARTNER_KEY) and use it server-side.

One-Call Tenant Onboarding

The headline endpoint is POST /api/platform/v1/tenants. A single call can provision the local tenant, provision the matching org in ctOneAuth, mint a tenant API key, register a webhook, and enable iframe embedding — replacing the entire ctsign.io sign-up + password-setup + key-copy flow.

POST /api/platform/v1/tenants
Authorization: Bearer ctps_live_aB3cDeFgH1iJkLmN2oPqRsT3uVwXy
Content-Type: application/json

{
  "companyName": "Smart of South Jersey, LLC",
  "adminName":   "Gary Coslop",
  "adminEmail":  "gary@smartsouthjersey.com",
  "mintApiKey":  true,
  "replyToEmail": "documents@smartsouthjersey.com",
  "webhook": {
    "url":    "https://pnbv5.cozzitech.com/webhooks/ctsign",
    "events": ["document.completed", "signer.signed"]
  },
  "embeddedSigning": {
    "enabled":        true,
    "allowedDomains": ["https://pnbv5.cozzitech.com"]
  }
}

// Response — everything shown once is shown ONCE.
{
  "tenantId":   123,
  "companyName": "Smart of South Jersey, LLC",
  "admin": {
    "userId": 456,
    "name":   "Gary Coslop",
    "email":  "gary@smartsouthjersey.com"
  },
  "setupUrl":           "https://auth.cozzitech.com/identity-ui/setup/<one-time-token>",
  "linkedExistingUser": false,
  "apiKey":             "ctds_live_aBcDeFg...",         // shown ONCE
  "webhook": {
    "id":     7,
    "url":    "https://pnbv5.cozzitech.com/webhooks/ctsign",
    "secret": "a1b2c3...64-hex-chars...",                // shown ONCE
    "events": ["document.completed", "signer.signed"]
  },
  "embeddedSigningEnabled": true,
  "createdDate":            "2026-06-09T19:01:23Z"
}

What to do with each field of the response:

• tenantId — persist on your side; use it to scope every subsequent partner-API call (/tenants/{tenantId}/...).
• apiKey — this is a ctds_live_ tenant key. Store it securely. You can now call the tenant API (/api/v1/documents, etc.) on the tenant’s behalf without ever asking the human admin to sign in.
• setupUrl — the IdP password-setup URL. Forward it to the admin verbatim (email, deep link from your UI, whatever you like). Do not append query parameters — the URL is signed.
• webhook.secret — the HMAC signing secret. Store it; use it to verify inbound webhook signatures (see Section 6.4).
• linkedExistingUser — when true, the admin email already existed in ctOneAuth and was linked to the new tenant instead of being issued a fresh password-setup link. In this case setupUrl is null — the admin can already sign in.

Endpoint Reference

Every endpoint is scoped to Tenant.PartnerId == <calling partner>. All paths are prefixed with /api/platform/v1.

Tenants

Users

API Keys (on the tenant’s behalf)

Webhooks

Embedded Signing

Gotchas

• One-shot secrets. apiKey (from a tenant key mint) and webhook.secret (from webhook creation) are returned once at creation. There is no recovery endpoint — revoke and re-mint if lost.
• Soft-disable, not hard-delete. DELETE /tenants/{id} sets IsActive=false. We deliberately do not hard-delete: that would orphan signed PDFs and the audit trail. There is no “undelete”; just PUT with { "isActive": true } to re-enable.
• Partner-scoped duplicate guard. POST /tenants returns 409 if the same admin email and the same company name already exists under this partner. Different company name (or different partner) is allowed.
• 404 vs 403. Any tenant-path call where tenantId belongs to a different partner returns 404 (not 403). This is intentional — we don’t want partners to discover the existence of other partners’ tenants by ID enumeration.
• Welcome email is suppressed. Tenants created via the Partner API do NOT trigger the standard ctsign.io welcome email — the partner is expected to deliver any onboarding messaging themselves.
• Set replyToEmail at provision time. Documents a tenant later creates with its API key have no signed-in user, so signer replies fall through to ctSignature unless the tenant-wide default is set. See Where Signer Replies Go.

Section 10

Dashboard Guide

The web dashboard gives tenant admins and users a visual interface for managing documents, templates, users, settings, and billing.

Documents

The Documents section lets you:

• Create documents — upload a PDF or select a template, enter recipient info
• Create multi-signer documents — add multiple signers with roles and ordering
• Track status — see pending, sent, signed, and expired documents
• Resend emails — re-send signing request emails to recipients
• Download signed PDFs — download the completed document with certificate
• View audit trail — see who signed, when, from where, and with what device

Dashboard Document Creation Endpoint

Same as the API v1 endpoint, but also supports creating documents from templates (when a template has pre-placed fields, it skips the placement step and sends immediately).

Stats Overview

Returns real-time document counts by status and trial information.

Templates

Templates are managed through the same API endpoints described in Section 4. From the dashboard, you can:

• Upload new templates
• Create templates from previously signed documents
• Send individual or batch documents from templates
• Edit template names and descriptions
• Deactivate templates you no longer need

User Management

Tenant admins can invite team members and control their access.

User Roles

User Management Endpoints

Settings & Branding

Account Settings

Update company name, contact email, or password.

Consent Settings

Read the current consent configuration:

Updates use separate sub-paths:

Branding

replyToEmail is the tenant-wide default Reply-To for signer emails (Branding page → Signer Replies) — see Where Signer Replies Go. Send "" to clear it; omit the field to leave it unchanged.

Document Retention

Set how long signed documents are kept before automatic deletion. Range: 30 to 36,500 days (default: 2,555 days / ~7 years).

Embedded Signing Settings

Enable or disable iframe-based embedded signing and set allowed domains.

Analytics

Returns daily document creation and signing counts for charting. Supports 7, 30, 60, and 90 day windows.

Returns aggregate statistics: total documents, completion rate, average time to sign, and template usage count.

Section 11

Configuration Reference

ctSignature is configured through appsettings.json (and environment-specific overrides). Below are all the settings you need to know.

Database

"ConnectionStrings": {
  "DefaultConnection": "Server=localhost;Database=ctDocSign;User=ctdocsign;Password=YOUR_PASSWORD;Port=3306;"
}

Requires MySQL 8.0 or later. Entity Framework Core handles migrations automatically.

JWT Settings

Stripe Settings

Platform Admin

Document Storage & Security

Testing & Development

Email Providers

Email delivery is configured at runtime by a platform admin through the Platform Admin UI — not via environment variables. The platform admin sets one of the following system settings:

Self-hosted deployments configure these through /admin-panel/ after the first platform-admin login.

Rate Limits

Section 12

Error Handling

All errors return a JSON object with an error field containing a human-readable message.

// Example error response
{
  "error": "Document not found"
}

HTTP Status Codes

Common Error Scenarios

Authentication Errors

// Missing API key
401: { "error": "Authorization header is required" }

// Invalid API key
401: { "error": "Invalid API key" }

// Expired JWT
401: { "error": "Token has expired" }

Document Errors

// File too large
400: { "error": "File size exceeds the maximum allowed (10 MB)" }

// Unsupported file type
400: { "error": "Only PDF, DOC, and DOCX files are accepted" }

// Word file could not be converted
400: { "error": "contract.docx: The Word document could not be converted to PDF. Ensure it is a valid, unencrypted document." }

// Trying to delete a signed document
400: { "error": "Signed documents cannot be deleted" }

// Trial expired
402: { "error": "Trial document limit reached. Please upgrade." }

Signing Errors

// Token expired
400: { "error": "This signing link has expired" }

// Consent not given
400: { "error": "Consent must be given before signing" }

// OTP not verified
400: { "error": "OTP verification is required before signing" }

// Sequential order violation
400: { "error": "Previous signer has not yet signed" }

// Too many OTP attempts
400: { "error": "TooManyAttempts" }

Section 13

Security & Compliance

Data Security

• Passwords — hashed with BCrypt (tenant passwords, user passwords, API keys)
• Tokens — compared using timing-safe operations to prevent timing attacks
• File storage — path traversal protection on all file access
• Tenant isolation — every query is scoped to the authenticated tenant; no cross-tenant data access is possible
• Rate limiting — prevents brute-force and abuse

ESIGN Act & UETA Compliance

ctSignature includes the following features to support ESIGN Act and UETA compliance:

Certificate of Completion

Every signed document has a Certificate of Completion automatically appended as the last page. It includes:

• Document public ID (for verification lookup)
• Original filename
• List of all signers with their signed dates
• SHA-256 hash of the signed document
• Audit trail summary

Document Verification

Anyone can verify a signed document's authenticity using the public verification endpoint:

// Look up by public ID (printed on the certificate)
GET /api/documents/verify/{publicId}

// Or verify a specific file's hash
POST /api/documents/verify/{publicId}
{ "hash": "sha256-hex-string-of-your-file" }

This does not require any authentication.

Security Best Practices for Integrators

Appendix

Quick Reference — All API Endpoints

Authentication

Documents (API v1)

Templates (API v1)

Recipients (API v1)

Webhooks

Billing

Signing Flow (Token-Based)

Dashboard