API Documentation - eDocsly

Introduction

The eDocsly API allows you to automate document signing workflows. You can list templates, send documents for signature, and track their status — all programmatically.

The API is available on Professional and Enterprise plans. All requests are made to:

https://docsly.com/api/v1/

All responses are JSON. Dates are returned in ISO 8601 format.

Authentication

All API requests require a Bearer token in the Authorization header.

Creating an API Key

Go to Organization → API Keys in the dashboard
Click Create Key and give it a name and role
Copy the key immediately — it is only shown once

Using the Key

Include the key in every request:

curl https://docsly.com/api/v1/templates \
  -H "Authorization: Bearer sk_live_abc123def456..."

Key Format

API keys start with sk_live_ followed by a 32-character hex string.

Key Roles

Role	Permissions
OWNER	Full access — read and send documents
EDITOR	Read and send documents

Rate Limits

Rate limits are applied per API key using a sliding 1-minute window.

Plan	Limit
Professional	60 requests / minute
Enterprise	120 requests / minute

Rate Limit Headers

When you exceed the rate limit, the API responds with 429 Too Many Requests and includes these headers:

Header	Description
Retry-After	Seconds to wait before retrying
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when the window resets

Endpoints Overview

Method	Path	Description
GET	/api/v1/templates	List active templates and their roles
GET	/api/v1/rules	List active signing rules
POST	/api/v1/documents/send	Send a document for signing
GET	/api/v1/documents/{id}	Get document status and recipient details

GET/api/v1/templates

Returns all active templates in your organization, including each template's roles (signer positions). Use the template ID and role IDs when sending documents.

Example Request

curl https://docsly.com/api/v1/templates \
  -H "Authorization: Bearer sk_live_abc123..."

Response

{
  "templates": [
    {
      "id": "tmpl_abc123",
      "name": "Employment Agreement",
      "description": "Standard employment contract",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "roles": [
        { "id": "role_1", "name": "Employee", "order": 0 },
        { "id": "role_2", "name": "Manager", "order": 1 }
      ]
    }
  ]
}

GET/api/v1/rules

Returns all active signing rules in your organization. You can optionally attach rules to individual recipients when sending documents.

Example Request

curl https://docsly.com/api/v1/rules \
  -H "Authorization: Bearer sk_live_abc123..."

Response

{
  "rules": [
    {
      "id": "rule_abc123",
      "name": "Office IP Only",
      "description": "Restrict signing to office network",
      "type": "IP_RESTRICTION",
      "action": "BLOCK",
      "createdAt": "2025-01-10T08:00:00.000Z"
    }
  ]
}

POST/api/v1/documents/send

Creates a new document from a template and sends it to the specified recipients for signing. Requires OWNER or EDITOR role.

Request Body

Field	Type	Required	Description
templateId	string	Yes	ID of the template to use
name	string	No	Custom name for the document
recipients	array	Yes	One entry per template role (see below)
expiresAt	string	No	ISO 8601 expiration date

Recipient Object

Field	Type	Description
roleId	string	Template role ID (from list templates)
name	string	Recipient's full name
email	string	Recipient's email address
signingRuleIds	string[]	Optional IDs of signing rules to enforce for this recipient

Example Request

curl -X POST https://docsly.com/api/v1/documents/send \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tmpl_abc123",
    "name": "John Doe - Employment Agreement",
    "recipients": [
      {
        "roleId": "role_1",
        "name": "John Doe",
        "email": "john@example.com",
        "signingRuleIds": ["rule_abc123"]
      },
      {
        "roleId": "role_2",
        "name": "Jane Smith",
        "email": "jane@example.com"
      }
    ],
    "expiresAt": "2025-12-31T23:59:59Z"
  }'

Response (201 Created)

{
  "documentId": "doc_xyz789",
  "name": "John Doe - Employment Agreement",
  "status": "PENDING",
  "recipients": [
    {
      "id": "rec_1",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "Employee",
      "order": 0,
      "status": "PENDING",
      "signingRules": [
        { "id": "rule_abc123", "name": "Office IP Only", "type": "IP_RESTRICTION", "action": "BLOCK" }
      ]
    },
    {
      "id": "rec_2",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "role": "Manager",
      "order": 1,
      "status": "PENDING",
      "signingRules": []
    }
  ],
  "createdAt": "2025-06-15T14:30:00.000Z"
}

GET/api/v1/documents/{id}

Returns the current status of a document, including each recipient's signing progress and their assigned signing rules.

Example Request

curl https://docsly.com/api/v1/documents/doc_xyz789 \
  -H "Authorization: Bearer sk_live_abc123..."

Response

{
  "id": "doc_xyz789",
  "name": "John Doe - Employment Agreement",
  "description": "",
  "status": "PENDING",
  "expiresAt": "2025-12-31T23:59:59.000Z",
  "completedAt": null,
  "createdAt": "2025-06-15T14:30:00.000Z",
  "updatedAt": "2025-06-15T14:30:00.000Z",
  "recipients": [
    {
      "id": "rec_1",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "Employee",
      "order": 0,
      "status": "SIGNED",
      "viewedAt": "2025-06-15T15:00:00.000Z",
      "signedAt": "2025-06-15T15:05:00.000Z",
      "declinedAt": null,
      "signingRules": [
        { "id": "rule_abc123", "name": "Office IP Only", "type": "IP_RESTRICTION", "action": "BLOCK" }
      ]
    },
    {
      "id": "rec_2",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "role": "Manager",
      "order": 1,
      "status": "PENDING",
      "viewedAt": null,
      "signedAt": null,
      "declinedAt": null,
      "signingRules": []
    }
  ]
}

Error Codes

All errors include an error message and a code string.

{
  "error": "Human-readable message",
  "code": "ERROR_CODE"
}

HTTP Status	Code	Description
400	VALIDATION_ERROR	Request body failed schema validation
400	TEMPLATE_NOT_FOUND	Template does not exist or is inactive
400	INCOMPLETE_RECIPIENTS	Not all template roles have a recipient
400	RULES_NOT_FOUND	One or more signing rule IDs are invalid
400	DOCUMENT_LIMIT_REACHED	Monthly document limit exceeded for your plan
401	UNAUTHORIZED	Missing, invalid, revoked, or expired API key
403	PERMISSION_DENIED	API key role does not have permission
403	PLAN_REQUIRED	No active Professional or Enterprise subscription
404	NOT_FOUND	Document not found in your organization
429	RATE_LIMIT_EXCEEDED	Too many requests — see Retry-After header

Quick Start

Send your first document in three steps.

Get your templates

Fetch available templates and note the template ID and role IDs.

curl https://docsly.com/api/v1/templates \
  -H "Authorization: Bearer sk_live_abc123..."

Send a document

Use a template ID and assign recipients to each role.

curl -X POST https://docsly.com/api/v1/documents/send \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "TEMPLATE_ID",
    "recipients": [
      { "roleId": "ROLE_ID", "name": "John Doe", "email": "john@example.com" }
    ]
  }'

Check status

Poll the document endpoint to track signing progress.

curl https://docsly.com/api/v1/documents/DOCUMENT_ID \
  -H "Authorization: Bearer sk_live_abc123..."

Tip: Create an API key in the dashboard to get started. Keys start with sk_live_.