easyesign API reference

A simple REST API to upload documents, collect signatures, and download signed PDFs — 100% free, no ads or watermarks.

Introduction

The easyesign API is organized around predictable resources. It accepts JSON request bodies (and multipart for uploads), returns JSON, and uses standard HTTP verbs and status codes. Everything you can do in the dashboard, you can do over the API.

Authentication

Authenticate every request to a protected endpoint with an API key, sent as a Bearer token:

# Header on every authoring request
Authorization: Bearer YOUR_API_KEY

Create and manage your own keys from the dashboard under API keys. Keep keys secret — treat them like passwords. Public signing endpoints (/sign/{token}) are scoped to an opaque per-recipient token and need no API key, so your signers never require an account.

Base URL & errors

All endpoints are relative to:

https://easyesign.us/api/v1

Errors return a JSON body with an error code and human-readable message:

{
  "error": "unauthorized",
  "message": "Missing API key. Send 'Authorization: Bearer <key>'."
}

Quickstart

Upload → create envelope → send, in three calls:

# 1) Upload a PDF or DOCX
DOC=$(curl -s -X POST https://easyesign.us/api/v1/documents \
  -H "Authorization: Bearer $KEY" -F file=@contract.pdf | jq -r .id)

# 2) Create a draft envelope with one signer
ENV=$(curl -s -X POST https://easyesign.us/api/v1/envelopes \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d "{\"documentId\":\"$DOC\",\"subject\":\"Please sign\",
       \"recipients\":[{\"name\":\"Aya\",\"email\":\"aya@acme.com\",\"order\":0}]}" | jq -r .id)

# 3) Send it — returns tokenized signing links
curl -s -X POST https://easyesign.us/api/v1/envelopes/$ENV/send \
  -H "Authorization: Bearer $KEY"

Upload a document

Upload a PDF or DOCX (multipart form field file). DOCX is normalized to PDF; page sizes are extracted.

curl -X POST https://easyesign.us/api/v1/documents \
  -H "Authorization: Bearer $KEY" -F file=@contract.pdf

{
  "id": "9a7f34c1-…",
  "filename": "contract.pdf",
  "mimeType": "application/pdf",
  "pageCount": 1,
  "pageSizes": [{ "width": 612, "height": 792 }]
}

Get document PDF

Streams the normalized PDF bytes (application/pdf).

Create an envelope

Create a draft from a document with one or more recipients. order controls signing sequence — recipients sharing the lowest order sign first (in parallel), then the next tier, and so on.

{
  "id": "cmr…",
  "status": "draft",
  "recipients": [{ "id": "…", "name": "Aya", "email": "aya@acme.com", "order": 0, "status": "pending" }]
}

Get an envelope

Returns the envelope with recipients, fields, and status (draft → sent → in_progress → completed).

Set fields

Replaces the whole field layout. Coordinates are normalized 0..1 relative to the page. Each field targets a recipientId, a page, a type (signature, initials, date, text), and whether it's required.

{
  "fields": [
    { "recipientId": "…", "page": 0, "type": "signature",
      "x": 0.15, "y": 0.80, "w": 0.30, "h": 0.06, "required": true }
  ]
}

Auto-place fields

Suggests signature-field boxes automatically (AI-assisted, with a heuristic fallback). Returns suggested boxes you can review and save via set fields.

Send for signing

Transitions the envelope to sent, activates the first signing tier, and emails their signing links. Returns per-recipient tokenized links.

{
  "envelopeId": "cmr…",
  "status": "sent",
  "signingLinks": [
    { "email": "aya@acme.com", "url": "https://easyesign.us/api/v1/sign/OPAQUE_TOKEN", "order": 0 }
  ]
}

Download signed PDF

Once status = completed, streams the finalized, stamped PDF — clean, with no watermark.

Audit trail

Returns the tamper-evident audit events plus a fresh hash-chain verification result.

Get signing view public

Recipient-scoped view of the document and the fields assigned to that signer. No API key — the opaque token is the credential. A signer only ever sees their own fields.

Submit signature public

Submits the recipient's field values and completes their part. When the last recipient signs, the envelope is finalized.

Templates

Reusable field layouts with named roles you can instantiate into new envelopes.

Instantiate maps template roles to real recipients and returns a new draft envelope, ready to send.