{ "openapi": "3.1.0", "info": { "title": "PDFBetter API", "version": "1.0.0", "description": "Create, fill, export and send PDFs for signature from your own systems. Requires the Business plan. Rate limit: 120 requests per 60 s per key. Guides: https://pdfbetter.com/developers/", "contact": { "name": "PDFBetter", "url": "https://pdfbetter.com/developers/" } }, "externalDocs": { "url": "https://pdfbetter.com/developers/" }, "servers": [ { "url": "https://api.pdfbetter.com", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Documents", "description": "Create documents from a file, a URL or a template; fill fields; export PDFs." }, { "name": "Signature requests", "description": "Send documents for e-signature and track every step." }, { "name": "Forms", "description": "Read published forms and their responses." }, { "name": "Templates", "description": "Your reusable templates and the PDFBetter template library." }, { "name": "Bulk fill", "description": "Fill one document per spreadsheet row." }, { "name": "Webhook endpoints", "description": "Receive signed event notifications." } ], "paths": { "/v1/documents/": { "post": { "operationId": "createDocument", "summary": "Create a document", "description": "From a multipart upload (`file`, up to ~4 MB per request — use an upload for larger files), an https `url` (≤ 50 MB; private addresses refused, redirects not followed), a library `template` slug, or an `uploadId`. Same file-size, page and encryption checks as the app.", "tags": [ "Documents" ], "x-required-scope": "documents:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Create a document", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" }, "example": { "object": "document", "id": "Xq3T9vLmA2pR7sKd", "title": "Vendor agreement", "kind": "document", "status": "draft", "pageCount": 4, "tags": [ "vendors" ], "folderId": null, "sourceName": "vendor-agreement.pdf", "sourceSize": 184233, "createdFromTemplate": null, "createdAt": "2026-10-15T09:30:00.000Z", "updatedAt": "2026-10-15T09:30:00.000Z" } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "minLength": 8, "maxLength": 2048, "description": "https URL of a PDF (≤ 50 MB). Private and internal addresses are refused; redirects aren't followed." }, "title": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "url" ], "additionalProperties": false }, { "type": "object", "properties": { "template": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Library template slug (see GET /v1/templates/)" }, "title": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "template" ], "additionalProperties": false }, { "type": "object", "properties": { "uploadId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$", "description": "From POST /v1/uploads/ after you PUT the file" }, "title": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "uploadId" ], "additionalProperties": false } ] }, "example": { "url": "https://example.com/files/vendor-agreement.pdf", "title": "Vendor agreement" } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The PDF" }, "title": { "type": "string", "description": "Optional title" } } } } } } }, "get": { "operationId": "listDocuments", "summary": "List documents", "description": "Your documents, newest first.", "tags": [ "Documents" ], "x-required-scope": "documents:read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1–100 (default 25)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "`nextCursor` from the previous page", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "description": "document, template or form", "schema": { "type": "string", "enum": [ "document", "template", "form" ] } }, { "name": "q", "in": "query", "required": false, "description": "Search titles and tags", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List documents", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentList" }, "example": { "object": "list", "data": [ { "object": "document", "id": "Xq3T9vLmA2pR7sKd", "title": "Vendor agreement", "kind": "document", "status": "draft", "pageCount": 4, "tags": [ "vendors" ], "folderId": null, "sourceName": "vendor-agreement.pdf", "sourceSize": 184233, "createdFromTemplate": null, "createdAt": "2026-10-15T09:30:00.000Z", "updatedAt": "2026-10-15T09:30:00.000Z" } ], "hasMore": false, "nextCursor": null } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/uploads/": { "post": { "operationId": "createUpload", "summary": "Create an upload (large files)", "description": "Returns a presigned URL valid for 10 minutes. PUT the PDF bytes to it with the returned headers, then call Create a document with `{ \"uploadId\" }`. Your plan's file-size limit applies.\n\nIdempotency-Key is ignored: the response holds a short-lived URL, so a replay would hand back an expired link. Retrying is safe — re-exporting unchanged content is free.", "tags": [ "Documents" ], "x-required-scope": "documents:write", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "201": { "description": "Create an upload (large files)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" }, "example": { "object": "upload", "id": "Up6tR3eW9qA2sD5f", "url": "https://files.pdfbetter.com/…presigned-put…", "method": "PUT", "headers": { "Content-Type": "application/pdf" }, "expiresAt": "2026-10-15T09:40:00.000Z" } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "size": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Exact byte size of the PDF" }, "contentType": { "default": "application/pdf", "type": "string", "const": "application/pdf" } }, "required": [ "name", "size" ], "additionalProperties": false }, "example": { "name": "annual-report.pdf", "size": 48211337 } } } } } }, "/v1/documents/{id}/": { "get": { "operationId": "getDocument", "summary": "Retrieve a document", "description": "Metadata only. Use Export to get the PDF.", "tags": [ "Documents" ], "x-required-scope": "documents:read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieve a document", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" }, "example": { "object": "document", "id": "Xq3T9vLmA2pR7sKd", "title": "Vendor agreement", "kind": "document", "status": "draft", "pageCount": 4, "tags": [ "vendors" ], "folderId": null, "sourceName": "vendor-agreement.pdf", "sourceSize": 184233, "createdFromTemplate": null, "createdAt": "2026-10-15T09:30:00.000Z", "updatedAt": "2026-10-15T09:30:00.000Z" } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateDocument", "summary": "Update a document", "description": "Rename it or replace its tags.", "tags": [ "Documents" ], "x-required-scope": "documents:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Update a document", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" }, "example": { "object": "document", "id": "Xq3T9vLmA2pR7sKd", "title": "Vendor agreement — Acme", "kind": "document", "status": "draft", "pageCount": 4, "tags": [ "vendors", "2026" ], "folderId": null, "sourceName": "vendor-agreement.pdf", "sourceSize": 184233, "createdFromTemplate": null, "createdAt": "2026-10-15T09:30:00.000Z", "updatedAt": "2026-10-15T09:30:00.000Z" } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "tags": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 } } }, "additionalProperties": false }, "example": { "title": "Vendor agreement — Acme", "tags": [ "vendors", "2026" ] } } } } }, "delete": { "operationId": "deleteDocument", "summary": "Delete a document", "description": "Removes it from your account immediately; stored files are purged within 30 days. Owner only.", "tags": [ "Documents" ], "x-required-scope": "documents:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete a document", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "object": "document", "id": "Xq3T9vLmA2pR7sKd", "deleted": true } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/documents/{id}/fields/": { "get": { "operationId": "listDocumentFields", "summary": "List fillable fields", "description": "Fields added in PDFBetter (`source: model`) and AcroForm fields already in the PDF (`source: pdf`), with types, options and current values. `revision` can be passed back as `expectedRevision` when filling.", "tags": [ "Documents" ], "x-required-scope": "documents:read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List fillable fields", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldList" }, "example": { "object": "field_list", "documentId": "Xq3T9vLmA2pR7sKd", "revision": 3, "data": [ { "name": "company_name", "type": "text", "source": "model", "label": "Company name", "required": true, "readOnly": false, "options": null, "value": "Acme Ltd", "page": 1, "multiline": false, "maxLength": 120 }, { "name": "plan", "type": "radio", "source": "model", "label": "plan", "required": true, "readOnly": false, "options": [ "basic", "pro" ], "value": "pro", "page": 1, "multiline": null, "maxLength": null }, { "name": "topmostSubform[0].Page1[0].f1_01[0]", "type": "text", "source": "pdf", "label": null, "required": false, "readOnly": false, "options": null, "value": "", "page": 1, "multiline": false, "maxLength": null } ] } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "fillDocumentFields", "summary": "Fill fields", "description": "Sets values by field name. Values are validated like in the editor (types, options, formats, patterns; formulas recalculated). If anything is invalid you get 422 `invalid_fields` with a message per field and nothing is saved. `complete: true` also requires every required field.\n\nSignature and button fields in the PDF can't be filled through the API — send a signature request instead.", "tags": [ "Documents" ], "x-required-scope": "documents:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Fill fields", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldList" }, "example": { "object": "field_list", "documentId": "Xq3T9vLmA2pR7sKd", "revision": 4, "data": [ { "name": "company_name", "type": "text", "source": "model", "label": "Company name", "required": true, "readOnly": false, "options": null, "value": "Acme Ltd", "page": 1, "multiline": false, "maxLength": 120 }, { "name": "plan", "type": "radio", "source": "model", "label": "plan", "required": true, "readOnly": false, "options": [ "basic", "pro" ], "value": "pro", "page": 1, "multiline": null, "maxLength": null }, { "name": "topmostSubform[0].Page1[0].f1_01[0]", "type": "text", "source": "pdf", "label": null, "required": false, "readOnly": false, "options": null, "value": "", "page": 1, "multiline": false, "maxLength": null } ], "updated": [ "company_name", "plan", "topmostSubform[0].Page1[0].f1_01[0]" ] } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "values": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 500 }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 100000 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, "complete": { "default": false, "type": "boolean" }, "expectedRevision": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "values" ], "additionalProperties": false }, "example": { "values": { "company_name": "Acme Ltd", "plan": "pro", "topmostSubform[0].Page1[0].f1_01[0]": "Acme Ltd" }, "complete": false } } } } } }, "/v1/documents/{id}/export/": { "post": { "operationId": "exportDocument", "summary": "Export a PDF", "description": "Renders the current version and returns a download link valid for 5 minutes. Counts against your plan exactly like a download in the app: the first export of new content uses one export; re-exporting unchanged content is free.\n\nIdempotency-Key is ignored: the response holds a short-lived URL, so a replay would hand back an expired link. Retrying is safe — re-exporting unchanged content is free.", "tags": [ "Documents" ], "x-required-scope": "documents:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Export a PDF", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" }, "example": { "object": "export", "id": "Ex4mP1eQ7rT2yU9i", "url": "https://files.pdfbetter.com/…signed-url…", "fileName": "Vendor agreement.pdf", "size": 201554, "expiresAt": "2026-10-15T09:35:00.000Z" } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "flatten": { "default": false, "description": "Burn fields and annotations into the page content", "type": "boolean" }, "includeComments": { "default": false, "type": "boolean" }, "fileName": { "type": "string", "maxLength": 120 } }, "additionalProperties": false }, "example": { "flatten": true } } } } } }, "/v1/documents/{id}/bulk-fill/": { "post": { "operationId": "bulkFillDocument", "summary": "Start a bulk fill", "description": "One filled PDF per row (≤ 5,000 rows), zipped in parts of 500. `mapping` is field name → column name. Returns a job (202); poll Retrieve a job or listen for `bulk_job.completed`. `dryRun: true` validates rows and previews file names without using quota.", "tags": [ "Bulk fill" ], "x-required-scope": "documents:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Start a bulk fill", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "object": "job", "id": "Jb2nM5qW8eR1tY4u", "type": "bulk_fill", "documentId": "Xq3T9vLmA2pR7sKd", "status": "queued", "rowCount": 120, "doneCount": 0, "succeededCount": 0, "failedCount": 0, "progress": 0, "failedRows": [], "error": null, "createdAt": "2026-10-15T09:30:00.000Z", "downloads": [] } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "minItems": 1, "maxItems": 5000, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string", "maxLength": 200 }, "additionalProperties": { "type": "string", "maxLength": 5000 } } }, "mapping": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 300 }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 200 } }, "fileNameTemplate": { "default": "document-{row}", "type": "string", "maxLength": 200 }, "flatten": { "default": true, "type": "boolean" }, "dryRun": { "default": false, "type": "boolean" } }, "required": [ "rows", "mapping" ], "additionalProperties": false }, "example": { "rows": [ { "Name": "Acme Ltd", "Email": "ap@acme.example" } ], "mapping": { "company_name": "Name", "email": "Email" }, "fileNameTemplate": "invoice-{Name}", "flatten": true } } } } } }, "/v1/jobs/{id}/": { "get": { "operationId": "getJob", "summary": "Retrieve a job", "description": "Progress, failed rows and download links (valid 15 minutes) for each finished zip part.", "tags": [ "Bulk fill" ], "x-required-scope": "documents:read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieve a job", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "object": "job", "id": "Jb2nM5qW8eR1tY4u", "type": "bulk_fill", "documentId": "Xq3T9vLmA2pR7sKd", "status": "running", "rowCount": 120, "doneCount": 45, "succeededCount": 44, "failedCount": 1, "progress": 38, "failedRows": [ { "row": 17, "error": "email: Enter a valid email address." } ], "error": null, "createdAt": "2026-10-15T09:30:00.000Z", "downloads": [] } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/signature-requests/": { "post": { "operationId": "createSignatureRequest", "summary": "Create and send a signature request", "description": "Locks the current version of the document and emails recipients (in order for sequential routing). Pass full `fields` (with `assignee` = recipient key) or `useDocumentFields: true` with `assignees` by field name. `send: false` creates a draft. Uses one signature request from your plan when sent.", "tags": [ "Signature requests" ], "x-required-scope": "signatures:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Create and send a signature request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureRequest" }, "example": { "object": "signature_request", "id": "Vb8nQ2wE5tYu1IoP", "documentId": "Xq3T9vLmA2pR7sKd", "title": "Vendor agreement", "message": "Please sign by Friday.", "status": "sent", "routing": "sequential", "reminderEveryDays": 3, "expiresAt": "2026-11-14T09:30:00.000Z", "sentAt": "2026-10-15T09:30:00.000Z", "completedAt": null, "createdAt": "2026-10-15T09:30:00.000Z", "fieldCount": 2, "hasCompletedFile": false, "hasCertificate": false, "recipients": [ { "id": "Lm4kJ7hG2fD9sA3q", "name": "Dana Smith", "email": "dana@example.com", "role": "signer", "order": 1, "status": "sent", "authMethod": "email_link", "sentAt": "2026-10-15T09:30:00.000Z", "viewedAt": null, "signedAt": null, "declinedAt": null, "declineReason": null } ] } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, "title": { "description": "Default: the document title", "type": "string", "minLength": 1, "maxLength": 200 }, "message": { "type": "string", "maxLength": 2000 }, "routing": { "default": "sequential", "type": "string", "enum": [ "sequential", "parallel" ] }, "recipients": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "key": { "description": "Your handle for the recipient, used by `fields[].assignee` / `assignees`; default r1, r2, …", "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "default": "signer", "type": "string", "enum": [ "signer", "approver", "cc" ] }, "order": { "description": "Sequential routing order; default = position in the list", "type": "integer", "minimum": 1, "maximum": 50 }, "authMethod": { "default": "email_link", "description": "email_otp: the recipient must also enter a one-time code we email them before they can open the document", "type": "string", "enum": [ "email_link", "access_code", "email_otp" ] }, "accessCode": { "type": "string", "minLength": 4, "maxLength": 32 } }, "required": [ "name", "email" ], "additionalProperties": false } }, "fields": { "description": "Full field definitions; `assignee` is a recipient key", "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "pageId": { "type": "string", "minLength": 1, "maxLength": 80 }, "kind": { "type": "string", "enum": [ "signature", "initials", "text", "date", "name", "email", "checkbox", "radio", "image", "dropdown", "number", "formula", "currency_usd", "currency_eur", "currency_jpy", "title", "company", "zip_us", "phone_us", "ein", "ssn", "age", "gender", "state_us", "phone_intl", "postal_code" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "label": { "type": "string", "maxLength": 200 }, "helpText": { "type": "string", "maxLength": 500 }, "placeholder": { "type": "string", "maxLength": 200 }, "box": { "type": "object", "properties": { "x": { "type": "number", "minimum": -10 }, "y": { "type": "number", "minimum": -10 }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 5000 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 5000 } }, "required": [ "x", "y", "width", "height" ] }, "required": { "type": "boolean" }, "readOnly": { "type": "boolean" }, "options": { "maxItems": 200, "type": "array", "items": { "type": "string", "maxLength": 200 } }, "group": { "type": "string", "maxLength": 120 }, "exportValue": { "type": "string", "maxLength": 200 }, "decimals": { "type": "integer", "minimum": 0, "maximum": 8 }, "min": { "type": "number" }, "max": { "type": "number" }, "maxLength": { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000 }, "multiline": { "type": "boolean" }, "pattern": { "type": "string", "maxLength": 300 }, "dateFormat": { "type": "string", "enum": [ "MM/DD/YYYY", "DD/MM/YYYY", "YYYY-MM-DD", "MMMM D, YYYY", "D MMMM YYYY", "DD.MM.YYYY", "YYYY/MM/DD" ] }, "numberLocale": { "type": "string", "maxLength": 35, "pattern": "^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$" }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "condition": { "type": "object", "properties": { "match": { "type": "string", "enum": [ "all", "any" ] }, "rules": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "maxLength": 120 }, "op": { "type": "string", "enum": [ "equals", "not_equals", "contains", "is_empty", "is_not_empty", "gt", "lt", "checked", "unchecked" ] }, "value": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" } ] } }, "required": [ "field", "op" ] } } }, "required": [ "match", "rules" ] }, "style": { "type": "object", "properties": { "font": { "type": "string", "enum": [ "Helvetica", "Times", "Courier", "Signature" ] }, "size": { "type": "number", "minimum": 4, "maximum": 72 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "bold": { "type": "boolean" }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "strikethrough": { "type": "boolean" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "align": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "valign": { "type": "string", "enum": [ "top", "middle", "bottom" ] }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "paragraphSpacing": { "type": "number", "minimum": 0, "maximum": 200 }, "letterSpacing": { "type": "number", "minimum": -20, "maximum": 100 }, "horizontalScale": { "type": "number", "minimum": 10, "maximum": 400 }, "script": { "type": "string", "enum": [ "normal", "superscript", "subscript" ] }, "list": { "type": "string", "enum": [ "none", "bullet", "number" ] }, "indent": { "type": "integer", "minimum": 0, "maximum": 8 }, "role": { "type": "string", "enum": [ "normal", "heading1", "heading2", "heading3", "caption" ] } } }, "defaultValue": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] }, "assignee": { "type": "string", "minLength": 1, "maxLength": 80 }, "tabOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "pageId", "kind", "name", "box" ] } }, "useDocumentFields": { "default": false, "description": "Use the fields already placed on the document", "type": "boolean" }, "assignees": { "description": "With useDocumentFields: field name → recipient key. Unlisted fields go to the only signer when there is exactly one.", "type": "object", "propertyNames": { "type": "string", "maxLength": 200 }, "additionalProperties": { "type": "string", "maxLength": 64 } }, "reminderEveryDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 30 }, { "type": "null" } ] }, "expiresInDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 365 }, { "type": "null" } ] }, "send": { "default": true, "description": "false = create a draft", "type": "boolean" }, "locale": { "description": "Language of the recipients' emails, signing page and certificate: en, es, ja, fr or de. Default: your account language, else en.", "type": "string", "enum": [ "en", "es", "ja", "fr", "de" ] } }, "required": [ "documentId", "recipients" ], "additionalProperties": false }, "example": { "documentId": "Xq3T9vLmA2pR7sKd", "message": "Please sign by Friday.", "recipients": [ { "key": "client", "name": "Dana Smith", "email": "dana@example.com" } ], "useDocumentFields": true, "assignees": { "client_signature": "client", "signed_on": "client" }, "reminderEveryDays": 3, "expiresInDays": 30 } } } } }, "get": { "operationId": "listSignatureRequests", "summary": "List signature requests", "description": "Newest first.", "tags": [ "Signature requests" ], "x-required-scope": "signatures:read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1–100 (default 25)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "`nextCursor` from the previous page", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status", "schema": { "type": "string", "enum": [ "draft", "sent", "completed", "declined", "canceled", "expired" ] } } ], "responses": { "200": { "description": "List signature requests", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureRequestList" }, "example": { "object": "list", "data": [ { "object": "signature_request", "id": "Vb8nQ2wE5tYu1IoP", "documentId": "Xq3T9vLmA2pR7sKd", "title": "Vendor agreement", "message": "Please sign by Friday.", "status": "sent", "routing": "sequential", "reminderEveryDays": 3, "expiresAt": "2026-11-14T09:30:00.000Z", "sentAt": "2026-10-15T09:30:00.000Z", "completedAt": null, "createdAt": "2026-10-15T09:30:00.000Z", "fieldCount": 2, "hasCompletedFile": false, "hasCertificate": false, "recipients": [ { "id": "Lm4kJ7hG2fD9sA3q", "name": "Dana Smith", "email": "dana@example.com", "role": "signer", "order": 1, "status": "sent", "authMethod": "email_link", "sentAt": "2026-10-15T09:30:00.000Z", "viewedAt": null, "signedAt": null, "declinedAt": null, "declineReason": null } ] } ], "hasMore": false, "nextCursor": null } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/signature-requests/{id}/": { "get": { "operationId": "getSignatureRequest", "summary": "Retrieve a signature request", "description": "Status, recipients and the audit timeline (IP addresses stay in the certificate).", "tags": [ "Signature requests" ], "x-required-scope": "signatures:read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieve a signature request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureRequestDetail" }, "example": { "object": "signature_request", "id": "Vb8nQ2wE5tYu1IoP", "documentId": "Xq3T9vLmA2pR7sKd", "title": "Vendor agreement", "message": "Please sign by Friday.", "status": "sent", "routing": "sequential", "reminderEveryDays": 3, "expiresAt": "2026-11-14T09:30:00.000Z", "sentAt": "2026-10-15T09:30:00.000Z", "completedAt": null, "createdAt": "2026-10-15T09:30:00.000Z", "fieldCount": 2, "hasCompletedFile": false, "hasCertificate": false, "recipients": [ { "id": "Lm4kJ7hG2fD9sA3q", "name": "Dana Smith", "email": "dana@example.com", "role": "signer", "order": 1, "status": "sent", "authMethod": "email_link", "sentAt": "2026-10-15T09:30:00.000Z", "viewedAt": null, "signedAt": null, "declinedAt": null, "declineReason": null } ], "timeline": [ { "seq": 1, "event": "created", "actorType": "user", "actorEmail": "you@example.com", "createdAt": "2026-10-15T09:30:00.000Z", "data": { "recipientCount": 1, "fieldCount": 2, "routing": "sequential" } }, { "seq": 2, "event": "sent", "actorType": "user", "actorEmail": "you@example.com", "createdAt": "2026-10-15T09:30:00.000Z", "data": { "pageCount": 4 } }, { "seq": 3, "event": "delivered", "actorType": "system", "actorEmail": null, "createdAt": "2026-10-15T09:30:00.000Z", "data": { "recipientId": "Lm4kJ7hG2fD9sA3q", "recipientName": "Dana Smith", "kind": "invite" } } ] } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/signature-requests/{id}/remind/": { "post": { "operationId": "remindSignatureRequest", "summary": "Send a reminder", "description": "Emails everyone whose turn it is, or one `recipientId`. People invited or reminded in the last hour are skipped.", "tags": [ "Signature requests" ], "x-required-scope": "signatures:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Send a reminder", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reminder" }, "example": { "reminded": 1, "signatureRequest": { "object": "signature_request", "id": "Vb8nQ2wE5tYu1IoP", "documentId": "Xq3T9vLmA2pR7sKd", "title": "Vendor agreement", "message": "Please sign by Friday.", "status": "sent", "routing": "sequential", "reminderEveryDays": 3, "expiresAt": "2026-11-14T09:30:00.000Z", "sentAt": "2026-10-15T09:30:00.000Z", "completedAt": null, "createdAt": "2026-10-15T09:30:00.000Z", "fieldCount": 2, "hasCompletedFile": false, "hasCertificate": false, "recipients": [ { "id": "Lm4kJ7hG2fD9sA3q", "name": "Dana Smith", "email": "dana@example.com", "role": "signer", "order": 1, "status": "sent", "authMethod": "email_link", "sentAt": "2026-10-15T09:30:00.000Z", "viewedAt": null, "signedAt": null, "declinedAt": null, "declineReason": null } ] } } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipientId": { "type": "string", "maxLength": 64 } }, "additionalProperties": false }, "example": {} } } } } }, "/v1/signature-requests/{id}/cancel/": { "post": { "operationId": "cancelSignatureRequest", "summary": "Cancel a signature request", "description": "Closes signing links and tells invited recipients. Canceling twice is harmless.", "tags": [ "Signature requests" ], "x-required-scope": "signatures:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Cancel a signature request", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureRequest" }, "example": { "object": "signature_request", "id": "Vb8nQ2wE5tYu1IoP", "documentId": "Xq3T9vLmA2pR7sKd", "title": "Vendor agreement", "message": "Please sign by Friday.", "status": "canceled", "routing": "sequential", "reminderEveryDays": 3, "expiresAt": "2026-11-14T09:30:00.000Z", "sentAt": "2026-10-15T09:30:00.000Z", "completedAt": null, "createdAt": "2026-10-15T09:30:00.000Z", "fieldCount": 2, "hasCompletedFile": false, "hasCertificate": false, "recipients": [ { "id": "Lm4kJ7hG2fD9sA3q", "name": "Dana Smith", "email": "dana@example.com", "role": "signer", "order": 1, "status": "sent", "authMethod": "email_link", "sentAt": "2026-10-15T09:30:00.000Z", "viewedAt": null, "signedAt": null, "declinedAt": null, "declineReason": null } ] } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } }, "additionalProperties": false }, "example": { "reason": "Terms changed" } } } } } }, "/v1/signature-requests/{id}/files/": { "get": { "operationId": "getSignatureRequestFile", "summary": "Download the signed PDF or certificate", "description": "A link valid for 5 minutes. `completed` and `certificate` are available once the request is completed; `original` is the locked PDF as sent.", "tags": [ "Signature requests" ], "x-required-scope": "signatures:read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "what", "in": "query", "required": true, "description": "completed, certificate or original", "schema": { "type": "string", "enum": [ "completed", "certificate", "original" ] } } ], "responses": { "200": { "description": "Download the signed PDF or certificate", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileLink" }, "example": { "object": "file_link", "url": "https://files.pdfbetter.com/…signed-url…", "fileName": "Vendor agreement (signed).pdf", "expiresAt": "2026-10-15T09:35:00.000Z" } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/forms/": { "get": { "operationId": "listForms", "summary": "List forms", "description": "Your published forms (up to 200), most recently updated first.", "tags": [ "Forms" ], "x-required-scope": "forms:read", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "List forms", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormList" }, "example": { "object": "list", "data": [ { "object": "form", "id": "Fo7mR2tQ9wZp4LxN", "documentId": "Xq3T9vLmA2pR7sKd", "title": "Event registration", "description": null, "status": "live", "edition": 2, "responseCount": 41, "fieldCount": 9, "url": "https://pdfbetter.com/f/k3m9q2w7x5zp/", "createdAt": "2026-10-15T09:30:00.000Z", "updatedAt": "2026-10-15T09:30:00.000Z" } ], "hasMore": false, "nextCursor": null } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/forms/{id}/": { "get": { "operationId": "getForm", "summary": "Retrieve a form", "description": "One published form.", "tags": [ "Forms" ], "x-required-scope": "forms:read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieve a form", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Form" }, "example": { "object": "form", "id": "Fo7mR2tQ9wZp4LxN", "documentId": "Xq3T9vLmA2pR7sKd", "title": "Event registration", "description": null, "status": "live", "edition": 2, "responseCount": 41, "fieldCount": 9, "url": "https://pdfbetter.com/f/k3m9q2w7x5zp/", "createdAt": "2026-10-15T09:30:00.000Z", "updatedAt": "2026-10-15T09:30:00.000Z" } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateForm", "summary": "Update a form", "description": "Pause, close or reopen it (`status`), or change its title/description. Reopening checks your plan's live-form allowance.", "tags": [ "Forms" ], "x-required-scope": "forms:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Update a form", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Form" }, "example": { "object": "form", "id": "Fo7mR2tQ9wZp4LxN", "documentId": "Xq3T9vLmA2pR7sKd", "title": "Event registration", "description": null, "status": "closed", "edition": 2, "responseCount": 41, "fieldCount": 9, "url": "https://pdfbetter.com/f/k3m9q2w7x5zp/", "createdAt": "2026-10-15T09:30:00.000Z", "updatedAt": "2026-10-15T09:30:00.000Z" } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "live", "paused", "closed" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] } }, "additionalProperties": false }, "example": { "status": "closed" } } } } } }, "/v1/forms/{id}/responses/": { "get": { "operationId": "listFormResponses", "summary": "List responses", "description": "Newest first, with answers keyed by field name.", "tags": [ "Forms" ], "x-required-scope": "forms:read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1–100 (default 25)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "`nextCursor` from the previous page", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List responses", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormResponseList" }, "example": { "object": "list", "data": [ { "object": "form_response", "id": "Rs5tY8uI1oP3aS6d", "formId": "Fo7mR2tQ9wZp4LxN", "edition": 2, "respondentEmail": "sam@example.com", "values": { "full_name": "Sam Lee", "attending": true, "sessions": "workshop" }, "createdAt": "2026-10-15T09:30:00.000Z", "pdf": null } ], "hasMore": false, "nextCursor": null } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/forms/{id}/responses/{responseId}/": { "get": { "operationId": "getFormResponse", "summary": "Retrieve a response", "description": "Answers plus a link to the filled PDF (valid 5 minutes).", "tags": [ "Forms" ], "x-required-scope": "forms:read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "responseId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieve a response", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormResponse" }, "example": { "object": "form_response", "id": "Rs5tY8uI1oP3aS6d", "formId": "Fo7mR2tQ9wZp4LxN", "edition": 2, "respondentEmail": "sam@example.com", "values": { "full_name": "Sam Lee", "attending": true, "sessions": "workshop" }, "createdAt": "2026-10-15T09:30:00.000Z", "pdf": { "object": "file_link", "url": "https://files.pdfbetter.com/…signed-url…", "fileName": "Event registration 2026-10-15 Rs5tY8.pdf", "expiresAt": "2026-10-15T09:35:00.000Z" } } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/templates/": { "get": { "operationId": "listTemplates", "summary": "List templates", "description": "Your reusable templates (`type: user`) followed by the PDFBetter library (`type: library`).", "tags": [ "Templates" ], "x-required-scope": "templates:read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "library or user", "schema": { "type": "string", "enum": [ "library", "user" ] } } ], "responses": { "200": { "description": "List templates", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateList" }, "example": { "object": "list", "data": [ { "object": "template", "id": "invoice", "type": "library", "name": "Invoice", "description": "A clean, fillable invoice with bill-to and ship-to, 12 line items, discount, sales tax and balance due.", "category": "invoices", "pageCount": null, "createdAt": null } ], "hasMore": false, "nextCursor": null } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/templates/{slug}/documents/": { "post": { "operationId": "instantiateTemplate", "summary": "Create a document from a template", "description": "`{slug}` is a library slug or one of your template ids. The template itself is never modified.", "tags": [ "Templates" ], "x-required-scope": "documents:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Create a document from a template", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" }, "example": { "object": "document", "id": "Xq3T9vLmA2pR7sKd", "title": "Invoice #1042", "kind": "document", "status": "draft", "pageCount": 4, "tags": [ "vendors" ], "folderId": null, "sourceName": "vendor-agreement.pdf", "sourceSize": 184233, "createdFromTemplate": "invoice", "createdAt": "2026-10-15T09:30:00.000Z", "updatedAt": "2026-10-15T09:30:00.000Z" } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "example": { "title": "Invoice #1042" } } } } } }, "/v1/webhook-endpoints/": { "post": { "operationId": "createWebhookEndpoint", "summary": "Create a webhook endpoint", "description": "https only; the host must resolve to a public address. The signing `secret` is returned in this response only. Up to 10 endpoints.\n\nIdempotency-Key is ignored here so the secret is never stored for replay.", "tags": [ "Webhook endpoints" ], "x-required-scope": "webhooks:write", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "201": { "description": "Create a webhook endpoint", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "example": { "object": "webhook_endpoint", "id": "We9pL3kJ6hG1fD4s", "url": "https://example.com/webhooks/pdfbetter", "description": "Production", "events": [ "signature_request.completed", "form.response_created" ], "status": "enabled", "disabledReason": null, "failingSince": null, "createdAt": "2026-10-15T09:30:00.000Z", "updatedAt": "2026-10-15T09:30:00.000Z", "secret": "whsec_…shown once…" } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 8, "maxLength": 2048, "description": "https URL that accepts POSTs" }, "events": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "signature_request.sent", "signature_request.viewed", "signature_request.signed", "signature_request.declined", "signature_request.completed", "signature_request.canceled", "signature_request.expired", "form.response_created", "document.exported", "bulk_job.completed", "workflow.run.awaiting_approval", "workflow.run.succeeded", "workflow.run.failed", "workflow.run.export_ready", "workflow.run.webhook" ] }, { "type": "string", "const": "*" } ] }, "description": "Event types to receive, or [\"*\"] for all" }, "description": { "type": "string", "maxLength": 200 } }, "required": [ "url", "events" ], "additionalProperties": false }, "example": { "url": "https://example.com/webhooks/pdfbetter", "events": [ "signature_request.completed", "form.response_created" ], "description": "Production" } } } } }, "get": { "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "description": "Newest first.", "tags": [ "Webhook endpoints" ], "x-required-scope": "webhooks:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1–100 (default 25)", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "`nextCursor` from the previous page", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List webhook endpoints", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" }, "example": { "object": "list", "data": [ { "object": "webhook_endpoint", "id": "We9pL3kJ6hG1fD4s", "url": "https://example.com/webhooks/pdfbetter", "description": "Production", "events": [ "signature_request.completed", "form.response_created" ], "status": "enabled", "disabledReason": null, "failingSince": null, "createdAt": "2026-10-15T09:30:00.000Z", "updatedAt": "2026-10-15T09:30:00.000Z" } ], "hasMore": false, "nextCursor": null } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook-endpoints/{id}/": { "get": { "operationId": "getWebhookEndpoint", "summary": "Retrieve a webhook endpoint", "description": "Without the secret.", "tags": [ "Webhook endpoints" ], "x-required-scope": "webhooks:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retrieve a webhook endpoint", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "example": { "object": "webhook_endpoint", "id": "We9pL3kJ6hG1fD4s", "url": "https://example.com/webhooks/pdfbetter", "description": "Production", "events": [ "signature_request.completed", "form.response_created" ], "status": "enabled", "disabledReason": null, "failingSince": null, "createdAt": "2026-10-15T09:30:00.000Z", "updatedAt": "2026-10-15T09:30:00.000Z" } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateWebhookEndpoint", "summary": "Update a webhook endpoint", "description": "Change the URL, events or description; `enabled: true` re-enables an endpoint we disabled after repeated failures, `enabled: false` pauses it.", "tags": [ "Webhook endpoints" ], "x-required-scope": "webhooks:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Update a webhook endpoint", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "example": { "object": "webhook_endpoint", "id": "We9pL3kJ6hG1fD4s", "url": "https://example.com/webhooks/pdfbetter", "description": "Production", "events": [ "signature_request.completed", "form.response_created" ], "status": "enabled", "disabledReason": null, "failingSince": null, "createdAt": "2026-10-15T09:30:00.000Z", "updatedAt": "2026-10-15T09:30:00.000Z" } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 8, "maxLength": 2048 }, "events": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "signature_request.sent", "signature_request.viewed", "signature_request.signed", "signature_request.declined", "signature_request.completed", "signature_request.canceled", "signature_request.expired", "form.response_created", "document.exported", "bulk_job.completed", "workflow.run.awaiting_approval", "workflow.run.succeeded", "workflow.run.failed", "workflow.run.export_ready", "workflow.run.webhook" ] }, { "type": "string", "const": "*" } ] } }, "description": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "enabled": { "description": "true re-enables an endpoint that was disabled after repeated failures", "type": "boolean" } }, "additionalProperties": false }, "example": { "enabled": true } } } } }, "delete": { "operationId": "deleteWebhookEndpoint", "summary": "Delete a webhook endpoint", "description": "Stops deliveries immediately, including queued retries.", "tags": [ "Webhook endpoints" ], "x-required-scope": "webhooks:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete a webhook endpoint", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "object": "webhook_endpoint", "id": "We9pL3kJ6hG1fD4s", "deleted": true } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook-endpoints/{id}/rotate-secret/": { "post": { "operationId": "rotateWebhookSecret", "summary": "Rotate the signing secret", "description": "Returns a new secret, effective immediately — deploy it to your receiver right away. The old secret stops verifying.", "tags": [ "Webhook endpoints" ], "x-required-scope": "webhooks:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rotate the signing secret", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "example": { "object": "webhook_endpoint", "id": "We9pL3kJ6hG1fD4s", "url": "https://example.com/webhooks/pdfbetter", "description": "Production", "events": [ "signature_request.completed", "form.response_created" ], "status": "enabled", "disabledReason": null, "failingSince": null, "createdAt": "2026-10-15T09:30:00.000Z", "updatedAt": "2026-10-15T09:30:00.000Z", "secret": "whsec_…shown once…" } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook-endpoints/{id}/test/": { "post": { "operationId": "testWebhookEndpoint", "summary": "Send a test event", "description": "Queues a signed `ping` event to this endpoint (same signing, retries and timeout as real events).", "tags": [ "Webhook endpoints" ], "x-required-scope": "webhooks:write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "Send a test event", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTest" }, "example": { "object": "webhook_test", "eventId": "evt_1aB2cD3eF4gH5iJ6kL7m", "deliveryId": "Dl3vR8yT2uI5oP9a" } } } }, "400": { "description": "Invalid request (see `error.details.issues`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Your plan doesn't include this (API access needs Business) or a monthly allowance is used up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The API key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (or not yours)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited — see RateLimit-* and Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "signature_request.sent": { "post": { "summary": "signature_request.sent event", "description": "Signed with `PDFBetter-Signature: t=,v1=`. Respond with any 2xx within 10 seconds.", "parameters": [ { "name": "PDFBetter-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; use it to de-duplicate" }, "type": { "type": "string", "const": "signature_request.sent" }, "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unix seconds" }, "data": { "type": "object", "properties": { "signatureRequest": { "type": "object", "properties": { "object": { "type": "string", "const": "signature_request" }, "id": { "type": "string" }, "documentId": { "type": "string" }, "title": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "sent", "completed", "declined", "canceled", "expired" ] }, "routing": { "type": "string", "enum": [ "sequential", "parallel" ] }, "reminderEveryDays": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "fieldCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasCompletedFile": { "type": "boolean" }, "hasCertificate": { "type": "boolean" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ] }, "order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "sent", "viewed", "signed", "declined" ] }, "authMethod": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "viewedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declineReason": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role", "order", "status", "authMethod", "sentAt", "viewedAt", "signedAt", "declinedAt", "declineReason" ], "additionalProperties": false } } }, "required": [ "object", "id", "documentId", "title", "message", "status", "routing", "reminderEveryDays", "expiresAt", "sentAt", "completedAt", "createdAt", "fieldCount", "hasCompletedFile", "hasCertificate", "recipients" ], "additionalProperties": false }, "recipient": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ] }, "order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "sent", "viewed", "signed", "declined" ] }, "authMethod": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "viewedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declineReason": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role", "order", "status", "authMethod", "sentAt", "viewedAt", "signedAt", "declinedAt", "declineReason" ], "additionalProperties": false }, { "type": "null" } ], "description": "The recipient who acted (viewed/signed/declined); null otherwise" } }, "required": [ "signatureRequest", "recipient" ], "additionalProperties": false } }, "required": [ "id", "type", "created", "data" ], "additionalProperties": false } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else (or no answer in 10 s) is retried." } } } }, "signature_request.viewed": { "post": { "summary": "signature_request.viewed event", "description": "Signed with `PDFBetter-Signature: t=,v1=`. Respond with any 2xx within 10 seconds.", "parameters": [ { "name": "PDFBetter-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; use it to de-duplicate" }, "type": { "type": "string", "const": "signature_request.viewed" }, "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unix seconds" }, "data": { "type": "object", "properties": { "signatureRequest": { "type": "object", "properties": { "object": { "type": "string", "const": "signature_request" }, "id": { "type": "string" }, "documentId": { "type": "string" }, "title": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "sent", "completed", "declined", "canceled", "expired" ] }, "routing": { "type": "string", "enum": [ "sequential", "parallel" ] }, "reminderEveryDays": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "fieldCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasCompletedFile": { "type": "boolean" }, "hasCertificate": { "type": "boolean" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ] }, "order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "sent", "viewed", "signed", "declined" ] }, "authMethod": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "viewedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declineReason": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role", "order", "status", "authMethod", "sentAt", "viewedAt", "signedAt", "declinedAt", "declineReason" ], "additionalProperties": false } } }, "required": [ "object", "id", "documentId", "title", "message", "status", "routing", "reminderEveryDays", "expiresAt", "sentAt", "completedAt", "createdAt", "fieldCount", "hasCompletedFile", "hasCertificate", "recipients" ], "additionalProperties": false }, "recipient": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ] }, "order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "sent", "viewed", "signed", "declined" ] }, "authMethod": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "viewedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declineReason": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role", "order", "status", "authMethod", "sentAt", "viewedAt", "signedAt", "declinedAt", "declineReason" ], "additionalProperties": false }, { "type": "null" } ], "description": "The recipient who acted (viewed/signed/declined); null otherwise" } }, "required": [ "signatureRequest", "recipient" ], "additionalProperties": false } }, "required": [ "id", "type", "created", "data" ], "additionalProperties": false } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else (or no answer in 10 s) is retried." } } } }, "signature_request.signed": { "post": { "summary": "signature_request.signed event", "description": "Signed with `PDFBetter-Signature: t=,v1=`. Respond with any 2xx within 10 seconds.", "parameters": [ { "name": "PDFBetter-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; use it to de-duplicate" }, "type": { "type": "string", "const": "signature_request.signed" }, "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unix seconds" }, "data": { "type": "object", "properties": { "signatureRequest": { "type": "object", "properties": { "object": { "type": "string", "const": "signature_request" }, "id": { "type": "string" }, "documentId": { "type": "string" }, "title": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "sent", "completed", "declined", "canceled", "expired" ] }, "routing": { "type": "string", "enum": [ "sequential", "parallel" ] }, "reminderEveryDays": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "fieldCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasCompletedFile": { "type": "boolean" }, "hasCertificate": { "type": "boolean" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ] }, "order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "sent", "viewed", "signed", "declined" ] }, "authMethod": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "viewedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declineReason": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role", "order", "status", "authMethod", "sentAt", "viewedAt", "signedAt", "declinedAt", "declineReason" ], "additionalProperties": false } } }, "required": [ "object", "id", "documentId", "title", "message", "status", "routing", "reminderEveryDays", "expiresAt", "sentAt", "completedAt", "createdAt", "fieldCount", "hasCompletedFile", "hasCertificate", "recipients" ], "additionalProperties": false }, "recipient": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ] }, "order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "sent", "viewed", "signed", "declined" ] }, "authMethod": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "viewedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declineReason": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role", "order", "status", "authMethod", "sentAt", "viewedAt", "signedAt", "declinedAt", "declineReason" ], "additionalProperties": false }, { "type": "null" } ], "description": "The recipient who acted (viewed/signed/declined); null otherwise" } }, "required": [ "signatureRequest", "recipient" ], "additionalProperties": false } }, "required": [ "id", "type", "created", "data" ], "additionalProperties": false }, "example": { "id": "evt_8aB3cD5eF7gH9iJ1kL2m", "type": "signature_request.signed", "created": 1792143000, "data": { "signatureRequest": { "object": "signature_request", "id": "Vb8nQ2wE5tYu1IoP", "documentId": "Xq3T9vLmA2pR7sKd", "title": "Vendor agreement", "message": "Please sign by Friday.", "status": "sent", "routing": "sequential", "reminderEveryDays": 3, "expiresAt": "2026-11-14T09:30:00.000Z", "sentAt": "2026-10-15T09:30:00.000Z", "completedAt": null, "createdAt": "2026-10-15T09:30:00.000Z", "fieldCount": 2, "hasCompletedFile": false, "hasCertificate": false, "recipients": [ { "id": "Lm4kJ7hG2fD9sA3q", "name": "Dana Smith", "email": "dana@example.com", "role": "signer", "order": 1, "status": "sent", "authMethod": "email_link", "sentAt": "2026-10-15T09:30:00.000Z", "viewedAt": null, "signedAt": null, "declinedAt": null, "declineReason": null } ] }, "recipient": { "id": "Lm4kJ7hG2fD9sA3q", "name": "Dana Smith", "email": "dana@example.com", "role": "signer", "order": 1, "status": "signed", "authMethod": "email_link", "sentAt": "2026-10-15T09:30:00.000Z", "viewedAt": null, "signedAt": "2026-10-15T09:30:00.000Z", "declinedAt": null, "declineReason": null } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else (or no answer in 10 s) is retried." } } } }, "signature_request.declined": { "post": { "summary": "signature_request.declined event", "description": "Signed with `PDFBetter-Signature: t=,v1=`. Respond with any 2xx within 10 seconds.", "parameters": [ { "name": "PDFBetter-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; use it to de-duplicate" }, "type": { "type": "string", "const": "signature_request.declined" }, "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unix seconds" }, "data": { "type": "object", "properties": { "signatureRequest": { "type": "object", "properties": { "object": { "type": "string", "const": "signature_request" }, "id": { "type": "string" }, "documentId": { "type": "string" }, "title": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "sent", "completed", "declined", "canceled", "expired" ] }, "routing": { "type": "string", "enum": [ "sequential", "parallel" ] }, "reminderEveryDays": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "fieldCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasCompletedFile": { "type": "boolean" }, "hasCertificate": { "type": "boolean" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ] }, "order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "sent", "viewed", "signed", "declined" ] }, "authMethod": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "viewedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declineReason": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role", "order", "status", "authMethod", "sentAt", "viewedAt", "signedAt", "declinedAt", "declineReason" ], "additionalProperties": false } } }, "required": [ "object", "id", "documentId", "title", "message", "status", "routing", "reminderEveryDays", "expiresAt", "sentAt", "completedAt", "createdAt", "fieldCount", "hasCompletedFile", "hasCertificate", "recipients" ], "additionalProperties": false }, "recipient": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ] }, "order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "sent", "viewed", "signed", "declined" ] }, "authMethod": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "viewedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declineReason": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role", "order", "status", "authMethod", "sentAt", "viewedAt", "signedAt", "declinedAt", "declineReason" ], "additionalProperties": false }, { "type": "null" } ], "description": "The recipient who acted (viewed/signed/declined); null otherwise" } }, "required": [ "signatureRequest", "recipient" ], "additionalProperties": false } }, "required": [ "id", "type", "created", "data" ], "additionalProperties": false } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else (or no answer in 10 s) is retried." } } } }, "signature_request.completed": { "post": { "summary": "signature_request.completed event", "description": "Signed with `PDFBetter-Signature: t=,v1=`. Respond with any 2xx within 10 seconds.", "parameters": [ { "name": "PDFBetter-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; use it to de-duplicate" }, "type": { "type": "string", "const": "signature_request.completed" }, "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unix seconds" }, "data": { "type": "object", "properties": { "signatureRequest": { "type": "object", "properties": { "object": { "type": "string", "const": "signature_request" }, "id": { "type": "string" }, "documentId": { "type": "string" }, "title": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "sent", "completed", "declined", "canceled", "expired" ] }, "routing": { "type": "string", "enum": [ "sequential", "parallel" ] }, "reminderEveryDays": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "fieldCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasCompletedFile": { "type": "boolean" }, "hasCertificate": { "type": "boolean" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ] }, "order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "sent", "viewed", "signed", "declined" ] }, "authMethod": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "viewedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declineReason": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role", "order", "status", "authMethod", "sentAt", "viewedAt", "signedAt", "declinedAt", "declineReason" ], "additionalProperties": false } } }, "required": [ "object", "id", "documentId", "title", "message", "status", "routing", "reminderEveryDays", "expiresAt", "sentAt", "completedAt", "createdAt", "fieldCount", "hasCompletedFile", "hasCertificate", "recipients" ], "additionalProperties": false }, "recipient": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ] }, "order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "sent", "viewed", "signed", "declined" ] }, "authMethod": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "viewedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declineReason": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role", "order", "status", "authMethod", "sentAt", "viewedAt", "signedAt", "declinedAt", "declineReason" ], "additionalProperties": false }, { "type": "null" } ], "description": "The recipient who acted (viewed/signed/declined); null otherwise" } }, "required": [ "signatureRequest", "recipient" ], "additionalProperties": false } }, "required": [ "id", "type", "created", "data" ], "additionalProperties": false }, "example": { "id": "evt_4fJ2kL9mN1pQ7rS3tU6v", "type": "signature_request.completed", "created": 1792143000, "data": { "signatureRequest": { "object": "signature_request", "id": "Vb8nQ2wE5tYu1IoP", "documentId": "Xq3T9vLmA2pR7sKd", "title": "Vendor agreement", "message": "Please sign by Friday.", "status": "completed", "routing": "sequential", "reminderEveryDays": 3, "expiresAt": "2026-11-14T09:30:00.000Z", "sentAt": "2026-10-15T09:30:00.000Z", "completedAt": "2026-10-15T09:30:00.000Z", "createdAt": "2026-10-15T09:30:00.000Z", "fieldCount": 2, "hasCompletedFile": false, "hasCertificate": false, "recipients": [ { "id": "Lm4kJ7hG2fD9sA3q", "name": "Dana Smith", "email": "dana@example.com", "role": "signer", "order": 1, "status": "signed", "authMethod": "email_link", "sentAt": "2026-10-15T09:30:00.000Z", "viewedAt": null, "signedAt": "2026-10-15T09:30:00.000Z", "declinedAt": null, "declineReason": null } ] }, "recipient": null } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else (or no answer in 10 s) is retried." } } } }, "signature_request.canceled": { "post": { "summary": "signature_request.canceled event", "description": "Signed with `PDFBetter-Signature: t=,v1=`. Respond with any 2xx within 10 seconds.", "parameters": [ { "name": "PDFBetter-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; use it to de-duplicate" }, "type": { "type": "string", "const": "signature_request.canceled" }, "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unix seconds" }, "data": { "type": "object", "properties": { "signatureRequest": { "type": "object", "properties": { "object": { "type": "string", "const": "signature_request" }, "id": { "type": "string" }, "documentId": { "type": "string" }, "title": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "sent", "completed", "declined", "canceled", "expired" ] }, "routing": { "type": "string", "enum": [ "sequential", "parallel" ] }, "reminderEveryDays": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "fieldCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasCompletedFile": { "type": "boolean" }, "hasCertificate": { "type": "boolean" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ] }, "order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "sent", "viewed", "signed", "declined" ] }, "authMethod": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "viewedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declineReason": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role", "order", "status", "authMethod", "sentAt", "viewedAt", "signedAt", "declinedAt", "declineReason" ], "additionalProperties": false } } }, "required": [ "object", "id", "documentId", "title", "message", "status", "routing", "reminderEveryDays", "expiresAt", "sentAt", "completedAt", "createdAt", "fieldCount", "hasCompletedFile", "hasCertificate", "recipients" ], "additionalProperties": false }, "recipient": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ] }, "order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "sent", "viewed", "signed", "declined" ] }, "authMethod": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "viewedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declineReason": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role", "order", "status", "authMethod", "sentAt", "viewedAt", "signedAt", "declinedAt", "declineReason" ], "additionalProperties": false }, { "type": "null" } ], "description": "The recipient who acted (viewed/signed/declined); null otherwise" } }, "required": [ "signatureRequest", "recipient" ], "additionalProperties": false } }, "required": [ "id", "type", "created", "data" ], "additionalProperties": false } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else (or no answer in 10 s) is retried." } } } }, "signature_request.expired": { "post": { "summary": "signature_request.expired event", "description": "Signed with `PDFBetter-Signature: t=,v1=`. Respond with any 2xx within 10 seconds.", "parameters": [ { "name": "PDFBetter-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; use it to de-duplicate" }, "type": { "type": "string", "const": "signature_request.expired" }, "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unix seconds" }, "data": { "type": "object", "properties": { "signatureRequest": { "type": "object", "properties": { "object": { "type": "string", "const": "signature_request" }, "id": { "type": "string" }, "documentId": { "type": "string" }, "title": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "sent", "completed", "declined", "canceled", "expired" ] }, "routing": { "type": "string", "enum": [ "sequential", "parallel" ] }, "reminderEveryDays": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "fieldCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasCompletedFile": { "type": "boolean" }, "hasCertificate": { "type": "boolean" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ] }, "order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "sent", "viewed", "signed", "declined" ] }, "authMethod": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "viewedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declineReason": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role", "order", "status", "authMethod", "sentAt", "viewedAt", "signedAt", "declinedAt", "declineReason" ], "additionalProperties": false } } }, "required": [ "object", "id", "documentId", "title", "message", "status", "routing", "reminderEveryDays", "expiresAt", "sentAt", "completedAt", "createdAt", "fieldCount", "hasCompletedFile", "hasCertificate", "recipients" ], "additionalProperties": false }, "recipient": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ] }, "order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "sent", "viewed", "signed", "declined" ] }, "authMethod": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "viewedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declineReason": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role", "order", "status", "authMethod", "sentAt", "viewedAt", "signedAt", "declinedAt", "declineReason" ], "additionalProperties": false }, { "type": "null" } ], "description": "The recipient who acted (viewed/signed/declined); null otherwise" } }, "required": [ "signatureRequest", "recipient" ], "additionalProperties": false } }, "required": [ "id", "type", "created", "data" ], "additionalProperties": false } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else (or no answer in 10 s) is retried." } } } }, "form.response_created": { "post": { "summary": "form.response_created event", "description": "Signed with `PDFBetter-Signature: t=,v1=`. Respond with any 2xx within 10 seconds.", "parameters": [ { "name": "PDFBetter-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; use it to de-duplicate" }, "type": { "type": "string", "const": "form.response_created" }, "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unix seconds" }, "data": { "type": "object", "properties": { "form": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, "response": { "type": "object", "properties": { "id": { "type": "string" }, "edition": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "respondentEmail": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" } }, "required": [ "id", "edition", "respondentEmail", "createdAt" ], "additionalProperties": false } }, "required": [ "form", "response" ], "additionalProperties": false } }, "required": [ "id", "type", "created", "data" ], "additionalProperties": false }, "example": { "id": "evt_2nO4pQ6rS8tU0vW1xY3z", "type": "form.response_created", "created": 1792143000, "data": { "form": { "id": "Fo7mR2tQ9wZp4LxN", "title": "Event registration" }, "response": { "id": "Rs5tY8uI1oP3aS6d", "edition": 2, "respondentEmail": "sam@example.com", "createdAt": "2026-10-15T09:30:00.000Z" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else (or no answer in 10 s) is retried." } } } }, "document.exported": { "post": { "summary": "document.exported event", "description": "Signed with `PDFBetter-Signature: t=,v1=`. Respond with any 2xx within 10 seconds.", "parameters": [ { "name": "PDFBetter-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; use it to de-duplicate" }, "type": { "type": "string", "const": "document.exported" }, "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unix seconds" }, "data": { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, "export": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "flatten": { "type": "boolean" } }, "required": [ "id", "fileName", "size", "flatten" ], "additionalProperties": false } }, "required": [ "document", "export" ], "additionalProperties": false } }, "required": [ "id", "type", "created", "data" ], "additionalProperties": false }, "example": { "id": "evt_6bC8dE0fG2hI4jK5lM7n", "type": "document.exported", "created": 1792143000, "data": { "document": { "id": "Xq3T9vLmA2pR7sKd", "title": "Vendor agreement" }, "export": { "id": "Ex4mP1eQ7rT2yU9i", "fileName": "Vendor agreement.pdf", "size": 201554, "flatten": true } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else (or no answer in 10 s) is retried." } } } }, "bulk_job.completed": { "post": { "summary": "bulk_job.completed event", "description": "Signed with `PDFBetter-Signature: t=,v1=`. Respond with any 2xx within 10 seconds.", "parameters": [ { "name": "PDFBetter-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; use it to de-duplicate" }, "type": { "type": "string", "const": "bulk_job.completed" }, "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unix seconds" }, "data": { "type": "object", "properties": { "job": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "bulk_fill" }, "documentId": { "type": "string" }, "status": { "type": "string", "enum": [ "succeeded", "failed" ] }, "rowCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "succeededCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failedCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "type", "documentId", "status", "rowCount", "succeededCount", "failedCount" ], "additionalProperties": false } }, "required": [ "job" ], "additionalProperties": false } }, "required": [ "id", "type", "created", "data" ], "additionalProperties": false }, "example": { "id": "evt_9oP1qR3sT5uV7wX8yZ0a", "type": "bulk_job.completed", "created": 1792143000, "data": { "job": { "id": "Jb2nM5qW8eR1tY4u", "type": "bulk_fill", "documentId": "Xq3T9vLmA2pR7sKd", "status": "succeeded", "rowCount": 120, "succeededCount": 119, "failedCount": 1 } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else (or no answer in 10 s) is retried." } } } }, "workflow.run.awaiting_approval": { "post": { "summary": "workflow.run.awaiting_approval event", "description": "Signed with `PDFBetter-Signature: t=,v1=`. Respond with any 2xx within 10 seconds.", "parameters": [ { "name": "PDFBetter-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; use it to de-duplicate" }, "type": { "type": "string", "const": "workflow.run.awaiting_approval" }, "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unix seconds" }, "data": { "type": "object", "properties": { "run": { "type": "object", "properties": { "id": { "type": "string" }, "workflowId": { "type": "string" }, "documentId": { "description": "null when the document was deleted", "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "awaiting_approval", "succeeded", "failed" ] }, "step": { "anyOf": [ { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "1-based step position" }, "kind": { "type": "string", "enum": [ "ocr", "extract", "review", "export", "summarize", "redact_suggest", "webhook", "add_to_workspace" ] }, "label": { "type": "string" } }, "required": [ "index", "kind", "label" ], "additionalProperties": false }, { "type": "null" } ], "description": "The step the run stopped at (the review step, the failing step, or the last step)" }, "error": { "description": "Why the run failed (`workflow.run.failed` only); null otherwise", "type": [ "string", "null" ] }, "url": { "type": "string", "description": "The run in the PDFBetter app" } }, "required": [ "id", "workflowId", "documentId", "status", "step", "error", "url" ], "additionalProperties": false } }, "required": [ "run" ], "additionalProperties": false } }, "required": [ "id", "type", "created", "data" ], "additionalProperties": false }, "example": { "id": "evt_1qW3eR5tY7uI9oP0aS2d", "type": "workflow.run.awaiting_approval", "created": 1792143000, "data": { "run": { "id": "Wr7nB4vC9xZ2mL5k", "workflowId": "Wf3kR8tY1uI6oP2a", "documentId": "Xq3T9vLmA2pR7sKd", "status": "awaiting_approval", "step": { "index": 3, "kind": "review", "label": "Review" }, "error": null, "url": "https://pdfbetter.com/app/workflows/?run=Wr7nB4vC9xZ2mL5k" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else (or no answer in 10 s) is retried." } } } }, "workflow.run.succeeded": { "post": { "summary": "workflow.run.succeeded event", "description": "Signed with `PDFBetter-Signature: t=,v1=`. Respond with any 2xx within 10 seconds.", "parameters": [ { "name": "PDFBetter-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; use it to de-duplicate" }, "type": { "type": "string", "const": "workflow.run.succeeded" }, "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unix seconds" }, "data": { "type": "object", "properties": { "run": { "type": "object", "properties": { "id": { "type": "string" }, "workflowId": { "type": "string" }, "documentId": { "description": "null when the document was deleted", "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "awaiting_approval", "succeeded", "failed" ] }, "step": { "anyOf": [ { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "1-based step position" }, "kind": { "type": "string", "enum": [ "ocr", "extract", "review", "export", "summarize", "redact_suggest", "webhook", "add_to_workspace" ] }, "label": { "type": "string" } }, "required": [ "index", "kind", "label" ], "additionalProperties": false }, { "type": "null" } ], "description": "The step the run stopped at (the review step, the failing step, or the last step)" }, "error": { "description": "Why the run failed (`workflow.run.failed` only); null otherwise", "type": [ "string", "null" ] }, "url": { "type": "string", "description": "The run in the PDFBetter app" } }, "required": [ "id", "workflowId", "documentId", "status", "step", "error", "url" ], "additionalProperties": false } }, "required": [ "run" ], "additionalProperties": false } }, "required": [ "id", "type", "created", "data" ], "additionalProperties": false }, "example": { "id": "evt_3sD5fG7hJ9kL1zX2cV4b", "type": "workflow.run.succeeded", "created": 1792143000, "data": { "run": { "id": "Wr7nB4vC9xZ2mL5k", "workflowId": "Wf3kR8tY1uI6oP2a", "documentId": "Xq3T9vLmA2pR7sKd", "status": "succeeded", "step": { "index": 4, "kind": "export", "label": "Export" }, "error": null, "url": "https://pdfbetter.com/app/workflows/?run=Wr7nB4vC9xZ2mL5k" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else (or no answer in 10 s) is retried." } } } }, "workflow.run.failed": { "post": { "summary": "workflow.run.failed event", "description": "Signed with `PDFBetter-Signature: t=,v1=`. Respond with any 2xx within 10 seconds.", "parameters": [ { "name": "PDFBetter-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; use it to de-duplicate" }, "type": { "type": "string", "const": "workflow.run.failed" }, "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unix seconds" }, "data": { "type": "object", "properties": { "run": { "type": "object", "properties": { "id": { "type": "string" }, "workflowId": { "type": "string" }, "documentId": { "description": "null when the document was deleted", "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "awaiting_approval", "succeeded", "failed" ] }, "step": { "anyOf": [ { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "1-based step position" }, "kind": { "type": "string", "enum": [ "ocr", "extract", "review", "export", "summarize", "redact_suggest", "webhook", "add_to_workspace" ] }, "label": { "type": "string" } }, "required": [ "index", "kind", "label" ], "additionalProperties": false }, { "type": "null" } ], "description": "The step the run stopped at (the review step, the failing step, or the last step)" }, "error": { "description": "Why the run failed (`workflow.run.failed` only); null otherwise", "type": [ "string", "null" ] }, "url": { "type": "string", "description": "The run in the PDFBetter app" } }, "required": [ "id", "workflowId", "documentId", "status", "step", "error", "url" ], "additionalProperties": false } }, "required": [ "run" ], "additionalProperties": false } }, "required": [ "id", "type", "created", "data" ], "additionalProperties": false }, "example": { "id": "evt_5nM7bV9cX1zA3sD4fG6h", "type": "workflow.run.failed", "created": 1792143000, "data": { "run": { "id": "Wr7nB4vC9xZ2mL5k", "workflowId": "Wf3kR8tY1uI6oP2a", "documentId": "Xq3T9vLmA2pR7sKd", "status": "failed", "step": { "index": 2, "kind": "extract", "label": "Extract data" }, "error": "Extract data: You're out of AI credits this month.", "url": "https://pdfbetter.com/app/workflows/?run=Wr7nB4vC9xZ2mL5k" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else (or no answer in 10 s) is retried." } } } }, "workflow.run.export_ready": { "post": { "summary": "workflow.run.export_ready event", "description": "Signed with `PDFBetter-Signature: t=,v1=`. Respond with any 2xx within 10 seconds.", "parameters": [ { "name": "PDFBetter-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; use it to de-duplicate" }, "type": { "type": "string", "const": "workflow.run.export_ready" }, "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unix seconds" }, "data": { "type": "object", "properties": { "run": { "type": "object", "properties": { "id": { "type": "string" }, "workflowId": { "type": "string" }, "documentId": { "type": "string" } }, "required": [ "id", "workflowId", "documentId" ], "additionalProperties": false }, "export": { "type": "object", "properties": { "fileName": { "type": "string" }, "mime": { "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string", "description": "Download link, valid 24 hours" }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" } }, "required": [ "fileName", "mime", "size", "url", "expiresAt" ], "additionalProperties": false } }, "required": [ "run", "export" ], "additionalProperties": false } }, "required": [ "id", "type", "created", "data" ], "additionalProperties": false }, "example": { "id": "evt_7jK9lZ1xC3vB5nM6qW8e", "type": "workflow.run.export_ready", "created": 1792143000, "data": { "run": { "id": "Wr7nB4vC9xZ2mL5k", "workflowId": "Wf3kR8tY1uI6oP2a", "documentId": "Xq3T9vLmA2pR7sKd" }, "export": { "fileName": "Vendor agreement.csv", "mime": "text/csv", "size": 2418, "url": "https://files.pdfbetter.com/…signed-url…", "expiresAt": "2026-10-16T09:30:00.000Z" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else (or no answer in 10 s) is retried." } } } }, "workflow.run.webhook": { "post": { "summary": "workflow.run.webhook event", "description": "Signed with `PDFBetter-Signature: t=,v1=`. Respond with any 2xx within 10 seconds.", "parameters": [ { "name": "PDFBetter-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; use it to de-duplicate" }, "type": { "type": "string", "const": "workflow.run.webhook" }, "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unix seconds" }, "data": { "type": "object", "properties": { "name": { "type": "string", "description": "The event name you gave the Send webhook step (e.g. `invoice.ready`)" }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "workflowId": { "type": "string" }, "documentId": { "type": "string" }, "step": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "1-based position of the webhook step" } }, "required": [ "id", "workflowId", "documentId", "step" ], "additionalProperties": false } }, "required": [ "name", "run" ], "additionalProperties": false } }, "required": [ "id", "type", "created", "data" ], "additionalProperties": false }, "example": { "id": "evt_9rT1yU3iO5pA7sD8fG0h", "type": "workflow.run.webhook", "created": 1792143000, "data": { "name": "invoice.ready", "run": { "id": "Wr7nB4vC9xZ2mL5k", "workflowId": "Wf3kR8tY1uI6oP2a", "documentId": "Xq3T9vLmA2pR7sKd", "step": 3 } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else (or no answer in 10 s) is retried." } } } }, "ping": { "post": { "summary": "ping event", "description": "Signed with `PDFBetter-Signature: t=,v1=`. Respond with any 2xx within 10 seconds.", "parameters": [ { "name": "PDFBetter-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…; use it to de-duplicate" }, "type": { "type": "string", "const": "ping" }, "created": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unix seconds" }, "data": { "type": "object", "properties": { "endpointId": { "type": "string" }, "message": { "type": "string" } }, "required": [ "endpointId", "message" ], "additionalProperties": false } }, "required": [ "id", "type", "created", "data" ], "additionalProperties": false } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else (or no answer in 10 s) is retried." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "pb_live_…", "description": "Create keys in Settings → API keys." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (≤ 255 chars). The first successful response is replayed for 24 hours for the same key and request.", "schema": { "type": "string", "maxLength": 255 } } }, "headers": { "X-Request-Id": { "description": "Quote it when contacting support", "schema": { "type": "string" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "Document": { "type": "object", "properties": { "object": { "type": "string", "const": "document" }, "id": { "type": "string" }, "title": { "type": "string" }, "kind": { "type": "string", "enum": [ "document", "template", "form" ] }, "status": { "type": "string", "enum": [ "draft", "completed", "archived" ] }, "pageCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "tags": { "type": "array", "items": { "type": "string" } }, "folderId": { "type": [ "string", "null" ] }, "sourceName": { "type": [ "string", "null" ] }, "sourceSize": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "createdFromTemplate": { "description": "Library template slug or user template id this document was created from", "type": [ "string", "null" ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" } }, "required": [ "object", "id", "title", "kind", "status", "pageCount", "tags", "folderId", "sourceName", "sourceSize", "createdFromTemplate", "createdAt", "updatedAt" ], "additionalProperties": false }, "Upload": { "type": "object", "properties": { "object": { "type": "string", "const": "upload" }, "id": { "type": "string" }, "url": { "type": "string", "description": "PUT the file bytes here (exact Content-Type and Content-Length)" }, "method": { "type": "string", "const": "PUT" }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" } }, "required": [ "object", "id", "url", "method", "headers", "expiresAt" ], "additionalProperties": false }, "DocumentList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "document" }, "id": { "type": "string" }, "title": { "type": "string" }, "kind": { "type": "string", "enum": [ "document", "template", "form" ] }, "status": { "type": "string", "enum": [ "draft", "completed", "archived" ] }, "pageCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "tags": { "type": "array", "items": { "type": "string" } }, "folderId": { "type": [ "string", "null" ] }, "sourceName": { "type": [ "string", "null" ] }, "sourceSize": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "createdFromTemplate": { "description": "Library template slug or user template id this document was created from", "type": [ "string", "null" ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" } }, "required": [ "object", "id", "title", "kind", "status", "pageCount", "tags", "folderId", "sourceName", "sourceSize", "createdFromTemplate", "createdAt", "updatedAt" ], "additionalProperties": false } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "hasMore", "nextCursor" ], "additionalProperties": false }, "Deleted": { "type": "object", "properties": { "object": { "type": "string" }, "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "object", "id", "deleted" ], "additionalProperties": false }, "FieldList": { "type": "object", "properties": { "object": { "type": "string", "const": "field_list" }, "documentId": { "type": "string" }, "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Document revision; pass as `expectedRevision` to fill safely" }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name you fill by. Radio groups are one entry named after the group." }, "type": { "type": "string", "description": "Model fields: text, number, date, checkbox, radio, dropdown, signature, … PDF fields: text, checkbox, radio, dropdown, optionlist, signature, button" }, "source": { "type": "string", "enum": [ "model", "pdf" ], "description": "`model` = added in PDFBetter; `pdf` = AcroForm field that was already in the uploaded PDF" }, "label": { "type": [ "string", "null" ] }, "required": { "type": "boolean" }, "readOnly": { "type": "boolean" }, "options": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "value": { "type": [ "string", "number", "boolean", "null" ] }, "page": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "1-based page number" }, "multiline": { "type": [ "boolean", "null" ] }, "maxLength": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "name", "type", "source", "label", "required", "readOnly", "options", "value", "page", "multiline", "maxLength" ], "additionalProperties": false } }, "updated": { "description": "Fields changed by this request (fill only)", "type": "array", "items": { "type": "string" } } }, "required": [ "object", "documentId", "revision", "data" ], "additionalProperties": false }, "Export": { "type": "object", "properties": { "object": { "type": "string", "const": "export" }, "id": { "type": "string" }, "url": { "type": "string" }, "fileName": { "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" } }, "required": [ "object", "id", "url", "fileName", "size", "expiresAt" ], "additionalProperties": false }, "Job": { "type": "object", "properties": { "object": { "type": "string", "const": "job" }, "id": { "type": "string" }, "type": { "type": "string", "const": "bulk_fill" }, "documentId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "canceled" ] }, "rowCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "doneCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "succeededCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failedCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "progress": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "0–100" }, "failedRows": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "error": { "type": "string" } }, "required": [ "row", "error" ], "additionalProperties": false } }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "downloads": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fromRow": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "toRow": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "name", "url", "size", "fromRow", "toRow" ], "additionalProperties": false }, "description": "Zip parts (≤ 500 rows each); links valid 15 minutes" } }, "required": [ "object", "id", "type", "documentId", "status", "rowCount", "doneCount", "succeededCount", "failedCount", "progress", "failedRows", "error", "createdAt", "downloads" ], "additionalProperties": false }, "SignatureRequest": { "type": "object", "properties": { "object": { "type": "string", "const": "signature_request" }, "id": { "type": "string" }, "documentId": { "type": "string" }, "title": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "sent", "completed", "declined", "canceled", "expired" ] }, "routing": { "type": "string", "enum": [ "sequential", "parallel" ] }, "reminderEveryDays": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "fieldCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasCompletedFile": { "type": "boolean" }, "hasCertificate": { "type": "boolean" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ] }, "order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "sent", "viewed", "signed", "declined" ] }, "authMethod": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "viewedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declineReason": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role", "order", "status", "authMethod", "sentAt", "viewedAt", "signedAt", "declinedAt", "declineReason" ], "additionalProperties": false } } }, "required": [ "object", "id", "documentId", "title", "message", "status", "routing", "reminderEveryDays", "expiresAt", "sentAt", "completedAt", "createdAt", "fieldCount", "hasCompletedFile", "hasCertificate", "recipients" ], "additionalProperties": false }, "SignatureRequestList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "signature_request" }, "id": { "type": "string" }, "documentId": { "type": "string" }, "title": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "sent", "completed", "declined", "canceled", "expired" ] }, "routing": { "type": "string", "enum": [ "sequential", "parallel" ] }, "reminderEveryDays": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "fieldCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasCompletedFile": { "type": "boolean" }, "hasCertificate": { "type": "boolean" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ] }, "order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "sent", "viewed", "signed", "declined" ] }, "authMethod": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "viewedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declineReason": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role", "order", "status", "authMethod", "sentAt", "viewedAt", "signedAt", "declinedAt", "declineReason" ], "additionalProperties": false } } }, "required": [ "object", "id", "documentId", "title", "message", "status", "routing", "reminderEveryDays", "expiresAt", "sentAt", "completedAt", "createdAt", "fieldCount", "hasCompletedFile", "hasCertificate", "recipients" ], "additionalProperties": false } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "hasMore", "nextCursor" ], "additionalProperties": false }, "SignatureRequestDetail": { "type": "object", "properties": { "object": { "type": "string", "const": "signature_request" }, "id": { "type": "string" }, "documentId": { "type": "string" }, "title": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "sent", "completed", "declined", "canceled", "expired" ] }, "routing": { "type": "string", "enum": [ "sequential", "parallel" ] }, "reminderEveryDays": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "fieldCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasCompletedFile": { "type": "boolean" }, "hasCertificate": { "type": "boolean" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ] }, "order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "sent", "viewed", "signed", "declined" ] }, "authMethod": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "viewedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declineReason": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role", "order", "status", "authMethod", "sentAt", "viewedAt", "signedAt", "declinedAt", "declineReason" ], "additionalProperties": false } }, "timeline": { "type": "array", "items": { "type": "object", "properties": { "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "event": { "type": "string", "description": "created, sent, delivered, viewed, consented, signed, approved, declined, completed, canceled, expired, reminded, …" }, "actorType": { "type": "string" }, "actorEmail": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "seq", "event", "actorType", "actorEmail", "createdAt", "data" ], "additionalProperties": false } } }, "required": [ "object", "id", "documentId", "title", "message", "status", "routing", "reminderEveryDays", "expiresAt", "sentAt", "completedAt", "createdAt", "fieldCount", "hasCompletedFile", "hasCertificate", "recipients", "timeline" ], "additionalProperties": false }, "Reminder": { "type": "object", "properties": { "reminded": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "signatureRequest": { "type": "object", "properties": { "object": { "type": "string", "const": "signature_request" }, "id": { "type": "string" }, "documentId": { "type": "string" }, "title": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "sent", "completed", "declined", "canceled", "expired" ] }, "routing": { "type": "string", "enum": [ "sequential", "parallel" ] }, "reminderEveryDays": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "fieldCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasCompletedFile": { "type": "boolean" }, "hasCertificate": { "type": "boolean" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ] }, "order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "enum": [ "pending", "sent", "viewed", "signed", "declined" ] }, "authMethod": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "viewedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "signedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declinedAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "declineReason": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "role", "order", "status", "authMethod", "sentAt", "viewedAt", "signedAt", "declinedAt", "declineReason" ], "additionalProperties": false } } }, "required": [ "object", "id", "documentId", "title", "message", "status", "routing", "reminderEveryDays", "expiresAt", "sentAt", "completedAt", "createdAt", "fieldCount", "hasCompletedFile", "hasCertificate", "recipients" ], "additionalProperties": false } }, "required": [ "reminded", "signatureRequest" ], "additionalProperties": false }, "FileLink": { "type": "object", "properties": { "object": { "type": "string", "const": "file_link" }, "url": { "type": "string" }, "fileName": { "type": "string" }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" } }, "required": [ "object", "url", "fileName", "expiresAt" ], "additionalProperties": false }, "FormList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "form" }, "id": { "type": "string" }, "documentId": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "live", "paused", "closed" ] }, "edition": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "responseCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fieldCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" } }, "required": [ "object", "id", "documentId", "title", "description", "status", "edition", "responseCount", "fieldCount", "url", "createdAt", "updatedAt" ], "additionalProperties": false } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "hasMore", "nextCursor" ], "additionalProperties": false }, "Form": { "type": "object", "properties": { "object": { "type": "string", "const": "form" }, "id": { "type": "string" }, "documentId": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "live", "paused", "closed" ] }, "edition": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "responseCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fieldCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" } }, "required": [ "object", "id", "documentId", "title", "description", "status", "edition", "responseCount", "fieldCount", "url", "createdAt", "updatedAt" ], "additionalProperties": false }, "FormResponseList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "form_response" }, "id": { "type": "string" }, "formId": { "type": "string" }, "edition": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "respondentEmail": { "type": [ "string", "null" ] }, "values": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] }, "description": "Answers keyed by field name (radio groups by group name). Images and drawn signatures are data URLs." }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "pdf": { "anyOf": [ { "type": "object", "properties": { "object": { "type": "string", "const": "file_link" }, "url": { "type": "string" }, "fileName": { "type": "string" }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" } }, "required": [ "object", "url", "fileName", "expiresAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Filled PDF (single-response endpoint only; link valid 5 minutes)" } }, "required": [ "object", "id", "formId", "edition", "respondentEmail", "values", "createdAt", "pdf" ], "additionalProperties": false } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "hasMore", "nextCursor" ], "additionalProperties": false }, "FormResponse": { "type": "object", "properties": { "object": { "type": "string", "const": "form_response" }, "id": { "type": "string" }, "formId": { "type": "string" }, "edition": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "respondentEmail": { "type": [ "string", "null" ] }, "values": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] }, "description": "Answers keyed by field name (radio groups by group name). Images and drawn signatures are data URLs." }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "pdf": { "anyOf": [ { "type": "object", "properties": { "object": { "type": "string", "const": "file_link" }, "url": { "type": "string" }, "fileName": { "type": "string" }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" } }, "required": [ "object", "url", "fileName", "expiresAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Filled PDF (single-response endpoint only; link valid 5 minutes)" } }, "required": [ "object", "id", "formId", "edition", "respondentEmail", "values", "createdAt", "pdf" ], "additionalProperties": false }, "TemplateList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "template" }, "id": { "type": "string", "description": "Library slug (type `library`) or template document id (type `user`)" }, "type": { "type": "string", "enum": [ "library", "user" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "pageCount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "createdAt": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] } }, "required": [ "object", "id", "type", "name", "description", "category", "pageCount", "createdAt" ], "additionalProperties": false } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "hasMore", "nextCursor" ], "additionalProperties": false }, "WebhookEndpoint": { "type": "object", "properties": { "object": { "type": "string", "const": "webhook_endpoint" }, "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "signature_request.sent", "signature_request.viewed", "signature_request.signed", "signature_request.declined", "signature_request.completed", "signature_request.canceled", "signature_request.expired", "form.response_created", "document.exported", "bulk_job.completed", "workflow.run.awaiting_approval", "workflow.run.succeeded", "workflow.run.failed", "workflow.run.export_ready", "workflow.run.webhook" ] }, { "type": "string", "const": "*" } ] } }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "disabledReason": { "type": [ "string", "null" ] }, "failingSince": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "secret": { "description": "Signing secret — returned only when the endpoint is created or its secret rotated", "type": "string" } }, "required": [ "object", "id", "url", "description", "events", "status", "disabledReason", "failingSince", "createdAt", "updatedAt" ], "additionalProperties": false }, "WebhookEndpointList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "webhook_endpoint" }, "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "anyOf": [ { "type": "string", "enum": [ "signature_request.sent", "signature_request.viewed", "signature_request.signed", "signature_request.declined", "signature_request.completed", "signature_request.canceled", "signature_request.expired", "form.response_created", "document.exported", "bulk_job.completed", "workflow.run.awaiting_approval", "workflow.run.succeeded", "workflow.run.failed", "workflow.run.export_ready", "workflow.run.webhook" ] }, { "type": "string", "const": "*" } ] } }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "disabledReason": { "type": [ "string", "null" ] }, "failingSince": { "anyOf": [ { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp (UTC)" }, "secret": { "description": "Signing secret — returned only when the endpoint is created or its secret rotated", "type": "string" } }, "required": [ "object", "id", "url", "description", "events", "status", "disabledReason", "failingSince", "createdAt", "updatedAt" ], "additionalProperties": false } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "hasMore", "nextCursor" ], "additionalProperties": false }, "WebhookTest": { "type": "object", "properties": { "object": { "type": "string", "const": "webhook_test" }, "eventId": { "type": "string" }, "deliveryId": { "type": "string" } }, "required": [ "object", "eventId", "deliveryId" ], "additionalProperties": false } }, "examples": { "Error": { "value": { "error": { "code": "invalid_fields", "message": "Some values need attention. Nothing was saved.", "details": { "errors": { "company_name": "This field is required." } } } } } } } }