🔌 API Reference

RESTful API documentation for integrating with EasySign.

Enterprise Only: API access requires an Enterprise plan subscription.

Authentication

All API requests require authentication via API key:

Authorization: Bearer YOUR_API_KEY

Getting an API Key

Go to Account → API Keys
Click "Generate New Key"
Give it a name (e.g., "Production")
Copy the key - it's only shown once

Base URL

https://your-domain.com/api/v1/

Response Format

All responses are JSON:

{
    "success": true,
    "data": { ... }
}

// Error response
{
    "success": false,
    "error": {
        "code": "NOT_FOUND",
        "message": "Document not found"
    }
}

Documents

List Documents

GET /api/v1/documents

Query parameters:

Param	Type	Description
limit	int	Max results (default: 50, max: 100)
offset	int	Pagination offset
status	string	Filter: draft, sent, completed, declined
search	string	Search by filename

Response:

{
    "success": true,
    "data": [
        {
            "id": 123,
            "filename": "Contract.pdf",
            "status": "sent",
            "created_at": "2024-01-15T10:30:00Z",
            "due_date": "2024-01-22T00:00:00Z",
            "signers_count": 2,
            "signed_count": 1
        }
    ],
    "pagination": {
        "total": 45,
        "limit": 50,
        "offset": 0
    }
}

Get Document

GET /api/v1/documents?id={id}

Response includes full details with signers.

Upload Document

POST /api/v1/documents
Content-Type: multipart/form-data

Field	Type	Required	Description
file	file	Yes	PDF file (max 50MB)
title	string	No	Document title

Delete Document

DELETE /api/v1/documents?id={id}

Signers

List Signers

GET /api/v1/signers?document_id={id}

Add Signer

POST /api/v1/signers
Content-Type: application/json

{
    "document_id": 123,
    "name": "John Doe",
    "email": "john@example.com",
    "action_type": "sign"  // sign, approve, or view
}

Remove Signer

DELETE /api/v1/signers?id={signer_id}

Send Document

POST /api/v1/signers/send
Content-Type: application/json

{
    "document_id": 123
}

Resend Notification

POST /api/v1/signers/resend
Content-Type: application/json

{
    "signer_id": 456
}

Analytics

Get Document Analytics

GET /api/v1/analytics?document_id={id}

Returns view counts, time-on-page, and activity data.

Download

Download Original PDF

GET /api/v1/download?document_id={id}&type=original

Download Signed PDF

GET /api/v1/download?document_id={id}&type=signed

Download Certificate

GET /api/v1/download?document_id={id}&type=certificate

Webhooks

Configure webhooks to receive event notifications:

Available Events

Event	Description
document.sent	Document sent for signing
document.signed	A signer completed signing
document.completed	All signers completed
document.declined	A signer declined
document.viewed	Signer viewed document

Webhook Payload

{
    "event": "document.signed",
    "timestamp": "2024-01-15T14:30:00Z",
    "data": {
        "document_id": 123,
        "document_name": "Contract.pdf",
        "signer_id": 456,
        "signer_name": "John Doe",
        "signer_email": "john@example.com"
    }
}

Register Webhook

POST /api/v1/webhooks
Content-Type: application/json

{
    "url": "https://your-server.com/webhook",
    "events": ["document.completed", "document.declined"]
}

Error Codes

Code	HTTP	Description
UNAUTHORIZED	401	Invalid or missing API key
FORBIDDEN	403	No access to this resource
NOT_FOUND	404	Resource doesn't exist
VALIDATION_ERROR	400	Invalid request data
RATE_LIMITED	429	Too many requests
SERVER_ERROR	500	Internal server error

Rate Limits

100 requests per minute per API key
1000 requests per hour per API key

SDK Examples

PHP

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://your-domain.com/api/v1/documents");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$data = json_decode($response, true);

JavaScript

const response = await fetch('https://your-domain.com/api/v1/documents', {
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
});
const data = await response.json();

Python

import requests

response = requests.get(
    'https://your-domain.com/api/v1/documents',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()