{ "openapi": "3.0.3", "info": { "title": "GoSignHere API", "version": "1", "description": "GoSignHere has an API, so it fits into your business and workflows and works with your other products through it. Create a key under Settings, API and webhooks, then send it as a bearer token." }, "servers": [ { "url": "https://app.gosignhere.com" } ], "security": [ { "apiKey": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "gsh_live_...", "description": "An API key from Settings, API and webhooks. Send Authorization: Bearer gsh_live_..." } } }, "paths": { "/api/v1/account": { "get": { "tags": [ "account" ], "summary": "The account: name, plan, usage.", "parameters": [], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "account": { "id": "018f6c1e-7b31-7c4d-8e3f-7a8b9caebfc0", "name": "Analytical Engines Ltd", "type": "business", "plan": "beta" } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] }, "patch": { "tags": [ "account" ], "summary": "Rename the account.", "parameters": [], "x-auth": "session (owner, admin)", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "account": { "id": "018f6c1e-7b31-7c4d-8e3f-7a8b9caebfc0", "name": "Analytical Engines Inc" } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "2 to 120 characters." } }, "required": [ "name" ] }, "example": { "name": "Analytical Engines Inc" } } } } }, "delete": { "tags": [ "account" ], "summary": "Delete the account and everything in it. Owner only; needs the password.", "parameters": [], "x-auth": "session (owner)", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "deleted": true } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "description": "The owner's password." } }, "required": [ "password" ] }, "example": { "password": "a long passphrase here" } } } } } }, "/api/v1/account/api-keys": { "get": { "tags": [ "account" ], "summary": "Your API keys (prefix and last use only, never the secret).", "parameters": [], "x-auth": "session (owner, admin)", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "keys": [ { "id": "018f6c1e-7b32-7c4d-8e3f-8a9babcfc0d1", "name": "CRM sync", "prefix": "gsh_live_ab12", "created_at": "2026-10-10T09:00:00Z", "last_used_at": null } ] } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] }, "post": { "tags": [ "account" ], "summary": "Create a key. The full key is in this response only.", "parameters": [], "x-auth": "session (owner, admin)", "responses": { "201": { "description": "Success", "content": { "application/json": { "example": { "data": { "id": "018f6c1e-7b32-7c4d-8e3f-8a9babcfc0d1", "name": "CRM sync", "prefix": "gsh_live_ab12", "key": "gsh_live_ab12EXAMPLEEXAMPLEEXAMPLE" } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "What the key is for." } }, "required": [ "name" ] }, "example": { "name": "CRM sync" } } } } } }, "/api/v1/account/api-keys/{id}": { "delete": { "tags": [ "account" ], "summary": "Revoke a key. It stops working at once.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "session (owner, admin)", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "revoked": true } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/account/settings": { "get": { "tags": [ "account" ], "summary": "Sending defaults, notification switches and the webhook URL.", "parameters": [], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "settings": { "default_expiry_days": 30, "reminder_days": 3, "default_subject": "", "default_message": "", "notify_viewed": false, "notify_signed": true, "notify_completed": true, "notify_declined": true, "webhook_url": "https://example.com/hooks/gsh", "webhook_secret_set": true } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] }, "patch": { "tags": [ "account" ], "summary": "Change any of the settings; only the keys you send change.", "parameters": [], "x-auth": "session (owner, admin)", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "settings": { "default_expiry_days": 30, "reminder_days": 3, "default_subject": "", "default_message": "", "notify_viewed": false, "notify_signed": true, "notify_completed": true, "notify_declined": true, "webhook_url": "https://example.com/hooks/gsh", "webhook_secret_set": true } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_url": { "type": "string", "description": "HTTPS URL for webhooks; empty clears it." }, "default_expiry_days": { "type": "integer", "description": "0 (never) to 365." }, "reminder_days": { "type": "integer", "description": "Days between reminders; 0 turns them off." }, "default_subject": { "type": "string", "description": "Email subject for new packages." }, "default_message": { "type": "string", "description": "Message for new packages." }, "notify_signed": { "type": "boolean", "description": "Email me when someone signs." } } }, "example": { "webhook_url": "https://example.com/hooks/gsh", "default_expiry_days": 14 } } } } } }, "/api/v1/account/settings/webhook-test": { "post": { "tags": [ "account" ], "summary": "Queue a package.test delivery to your webhook URL.", "parameters": [], "x-auth": "session (owner, admin)", "responses": { "202": { "description": "Success", "content": { "application/json": { "example": { "data": { "delivery": { "id": "018f6c1e-7b33-7c4d-8e3f-9aabbcd0d1e2", "event": "package.test", "status": "queued" } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/account/transfer-ownership": { "post": { "tags": [ "account" ], "summary": "Hand the account to another user. Owner only; needs the password.", "parameters": [], "x-auth": "session (owner)", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "transferred": true } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid", "description": "The new owner." }, "password": { "type": "string", "description": "Your password." } }, "required": [ "user_id", "password" ] }, "example": { "user_id": "018f6c1e-7b30-7c4d-8e3f-6a7b8c9daebf", "password": "a long passphrase here" } } } } } }, "/api/v1/account/users": { "get": { "tags": [ "account" ], "summary": "The people on the account.", "parameters": [], "x-auth": "session", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "users": [ { "id": "018f6c1e-7b30-7c4d-8e3f-6a7b8c9daebf", "name": "Grace Hopper", "email": "grace@example.com", "role": "admin", "status": "active" } ] } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/account/users/invite": { "post": { "tags": [ "account" ], "summary": "Invite a teammate by email.", "parameters": [], "x-auth": "session (owner, admin)", "responses": { "201": { "description": "Success", "content": { "application/json": { "example": { "data": { "user": { "id": "018f6c1e-7b30-7c4d-8e3f-6a7b8c9daebf", "name": "Grace Hopper", "email": "grace@example.com", "role": "admin", "status": "active" } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Their address." }, "name": { "type": "string", "description": "Their name." }, "role": { "type": "string", "description": "admin or member." } }, "required": [ "email" ] }, "example": { "email": "grace@example.com", "name": "Grace Hopper", "role": "member" } } } } } }, "/api/v1/account/users/{id}": { "patch": { "tags": [ "account" ], "summary": "Change a teammate's role or switch them off.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "session (owner, admin)", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "user": { "id": "018f6c1e-7b30-7c4d-8e3f-6a7b8c9daebf", "name": "Grace Hopper", "email": "grace@example.com", "role": "admin", "status": "active" } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "description": "admin or member." }, "active": { "type": "boolean", "description": "false disables the user." } } }, "example": { "role": "admin" } } } } } }, "/api/v1/account/users/{id}/resend-invite": { "post": { "tags": [ "account" ], "summary": "Send a pending invitation again.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "session (owner, admin)", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "sent": true } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/auth/email/change": { "post": { "tags": [ "auth" ], "summary": "Start an email change; the new address must confirm.", "parameters": [], "x-auth": "session", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "sent": true } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "new_email": { "type": "string", "description": "The new address." }, "password": { "type": "string", "description": "Your password." } }, "required": [ "new_email", "password" ] }, "example": { "new_email": "ada@new.example.com", "password": "a long passphrase here" } } } } } }, "/api/v1/auth/invite/accept": { "post": { "tags": [ "auth" ], "summary": "Accept a team invitation: set your name and password.", "parameters": [], "x-auth": "public", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "accepted": true } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "From the invitation email." }, "name": { "type": "string", "description": "Your name." }, "password": { "type": "string", "description": "Your password." } }, "required": [ "token", "name", "password" ] }, "example": { "token": "tok_EXAMPLE", "name": "Grace Hopper", "password": "a long passphrase here" } } } } } }, "/api/v1/auth/login": { "post": { "tags": [ "auth" ], "summary": "Start a session. Returns the CSRF token to send as X-CSRF on later writes; the session cookie is set.", "parameters": [], "x-auth": "public", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "user": { "id": "018f6c1e-7b30-7c4d-8e3f-6a7b8c9daebf", "name": "Ada Lovelace", "role": "owner" }, "csrf": "EXAMPLE_CSRF_TOKEN" } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Account email." }, "password": { "type": "string", "description": "Account password." } }, "required": [ "email", "password" ] }, "example": { "email": "ada@example.com", "password": "a long passphrase here" } } } } } }, "/api/v1/auth/logout": { "post": { "tags": [ "auth" ], "summary": "End the session.", "parameters": [], "x-auth": "session", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "logged_out": true } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/auth/me": { "get": { "tags": [ "auth" ], "summary": "The signed-in user and account (works with a key too).", "parameters": [], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "user": { "id": "018f6c1e-7b30-7c4d-8e3f-6a7b8c9daebf", "name": "Grace Hopper", "email": "grace@example.com", "role": "admin", "status": "active" }, "account": { "id": "018f6c1e-7b31-7c4d-8e3f-7a8b9caebfc0", "name": "Analytical Engines Ltd", "plan": "beta" } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/auth/password/change": { "post": { "tags": [ "auth" ], "summary": "Change your password. Other sessions end.", "parameters": [], "x-auth": "session", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "changed": true } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "current_password": { "type": "string", "description": "The password now." }, "new_password": { "type": "string", "description": "The new password." } }, "required": [ "current_password", "new_password" ] }, "example": { "current_password": "old passphrase", "new_password": "a new long passphrase" } } } } } }, "/api/v1/auth/password/forgot": { "post": { "tags": [ "auth" ], "summary": "Email a password reset link. Always answers the same, whether or not the address exists.", "parameters": [], "x-auth": "public", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "sent": true } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Account email." } }, "required": [ "email" ] }, "example": { "email": "ada@example.com" } } } } } }, "/api/v1/auth/password/reset": { "post": { "tags": [ "auth" ], "summary": "Set a new password with the token from the reset email.", "parameters": [], "x-auth": "public", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "reset": true } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "From the reset link." }, "password": { "type": "string", "description": "The new password." } }, "required": [ "token", "password" ] }, "example": { "token": "tok_EXAMPLE", "password": "a new long passphrase" } } } } } }, "/api/v1/auth/register": { "post": { "tags": [ "auth" ], "summary": "Create an account and its first owner. A confirmation email follows.", "parameters": [], "x-auth": "public", "responses": { "201": { "description": "Success", "content": { "application/json": { "example": { "data": { "user": { "id": "018f6c1e-7b30-7c4d-8e3f-6a7b8c9daebf", "name": "Ada Lovelace", "email": "ada@example.com", "role": "owner" }, "verification_sent": true } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Your name, up to 120 characters." }, "email": { "type": "string", "description": "Sign-in address." }, "password": { "type": "string", "description": "At least 10 characters." }, "account_name": { "type": "string", "description": "Company or workspace name." }, "account_type": { "type": "string", "description": "business or personal." }, "invite_code": { "type": "string", "description": "Only when registration is closed." } }, "required": [ "name", "email", "password", "account_name", "account_type" ] }, "example": { "name": "Ada Lovelace", "email": "ada@example.com", "password": "a long passphrase here", "account_name": "Analytical Engines Ltd", "account_type": "business" } } } } } }, "/api/v1/auth/verify-email": { "post": { "tags": [ "auth" ], "summary": "Confirm an email address with the token from the email.", "parameters": [], "x-auth": "public", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "verified": true } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "From the confirmation link." } }, "required": [ "token" ] }, "example": { "token": "tok_EXAMPLE" } } } } } }, "/api/v1/auth/verify-email/resend": { "post": { "tags": [ "auth" ], "summary": "Send the confirmation email again.", "parameters": [], "x-auth": "public", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "sent": true } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The address to confirm." } }, "required": [ "email" ] }, "example": { "email": "ada@example.com" } } } } } }, "/api/v1/documents": { "get": { "tags": [ "documents" ], "summary": "List documents. Filter with the query parameters.", "parameters": [ { "name": "folder_id", "in": "query", "required": false, "description": "Only this folder.", "schema": { "type": "string", "format": "uuid" } }, { "name": "q", "in": "query", "required": false, "description": "Search the title.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "draft, ready or archived.", "schema": { "type": "string" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "documents": [ { "id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "folder_id": "018f6c1e-7b2e-7c4d-8e3f-4a5b6c7d8e9f", "folder_name": "Contracts", "status": "ready", "kind": "upload", "created_by": "018f6c1e-7b30-7c4d-8e3f-6a7b8c9daebf", "created_by_name": "Grace Hopper", "created_at": "2026-10-10T09:30:00Z", "updated_at": "2026-10-10T09:31:00Z", "tags": [], "render_status": "ready", "render_error": null, "page_count": 3, "source_name": "agreement.pdf", "source_bytes": 184320 } ] } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] }, "post": { "tags": [ "documents" ], "summary": "Upload a document (PDF, Word, Excel, PowerPoint, OpenDocument, RTF, text, PNG or JPG; 25 MB) as multipart, or create one from HTML as JSON. Rendering is asynchronous: poll GET /documents/{id} until render_status is ready.", "parameters": [], "x-auth": "any", "responses": { "201": { "description": "Success", "content": { "application/json": { "example": { "data": { "document": { "render_status": "queued", "page_count": null, "id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "folder_id": "018f6c1e-7b2e-7c4d-8e3f-4a5b6c7d8e9f", "folder_name": "Contracts", "status": "ready", "kind": "upload", "created_by": "018f6c1e-7b30-7c4d-8e3f-6a7b8c9daebf", "created_by_name": "Grace Hopper", "created_at": "2026-10-10T09:30:00Z", "updated_at": "2026-10-10T09:31:00Z", "tags": [], "render_error": null, "source_name": "agreement.pdf", "source_bytes": 184320 } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Multipart form field." }, "folder_id": { "type": "string", "format": "uuid", "description": "Target folder; defaults to your home folder." }, "title": { "type": "string", "description": "Defaults to the file name. Required with html." }, "html": { "type": "string", "description": "JSON alternative to file: the document body as HTML." } }, "required": [ "file" ] }, "example": { "file": "@agreement.pdf", "folder_id": "018f6c1e-7b2e-7c4d-8e3f-4a5b6c7d8e9f" } } } } } }, "/api/v1/documents/{id}": { "get": { "tags": [ "documents" ], "summary": "One document and its processing state.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "document": { "id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "folder_id": "018f6c1e-7b2e-7c4d-8e3f-4a5b6c7d8e9f", "folder_name": "Contracts", "status": "ready", "kind": "upload", "created_by": "018f6c1e-7b30-7c4d-8e3f-6a7b8c9daebf", "created_by_name": "Grace Hopper", "created_at": "2026-10-10T09:30:00Z", "updated_at": "2026-10-10T09:31:00Z", "tags": [], "render_status": "ready", "render_error": null, "page_count": 3, "source_name": "agreement.pdf", "source_bytes": 184320 } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] }, "patch": { "tags": [ "documents" ], "summary": "Rename or move a document.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "document": { "id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "folder_id": "018f6c1e-7b2e-7c4d-8e3f-4a5b6c7d8e9f", "folder_name": "Contracts", "status": "ready", "kind": "upload", "created_by": "018f6c1e-7b30-7c4d-8e3f-6a7b8c9daebf", "created_by_name": "Grace Hopper", "created_at": "2026-10-10T09:30:00Z", "updated_at": "2026-10-10T09:31:00Z", "tags": [], "render_status": "ready", "render_error": null, "page_count": 3, "source_name": "agreement.pdf", "source_bytes": 184320 } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "New title." }, "folder_id": { "type": "string", "format": "uuid", "description": "New folder." } } }, "example": { "title": "Services agreement v2" } } } } } }, "/api/v1/documents/{id}/archive": { "post": { "tags": [ "documents" ], "summary": "Archive a document (it leaves the library; sent packages keep their copy).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "document": { "status": "archived", "id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "folder_id": "018f6c1e-7b2e-7c4d-8e3f-4a5b6c7d8e9f", "folder_name": "Contracts", "kind": "upload", "created_by": "018f6c1e-7b30-7c4d-8e3f-6a7b8c9daebf", "created_by_name": "Grace Hopper", "created_at": "2026-10-10T09:30:00Z", "updated_at": "2026-10-10T09:31:00Z", "tags": [], "render_status": "ready", "render_error": null, "page_count": 3, "source_name": "agreement.pdf", "source_bytes": 184320 } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/documents/{id}/fields": { "get": { "tags": [ "documents" ], "summary": "The signing fields and the fields_revision to send back as If-Match.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "fields_revision": 4, "roles": [ { "role": "R1", "label": "Client" } ], "fields": [ { "id": "018f6c1e-7b34-7c4d-8e3f-0abbcdd1e2f3", "field_key": "client_signature", "field_type": "signature", "label": "Client signature", "recipient_role": "R1", "page": 1, "x_bp": 1000, "y_bp": 8000, "w_bp": 3000, "h_bp": 700, "required": true } ] } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] }, "put": { "tags": [ "documents" ], "summary": "Replace the document's fields. Positions are basis points (0 to 10000) of the page. Send If-Match: the fields_revision you loaded.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "example": "4" } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "fields_revision": 5, "fields": [ { "id": "018f6c1e-7b34-7c4d-8e3f-0abbcdd1e2f3", "field_key": "client_signature" } ] } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "description": "field_key, field_type (signature, initials, date, text, checkbox), recipient_role, page, x_bp, y_bp, w_bp, h_bp, required, label." } }, "required": [ "fields" ] }, "example": { "fields": [ { "field_key": "client_signature", "field_type": "signature", "label": "Client signature", "recipient_role": "R1", "page": 1, "x_bp": 1000, "y_bp": 8000, "w_bp": 3000, "h_bp": 700, "required": true } ] } } } } } }, "/api/v1/documents/{id}/file": { "post": { "tags": [ "documents" ], "summary": "Replace the file. Refused when a sent package already uses the document.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "document": { "id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "folder_id": "018f6c1e-7b2e-7c4d-8e3f-4a5b6c7d8e9f", "folder_name": "Contracts", "status": "ready", "kind": "upload", "created_by": "018f6c1e-7b30-7c4d-8e3f-6a7b8c9daebf", "created_by_name": "Grace Hopper", "created_at": "2026-10-10T09:30:00Z", "updated_at": "2026-10-10T09:31:00Z", "tags": [], "render_status": "ready", "render_error": null, "page_count": 3, "source_name": "agreement.pdf", "source_bytes": 184320 } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Multipart form field." } }, "required": [ "file" ] }, "example": { "file": "@agreement-v2.pdf" } } } } } }, "/api/v1/documents/{id}/pages/{p}": { "get": { "tags": [ "documents" ], "summary": "A rendered page image (PNG).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } }, { "name": "p", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "x-auth": "any", "responses": { "200": { "description": "The file", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/documents/{id}/preview.pdf": { "get": { "tags": [ "documents" ], "summary": "The document with its fields drawn on, as a PDF.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "The file", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/documents/{id}/roles": { "put": { "tags": [ "documents" ], "summary": "Name the signing roles (R1, R2, ...) of the document.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "roles": [ { "role": "R1", "label": "Client" } ] } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "roles": { "type": "array", "description": "Objects with role and label." } }, "required": [ "roles" ] }, "example": { "roles": [ { "role": "R1", "label": "Client" } ] } } } } } }, "/api/v1/documents/{id}/tags": { "put": { "tags": [ "documents" ], "summary": "Replace the document's tags.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "document": { "tags": [ { "id": "018f6c1e-7b2f-7c4d-8e3f-5a6b7c8d9eaf", "name": "Legal" } ], "id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "folder_id": "018f6c1e-7b2e-7c4d-8e3f-4a5b6c7d8e9f", "folder_name": "Contracts", "status": "ready", "kind": "upload", "created_by": "018f6c1e-7b30-7c4d-8e3f-6a7b8c9daebf", "created_by_name": "Grace Hopper", "created_at": "2026-10-10T09:30:00Z", "updated_at": "2026-10-10T09:31:00Z", "render_status": "ready", "render_error": null, "page_count": 3, "source_name": "agreement.pdf", "source_bytes": 184320 } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "description": "Tag ids.", "items": { "type": "string", "format": "uuid" } } }, "required": [ "tags" ] }, "example": { "tags": [ "018f6c1e-7b2f-7c4d-8e3f-5a6b7c8d9eaf" ] } } } } } }, "/api/v1/documents/{id}/template": { "put": { "tags": [ "documents" ], "summary": "Mark or unmark the document as a reusable template.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "document": { "is_template": true, "id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "folder_id": "018f6c1e-7b2e-7c4d-8e3f-4a5b6c7d8e9f", "folder_name": "Contracts", "status": "ready", "kind": "upload", "created_by": "018f6c1e-7b30-7c4d-8e3f-6a7b8c9daebf", "created_by_name": "Grace Hopper", "created_at": "2026-10-10T09:30:00Z", "updated_at": "2026-10-10T09:31:00Z", "tags": [], "render_status": "ready", "render_error": null, "page_count": 3, "source_name": "agreement.pdf", "source_bytes": 184320 } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "is_template": { "type": "boolean", "description": "true or false." } }, "required": [ "is_template" ] }, "example": { "is_template": true } } } } } }, "/api/v1/folders": { "get": { "tags": [ "folders" ], "summary": "The folders you can see.", "parameters": [], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "folders": [ { "id": "018f6c1e-7b2e-7c4d-8e3f-4a5b6c7d8e9f", "name": "Contracts", "parent_id": null, "is_default": false } ] } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] }, "post": { "tags": [ "folders" ], "summary": "Create a folder.", "parameters": [], "x-auth": "any", "responses": { "201": { "description": "Success", "content": { "application/json": { "example": { "data": { "folder": { "id": "018f6c1e-7b2e-7c4d-8e3f-4a5b6c7d8e9f", "name": "Contracts", "parent_id": null, "is_default": false } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Up to 120 characters." }, "parent_id": { "type": "string", "format": "uuid", "description": "Nest it inside another folder." } }, "required": [ "name" ] }, "example": { "name": "Contracts" } } } } } }, "/api/v1/folders/{id}": { "get": { "tags": [ "folders" ], "summary": "One folder.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "folder": { "id": "018f6c1e-7b2e-7c4d-8e3f-4a5b6c7d8e9f", "name": "Contracts", "parent_id": null, "is_default": false } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] }, "patch": { "tags": [ "folders" ], "summary": "Rename or move a folder.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "folder": { "id": "018f6c1e-7b2e-7c4d-8e3f-4a5b6c7d8e9f", "name": "Contracts", "parent_id": null, "is_default": false } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name." }, "parent_id": { "type": "string", "format": "uuid", "description": "New parent." } } }, "example": { "name": "Signed contracts" } } } } }, "delete": { "tags": [ "folders" ], "summary": "Delete an empty folder.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "deleted": true } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/folders/{id}/shares": { "get": { "tags": [ "folders" ], "summary": "Who else can see or edit the folder.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "shares": [ { "user_id": "018f6c1e-7b30-7c4d-8e3f-6a7b8c9daebf", "access": "edit" } ] } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] }, "put": { "tags": [ "folders" ], "summary": "Replace the folder's share list.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "shares": [ { "user_id": "018f6c1e-7b30-7c4d-8e3f-6a7b8c9daebf", "access": "edit" } ] } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shares": { "type": "array", "description": "Objects with user_id and access (view or edit)." } }, "required": [ "shares" ] }, "example": { "shares": [ { "user_id": "018f6c1e-7b30-7c4d-8e3f-6a7b8c9daebf", "access": "edit" } ] } } } } } }, "/api/v1/packages": { "post": { "tags": [ "packages" ], "summary": "Send a document for signature in one call: pass document_id and signers. For several documents, a draft, or per-signer kinds, pass documents (a list of ids) and optionally send:true.", "parameters": [], "x-auth": "any", "responses": { "201": { "description": "Success", "content": { "application/json": { "example": { "data": { "package": { "id": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f", "status": "sent", "title": "Services agreement", "message": "Please sign by Friday.", "expires_in_days": 30, "expires_at": "2026-11-09T10:00:00Z", "signing_mode": "sequential", "created_at": "2026-10-10T10:00:00Z", "document_count": 1, "page_count": 3, "documents": [ { "document_id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "page_count": 3 } ], "signers": [ { "id": "018f6c1e-7b2d-7c4d-8e3f-3a4b5c6d7e8f", "slot": 1, "role": "R1", "kind": "signer", "name": "Ada Lovelace", "email": "ada@example.com", "sequence": 1, "status": "pending", "approval": false } ], "validation": { "ok": true, "messages": [] } } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "document_id": { "type": "string", "format": "uuid", "description": "A ready document with fields placed." }, "signers": { "type": "array", "description": "1 to 8 objects: role (R1...), name, email." }, "title": { "type": "string", "description": "Defaults to the document title." }, "message": { "type": "string", "description": "Up to 2,000 characters." }, "expires_in_days": { "type": "integer", "description": "0 (never) to 365." }, "documents": { "type": "array", "description": "Assembly form: document ids; with signers (kind signer, approver or cc) and send.", "items": { "type": "string", "format": "uuid" } }, "draft": { "type": "boolean", "description": "Create a draft, do not send." } }, "required": [ "document_id", "signers" ] }, "example": { "document_id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "message": "Please sign by Friday.", "signers": [ { "role": "R1", "name": "Ada Lovelace", "email": "ada@example.com" } ] } } } } }, "get": { "tags": [ "packages" ], "summary": "List packages, newest first.", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "draft, sent, in_progress, completed, declined, expired, voided.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search title or signer.", "schema": { "type": "string" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "packages": [ { "id": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f", "status": "sent", "title": "Services agreement", "message": "Please sign by Friday.", "expires_in_days": 30, "expires_at": "2026-11-09T10:00:00Z", "signing_mode": "sequential", "created_at": "2026-10-10T10:00:00Z", "document_count": 1, "page_count": 3, "documents": [ { "document_id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "page_count": 3 } ], "signers": [ { "id": "018f6c1e-7b2d-7c4d-8e3f-3a4b5c6d7e8f", "slot": 1, "role": "R1", "kind": "signer", "name": "Ada Lovelace", "email": "ada@example.com", "sequence": 1, "status": "pending", "approval": false } ], "validation": { "ok": true, "messages": [] } } ] } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/packages/{id}": { "get": { "tags": [ "packages" ], "summary": "One package: signers, documents, timeline and webhook deliveries.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "package": { "id": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f", "status": "sent", "title": "Services agreement", "message": "Please sign by Friday.", "expires_in_days": 30, "expires_at": "2026-11-09T10:00:00Z", "signing_mode": "sequential", "created_at": "2026-10-10T10:00:00Z", "document_count": 1, "page_count": 3, "documents": [ { "document_id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "page_count": 3 } ], "signers": [ { "id": "018f6c1e-7b2d-7c4d-8e3f-3a4b5c6d7e8f", "slot": 1, "role": "R1", "kind": "signer", "name": "Ada Lovelace", "email": "ada@example.com", "sequence": 1, "status": "pending", "approval": false } ], "validation": { "ok": true, "messages": [] }, "events": [ { "type": "package.sent", "at": "2026-10-10T10:00:00Z" } ], "deliveries": [] } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] }, "patch": { "tags": [ "packages" ], "summary": "Edit a draft: title, message, expiry, signing_mode, documents or signers.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "package": { "id": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f", "status": "sent", "title": "Services agreement", "message": "Please sign by Friday.", "expires_in_days": 30, "expires_at": "2026-11-09T10:00:00Z", "signing_mode": "sequential", "created_at": "2026-10-10T10:00:00Z", "document_count": 1, "page_count": 3, "documents": [ { "document_id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "page_count": 3 } ], "signers": [ { "id": "018f6c1e-7b2d-7c4d-8e3f-3a4b5c6d7e8f", "slot": 1, "role": "R1", "kind": "signer", "name": "Ada Lovelace", "email": "ada@example.com", "sequence": 1, "status": "pending", "approval": false } ], "validation": { "ok": true, "messages": [] } } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "New title." }, "message": { "type": "string", "description": "New message." }, "expires_in_days": { "type": "integer", "description": "0 to 365." }, "signing_mode": { "type": "string", "description": "sequential or parallel." }, "signers": { "type": "array", "description": "The full signer list." } } }, "example": { "title": "Services agreement v2" } } } } }, "delete": { "tags": [ "packages" ], "summary": "Delete a draft package.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "deleted": true } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/packages/{id}/completed.pdf": { "get": { "tags": [ "packages" ], "summary": "The signed PDF with its certificate page. Only after completion.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "The file", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/packages/{id}/documents": { "post": { "tags": [ "packages" ], "summary": "Add a document to a draft.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "package": { "id": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f", "status": "sent", "title": "Services agreement", "message": "Please sign by Friday.", "expires_in_days": 30, "expires_at": "2026-11-09T10:00:00Z", "signing_mode": "sequential", "created_at": "2026-10-10T10:00:00Z", "document_count": 1, "page_count": 3, "documents": [ { "document_id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "page_count": 3 } ], "signers": [ { "id": "018f6c1e-7b2d-7c4d-8e3f-3a4b5c6d7e8f", "slot": 1, "role": "R1", "kind": "signer", "name": "Ada Lovelace", "email": "ada@example.com", "sequence": 1, "status": "pending", "approval": false } ], "validation": { "ok": true, "messages": [] } } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "document_id": { "type": "string", "format": "uuid", "description": "A ready document." } }, "required": [ "document_id" ] }, "example": { "document_id": "018f6c1e-7b2c-7c4d-8e3f-2a3b4c5d6e7f" } } } } } }, "/api/v1/packages/{id}/documents/{docId}": { "delete": { "tags": [ "packages" ], "summary": "Remove a document from a draft.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } }, { "name": "docId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "package": { "id": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f", "status": "sent", "title": "Services agreement", "message": "Please sign by Friday.", "expires_in_days": 30, "expires_at": "2026-11-09T10:00:00Z", "signing_mode": "sequential", "created_at": "2026-10-10T10:00:00Z", "document_count": 1, "page_count": 3, "documents": [ { "document_id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "page_count": 3 } ], "signers": [ { "id": "018f6c1e-7b2d-7c4d-8e3f-3a4b5c6d7e8f", "slot": 1, "role": "R1", "kind": "signer", "name": "Ada Lovelace", "email": "ada@example.com", "sequence": 1, "status": "pending", "approval": false } ], "validation": { "ok": true, "messages": [] } } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/packages/{id}/flow-preview": { "get": { "tags": [ "packages" ], "summary": "Who receives the package, in which order.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "steps": [ { "sequence": 1, "signers": [ { "name": "Ada Lovelace", "kind": "signer" } ] } ] } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/packages/{id}/reorder": { "post": { "tags": [ "packages" ], "summary": "Set the document order of a draft.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "package": { "id": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f", "status": "sent", "title": "Services agreement", "message": "Please sign by Friday.", "expires_in_days": 30, "expires_at": "2026-11-09T10:00:00Z", "signing_mode": "sequential", "created_at": "2026-10-10T10:00:00Z", "document_count": 1, "page_count": 3, "documents": [ { "document_id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "page_count": 3 } ], "signers": [ { "id": "018f6c1e-7b2d-7c4d-8e3f-3a4b5c6d7e8f", "slot": 1, "role": "R1", "kind": "signer", "name": "Ada Lovelace", "email": "ada@example.com", "sequence": 1, "status": "pending", "approval": false } ], "validation": { "ok": true, "messages": [] } } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "array", "description": "Every document id once.", "items": { "type": "string", "format": "uuid" } } }, "required": [ "order" ] }, "example": { "order": [ "018f6c1e-7b2c-7c4d-8e3f-2a3b4c5d6e7f", "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f" ] } } } } } }, "/api/v1/packages/{id}/send": { "post": { "tags": [ "packages" ], "summary": "Send a draft. Emails go to the first signer(s).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "package": { "id": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f", "status": "sent", "title": "Services agreement", "message": "Please sign by Friday.", "expires_in_days": 30, "expires_at": "2026-11-09T10:00:00Z", "signing_mode": "sequential", "created_at": "2026-10-10T10:00:00Z", "document_count": 1, "page_count": 3, "documents": [ { "document_id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "page_count": 3 } ], "signers": [ { "id": "018f6c1e-7b2d-7c4d-8e3f-3a4b5c6d7e8f", "slot": 1, "role": "R1", "kind": "signer", "name": "Ada Lovelace", "email": "ada@example.com", "sequence": 1, "status": "pending", "approval": false } ], "validation": { "ok": true, "messages": [] } } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prefill": { "type": "object", "description": "Values for prefilled fields, keyed by field_key." } } }, "example": { "prefill": {} } } } } } }, "/api/v1/packages/{id}/signers/{sid}": { "patch": { "tags": [ "packages" ], "summary": "Correct an unsigned signer's name or email.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } }, { "name": "sid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "package": { "id": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f", "status": "sent", "title": "Services agreement", "message": "Please sign by Friday.", "expires_in_days": 30, "expires_at": "2026-11-09T10:00:00Z", "signing_mode": "sequential", "created_at": "2026-10-10T10:00:00Z", "document_count": 1, "page_count": 3, "documents": [ { "document_id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "page_count": 3 } ], "signers": [ { "id": "018f6c1e-7b2d-7c4d-8e3f-3a4b5c6d7e8f", "slot": 1, "role": "R1", "kind": "signer", "name": "Ada Lovelace", "email": "ada@example.com", "sequence": 1, "status": "pending", "approval": false } ], "validation": { "ok": true, "messages": [] } } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name." }, "email": { "type": "string", "description": "New address." } } }, "example": { "name": "Ada King" } } } } } }, "/api/v1/packages/{id}/signers/{sid}/edit": { "post": { "tags": [ "packages" ], "summary": "Same as PATCH on the signer, for clients that cannot send PATCH.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } }, { "name": "sid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "package": { "id": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f", "status": "sent", "title": "Services agreement", "message": "Please sign by Friday.", "expires_in_days": 30, "expires_at": "2026-11-09T10:00:00Z", "signing_mode": "sequential", "created_at": "2026-10-10T10:00:00Z", "document_count": 1, "page_count": 3, "documents": [ { "document_id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "page_count": 3 } ], "signers": [ { "id": "018f6c1e-7b2d-7c4d-8e3f-3a4b5c6d7e8f", "slot": 1, "role": "R1", "kind": "signer", "name": "Ada Lovelace", "email": "ada@example.com", "sequence": 1, "status": "pending", "approval": false } ], "validation": { "ok": true, "messages": [] } } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name." }, "email": { "type": "string", "description": "New address." } } }, "example": { "name": "Ada King" } } } } } }, "/api/v1/packages/{id}/signers/{sid}/resend": { "post": { "tags": [ "packages" ], "summary": "Email a signer a fresh link (the old link stops working). Pass a new email to redirect it.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } }, { "name": "sid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "package": { "id": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f", "status": "sent", "title": "Services agreement", "message": "Please sign by Friday.", "expires_in_days": 30, "expires_at": "2026-11-09T10:00:00Z", "signing_mode": "sequential", "created_at": "2026-10-10T10:00:00Z", "document_count": 1, "page_count": 3, "documents": [ { "document_id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "page_count": 3 } ], "signers": [ { "id": "018f6c1e-7b2d-7c4d-8e3f-3a4b5c6d7e8f", "slot": 1, "role": "R1", "kind": "signer", "name": "Ada Lovelace", "email": "ada@example.com", "sequence": 1, "status": "pending", "approval": false } ], "validation": { "ok": true, "messages": [] } } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "A corrected address." } } }, "example": { "email": "ada@new.example.com" } } } } } }, "/api/v1/packages/{id}/validate": { "get": { "tags": [ "packages" ], "summary": "Check a draft is ready to send; lists what is missing.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "ok": true, "messages": [] } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/packages/{id}/verify": { "get": { "tags": [ "packages" ], "summary": "Check the package's hash chain. Pass hash= (the SHA-256 of a PDF you hold) to learn whether that exact file is the signed one.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } }, { "name": "hash", "in": "query", "required": false, "description": "SHA-256 of your copy, 64 hex characters.", "schema": { "type": "string" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "ok": true, "found": true, "state": "consistent", "status": "completed", "pre_match": true, "post_match": true, "pdf_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "given_matches": true, "verify_url": "https://app.gosignhere.com/verify/3f6c1c52-8b0e-4c1a-9a53-0d2f6c1b7e10" } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/packages/{id}/void": { "post": { "tags": [ "packages" ], "summary": "Cancel a package in progress. Signers' links stop working.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "package": { "status": "voided", "id": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f", "title": "Services agreement", "message": "Please sign by Friday.", "expires_in_days": 30, "expires_at": "2026-11-09T10:00:00Z", "signing_mode": "sequential", "created_at": "2026-10-10T10:00:00Z", "document_count": 1, "page_count": 3, "documents": [ { "document_id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "page_count": 3 } ], "signers": [ { "id": "018f6c1e-7b2d-7c4d-8e3f-3a4b5c6d7e8f", "slot": 1, "role": "R1", "kind": "signer", "name": "Ada Lovelace", "email": "ada@example.com", "sequence": 1, "status": "pending", "approval": false } ], "validation": { "ok": true, "messages": [] } } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Up to 500 characters; shown to signers." } } }, "example": { "reason": "Terms changed" } } } } } }, "/api/v1/tags": { "get": { "tags": [ "tags" ], "summary": "Your tags.", "parameters": [], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "tags": [ { "id": "018f6c1e-7b2f-7c4d-8e3f-5a6b7c8d9eaf", "name": "Legal" } ] } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] }, "post": { "tags": [ "tags" ], "summary": "Create a tag.", "parameters": [], "x-auth": "any", "responses": { "201": { "description": "Success", "content": { "application/json": { "example": { "data": { "tag": { "id": "018f6c1e-7b2f-7c4d-8e3f-5a6b7c8d9eaf", "name": "Legal" } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Up to 60 characters." } }, "required": [ "name" ] }, "example": { "name": "Legal" } } } } } }, "/api/v1/tags/{id}": { "patch": { "tags": [ "tags" ], "summary": "Rename a tag.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "tag": { "id": "018f6c1e-7b2f-7c4d-8e3f-5a6b7c8d9eaf", "name": "Legal" } } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name." } }, "required": [ "name" ] }, "example": { "name": "Contracts" } } } } }, "delete": { "tags": [ "tags" ], "summary": "Delete a tag; documents keep existing.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "018f6c1e-7b2a-7c4d-9e3f-0a1b2c3d4e5f" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "deleted": true } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/templates": { "get": { "tags": [ "templates" ], "summary": "Your templates.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search the title.", "schema": { "type": "string" } } ], "x-auth": "any", "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "data": { "documents": [ { "is_template": true, "id": "018f6c1e-7b2b-7c4d-8e3f-1a2b3c4d5e6f", "title": "Services agreement", "folder_id": "018f6c1e-7b2e-7c4d-8e3f-4a5b6c7d8e9f", "folder_name": "Contracts", "status": "ready", "kind": "upload", "created_by": "018f6c1e-7b30-7c4d-8e3f-6a7b8c9daebf", "created_by_name": "Grace Hopper", "created_at": "2026-10-10T09:30:00Z", "updated_at": "2026-10-10T09:31:00Z", "tags": [], "render_status": "ready", "render_error": null, "page_count": 3, "source_name": "agreement.pdf", "source_bytes": 184320 } ] } } } } }, "default": { "description": "Error; body {\"error\": {\"code\", \"message\", \"field\"}}" } }, "security": [ { "apiKey": [] } ] } } } }