eSign API Reference

The DocsAutomator eSign API enables programmatic management of signing sessions, retrieval of signing links, progress tracking, and audit trail access.

Authentication

All API endpoints require bearer token authentication:

Authorization: Bearer YOUR_API_KEY

Base URL

https://api.docsautomator.co/esign

Session Management

List Signing Sessions

/esign/sessions

Retrieve all signing sessions with optional filtering.

Query Parameters:

Parameter	Type	Required	Description
`status`	string	No	Filter by status
`page`	number	No	Page number (default: 1)
`limit`	number	No	Results per page (default: 20, max: 100)
`email`	string	No	Search by signer email

Valid Status Values: pending, awaiting_approval, in_progress, completed, expired, cancelled, declined A session that waits for approval has the status awaiting_approval and an approval summary: { "status", "rule", "approvers": [{ "name", "email", "decision" }] }.

curl -X GET "https://api.docsautomator.co/esign/sessions?status=pending&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "sessions": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0d1",
      "documentName": "Invoice #123",
      "status": "in_progress",
      "signingOrder": "sequential",
      "signers": [
        { "index": 1, "email": "alice@example.com", "name": "Alice", "status": "signed" },
        { "index": 2, "email": "bob@example.com", "name": "Bob", "status": "invited" }
      ],
      "webhookParams": { "recId": "recAbC123XyZ" },
      "expiresAt": "2026-05-20T10:00:00.000Z",
      "completedAt": null,
      "createdAt": "2026-04-20T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47,
    "pages": 3
  }
}

Get Session Details

/esign/sessions/:sessionId

Returns comprehensive session information including signer statuses, document hashes, e-sign fields with positions, and completion timestamps.

Per-signer fields include declinedAt and declineReason for any signer who declined. When the session status is declined, the response additionally includes top-level declinedAt, declinedBy (email, name, signerIndex), and declineReason so you can read refusal details without inspecting the signers array. closeType tells you how the session closes: signature (the default) or acceptance. An acceptance session has no esignFields. A recipient who accepted has the signer status signed, and the signer object carries typedName when the recipient typed their name before accepting. Both the list and the detail endpoints return closeType. Response:

{
  "id": "66f1a2b3c4d5e6f7a8b9c0d1",
  "documentName": "Invoice #123",
  "status": "completed",
  "closeType": "signature",
  "signingOrder": "sequential",
  "deliveryMethod": "email",
  "currentSignerIndex": 2,
  "originalPdfUrl": "https://files.docsautomator.co/f/...",
  "signedPdfUrl": "https://files.docsautomator.co/f/...",
  "originalDocumentHash": "sha256:...",
  "signedDocumentHash": "sha256:...",
  "esignFields": [
    {
      "fieldId": "signature_1",
      "type": "signature",
      "tagName": "{{esign.signature_1}}",
      "signerIndex": 1,
      "role": "buyer",
      "value": "data:image/png;base64,...",
      "signedAt": "2026-04-22T14:02:11.000Z",
      "signedBy": "alice@example.com"
    }
  ],
  "signers": [
    {
      "index": 1,
      "email": "alice@example.com",
      "name": "Alice",
      "role": "buyer",
      "status": "signed",
      "typedName": null,
      "accessToken": "a1b2c3...",
      "invitedAt": "2026-04-20T10:00:00.000Z",
      "inviteDelivery": {
        "kind": "invitation",
        "outcome": "accepted",
        "provider": "gmail",
        "fromAccount": "jane@acme.com",
        "to": "alice@example.com",
        "providerMessageId": "18f3a9c2b4d5e6f7",
        "providerThreadId": "18f3a9c2b4d5e6f7",
        "fallbackFrom": null,
        "fallbackReason": null,
        "error": null,
        "sentAt": "2026-04-20T10:00:00.000Z"
      },
      "openedAt": "2026-04-22T13:55:04.000Z",
      "signedAt": "2026-04-22T14:02:11.000Z",
      "declinedAt": null,
      "declineReason": null,
      "ipAddress": "203.0.113.42",
      "consentGivenAt": "2026-04-22T13:55:30.000Z",
      "timezone": "America/New_York",
      "geoLocation": { "country": "US", "region": "NY", "city": "New York" },
      "signingDurationSeconds": 427
    }
  ],
  "reminderEnabled": true,
  "reminderDays": 3,
  "reminderCount": 0,
  "lastReminderSent": null,
  "webhookParams": { "recId": "recAbC123XyZ" },
  "expiresAt": "2026-05-20T10:00:00.000Z",
  "completedAt": "2026-04-22T14:02:45.000Z",
  "createdAt": "2026-04-20T10:00:00.000Z"
}

webhookParams echoes the custom parameters from the original document creation request, plus the identifier of the triggering record, folded in automatically per data source: recId (Airtable, SmartSuite, Notion — pageId and Notion Button payloads are normalized to recId), taskId (ClickUp), or rowNumber (Google Sheets — positional at trigger time, so treat it as “which row triggered this”, not a durable key). Your own webhookParams keys are never overwritten by the folded identifier. Use it to correlate signing sessions with records in your data source — for example, when polling sessions periodically to reconcile signing status against your own records. It is null when no identifier or parameters were passed. When status is declined, the response also includes:

{
  "declinedAt": "2026-04-22T14:10:00.000Z",
  "declinedBy": {
    "email": "bob@example.com",
    "name": "Bob",
    "signerIndex": 2
  },
  "declineReason": "Terms need to be revised"
}

Get Signing Links

/esign/sessions/:sessionId/links

Retrieves signing links for all signers when using manual delivery mode.

Returns expiration dates and signer status for each link. While a session waits for internal approval (status: "awaiting_approval"), no signing links exist yet: signingLink is null for every signer. The links appear after approval. The same applies to the session details. Response:

{
  "success": true,
  "sessionId": "66f1a2b3c4d5e6f7a8b9c0d1",
  "documentName": "Invoice #123",
  "deliveryMethod": "manual",
  "status": "pending",
  "signers": [
    {
      "signerIndex": 1,
      "email": "alice@example.com",
      "name": "Alice",
      "signingLink": "https://app.docsautomator.co/sign/a1b2c3d4e5f6g7h8",
      "expiresAt": "2026-05-20T10:00:00.000Z",
      "status": "pending"
    }
  ]
}

Get Audit Trail

/esign/sessions/:sessionId/audit

Returns chronological event log for the signing session.

Event Types:

Event	Description
`session_created`	Signing session initiated
`invite_sent`	Email invitation dispatched
`invite_resent`	Invitation re-sent to signer
`link_opened`	Signer accessed signing link
`document_viewed`	Signer viewed PDF
`consent_given`	E-consent provided
`field_signed`	Field value entered
`field_cleared`	Field value cleared
`signer_completed`	All fields finished
`document_accepted`	Recipient clicked Accept on an acceptance session (`metadata.typedName` holds the typed name)
`signer_declined`	Signer declined to sign
`session_completed`	All signers done, PDF generated
`session_cancelled`	Session cancelled
`session_expired`	Session expired
`session_voided`	Session voided by admin
`reminder_sent`	Reminder email sent
`email_sent`	Completion, progress, decline or expiration email accepted by a provider
`email_send_failed`	Any e-sign email ended with outcome `failed` or `unknown`

invite_sent, invite_resent, reminder_sent, email_sent and email_send_failed carry the delivery record in metadata.delivery. See Email Delivery Outcomes. Response:

{
  "sessionId": "66f1a2b3c4d5e6f7a8b9c0d1",
  "events": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0e5",
      "eventType": "session_created",
      "actorType": "system",
      "actorEmail": null,
      "actorSignerIndex": null,
      "fieldId": null,
      "fieldType": null,
      "metadata": {
        "documentName": "Invoice #123",
        "signerCount": 2,
        "signingOrder": "sequential"
      },
      "ipAddress": null,
      "userAgent": null,
      "timestamp": "2026-04-20T10:00:00.000Z",
      "timezone": null,
      "geoLocation": null
    },
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0e6",
      "eventType": "field_signed",
      "actorType": "signer",
      "actorEmail": "alice@example.com",
      "actorSignerIndex": 1,
      "fieldId": "signature_1",
      "fieldType": "signature",
      "metadata": {},
      "ipAddress": "203.0.113.42",
      "userAgent": "Mozilla/5.0 ...",
      "timestamp": "2026-04-22T14:02:11.000Z",
      "timezone": "America/New_York",
      "geoLocation": { "country": "US", "region": "NY", "city": "New York" }
    }
  ],
  "reconstructed": false
}

reconstructed: true indicates that some events were inferred from the session document because the original audit events were missing (e.g., pruned from an older session).

Cancel Session

/esign/sessions/:sessionId/cancel

Cancel an active signing session.

Request body:

{
  "reason": "Optional cancellation reason"
}

Response:

{
  "success": true,
  "message": "Signing session has been cancelled"
}

Cannot cancel completed sessions.

Resend Invitation

/esign/sessions/:sessionId/resend/:signerIndex

Resends invitation email to a specific signer (indexed 1, 2, 3, etc.).

Response:

{
  "success": true,
  "message": "Invitation resent to alice@example.com"
}

Webhook Events

Event	When it fires
(no `event` field)	All signers completed — signed PDF ready
`esign.session_created`	Session created with `deliveryMethod: "manual"`
`esign.signer_signed`	An individual signer completed all their fields
`esign.session_declined`	A signer declined to sign
`esign.session_expired`	Session expired before all signers completed
`esign.email_sent`	An e-sign email was accepted by a mail provider
`esign.email_failed`	An e-sign email ended with outcome `failed` or `unknown`
`esign.approval_requested`	A session waits for internal approval; the approvers were asked
`esign.approval_approved`	The approval rule is met; the request goes out now
`esign.approval_rejected`	An approver rejected the document; the session is cancelled

See eSign overview — Webhook Integration for the full payload of each event. Acceptance sessions fire the same events with the same payload keys. closeType is "signature" or "acceptance" on every session event. On an acceptance session, esign.signer_signed fires when a recipient clicks Accept, and the signer entries carry two extra fields: typedName (the name the recipient typed, or null) and acceptedAt.

Session Created (Manual Delivery)

Triggered when signing session created with deliveryMethod: "manual". Use to retrieve and distribute signing links manually. With internal approval on, it fires after approval, when the links exist.

Session Completed

Triggered when all signers complete signing and final PDF is generated. Payload:

{
  "signedPdfUrl": "https://...",
  "sessionId": "unique-identifier",
  "documentName": "Document name",
  "closeType": "signature",
  "status": "completed",
  "completedAt": "ISO date string",
  "signers": [
    {
      "email": "signer@example.com",
      "name": "Signer Name",
      "signedAt": "ISO date string",
      "typedName": null,
      "acceptedAt": null
    }
  ],
  "fieldValues": { },
  "googleDriveFileId": "1aBcDeFgHiJkLmNoPqRsTuVwXyZ",
  "googleDriveUrl": "https://drive.google.com/file/d/1aBcDeFgHiJkLmNoPqRsTuVwXyZ/view",
  "googleDriveFolderId": "0BxAbCdEfGhIjKlMnOpQrStUvWx",
  "sourceData": { },
  "webhookParams": { },
  "additionalParams": { }
}

The googleDriveFileId, googleDriveUrl, and googleDriveFolderId fields are only present when “Save to Google Drive” is enabled in the Signed PDF Delivery settings.

Signer Signed

Fires once per signer as they complete, including the final signer. Use to track progress for multi-party documents.

{
  "event": "esign.signer_signed",
  "sessionId": "unique-identifier",
  "documentName": "Document name",
  "closeType": "signature",
  "status": "in_progress",
  "signer": {
    "email": "signer@example.com",
    "name": "Signer Name",
    "signerIndex": 1,
    "role": "buyer",
    "signedAt": "ISO date string",
    "typedName": null,
    "acceptedAt": null
  },
  "progress": {
    "completed": 1,
    "total": 2,
    "allSigned": false
  },
  "sourceData": { },
  "webhookParams": { },
  "additionalParams": { }
}

For the final signer, progress.allSigned is true but the session status is still in_progress. The separate Session Completed webhook fires afterwards, once the signed PDF is ready.

Session Expired

Fires when a signing session expires before all signers complete. An expiration email is also sent to workspace notification recipients.

{
  "event": "esign.session_expired",
  "sessionId": "unique-identifier",
  "documentName": "Document name",
  "closeType": "signature",
  "status": "expired",
  "expiredAt": "ISO date string",
  "expiresAt": "ISO date string",
  "pendingSigners": [
    {
      "email": "signer@example.com",
      "name": "Signer Name",
      "signerIndex": 2,
      "status": "invited"
    }
  ],
  "sourceData": { },
  "webhookParams": { },
  "additionalParams": { }
}

If a session is already declined, cancelled, or completed before its expiration time, this webhook does not fire.

Approval Events

Fire for automations with approval switched on. esign.approval_requested fires when the session is created and the approvers are asked:

{
  "event": "esign.approval_requested",
  "sessionId": "unique-identifier",
  "documentName": "Quote Q-1042",
  "closeType": "signature",
  "status": "awaiting_approval",
  "approval": {
    "status": "pending",
    "rule": "all",
    "requestedAt": "ISO date string",
    "requestedBy": { "email": "jonas@example.com", "name": "Jonas Weber" },
    "approvers": [
      { "email": "priya@example.com", "name": "Priya Nair", "decision": "pending", "decidedAt": null },
      { "email": "leo@example.com", "name": "Leo Rossi", "decision": "pending", "decidedAt": null }
    ]
  },
  "sourceData": { },
  "webhookParams": { },
  "additionalParams": { }
}

approval.requestedBy names the team member who created the document in the app. It is null when the document came from the API, a trigger or another integration, and its name is null when the email is not a team member. sourceData, webhookParams and additionalParams are included when set, as in the other e-sign events. esign.approval_approved fires once, when the approval completes the rule and the request goes out. status is pending, approval.status is approved, and approval.decidedBy names the approver whose decision completed the rule. When an owner or admin decided on behalf of an approver, decidedBy names the owner or admin and forApprover names the approver.

{
  "event": "esign.approval_approved",
  "sessionId": "unique-identifier",
  "documentName": "Quote Q-1042",
  "closeType": "signature",
  "status": "pending",
  "approval": {
    "status": "approved",
    "rule": "all",
    "requestedAt": "ISO date string",
    "requestedBy": { "email": "jonas@example.com", "name": "Jonas Weber" },
    "decidedAt": "ISO date string",
    "decidedBy": { "email": "leo@example.com", "name": "Leo Rossi", "forApprover": null },
    "approvers": [
      { "email": "priya@example.com", "name": "Priya Nair", "decision": "approved", "decidedAt": "ISO date string" },
      { "email": "leo@example.com", "name": "Leo Rossi", "decision": "approved", "decidedAt": "ISO date string" }
    ]
  },
  "sourceData": { },
  "webhookParams": { },
  "additionalParams": { }
}

esign.approval_rejected fires when an approver rejects the document. The session is cancelled, and approval.reason holds the reason the approver gave:

{
  "event": "esign.approval_rejected",
  "sessionId": "unique-identifier",
  "documentName": "Quote Q-1042",
  "closeType": "signature",
  "status": "cancelled",
  "approval": {
    "status": "rejected",
    "rule": "all",
    "requestedAt": "ISO date string",
    "requestedBy": { "email": "jonas@example.com", "name": "Jonas Weber" },
    "decidedAt": "ISO date string",
    "decidedBy": { "email": "priya@example.com", "name": "Priya Nair", "forApprover": null },
    "reason": "Discount too high, please use 10%.",
    "approvers": [
      { "email": "priya@example.com", "name": "Priya Nair", "decision": "rejected", "decidedAt": "ISO date string" },
      { "email": "leo@example.com", "name": "Leo Rossi", "decision": "pending", "decidedAt": null }
    ]
  },
  "sourceData": { },
  "webhookParams": { },
  "additionalParams": { }
}

An approval that does not complete the rule (for example the first of two approvals under “all must approve”) sends no webhook. An approval that expires fires the existing esign.session_expired event.

Passing Additional Parameters

Include webhookParams in document creation requests to receive custom data in webhook notifications:

{
  "docId": "your-automation-id",
  "data": { ... },
  "webhookParams": {
    "orderId": "ORD-12345",
    "customerId": "CUST-789"
  }
}

Parameters are returned in all webhook notifications under webhookParams, together with the automatically included trigger record identifier (recId, taskId, or rowNumber depending on the data source). An identical additionalParams key is also present — it exists only for legacy reasons, so use webhookParams in new integrations.

Status Reference

Session Statuses

Status	Description
`pending`	Awaiting signer action
`in_progress`	At least one signer started
`completed`	All signers finished
`expired`	Expired before completion
`awaiting_approval`	Waiting for internal approval; nothing went to the signers yet
`cancelled`	Cancelled by admin, or rejected by an approver (`approval.status: "rejected"`)
`declined`	Signer declined

Signer Statuses

Status	Description
`pending`	Invitation not sent
`invited`	Email sent
`opened`	Link opened
`signed`	All fields completed, or the document accepted
`declined`	Declined to sign or to accept

Acceptance Sessions

Sessions with closeType: "acceptance" use the same session and signer statuses. A recipient who clicked Accept has the signer status signed. The session is completed when every recipient has accepted. The audit trail records the click as a document_accepted event, with the typed name in metadata.typedName when the recipient typed one.

Error Responses

{
  "error": true,
  "message": "Description"
}

Code	Description
400	Bad request — invalid parameters
401	Unauthorized — invalid/missing API key
404	Not found — session doesn’t exist
429	Rate limited
500	Server error

Rate Limits

Rate limits apply to the public signing page routes (not the authenticated admin API endpoints):

Route	Limit
Signing page access	100 requests per 15 minutes per IP
Field submissions	30 requests per minute per IP

Code Examples

Node.js — List and Monitor Sessions

const axios = require('axios');

const API_KEY = 'your_api_key';
const BASE_URL = 'https://api.docsautomator.co/esign';

async function listPendingSessions() {
  const response = await axios.get(`${BASE_URL}/sessions`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
    params: { status: 'pending', limit: 50 }
  });
  return response.data.sessions;
}

async function getSessionWithAudit(sessionId) {
  const [session, audit] = await Promise.all([
    axios.get(`${BASE_URL}/sessions/${sessionId}`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    }),
    axios.get(`${BASE_URL}/sessions/${sessionId}/audit`, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    })
  ]);

  return {
    ...session.data,
    auditTrail: audit.data.events
  };
}

Python — Webhook Handler

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook/esign', methods=['POST'])
def handle_esign_webhook():
    payload = request.json

    if payload.get('event') == 'esign.session_created':
        for signer in payload.get('signingLinks', []):
            send_custom_email(
                to=signer['email'],
                signing_link=signer['signingLink']
            )

    elif payload.get('status') == 'completed':
        signed_pdf_url = payload['signedPdfUrl']
        order_id = payload.get('webhookParams', {}).get('orderId')
        drive_url = payload.get('googleDriveUrl')  # Present if Save to Drive is enabled
        process_signed_document(signed_pdf_url, order_id, drive_url=drive_url)

    return jsonify({'received': True})

Getting Started

Integrations

Features

Use Cases

Account & Billing

Resources

Authentication

Base URL

Session Management

List Signing Sessions

Get Session Details

Get Signing Links

Get Audit Trail

Cancel Session

Resend Invitation

Webhook Events

Session Created (Manual Delivery)

Session Completed

Signer Signed

Session Expired

Approval Events

Passing Additional Parameters

Status Reference

Session Statuses

Signer Statuses

Acceptance Sessions

Error Responses

Rate Limits

Code Examples

Node.js — List and Monitor Sessions

Python — Webhook Handler

​Authentication

​Base URL

​Session Management

​List Signing Sessions

​Get Session Details

​Get Signing Links

​Get Audit Trail

​Cancel Session

​Resend Invitation

​Webhook Events

​Session Created (Manual Delivery)

​Session Completed

​Signer Signed

​Session Expired

​Approval Events

​Passing Additional Parameters

​Status Reference

​Session Statuses

​Signer Statuses

​Acceptance Sessions

​Error Responses

​Rate Limits

​Code Examples

​Node.js — List and Monitor Sessions

​Python — Webhook Handler

Authentication

Base URL

Session Management

List Signing Sessions

Get Session Details

Get Signing Links

Get Audit Trail

Cancel Session

Resend Invitation

Webhook Events

Session Created (Manual Delivery)

Session Completed

Signer Signed

Session Expired

Approval Events

Passing Additional Parameters

Status Reference

Session Statuses

Signer Statuses

Acceptance Sessions

Error Responses

Rate Limits

Code Examples

Node.js — List and Monitor Sessions

Python — Webhook Handler