CT Signature

Section 1

Getting Started

Platform Overview

CT Signature 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)

Follow these steps to send your first document for signing:

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

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

POST /api/dashboard/api-keys
Authorization: Bearer <jwt-token>

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

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

GET /api/v1/documents/{documentId}
Authorization: Bearer ctds_aBcDeFgHiJkLm...

Section 2

Authentication

CT Signature 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

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

Register a New Account

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

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

// Response
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "tenant": {
    "id": 1,
    "companyName": "Acme Corp",
    "email": "jane@acme.com",
    "isTrial": true
  },
  "user": {
    "id": 1,
    "name": "Jane Developer",
    "role": "Admin"
  }
}

Log In to an Existing Account

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

{
  "email": "jane@acme.com",
  "password": "SecureP@ss123"
}

// Response — same shape as register

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 and specify who should sign it.

Request

Content-Type: multipart/form-data

Example

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

Response (201 Created)

{
  "documentId": 42,
  "placementUrl": "https://api.example.com/sign/place/abc123...",
  "signingUrl": "https://api.example.com/sign/document/xyz789...",
  "placementToken": "abc123...",
  "secureToken": "xyz789...",
  "expirationDate": "2026-04-19T10:00:00Z"
}

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://api.example.com/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 (201 Created)

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

List Documents

Query Parameters

Response (200)

{
  "items": [
    {
      "documentId": 42,
      "originalFilename": "contract.pdf",
      "recipientName": "John Smith",
      "recipientEmail": "john@example.com",
      "status": "signed",
      "createdDate": "2026-04-17T10:00:00Z",
      "signedDate": "2026-04-17T14:30:00Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "totalCount": 1,
  "totalPages": 1
}

Get Document Details

Returns full details including field placements, signer information, and audit signatures.

Response (200)

{
  "documentId": 42,
  "publicId": "550e8400-e29b-41d4-a716-446655440000",
  "originalFilename": "contract.pdf",
  "recipientName": "John Smith",
  "recipientEmail": "john@example.com",
  "status": "signed",
  "workflowType": "single",
  "expirationDate": "2026-04-19T10:00:00Z",
  "createdDate": "2026-04-17T10:00:00Z",
  "signedDate": "2026-04-17T14:30:00Z",
  "signedPdfHash": "a1b2c3d4e5f6...",
  "fieldPlacements": {
    "signatureField": { "x": 100, "y": 200, "width": 200, "height": 50, "page": 1 },
    "signerNameField": { "x": 100, "y": 260, "width": 200, "height": 30, "page": 1 },
    "dateTimeField": { "x": 100, "y": 300, "width": 150, "height": 25, "page": 1 }
  },
  "initialsFields": [
    { "id": 1, "x": 450, "y": 700, "width": 60, "height": 30, "page": 2, "isRequired": true }
  ],
  "signatures": [
    {
      "signatureText": "John Smith",
      "signatureFont": "Dancing Script",
      "ipAddress": "203.0.113.42",
      "platform": "Windows",
      "timezone": "America/New_York",
      "createdDate": "2026-04-17T14:30:00Z"
    }
  ]
}

Check Document Status

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

Document Status Values

Delete a Document

Delete a pending document. Signed documents cannot be deleted through the API.

Download Signed PDF

Downloads the fully signed PDF with the Certificate of Completion appended. The download is logged in the audit trail.

From the dashboard, use:

Verify a Signed Document

CT Signature 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://api.example.com/sign/document/xyz...?embed=true",
  "expiresAt": "2026-04-17T11:00:00Z"
}

Step 3: Embed in Your Page

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

<script>
  window.addEventListener('message', function(event) {
    // Verify origin matches your CT Signature domain
    if (event.origin !== 'https://api.example.com') return;

    if (event.data.type === 'signing-complete') {
      console.log('Document signed!', event.data.documentId);
      // Redirect user, show confirmation, etc.
    }
  });
</script>

Section 4

Templates API

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

Create a Template

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

This copies the original (unsigned) PDF and all field placements into a new template.

Other Template Endpoints

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.

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

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

// Response
{
  "documentId": 44,
  "signingUrl": "https://api.example.com/sign/document/xyz...",
  "templateId": 5,
  "skippedPlacement": true
}

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": "..." }
  ]
}

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 CT Signature — 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 of them.

Payload Format

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

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

Headers Sent

Verifying Webhook Signatures

Always verify the X-Signature header to make sure the request actually came from CT Signature.

How it works:

1. Read the raw request body (as bytes or a UTF-8 string)
2. Compute HMAC-SHA256 of the body using your webhook secret
3. Compare your computed signature to the X-Signature header value

Node.js Example

const crypto = require('crypto');

function verifyWebhook(req, secret) {
  const payload = JSON.stringify(req.body);
  const signature = req.headers['x-signature'];

  const expected = 'sha256=' +
    crypto.createHmac('sha256', Buffer.from(secret, 'hex'))
      .update(payload)
      .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Python Example

import hmac, hashlib

def verify_webhook(body: bytes, secret: str, signature: str) -> bool:
    expected = 'sha256=' + hmac.new(
        bytes.fromhex(secret),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

C# Example

using System.Security.Cryptography;

bool VerifyWebhook(string payload, string secret, string signature)
{
    var key = Convert.FromHexString(secret);
    using var hmac = new HMACSHA256(key);
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));
    var expected = "sha256=" + Convert.ToHexString(hash).ToLower();
    return CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(expected),
        Encoding.UTF8.GetBytes(signature)
    );
}

Retries & Deliveries

If your endpoint returns a non-2xx status code (or times out after 10 seconds), CT Signature retries delivery with exponential backoff:

After 5 failed attempts, the delivery is marked as failed. You can view delivery history:

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

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

Manage consent disclosure flow type (modal or page), publish custom disclosure text, and enable/disable OTP verification.

Branding

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 10

Configuration Reference

CT Signature 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

Set one of these environment variables to enable email delivery:

Rate Limits

Section 11

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)" }

// Not a PDF
400: { "error": "Only PDF files are accepted" }

// 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 12

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

CT Signature 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 (API v1)

Billing

Signing Flow (Token-Based)

Dashboard