{
  "openapi": "3.1.0",
  "info": {
    "title": "eSignSimple API",
    "version": "1.0.0",
    "summary": "Send PDF and Word documents for e-signature, track signers and download the signed PDF.",
    "description": "A small REST API for eSignSimple (https://esignsimple.com). Upload a PDF or Word document, say who signs where, and get told when it is done. Authenticate with a bearer API key from Settings → Developers (Silver and Gold plans). Field coordinates are fractions of the page (0–1, origin top-left). Webhooks (document.completed, document.declined, document.voided, signer.signed) are signed with HMAC-SHA256 in the `esign-signature` header. Human-readable docs: https://esignsimple.com/developers",
    "termsOfService": "https://esignsimple.com/legal/terms",
    "contact": { "name": "eSignSimple", "url": "https://esignsimple.com/contact" },
    "license": { "name": "CC BY 4.0 (this description)", "url": "https://creativecommons.org/licenses/by/4.0/" }
  },
  "externalDocs": { "description": "API guide", "url": "https://esignsimple.com/developers" },
  "servers": [{ "url": "https://esignsimple.com" }],
  "security": [{ "bearerAuth": [] }],
  "tags": [
    { "name": "Account" },
    { "name": "Documents" },
    { "name": "Templates" },
    { "name": "Verification", "description": "Public, no key needed." }
  ],
  "paths": {
    "/api/v1/me": {
      "get": {
        "tags": ["Account"],
        "operationId": "getAccount",
        "summary": "Your account, plan and documents used this month",
        "responses": {
          "200": { "description": "Account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/documents": {
      "get": {
        "tags": ["Documents"],
        "operationId": "listDocuments",
        "summary": "List documents, newest first",
        "parameters": [
          { "name": "status", "in": "query", "description": "Comma-separated statuses, e.g. `sent,finalizing`.", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } },
          { "name": "before", "in": "query", "description": "Cursor: pass `next_before` from the previous page.", "schema": { "type": "string", "format": "date-time" } }
        ],
        "responses": {
          "200": {
            "description": "A page of documents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "has_more"],
                  "properties": {
                    "data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } },
                    "has_more": { "type": "boolean" },
                    "next_before": { "type": ["string", "null"], "format": "date-time" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" }
        }
      },
      "post": {
        "tags": ["Documents"],
        "operationId": "createDocument",
        "summary": "Upload a document, add signers and fields, and send it",
        "description": "Multipart upload. `file` is a PDF, .doc, .docx, .odt or .rtf (Word files are converted to PDF; up to 25 MB). `data` is a JSON string. Set `send: false` to keep a draft that emails nobody.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file", "data"],
                "properties": {
                  "file": { "type": "string", "format": "binary" },
                  "data": { "$ref": "#/components/schemas/CreateDocumentData" }
                }
              },
              "encoding": { "data": { "contentType": "application/json" } }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created (and sent unless `send` was false)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/Document" },
                    {
                      "type": "object",
                      "properties": {
                        "signing_links": {
                          "type": "array",
                          "description": "Filled when the account has no email delivery: deliver each link yourself.",
                          "items": { "type": "object", "properties": { "signer_id": { "type": "string" }, "email": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "413": { "$ref": "#/components/responses/Error" },
          "422": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/documents/{id}": {
      "parameters": [{ "$ref": "#/components/parameters/id" }],
      "get": {
        "tags": ["Documents"],
        "operationId": "getDocument",
        "summary": "Status, signers and the full audit trail",
        "responses": {
          "200": { "description": "Document with events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentWithEvents" } } } },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      },
      "delete": {
        "tags": ["Documents"],
        "operationId": "deleteDocument",
        "summary": "Permanently delete a draft, voided, declined or completed document",
        "responses": {
          "204": { "description": "Deleted" },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/documents/{id}/download": {
      "parameters": [{ "$ref": "#/components/parameters/id" }],
      "get": {
        "tags": ["Documents"],
        "operationId": "downloadDocument",
        "summary": "Download the signed PDF (or the original)",
        "parameters": [{ "name": "file", "in": "query", "schema": { "type": "string", "enum": ["final", "original"], "default": "final" } }],
        "responses": {
          "200": { "description": "PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/documents/{id}/void": {
      "parameters": [{ "$ref": "#/components/parameters/id" }],
      "post": {
        "tags": ["Documents"],
        "operationId": "voidDocument",
        "summary": "Withdraw a document that is waiting for signatures",
        "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } },
        "responses": {
          "200": { "description": "Voided", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/templates": {
      "get": {
        "tags": ["Templates"],
        "operationId": "listTemplates",
        "summary": "Your saved templates and their roles",
        "responses": {
          "200": {
            "description": "Templates",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } } } } }
          },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/templates/{id}/send": {
      "parameters": [{ "$ref": "#/components/parameters/id" }],
      "post": {
        "tags": ["Templates"],
        "operationId": "sendTemplate",
        "summary": "Send a saved template",
        "description": "One signer per template role, in role order.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["signers"],
                "properties": {
                  "title": { "type": "string" },
                  "signers": { "type": "array", "items": { "$ref": "#/components/schemas/SignerInput" } }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/verify": {
      "get": {
        "tags": ["Verification"],
        "operationId": "verifyFingerprint",
        "summary": "Check whether eSignSimple issued a completed PDF with this SHA-256",
        "security": [],
        "parameters": [{ "name": "sha256", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" } }],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["found"],
                  "properties": {
                    "found": { "type": "boolean" },
                    "title": { "type": "string" },
                    "completedAt": { "type": "string", "format": "date-time" },
                    "signers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "signedAt": { "type": ["string", "null"], "format": "date-time" } } } }
                  }
                }
              }
            }
          },
          "400": { "description": "Not a SHA-256 hex string" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key `es_live_…` from Settings → Developers." }
    },
    "parameters": {
      "id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
    },
    "responses": {
      "Error": {
        "description": "Error",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "object",
                  "properties": {
                    "code": { "type": "string", "enum": ["unauthorized", "invalid_request", "not_found", "not_completed", "too_large", "conversion_failed", "internal"] },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "Account": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "email": { "type": "string" },
          "name": { "type": ["string", "null"] },
          "plan": { "type": "string" },
          "documents_this_month": { "type": "integer" },
          "monthly_limit": { "type": ["integer", "null"] }
        }
      },
      "SignerInput": {
        "type": "object",
        "required": ["name", "email"],
        "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }
      },
      "FieldInput": {
        "type": "object",
        "required": ["signer", "kind", "page", "x", "y", "w", "h"],
        "properties": {
          "signer": { "type": "integer", "minimum": 0, "description": "Index into `signers`." },
          "kind": { "type": "string", "enum": ["signature", "initials", "date", "name", "email", "text", "company", "title", "number", "checkbox", "dropdown", "radio"] },
          "page": { "type": "integer", "minimum": 0, "description": "Zero-based page index." },
          "x": { "type": "number", "minimum": 0, "maximum": 1 },
          "y": { "type": "number", "minimum": 0, "maximum": 1 },
          "w": { "type": "number", "minimum": 0, "maximum": 1 },
          "h": { "type": "number", "minimum": 0, "maximum": 1 },
          "required": { "type": "boolean", "default": true },
          "label": { "type": "string" },
          "options": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 20, "description": "Required for dropdown and radio." }
        }
      },
      "CreateDocumentData": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "message": { "type": "string" },
          "sequential": { "type": "boolean", "default": false },
          "send": { "type": "boolean", "default": true },
          "signers": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/SignerInput" } },
          "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FieldInput" } }
        }
      },
      "Signer": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "email": { "type": "string" },
          "order": { "type": "integer" },
          "status": { "type": "string" },
          "signed_at": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "Document": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "title": { "type": "string" },
          "status": { "type": "string", "enum": ["draft", "sent", "finalizing", "completed", "voided", "declined"] },
          "status_reason": { "type": ["string", "null"] },
          "sequential": { "type": "boolean" },
          "pages": { "type": "integer" },
          "created_at": { "type": "string", "format": "date-time" },
          "sent_at": { "type": ["string", "null"], "format": "date-time" },
          "completed_at": { "type": ["string", "null"], "format": "date-time" },
          "original_sha256": { "type": ["string", "null"] },
          "final_sha256": { "type": ["string", "null"] },
          "download_url": { "type": ["string", "null"], "format": "uri" },
          "signers": { "type": "array", "items": { "$ref": "#/components/schemas/Signer" } }
        }
      },
      "DocumentWithEvents": {
        "allOf": [
          { "$ref": "#/components/schemas/Document" },
          {
            "type": "object",
            "properties": {
              "events": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "type": { "type": "string" },
                    "at": { "type": "string", "format": "date-time" },
                    "signer_id": { "type": ["string", "null"] },
                    "ip": { "type": ["string", "null"] }
                  }
                }
              }
            }
          }
        ]
      },
      "Template": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "title": { "type": "string" },
          "sequential": { "type": "boolean" },
          "pages": { "type": "integer" },
          "roles": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "label": { "type": "string" } } } },
          "fields": { "type": "integer" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      }
    }
  }
}