Easy Sign API

-H "Idempotency-Key: 5f3a...-unique-per-send"

curl -X POST https://www.easy-sign.ca/api/agent/sign-request \
  -H "Authorization: Bearer es_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": {
      "email": "client@example.com",
      "name": "Jane Smith"
    },
    "document": {
      "url": "https://example.com/contract.pdf"
    },
    "fields": [
      {
        "type": "signature",
        "page": 1,
        "preset": "signature_bottom_right"
      },
      {
        "type": "date",
        "page": 1,
        "preset": "date_after_signature"
      }
    ],
    "envelope_name": "Contract Agreement"
  }'

{
  "type": "signature",
  "page": 1,
  "position": {
    "x": 60,      // X position (0-100%)
    "y": 85,      // Y position (0-100%)
    "width": 25,  // Width (1-50%)
    "height": 8   // Height (1-20%)
  }
}

{
  "success": true,
  "envelope_id": "550e8400-e29b-41d4-a716-446655440000",
  "signing_url": "https://www.easy-sign.ca/sign/550e8400...?token=abc123",
  "expires_at": "<ISO 8601 timestamp, ~7 days from request time by default, up to 30 on Pro>",
  "recipient_email": "client@example.com"
}

{
  "success": false,
  "error": {
    "code": "INVALID_EMAIL",
    "message": "Valid recipient email is required"
  }
}

curl -X POST https://www.easy-sign.ca/api/verify \
  -H "Content-Type: application/json" \
  -d '{ "transactionId": "ES-20241206-ABC12345" }'

curl -X POST https://www.easy-sign.ca/api/verify \
  -F "file=@signed-document.pdf" \
  -F "transactionId=ES-20241206-ABC12345"

{
  "verified": true,
  "transactionId": "ES-20241206-ABC12345",
  "status": "valid",
  "verificationType": "full",
  "hashComparison": "match",
  "message": "Document verified successfully. File integrity confirmed - no modifications detected.",
  "details": {
    "envelopeName": "Contract Agreement",
    "status": "completed",
    "createdAt": "2024-12-06T10:00:00Z",
    "completedAt": "2024-12-06T11:30:00Z",
    "recipientCount": 1,
    "signedCount": 1,
    "documentCount": 1
  }
}

{
  "verified": true,
  "transactionId": "ES-20241206-ABC12345",
  "status": "valid",
  "verificationType": "transaction_only",
  "hashComparison": "unrecognized",
  "message": "Transaction record found, but the uploaded file is not one of the 1 document(s) we hold a hash for on this transaction, so its integrity can be neither confirmed nor denied. This is expected for the audit certificate, for a re-saved, printed or scanned copy, and for documents signed before hashes were recorded. A hash match is the only positive confirmation we can give: a file we hold no hash for and a file that was altered are indistinguishable to us. The transaction details below come from our records, not from the file you provided.",
  "details": {
    "envelopeName": "Contract Agreement",
    "status": "completed",
    "createdAt": "2024-12-06T10:00:00Z",
    "completedAt": "2024-12-06T11:30:00Z",
    "recipientCount": 1,
    "signedCount": 1,
    "documentCount": 1
  }
}

{
  "name": "Easy Sign Document Verification API",
  "version": "1.0",
  "description": "Verify the authenticity of documents signed via Easy Sign",
  "usage": {
    "method": "POST",
    "contentType": "application/json or multipart/form-data",
    "parameters": {
      "transactionId": "The Transaction ID found on the document (format: ES-YYYYMMDD-XXXXXXXX)",
      "file": "Optional: Upload the signed PDF file for verification"
    }
  },
  "legal": {
    "notice": "Electronic signatures on documents signed via Easy Sign may have legal effect under Canadian provincial e-commerce legislation (e.g., Ontario Electronic Commerce Act, 2000) and, in federal contexts, PIPEDA Part 2, as well as ESIGN/UETA (US) and eIDAS (EU).",
    "auditTrail": "Complete audit trails are maintained for all signed documents."
  }
}

/plugin install easy-sign --marketplace synthmind-canada/Easy-Sign-Skills

---
name: easy-sign-send
description: Send a PDF for electronic signature with the Easy Sign API. Use when the user asks to send a PDF to someone for signature.
---

# Send a PDF for signature with Easy Sign

Every request emails a real person and cannot be recalled.
One request sends one PDF to one signer.

## Before you send
1. Confirm with the user: the signer's name and email, which PDF, the page and
   position of each field, and the envelope name. Send only after the user
   says yes in this conversation.
2. The API key is in the environment variable EASY_SIGN_API_KEY.
   Never print it or write it to a file.

## Build the request
- Local PDF (up to 3 MB): the example reads and base64-encodes it inside Node.
  Never put base64 on the command line: it quickly exceeds the shell's
  argument limit.
- PDF at a public URL (up to 20 MB): send "document": { "url": "https://..." }
  instead.
- Up to 15 pages. Pages are numbered from 1.
- Field types: signature, signature_date, date (filled with the date the
  request is sent), signed_datetime (filled in when the signer signs).
- Position each field with a preset (signature_bottom_right,
  signature_bottom_left, signature_bottom_center, signature_footer,
  date_after_signature) or with "position": { "x", "y", "width", "height" }
  in percent of the page, measured from its top-left corner.
- sender_timezone: the user's time zone. Easy Sign stamps the date and time
  of each signature in it. The example uses this computer's zone. A "date"
  field is different: it shows the date the request is sent, in UTC.
- Idempotency-Key: make a new one for every send the user approves (include
  the date and time, as in the example). Reuse it only to retry that same send.

Example: build the request and send it from Node. The output leaves out
signing_url.

```bash
node -e '
const fs = require("fs");
const path = require("path");
const [pdf, email, name, page, envelopeName, idempotencyKey] = process.argv.slice(1);
const body = {
  recipient: { email, name },
  document: {
    file_name: path.basename(pdf),
    base64: fs.readFileSync(pdf).toString("base64")
  },
  fields: [
    { type: "signature", page: Number(page), preset: "signature_bottom_right" },
    { type: "date", page: Number(page), preset: "date_after_signature" }
  ],
  envelope_name: envelopeName,
  sender_timezone: Intl.DateTimeFormat().resolvedOptions().timeZone
};
fetch("https://www.easy-sign.ca/api/agent/sign-request", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.EASY_SIGN_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey
  },
  body: JSON.stringify(body)
}).then(async (res) => {
  const result = await res.json().catch(() => ({}));
  delete result.signing_url;
  console.log(JSON.stringify({
    http_status: res.status,
    retry_after: res.headers.get("retry-after"),
    replayed: res.headers.get("idempotent-replay") === "true",
    ...result
  }, null, 2));
});
' contract.pdf jane@example.com "Jane Smith" 1 "Contract Agreement" contract-agreement-jane-20261025-1403
```

## After you send
- replayed: true means this key was used before. Nothing new was sent; the
  result is the earlier send's. Tell the user.
- 201: tell the user the envelope_id, recipient_email and expires_at. The
  envelope is at https://www.easy-sign.ca/envelope/<envelope_id>.
- Never show or open signing_url. It is the signer's personal link, and
  opening it records a visit by the signer.
- The signing link stays valid for 7 days by default; Pro accounts can set up to 30 in Settings.
- 429 RATE_LIMITED: wait retry_after seconds, then retry with the same key.
- 409 IDEMPOTENCY_IN_PROGRESS: the first try is still running. Wait, then
  retry with the same key. Never switch to a new key here: that sends a
  second email.
- 5xx, or 401 DATABASE_ERROR: wait a few seconds, then retry with the same key.
- Any other 4xx: nothing was sent. Fix the request, confirm with the user
  again, then send with a new key.

[sandbox_workspace_write]
network_access = true

{
  "name": "easy_sign_send_signature_request",
  "description": "Send a PDF document for electronic signature. The recipient receives an email with a signing link.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "recipient": {
        "type": "object",
        "properties": {
          "email":  { "type": "string", "format": "email" },
          "name":   { "type": "string" },
          "locale": { "type": "string", "enum": ["en", "fr", "zh-hans"], "description": "Language of the invitation email and signing page (optional, defaults to en)" }
        },
        "required": ["email"]
      },
      "document": {
        "type": "object",
        "description": "Provide either url (max 20MB) or base64 (max 3MB), up to 15 pages",
        "properties": {
          "url":       { "type": "string", "format": "uri" },
          "base64":    { "type": "string" },
          "file_name": { "type": "string" }
        }
      },
      "fields": {
        "type": "array",
        "minItems": 1,
        "description": "Signature fields. At least one is required. Each field must have either a preset or a position.",
        "items": {
          "type": "object",
          "properties": {
            "type":   { "type": "string", "enum": ["signature", "signature_date", "date", "signed_datetime"] },
            "page":   { "type": "integer", "minimum": 1 },
            "preset": {
              "type": "string",
              "enum": [
                "signature_bottom_right",
                "signature_bottom_left",
                "signature_bottom_center",
                "signature_footer",
                "date_after_signature"
              ]
            },
            "position": {
              "type": "object",
              "description": "Custom placement as percent of page. Use instead of preset.",
              "properties": {
                "x":      { "type": "number", "minimum": 0, "maximum": 100 },
                "y":      { "type": "number", "minimum": 0, "maximum": 100 },
                "width":  { "type": "number", "minimum": 1, "maximum": 50 },
                "height": { "type": "number", "minimum": 1, "maximum": 20 }
              },
              "required": ["x", "y", "width", "height"]
            },
            "required": { "type": "boolean", "description": "Whether the field is mandatory (default true)" }
          },
          "required": ["type", "page"],
          "anyOf": [
            { "required": ["preset"] },
            { "required": ["position"] }
          ]
        }
      },
      "envelope_name": { "type": "string", "description": "Custom envelope name (optional)" },
      "sender_timezone": { "type": "string", "description": "IANA timezone name for the timestamp stamped next to the signature, e.g. America/Toronto (optional, defaults to UTC). Invalid values fall back to UTC; fresh responses echo the zone actually applied (replayed idempotent responses return the originally cached body)." }
    },
    "required": ["recipient", "document", "fields"]
  }
}

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export EASY_SIGN_API_KEY="es_live_your_api_key_here"