eSora Sign⁠An eSora Labs company
ENFR Sign in Start free
Guide

Quickstart

Send your first document for signature with one API call.

Before you start

  • An eSora Sign workspace where you are an admin.
  • An API key: in the app, open Settings, Developers and choose Create key. It starts with sk_live_ and is shown once.
  • A PDF to send (up to 50 MB).
  • curl, Node 18 or later, or Python 3.9 or later.

Every call is real: the people you add get real emails. Use your own addresses while you build.

bash
export ESORA_API_KEY="sk_live_…"

1. Create and send a document in one call

POST /documents takes the file, the people, the fields they fill in, and send: true. Upload the file as multipart/form-data and put everything else as JSON in a part named data.

Field positions are fractions of the page: x and y from the top-left corner, width and height, all between 0 and 1. Pages are numbered from 1.

bash
curl -X POST "https://api.esorasign.com/v1/documents" \
  -H "Authorization: Bearer $ESORA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@service-agreement.pdf;type=application/pdf" \
  -F 'data={
    "title": "Service agreement - Northwind",
    "message": "Please review and sign by Friday.",
    "recipients": [
      { "key": "client", "name": "Maya Chen", "email": "maya.chen@example.com" },
      { "name": "Jordan Okafor", "email": "jordan.okafor@example.com", "role": "cc" }
    ],
    "fields": [
      { "recipient": "client", "type": "signature", "page": 6, "x": 0.12, "y": 0.71, "width": 0.3, "height": 0.06 },
      { "recipient": "client", "type": "date_signed", "page": 6, "x": 0.55, "y": 0.73, "width": 0.2, "height": 0.04 }
    ],
    "labels": ["sales"],
    "metadata": { "crm_deal_id": "D-10442" },
    "send": true
  }'
javascript
// Node 18 or later: plain fetch and FormData, no dependencies.
import { readFile } from 'node:fs/promises';
import { randomUUID } from 'node:crypto';

const form = new FormData();
form.append('file', new Blob([await readFile('service-agreement.pdf')], { type: 'application/pdf' }), 'service-agreement.pdf');
form.append('data', JSON.stringify({
  title: 'Service agreement - Northwind',
  recipients: [{ key: 'client', name: 'Maya Chen', email: 'maya.chen@example.com' }],
  fields: [{ recipient: 'client', type: 'signature', page: 6, x: 0.12, y: 0.71, width: 0.3, height: 0.06 }],
  metadata: { crm_deal_id: 'D-10442' },
  send: true,
}));

const res = await fetch('https://api.esorasign.com/v1/documents', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.ESORA_API_KEY}`, 'Idempotency-Key': randomUUID() },
  body: form,
});
const doc = await res.json();
if (!res.ok) throw new Error(`${doc.error.code}: ${doc.error.message}`);
console.log(doc.id, doc.status); // doc_… sent
python
# Python 3.9 or later with requests (pip install requests).
import json, os, uuid
import requests

data = {
    "title": "Service agreement - Northwind",
    "recipients": [{"key": "client", "name": "Maya Chen", "email": "maya.chen@example.com"}],
    "fields": [{"recipient": "client", "type": "signature", "page": 6, "x": 0.12, "y": 0.71, "width": 0.3, "height": 0.06}],
    "metadata": {"crm_deal_id": "D-10442"},
    "send": True,
}
with open("service-agreement.pdf", "rb") as f:
    res = requests.post(
        "https://api.esorasign.com/v1/documents",
        headers={"Authorization": f"Bearer {os.environ['ESORA_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
        files={"file": ("service-agreement.pdf", f, "application/pdf")},
        data={"data": json.dumps(data)},
        timeout=60,
    )
doc = res.json()
res.raise_for_status()
print(doc["id"], doc["status"])  # doc_... sent

2. Follow its progress

Each signer gets an email with their own link. They confirm a 6-digit code sent to the same address, agree to sign electronically and sign. They never need an account.

Check the status any time, or add a webhook for document.completed so you hear about it right away.

bash
curl "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F" \
  -H "Authorization: Bearer $ESORA_API_KEY"

3. Download the signed record

When the status is completed, download the sealed PDF, its Certificate of Completion and the evidence pack (the signed manifest of everything that happened).

bash
curl "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F/download" \
  -H "Authorization: Bearer $ESORA_API_KEY" -o signed.pdf

Next

  • Templates: send the same document again with new people.
  • Webhooks: react to signatures in your systems.
  • Embedded signing: let people sign inside your own site.