DocsAutomator eSign API Reference

The DocsAutomator eSign API allows you to programmatically manage signing sessions, retrieve signing links, track progress, and access audit trails.

Authentication

All API endpoints require authentication via API key in the header:

Authorization: Bearer YOUR_API_KEY

Base URL

https://api.docsautomator.co/esign

---

Session Management

List Signing Sessions

Retrieve a paginated list of signing sessions for your workspace.

GET /esign/sessions

Query Parameters

Parameter	Type	Required	Description
status	string	No	Filter by status: pending, in_progress, completed, expired, cancelled, declined
page	number	No	Page number (default: 1)
limit	number	No	Results per page (default: 20, max: 100)
email	string	No	Search by signer email (case-insensitive partial match)

Example Request

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

Response

{
  "sessions": [
    {
      "id": "6789abc123def456",
      "documentName": "Sales Contract - Acme Corp",
      "status": "pending",
      "signingOrder": "parallel",
      "signers": [
        {
          "index": 1,
          "email": "[email protected]",
          "name": "John Buyer",
          "status": "pending"
        },
        {
          "index": 2,
          "email": "[email protected]",
          "name": "Jane Seller",
          "status": "pending"
        }
      ],
      "expiresAt": "2025-02-15T00:00:00.000Z",
      "completedAt": null,
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "pages": 3
  }
}

---

Get Session Details

Retrieve detailed information about a specific signing session.

GET /esign/sessions/:sessionId

Path Parameters

Parameter	Type	Description
sessionId	string	The signing session ID

Example Request

curl -X GET "https://api.docsautomator.co/esign/sessions/6789abc123def456" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "6789abc123def456",
  "documentName": "Sales Contract - Acme Corp",
  "status": "completed",
  "signingOrder": "sequential",
  "deliveryMethod": "email",
  "currentSignerIndex": 2,
  "originalPdfUrl": "https://storage.example.com/original.pdf",
  "signedPdfUrl": "https://storage.example.com/signed.pdf",
  "originalDocumentHash": "sha256:abc123...",
  "signedDocumentHash": "sha256:def456...",
  "esignFields": [
    {
      "fieldId": "field_1",
      "type": "signature",
      "tagName": "{{esign.signature_1}}",
      "signerIndex": 1,
      "required": true,
      "position": {
        "page": 1,
        "x": 100,
        "y": 500,
        "width": 200,
        "height": 50
      },
      "value": "data:image/png;base64,...",
      "signedAt": "2025-01-15T11:00:00.000Z"
    }
  ],
  "signers": [
    {
      "index": 1,
      "email": "[email protected]",
      "name": "John Buyer",
      "role": "buyer",
      "status": "signed",
      "accessToken": "tok_abc123...",
      "invitedAt": "2025-01-15T10:30:00.000Z",
      "openedAt": "2025-01-15T10:45:00.000Z",
      "signedAt": "2025-01-15T11:00:00.000Z",
      "ipAddress": "192.168.1.1",
      "consentGivenAt": "2025-01-15T10:46:00.000Z",
      "timezone": "America/New_York",
      "geoLocation": {
        "country": "US",
        "region": "NY",
        "city": "New York"
      },
      "signingDurationSeconds": 900
    }
  ],
  "reminderEnabled": true,
  "reminderDays": 3,
  "reminderCount": 0,
  "lastReminderSent": null,
  "expiresAt": "2025-02-15T00:00:00.000Z",
  "completedAt": "2025-01-15T12:00:00.000Z",
  "createdAt": "2025-01-15T10:30:00.000Z"
}

---

Get Signing Links

Retrieve signing links for all signers in a session. Useful for manual delivery mode where you distribute links yourself.

GET /esign/sessions/:sessionId/links

Example Request

curl -X GET "https://api.docsautomator.co/esign/sessions/6789abc123def456/links" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "sessionId": "6789abc123def456",
  "documentName": "Sales Contract - Acme Corp",
  "deliveryMethod": "manual",
  "status": "pending",
  "signers": [
    {
      "signerIndex": 1,
      "email": "[email protected]",
      "name": "John Buyer",
      "signingLink": "https://app.docsautomator.co/sign/tok_abc123...",
      "expiresAt": "2025-02-15T00:00:00.000Z",
      "status": "pending"
    },
    {
      "signerIndex": 2,
      "email": "[email protected]",
      "name": "Jane Seller",
      "signingLink": "https://app.docsautomator.co/sign/tok_def456...",
      "expiresAt": "2025-02-15T00:00:00.000Z",
      "status": "pending"
    }
  ]
}

---

Get Audit Trail

Retrieve the complete audit trail for a signing session, including all events in chronological order.

GET /esign/sessions/:sessionId/audit

Example Request

curl -X GET "https://api.docsautomator.co/esign/sessions/6789abc123def456/audit" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "sessionId": "6789abc123def456",
  "events": [
    {
      "id": "evt_001",
      "eventType": "session_created",
      "actorType": "system",
      "timestamp": "2025-01-15T10:30:00.000Z",
      "metadata": {}
    },
    {
      "id": "evt_002",
      "eventType": "invitation_sent",
      "actorType": "system",
      "actorEmail": "[email protected]",
      "actorSignerIndex": 1,
      "timestamp": "2025-01-15T10:30:05.000Z"
    },
    {
      "id": "evt_003",
      "eventType": "link_opened",
      "actorType": "signer",
      "actorEmail": "[email protected]",
      "actorSignerIndex": 1,
      "ipAddress": "192.168.1.1",
      "userAgent": "Mozilla/5.0...",
      "timestamp": "2025-01-15T10:45:00.000Z"
    },
    {
      "id": "evt_004",
      "eventType": "consent_given",
      "actorType": "signer",
      "actorEmail": "[email protected]",
      "actorSignerIndex": 1,
      "ipAddress": "192.168.1.1",
      "timestamp": "2025-01-15T10:46:00.000Z"
    },
    {
      "id": "evt_005",
      "eventType": "field_submitted",
      "actorType": "signer",
      "actorEmail": "[email protected]",
      "actorSignerIndex": 1,
      "metadata": {
        "fieldId": "field_1",
        "fieldType": "signature"
      },
      "timestamp": "2025-01-15T11:00:00.000Z"
    },
    {
      "id": "evt_006",
      "eventType": "signer_completed",
      "actorType": "signer",
      "actorEmail": "[email protected]",
      "actorSignerIndex": 1,
      "timestamp": "2025-01-15T11:00:05.000Z"
    },
    {
      "id": "evt_007",
      "eventType": "session_completed",
      "actorType": "system",
      "metadata": {
        "signedPdfUrl": "https://storage.example.com/signed.pdf",
        "signedDocumentHash": "sha256:def456..."
      },
      "timestamp": "2025-01-15T12:00:00.000Z"
    }
  ]
}

Event Types

Event Type	Description
session_created	Signing session was created
invitation_sent	Invitation email sent to signer
link_opened	Signer opened the signing link
document_viewed	Signer viewed the PDF document
consent_given	Signer gave e-consent
field_submitted	Signer submitted a field value
signer_completed	Signer completed all their fields
session_completed	All signers finished, signed PDF generated
reminder_sent	Reminder email sent
session_cancelled	Session was cancelled
session_declined	Signer declined to sign
session_expired	Session expired

---

Cancel Session

Cancel a pending signing session. Cannot cancel completed sessions.

POST /esign/sessions/:sessionId/cancel

Request Body

{
  "reason": "Contract terms changed, new document required"
}

Field	Type	Required	Description
reason	string	No	Optional cancellation reason

Example Request

curl -X POST "https://api.docsautomator.co/esign/sessions/6789abc123def456/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Contract terms changed"}'

Response

{
  "success": true,
  "message": "Signing session cancelled",
  "sessionId": "6789abc123def456"
}

---

Resend Invitation

Resend the invitation email to a specific signer.

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

Path Parameters

Parameter	Type	Description
sessionId	string	The signing session ID
signerIndex	number	The signer's index (1, 2, 3, etc.)

Example Request

curl -X POST "https://api.docsautomator.co/esign/sessions/6789abc123def456/resend/1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "message": "Invitation resent to [email protected]"
}

---

Webhook Events

When webhooks are enabled on your automation, DocsAutomator sends POST requests to your webhook URL for e-signing events.

Session Created (Manual Delivery)

Sent when a signing session is created with deliveryMethod: "manual". Use this to retrieve signing links and distribute them yourself.

{
  "event": "esign.session_created",
  "sessionId": "6789abc123def456",
  "documentName": "Sales Contract - Acme Corp",
  "deliveryMethod": "manual",
  "status": "pending",
  "signingLinks": [
    {
      "signerIndex": 1,
      "email": "[email protected]",
      "name": "John Buyer",
      "signingLink": "https://app.docsautomator.co/sign/tok_abc123...",
      "expiresAt": "2025-02-15T00:00:00.000Z"
    }
  ],
  "expiresAt": "2025-02-15T00:00:00.000Z",
  "additionalParams": {
    "orderId": "ORD-12345",
    "customerId": "CUST-789"
  }
}

Signing Completed

Sent when all signers have completed signing and the final PDF is generated.

{
  "signedPdfUrl": "https://storage.example.com/signed.pdf",
  "sessionId": "6789abc123def456",
  "documentName": "Sales Contract - Acme Corp",
  "status": "completed",
  "completedAt": "2025-01-15T12:00:00.000Z",
  "signers": [
    {
      "email": "[email protected]",
      "name": "John Buyer",
      "signedAt": "2025-01-15T11:00:00.000Z"
    },
    {
      "email": "[email protected]",
      "name": "Jane Seller",
      "signedAt": "2025-01-15T12:00:00.000Z"
    }
  ],
  "fieldValues": {
    "text_1_companyName": "Acme Corporation",
    "checkbox_1_agree": true,
    "date_1": "2025-01-15"
  },
  "additionalParams": {
    "orderId": "ORD-12345",
    "customerId": "CUST-789"
  }
}

Passing Additional Parameters

To receive custom data in webhook notifications, include webhookParams in your document creation request:

POST /createDocument
{
  "docId": "your-automation-id",
  "data": { ... },
  "webhookParams": {
    "orderId": "ORD-12345",
    "customerId": "CUST-789",
    "internalRef": "any-custom-data"
  }
}

These parameters are stored with the signing session and returned in all webhook notifications as additionalParams.

---

Session Statuses

Status	Description
pending	Session created, waiting for signers
in_progress	At least one signer has started
completed	All signers finished, signed PDF available
expired	Session expired before completion
cancelled	Session was cancelled by admin
declined	A signer declined to sign

Signer Statuses

Status	Description
pending	Invitation not yet sent
invited	Invitation email sent
opened	Signer opened the signing link
signed	Signer completed all fields
declined	Signer declined to sign

---

Error Responses

All endpoints return errors in this format:

{
  "error": true,
  "message": "Signing session not found"
}

Common Error Codes

Status Code	Description
400	Bad request - invalid parameters
401	Unauthorized - invalid or missing API key
404	Not found - session doesn't exist or doesn't belong to workspace
429	Rate limited - too many requests
500	Server error

---

Rate Limits

Endpoint Type	Limit
Admin endpoints	500 requests per 15 minutes
Session list	100 requests per minute

---

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':
        # Manual delivery - distribute signing links
        for signer in payload.get('signingLinks', []):
            send_custom_email(
                to=signer['email'],
                signing_link=signer['signingLink']
            )

    elif payload.get('status') == 'completed':
        # Signing completed - process signed PDF
        signed_pdf_url = payload['signedPdfUrl']
        order_id = payload.get('additionalParams', {}).get('orderId')
        process_signed_document(signed_pdf_url, order_id)

    return jsonify({'received': True})