{ "openapi": "3.0.3", "info": { "title": "eDocYouSign API", "version": "1.0.0", "description": "End-to-end encrypted e-signatures, PowerForms, agreement management and webhooks. Available on Business and Enterprise plans. Documents are encrypted on your side (use the JavaScript SDK at /api/sdk/edocyousign.js); the API only accepts and returns ciphertext.", "contact": { "url": "/developers.html" } }, "servers": [ { "url": "/api/v1", "description": "Your eDocYouSign site" } ], "security": [ { "bearer": [] } ], "tags": [ { "name": "Account" }, { "name": "Envelopes" }, { "name": "PowerForms" }, { "name": "Agreements" }, { "name": "Webhooks" } ], "paths": { "/me": { "get": { "summary": "Who am I", "description": "The workspace, plan and permissions of this API key, plus the workspace recovery public key the SDK uses for two-person recovery.", "tags": [ "Account" ], "operationId": "getMe", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read" } }, "/envelopes": { "get": { "summary": "List envelopes", "description": "Envelopes the key's creator can see (all workspace envelopes for owners and admins), newest first.", "tags": [ "Envelopes" ], "operationId": "listEnvelopes", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeList" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "sent, signed, completed, declined or voided" }, { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "1-200, default 50" }, { "name": "offset", "in": "query", "schema": { "type": "integer" }, "description": "Skip this many" } ], "x-scope": "read" }, "post": { "summary": "Send an envelope", "description": "Send an end-to-end encrypted document for signature. Build the request with the SDK's send() method, which encrypts the PDF and wraps its key with a new access code.", "tags": [ "Envelopes" ], "operationId": "createEnvelope", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Created" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "meta", "pdf" ], "properties": { "meta": { "type": "string", "description": "JSON: title, subject, message, ordered, pages, enc {v, salt, iter, wrapped, plainHash, escrow?}, recipients [{id, name, email, color}], fields [{type, recipientId, page, x, y, w, h, required, placeholder}], agreement?, replaces?" }, "pdf": { "type": "string", "format": "binary", "description": "The encrypted document (starts with EDYS1)" } } } } } }, "x-scope": "write" } }, "/envelopes/{id}": { "get": { "summary": "Get an envelope", "description": "Status, recipients (with their signing links, for embedded signing), the wrapped document key and the audit trail.", "tags": [ "Envelopes" ], "operationId": "getEnvelope", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Envelope ID" } ], "x-scope": "read" } }, "/envelopes/{id}/audit": { "get": { "summary": "Get the audit trail", "description": "Every event with its time.", "tags": [ "Envelopes" ], "operationId": "getAudit", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audit" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Envelope ID" } ], "x-scope": "read" } }, "/envelopes/{id}/documents/{kind}": { "get": { "summary": "Download a document", "description": "The encrypted original or signed PDF. Decrypt with the access code (SDK: download()).", "tags": [ "Envelopes" ], "operationId": "getDocument", "responses": { "200": { "description": "Encrypted file", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Envelope ID" }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "original", "signed" ] } } ], "x-scope": "read" } }, "/envelopes/{id}/remind": { "post": { "summary": "Send a reminder", "description": "Email a recipient whose turn it is (at most once an hour).", "tags": [ "Envelopes" ], "operationId": "remind", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Envelope ID" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "recipientId" ], "properties": { "recipientId": { "type": "string" } } } } } }, "x-scope": "write" } }, "/envelopes/{id}/void": { "post": { "summary": "Void an envelope", "description": "Cancel it; signing links stop working and recipients are emailed.", "tags": [ "Envelopes" ], "operationId": "voidEnvelope", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Envelope ID" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } }, "x-scope": "write" } }, "/envelopes/{id}/layout": { "get": { "summary": "Get field layout", "description": "Recipients and field positions (never values), for building a corrected copy.", "tags": [ "Envelopes" ], "operationId": "getLayout", "responses": { "200": { "description": "OK" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Envelope ID" } ], "x-scope": "read" } }, "/powerforms": { "get": { "summary": "List PowerForms", "description": "Reusable signing links and their response counts.", "tags": [ "PowerForms" ], "operationId": "listPowerForms", "responses": { "200": { "description": "OK" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read" } }, "/agreements": { "get": { "summary": "List agreements", "description": "The contract repository with lifecycle status.", "tags": [ "Agreements" ], "operationId": "listAgreements", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementList" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "draft, review, approval, sent, signed, active, expiring, expired, renewed or terminated" } ], "x-scope": "read" }, "post": { "summary": "Create an agreement", "description": "Track a contract: type, counterparty, value, dates and renewal.", "tags": [ "Agreements" ], "operationId": "createAgreement", "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agreement" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementInput" } } } }, "x-scope": "write" } }, "/agreements/{id}": { "get": { "summary": "Get an agreement", "description": "Including obligations, approvals and history.", "tags": [ "Agreements" ], "operationId": "getAgreement", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agreement" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agreement ID" } ], "x-scope": "read" }, "patch": { "summary": "Update an agreement", "description": "Change details or stage. Only send the fields you want to change.", "tags": [ "Agreements" ], "operationId": "updateAgreement", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agreement" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Agreement ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementInput" } } } }, "x-scope": "write" } }, "/webhooks": { "get": { "summary": "List webhooks", "description": "Endpoints subscribed to events.", "tags": [ "Webhooks" ], "operationId": "listWebhooks", "responses": { "200": { "description": "OK" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read" }, "post": { "summary": "Create a webhook", "description": "Subscribe a public HTTPS URL. The response includes the signing secret, shown once.", "tags": [ "Webhooks" ], "operationId": "createWebhook", "responses": { "201": { "description": "Created" }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "*", "envelope.sent", "envelope.viewed", "envelope.signed", "envelope.completed", "envelope.declined", "envelope.voided", "comment.added", "powerform.submitted", "agreement.created", "agreement.updated" ] } } } } } } }, "x-scope": "write" } }, "/webhooks/{id}": { "delete": { "summary": "Delete a webhook", "description": "", "tags": [ "Webhooks" ], "operationId": "deleteWebhook", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook ID" } ], "x-scope": "write" } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "API key from API & webhooks in the app: edys_xxxxxxxx_..." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } } } } }, "Ok": { "type": "object" }, "Me": { "type": "object", "properties": { "workspace": { "type": "object" }, "key": { "type": "object" }, "actingAs": { "type": "object" }, "events": { "type": "array", "items": { "type": "string" } }, "recoveryKey": { "type": "string", "nullable": true } } }, "Created": { "type": "object", "properties": { "id": { "type": "string" }, "agreementId": { "type": "integer", "nullable": true }, "failedEmails": { "type": "array", "items": { "type": "object" } } } }, "Recipient": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "status": { "type": "string" }, "viewedAt": { "type": "string", "nullable": true }, "signedAt": { "type": "string", "nullable": true }, "link": { "type": "string", "description": "Signing link (only for the sender's own use)" } } }, "EnvelopeSummary": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "sent", "signed", "completed", "declined", "voided" ] }, "createdAt": { "type": "string" }, "completedAt": { "type": "string", "nullable": true }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/Recipient" } } } }, "EnvelopeList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EnvelopeSummary" } }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" } } }, "Envelope": { "allOf": [ { "$ref": "#/components/schemas/EnvelopeSummary" }, { "type": "object", "properties": { "enc": { "type": "object", "description": "Wrapped document key: unwrap with the access code" }, "audit": { "type": "array", "items": { "type": "object" } }, "commentCount": { "type": "integer" }, "markupCount": { "type": "integer" } } } ] }, "Audit": { "type": "object", "properties": { "id": { "type": "string" }, "audit": { "type": "array", "items": { "type": "object", "properties": { "t": { "type": "string" }, "event": { "type": "string" } } } } } }, "AgreementInput": { "type": "object", "properties": { "title": { "type": "string" }, "type": { "type": "string" }, "counterparty": { "type": "string" }, "value": { "type": "number" }, "currency": { "type": "string" }, "effectiveDate": { "type": "string", "format": "date" }, "expiryDate": { "type": "string", "format": "date" }, "renewal": { "type": "string", "enum": [ "none", "auto", "manual" ] }, "renewalMonths": { "type": "integer" }, "noticeDays": { "type": "integer" }, "tags": { "type": "string" }, "notes": { "type": "string" }, "stage": { "type": "string" }, "envelopeId": { "type": "string" } } }, "Agreement": { "type": "object" }, "AgreementList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "total": { "type": "integer" } } }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "type": "string", "enum": [ "envelope.sent", "envelope.viewed", "envelope.signed", "envelope.completed", "envelope.declined", "envelope.voided", "comment.added", "powerform.submitted", "agreement.created", "agreement.updated" ] }, "created": { "type": "string" }, "workspace": { "type": "object" }, "data": { "type": "object" } } } } }, "x-webhooks": { "event": { "post": { "summary": "Event notification", "description": "Signed with X-eDocYouSign-Signature: t=,v1=.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Return any 2xx within 8 seconds" } } } } } }