{ "openapi": "3.1.1", "info": { "title": "Signable API", "description": "The Signable API provides secure and efficient access to Signable's electronic signature platform. With this RESTful API, you can send documents for signature, manage templates, track envelope status, and automate your document workflows from within your own applications.\n", "version": "1.0.0", "contact": { "name": "Signable", "email": "help@signable.co.uk" }, "termsOfService": "https://www.signable.co.uk/terms-conditions/", "license": { "name": "Proprietary", "url": "https://www.signable.co.uk/terms-conditions/" }, "x-metadata": { "showLastModified": true } }, "servers": [ { "url": "https://api.signable.co.uk/v1", "description": "Production server" } ], "security": [ { "basicAuth": [] } ], "tags": [ { "name": "Envelopes", "description": "Send, track, and manage documents for e-signature." }, { "name": "Templates", "description": "Create and reuse predefined document templates." }, { "name": "Contacts", "description": "Manage contact details for signers and stakeholders." }, { "name": "Users", "description": "Control user accounts and roles." }, { "name": "Branding", "description": "Customize visual and branding settings for emails." }, { "name": "Settings", "description": "Configure account-wide preferences and defaults." }, { "name": "Partners", "description": "Manage partner integrations." }, { "name": "Embed Sessions", "description": "Create and manage sessions for embedding Signable components in your application." }, { "name": "Webhooks", "description": "Create, read, update, and delete Webhook subscriptions." }, { "name": "Webhook Events", "description": "Definitions for asynchronous event payloads sent by Signable." } ], "webhooks": { "send-envelope": { "post": { "summary": "Envelope sent", "description": "This webhook is triggered after an envelope has been successfully processed and sent. It delivers information about the envelope, the recipient, any additional metadata, and a download URL.\n", "operationId": "receiveSendEnvelopeWebhook", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "envelope_fingerprint": { "type": "string", "description": "A string representing the envelope that was sent", "example": "584ea8b41b0d4c17a96b967433b211e6" }, "envelope_documents": { "type": "string", "description": "A JSON string representing the documents within the envelope", "example": "[{\"document_title\":\"Untitled document\",\"document_fingerprint\":\"584ea8b41b0d4c17a96b967433b211e6\",\"document_pdf\":\"https://api.signableapi.com/shareable/document?t=03cbb315-4f68-400d-a5cc-c2884996d061\",\"document_download\":\"https://api.signableapi.com/shareable/document?t=03cbb315-4f68-400d-a5cc-c2884996d061\"}]" }, "envelope_download": { "type": "string", "format": "uri", "description": "A URL to download the envelope contents", "example": "https://api.signableapi.com/shareable/envelope?t=03cbb315-4f68-400d-a5cc-c2884996d061" }, "contact_id": { "type": "integer", "description": "The ID of the contact the envelope was sent to", "example": 14029945 }, "contact_name": { "type": "string", "description": "The name of the contact the envelope was sent to", "example": "Abby Smith" }, "contact_email": { "type": "string", "format": "email", "description": "The email address of the contact the envelope was sent to", "example": "abby@signable.co.uk" }, "action": { "type": "string", "description": "The action taken. Defaults to `send-envelope`.", "example": "send-envelope" }, "action_date": { "type": "string", "format": "date-time", "description": "The UTC timestamp of when the action occurred", "example": "2025-06-20T15:50:10+00:00" }, "envelope_meta": { "type": "string", "description": "A JSON string of any meta information added when sending the envelope", "example": "" }, "envelope_signing_embed": { "type": "string", "description": "An iframe URL for embedded signing, if enabled", "example": "" } }, "required": [ "envelope_fingerprint", "envelope_documents", "envelope_download", "contact_id", "contact_name", "contact_email", "action", "action_date" ] }, "example": { "envelope_fingerprint": "584ea8b41b0d4c17a96b967433b211e6", "envelope_documents": "[{\"document_title\":\"Untitled document\",\"document_fingerprint\":\"584ea8b41b0d4c17a96b967433b211e6\",\"document_pdf\":\"https://api.signableapi.com/shareable/document?t=03cbb315-4f68-400d-a5cc-c2884996d061\",\"document_download\":\"https://api.signableapi.com/shareable/document?t=03cbb315-4f68-400d-a5cc-c2884996d061\"}]", "envelope_download": "https://api.signableapi.com/shareable/envelope?t=03cbb315-4f68-400d-a5cc-c2884996d061", "envelope_signing_embed": "", "contact_id": 14029945, "contact_name": "Abby Smith", "contact_email": "abby@signable.co.uk", "action": "send-envelope", "action_date": "2025-06-20T15:50:10+00:00", "envelope_meta": "" } } } }, "responses": { "200": { "description": "Acknowledge receipt" } } } }, "signed-envelope": { "post": { "summary": "Envelope signed", "description": "This webhook is triggered when a recipient completes signing an envelope. It includes detailed information about the envelope, signer, documents, custom fields, and signature fingerprint.\n", "operationId": "receiveSignedEnvelopeWebhook", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "envelope_fingerprint": { "type": "string", "description": "A string of the signed envelope", "example": "584ea8b41b0d4c17a96b967433b211e6" }, "envelope_documents": { "type": "string", "description": "JSON string of the documents within the envelope", "example": "[{\"document_title\":\"Make Tests\",\"document_fingerprint\":\"584ea8b41b0d4c17a96b967433b211e6\",\"document_pdf\":\"https://api.signableapi.com/shareable/document?t=03cbb315-4f68-400d-a5cc-c2884996d061\",\"document_download\":\"https://api.signableapi.com/shareable/document?t=03cbb315-4f68-400d-a5cc-c2884996d061\"}]" }, "envelope_fields": { "type": "string", "description": "JSON string of completed fields in the envelope", "example": "[{\"field_id\":458946901,\"field_name\":\"Untitled\",\"field_type\":\"text\",\"field_value\":\"1st Aug\"},{\"field_id\":458946905,\"field_name\":\"Untitled\",\"field_type\":\"text\",\"field_value\":\"hiousfdjp\"}]" }, "envelope_download": { "type": "string", "format": "uri", "description": "URL to download the full signed envelope", "example": "https://api.signableapi.com/shareable/envelope?t=03cbb315-4f68-400d-a5cc-c2884996d061" }, "contact_id": { "type": "integer", "description": "ID of the signer", "example": 7418454 }, "contact_name": { "type": "string", "description": "Name of the signer", "example": "Abby" }, "contact_email": { "type": "string", "format": "email", "description": "Email address of the signer", "example": "abby@signable.co.uk" }, "company_id": { "type": "integer", "description": "ID of the sub-account (company) the envelope belongs to", "example": 64034 }, "user_id": { "type": "integer", "description": "Internal user ID associated with the signing action", "example": 267199 }, "signature_fingerprint": { "type": "string", "description": "Unique fingerprint identifying the signature event", "example": "584ea8b41b0d4c17a96b967433b211e6" }, "client_ip": { "type": "string", "format": "ipv4", "description": "IP address of the device used to sign", "example": "65.179.58.205" }, "envelope_meta": { "type": "string", "description": "A JSON string of any additional metadata attached to the envelope", "example": "" }, "action": { "type": "string", "description": "The action taken. Defaults to `signed-envelope`.", "example": "signed-envelope" }, "action_date": { "type": "string", "format": "date-time", "description": "UTC timestamp of when the signing occurred", "example": "2025-08-01T14:37:47+00:00" } }, "required": [ "envelope_fingerprint", "envelope_documents", "envelope_fields", "envelope_download", "contact_id", "contact_name", "contact_email", "action", "action_date", "signature_fingerprint", "user_id", "client_ip", "company_id" ] }, "example": { "envelope_fingerprint": "584ea8b41b0d4c17a96b967433b211e6", "envelope_documents": "[{\"document_title\":\"Make Tests\",\"document_fingerprint\":\"584ea8b41b0d4c17a96b967433b211e6\",\"document_pdf\":\"https://api.signableapi.com/shareable/document?t=03cbb315-4f68-400d-a5cc-c2884996d061\",\"document_download\":\"https://api.signableapi.com/shareable/document?t=03cbb315-4f68-400d-a5cc-c2884996d061\"}]", "envelope_fields": "[{\"field_id\":458946901,\"field_name\":\"Untitled\",\"field_type\":\"text\",\"field_value\":\"1st Aug\"}]", "envelope_download": "https://api.signableapi.com/shareable/envelope?t=03cbb315-4f68-400d-a5cc-c2884996d061", "contact_id": 7418454, "contact_name": "Abby", "contact_email": "abby@signable.co.uk", "company_id": 64034, "user_id": 267199, "signature_fingerprint": "584ea8b41b0d4c17a96b967433b211e6", "client_ip": "87.177.50.205", "envelope_meta": "", "action": "signed-envelope", "action_date": "2025-08-01T14:37:47+00:00" } } } }, "responses": { "200": { "description": "Acknowledge receipt" } } } }, "cancelled-envelope": { "post": { "summary": "Envelope cancelled", "description": "This webhook is triggered when an envelope is cancelled before completion. It includes the envelope fingerprint, user details, and any metadata associated with the envelope.\n", "operationId": "receiveCancelledEnvelopeWebhook", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "envelope_fingerprint": { "type": "string", "description": "A string representing the cancelled envelope", "example": "584ea8b41b0d4c17a96b967433b211e6" }, "envelope_title": { "type": "string", "description": "The title of the cancelled envelope", "example": "tagstest - Copy" }, "action": { "type": "string", "description": "The action taken. Defaults to `cancelled-envelope`.", "example": "cancelled-envelope" }, "action_date": { "type": "string", "format": "date-time", "description": "The UTC timestamp of when the envelope was cancelled", "example": "2025-08-06T12:59:03+00:00" }, "envelope_meta": { "type": "string", "description": "A JSON string of any meta information associated with the envelope", "example": "" }, "company_id": { "type": "integer", "description": "The ID of the company linked to the envelope", "example": 64034 }, "user_id": { "type": "integer", "description": "The ID of the user who cancelled the envelope", "example": 267199 }, "client_ip": { "type": "string", "format": "ipv4", "description": "The IP address of the user or system that triggered the cancellation", "example": "203.0.113.42" } }, "required": [ "envelope_fingerprint", "envelope_title", "action", "action_date", "company_id", "user_id", "client_ip" ] }, "example": { "envelope_fingerprint": "584ea8b41b0d4c17a96b967433b211e6", "envelope_title": "tagstest - Copy", "action": "cancelled-envelope", "action_date": "2025-08-06T12:59:03+00:00", "envelope_meta": "", "company_id": 64034, "user_id": 267199, "client_ip": "203.0.113.42" } } } }, "responses": { "200": { "description": "Acknowledge receipt" } } } }, "expired-envelope": { "post": { "summary": "Envelope expired", "description": "This webhook is triggered when an envelope expires. It includes basic information about the envelope and the recipient.\n", "operationId": "receiveExpiredEnvelopeWebhook", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "envelope_fingerprint": { "type": "string", "description": "A string identifying the expired envelope", "example": "584ea8b41b0d4c17a96b967433b211e6" }, "envelope_title": { "type": "string", "description": "The title of the expired envelope", "example": "tagstest - Copy" }, "user_id": { "type": "integer", "description": "The ID of the user associated with this event", "example": 267199 }, "action": { "type": "string", "description": "The action taken. Defaults to `expired-envelope`.", "example": "expired-envelope" }, "action_date": { "type": "string", "format": "date-time", "description": "The UTC timestamp of when the envelope expired", "example": "2025-08-07T10:14:26+00:00" }, "company_id": { "type": "integer", "description": "The ID of the company that owns the envelope", "example": 64034 } }, "required": [ "envelope_fingerprint", "envelope_title", "user_id", "action", "action_date", "company_id" ] } } } }, "responses": { "200": { "description": "Acknowledge receipt" } } } }, "signed-envelope-complete": { "post": { "summary": "Envelope signed and complete", "description": "This webhook is triggered when all required parties have completed signing an envelope. It includes the envelope fingerprint, documents, any captured field data, and a download link.\n", "operationId": "receiveSignedEnvelopeCompleteWebhook", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "envelope_fingerprint": { "type": "string", "description": "A string representing the signed envelope", "example": "584ea8b41b0d4c17a96b967433b211e6" }, "envelope_documents": { "type": "string", "description": "A JSON string representing the signed documents within the envelope", "example": "[{\"document_title\":\"Word Doc\",\"document_fingerprint\":\"584ea8b41b0d4c17a96b967433b211e6\",\"document_pdf\":\"https://api.signableapi.com/shareable/document?t=03cbb315-4f68-400d-a5cc-c2884996d061\",\"document_download\":\"https://api.signableapi.com/shareable/document?t=03cbb315-4f68-400d-a5cc-c2884996d061\"}]" }, "envelope_download": { "type": "string", "format": "uri", "description": "A URL to download the completed envelope", "example": "https://api.signableapi.com/shareable/envelope?t=03cbb315-4f68-400d-a5cc-c2884996d061" }, "envelope_fields": { "type": "string", "description": "A JSON string of captured field values within the envelope", "example": "[{\"field_id\":460133805,\"field_name\":\"Untitled\",\"field_type\":\"text\",\"field_value\":\"Test\"}]" }, "envelope_meta": { "type": "string", "description": "A JSON string of any meta information associated with the envelope", "example": "" }, "action": { "type": "string", "description": "The action taken. Defaults to `signed-envelope-complete`.", "example": "signed-envelope-complete" }, "action_date": { "type": "string", "format": "date-time", "description": "The UTC timestamp of when the envelope was fully signed", "example": "2025-08-07T10:14:33+00:00" }, "company_id": { "type": "integer", "description": "The ID of the company associated with the envelope", "example": 64034 }, "user_id": { "type": "integer", "description": "The ID of the user who sent or owns the envelope", "example": 267199 }, "client_ip": { "type": "string", "format": "ipv4", "description": "The IP address of the client that triggered the completion", "example": "203.0.113.17" } }, "required": [ "envelope_fingerprint", "envelope_documents", "envelope_download", "envelope_fields", "action", "action_date", "company_id", "user_id", "client_ip" ] }, "example": { "envelope_fingerprint": "584ea8b41b0d4c17a96b967433b211e6", "envelope_documents": "[{\"document_title\":\"Word Doc\",\"document_fingerprint\":\"584ea8b41b0d4c17a96b967433b211e6\",\"document_pdf\":\"https://api.signableapi.com/shareable/document?t=03cbb315-4f68-400d-a5cc-c2884996d061\",\"document_download\":\"https://api.signableapi.com/shareable/document?t=03cbb315-4f68-400d-a5cc-c2884996d061\"}]", "envelope_download": "https://api.signableapi.com/shareable/envelope?t=03cbb315-4f68-400d-a5cc-c2884996d061", "envelope_fields": "[{\"field_id\":460133805,\"field_name\":\"Untitled\",\"field_type\":\"text\",\"field_value\":\"Test\"}]", "envelope_meta": "", "action": "signed-envelope-complete", "action_date": "2025-08-07T10:14:33+00:00", "company_id": 64034, "user_id": 267199, "client_ip": "203.0.113.17" } } } }, "responses": { "200": { "description": "Acknowledge receipt" } } } }, "rejected-envelope": { "post": { "summary": "Envelope rejected", "description": "This webhook is triggered when a recipient rejects an envelope. It includes details about the envelope, the rejecting contact, and relevant metadata.\n", "operationId": "receiveRejectedEnvelopeWebhook", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "action": { "type": "string", "description": "The action taken. Defaults to `rejected-envelope`.", "example": "rejected-envelope" }, "action_date": { "type": "string", "format": "date-time", "description": "The UTC timestamp of when the action occurred", "example": "2025-08-07T11:10:39+00:00" }, "envelope_fingerprint": { "type": "string", "description": "A string representing the rejected envelope", "example": "584ea8b41b0d4c17a96b967433b211e6" }, "document_id": { "type": "integer", "description": "The ID of the document that was rejected", "example": 0 }, "document_title": { "type": "string", "description": "The title of the rejected document", "example": "Word Doc" }, "contact_id": { "type": "integer", "description": "The ID of the contact who rejected the envelope", "example": 7418454 }, "contact_name": { "type": "string", "description": "The name of the contact who rejected the envelope", "example": "Abby" }, "contact_email": { "type": "string", "format": "email", "description": "The email address of the contact who rejected the envelope", "example": "abby@signable.co.uk" }, "signature_fingerprint": { "type": "string", "description": "A fingerprint identifying the signature session that triggered the rejection", "example": "584ea8b41b0d4c17a96b967433b211e6" }, "envelope_meta": { "type": "string", "description": "A JSON string of any meta information added to the envelope", "example": "" }, "client_ip": { "type": "string", "format": "ipv4", "description": "The IP address from which the rejection was submitted", "example": "203.0.113.42" } }, "required": [ "action", "action_date", "envelope_fingerprint", "document_id", "document_title", "contact_id", "contact_name", "contact_email", "signature_fingerprint", "client_ip" ] } } } }, "responses": { "200": { "description": "Acknowledge receipt" } } } }, "opened-envelope": { "post": { "summary": "Envelope opened", "description": "This webhook is triggered when a recipient opens an envelope. It includes basic information about the envelope, the recipient, and associated documents.\n", "operationId": "receiveOpenedEnvelopeWebhook", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "action": { "type": "string", "description": "The action taken. Defaults to `opened-envelope`.", "example": "opened-envelope" }, "action_date": { "type": "string", "format": "date-time", "description": "The UTC timestamp of when the envelope was opened", "example": "2025-08-07T10:14:26+00:00" }, "company_id": { "type": "integer", "description": "The ID of the company that owns the envelope", "example": 64034 }, "contact_id": { "type": "integer", "description": "The ID of the contact who opened the envelope", "example": 7418454 }, "contact_name": { "type": "string", "description": "The name of the contact who opened the envelope", "example": "Abby" }, "contact_email": { "type": "string", "format": "email", "description": "The email address of the contact who opened the envelope", "example": "abby@signable.co.uk" }, "envelope_fingerprint": { "type": "string", "description": "A string identifying the opened envelope", "example": "584ea8b41b0d4c17a96b967433b211e6" }, "envelope_documents": { "type": "string", "description": "A stringified JSON array of documents in the envelope", "example": "[{\"document_title\":\"Blank Word Doc\",\"document_fingerprint\":\"584ea8b41b0d4c17a96b967433b211e6\",\"document_pdf\":\"https://api.signableapi.com/shareable/document?t=03cbb315-4f68-400d-a5cc-c2884996d061\",\"document_download\":\"https://api.signableapi.com/shareable/document?t=03cbb315-4f68-400d-a5cc-c2884996d061\"}]" }, "envelope_download": { "type": "string", "format": "uri", "description": "A download link for the entire envelope", "example": "https://api.signableapi.com/shareable/envelope?t=03cbb315-4f68-400d-a5cc-c2884996d061" }, "envelope_meta": { "type": "string", "description": "A JSON string of any meta information added to the envelope", "example": "" }, "user_id": { "type": "integer", "description": "The ID of the user associated with this event", "example": 267199 }, "client_ip": { "type": "string", "format": "ipv4", "description": "The IP address from which the envelope was opened", "example": "203.0.113.106" } }, "required": [ "action", "action_date", "company_id", "contact_id", "contact_name", "contact_email", "envelope_fingerprint", "envelope_documents", "envelope_download", "user_id", "client_ip" ] } } } }, "responses": { "200": { "description": "Acknowledge receipt" } } } }, "bounced-envelope": { "post": { "summary": "Envelope email bounced", "description": "Triggered when an email to a signer fails to deliver.\n", "operationId": "receiveBouncedEnvelopeWebhook", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "action": { "type": "string", "description": "The action taken. Defaults to `bounced-envelope`.", "example": "bounced-envelope" }, "action_date": { "type": "string", "format": "date-time", "description": "The UTC timestamp of when the email bounced", "example": "2025-08-07T11:33:03+00:00" }, "company_id": { "type": "integer", "description": "The ID of the company that owns the envelope", "example": 64034 }, "envelope_bounce_email": { "type": "string", "format": "email", "description": "The email address that bounced", "example": "abby@singable.co.uk" }, "envelope_bounce_reason": { "type": "string", "description": "The reason the email failed to deliver", "example": "unable to get mx info: failed to get IPs from PTR record: lookup : unrecognized address" }, "envelope_bounce_url": { "type": "string", "format": "uri", "description": "A link to view the bounce details", "example": "https://app.signable.co.uk/envelope/bounce/584ea8b41b0d4c17a96b967433b211e6/584ea8b41b0d4c17a96b967433b211e6" }, "envelope_fingerprint": { "type": "string", "description": "A string identifying the bounced envelope", "example": "584ea8b41b0d4c17a96b967433b211e6" }, "client_ip": { "type": "string", "format": "ipv4", "description": "The IP address from which the bounce originated", "example": "198.51.100.36" } }, "required": [ "action", "action_date", "company_id", "envelope_bounce_email", "envelope_bounce_reason", "envelope_bounce_url", "envelope_fingerprint", "client_ip" ] } } } }, "responses": { "200": { "description": "Acknowledge receipt" } } } }, "send-envelope-failed": { "post": { "summary": "Envelope send failed", "description": "This webhook is triggered when an envelope fails to send.\n", "operationId": "receiveSendEnvelopeFailedWebhook", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "action": { "type": "string", "description": "The action taken. Defaults to `send-envelope-failed`.", "example": "send-envelope-failed" }, "action_date": { "type": "string", "format": "date-time", "description": "The UTC timestamp of when the action occurred", "example": "2026-03-19T12:39:54+00:00" }, "envelope_fingerprint": { "type": "string", "description": "A string representing the failed envelope", "example": "821e2c9cb2203dec82279efabc4c65633" }, "envelope_meta": { "type": "string", "description": "A JSON string of any meta information added to the envelope", "example": "" }, "client_ip": { "type": "string", "format": "ipv4", "description": "The IP address from which the failed envelope was submitted", "example": "203.0.113.42" } }, "required": [ "action", "action_date", "envelope_fingerprint", "client_ip" ] } } } }, "responses": { "200": { "description": "Acknowledge receipt" } } } }, "verify-envelope-widget": { "post": { "summary": "Widget completed (Awaiting verification)", "description": "This webhook is triggered when a recipient signs an envelope via the widget, but has not yet verified. It includes contact and document details.\n", "operationId": "receiveVerifyEnvelopeWidgetWebhook", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "action": { "type": "string", "description": "The action taken. Defaults to `verify-envelope-widget`.", "example": "verify-envelope-widget" }, "action_date": { "type": "string", "format": "date-time", "description": "The UTC timestamp of when the envelope was signed", "example": "2025-08-07T11:32:54+00:00" }, "company_id": { "type": "integer", "description": "The ID of the company that owns the envelope", "example": 64034 }, "contact_id": { "type": "integer", "description": "The ID of the contact who signed the envelope", "example": 8117397 }, "contact_name": { "type": "string", "description": "The name of the contact who signed the envelope", "example": "Abby" }, "contact_email": { "type": "string", "format": "email", "description": "The email address of the contact who signed the envelope", "example": "abby@signable.co.uk" }, "envelope_fingerprint": { "type": "string", "description": "A string identifying the signed envelope", "example": "584ea8b41b0d4c17a96b967433b211e6" }, "envelope_documents": { "type": "string", "description": "A stringified JSON array of documents in the envelope", "example": "[{\"document_fingerprint\":\"584ea8b41b0d4c17a96b967433b211e6\",\"document_title\":\"Word Doc\",\"document_download\":\"https://api.signableapi.com/shareable/document?t=03cbb315-4f68-400d-a5cc-c2884996d061\"}]" }, "envelope_meta": { "type": "string", "description": "A JSON string of any meta information added to the envelope", "example": "{\"envelope_title\":\"Word Doc\"}" }, "user_id": { "type": "integer", "description": "The ID of the user associated with this event", "example": 0 }, "client_ip": { "type": "string", "format": "ipv4", "description": "The IP address from which the envelope was signed", "example": "203.0.113.123" } }, "required": [ "action", "action_date", "company_id", "contact_id", "contact_name", "contact_email", "envelope_fingerprint", "envelope_documents", "user_id", "client_ip" ] } } } }, "responses": { "200": { "description": "Acknowledge receipt" } } } }, "verified-envelope-widget": { "post": { "summary": "Widget signature verified", "description": "This webhook is triggered when a recipient verifies their signed envelope through the verification email. It includes details about the contact, documents, and verification.\n", "operationId": "receiveVerifiedEnvelopeWidgetWebhook", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "action": { "type": "string", "description": "The action taken. Defaults to `verified-envelope-widget`.", "example": "verified-envelope-widget" }, "action_date": { "type": "string", "format": "date-time", "description": "The UTC timestamp of when the envelope was verified", "example": "2025-08-07T12:10:48+00:00" }, "company_id": { "type": "integer", "description": "The ID of the company that owns the envelope", "example": 64034 }, "contact_id": { "type": "integer", "description": "The ID of the contact who verified the envelope", "example": 8117397 }, "contact_name": { "type": "string", "description": "The name of the contact who verified the envelope", "example": "Abby" }, "contact_email": { "type": "string", "format": "email", "description": "The email address of the contact who verified the envelope", "example": "abby@signable.co.uk" }, "envelope_fingerprint": { "type": "string", "description": "A string identifying the verified envelope", "example": "584ea8b41b0d4c17a96b967433b211e6" }, "envelope_documents": { "type": "string", "description": "A stringified JSON array of documents in the envelope", "example": "[{\"document_title\":\"Word Doc\",\"document_fingerprint\":\"584ea8b41b0d4c17a96b967433b211e6\",\"document_pdf\":\"https://api.signableapi.com/shareable/document?t=03cbb315-4f68-400d-a5cc-c2884996d061\",\"document_download\":\"https://api.signableapi.com/shareable/document?t=03cbb315-4f68-400d-a5cc-c2884996d061\"}]" }, "envelope_download": { "type": "string", "format": "uri", "description": "A download link for the entire envelope", "example": "https://api.signableapi.com/shareable/envelope?t=03cbb315-4f68-400d-a5cc-c2884996d061" }, "envelope_fields": { "type": "string", "description": "A stringified JSON array of fields completed during verification", "example": "[{\"field_id\":460176431,\"field_name\":\"Untitled\",\"field_type\":\"text\",\"field_value\":\"Abby\"}]" }, "envelope_meta": { "type": "string", "description": "A JSON string of any meta information added to the envelope", "example": "{\"envelope_title\":\"Word Doc\"}" }, "signature_fingerprint": { "type": "string", "description": "A string identifying the verification applied", "example": "584ea8b41b0d4c17a96b967433b211e6" }, "client_ip": { "type": "string", "format": "ipv4", "description": "The IP address from which the envelope was verified", "example": "203.0.113.124" } }, "required": [ "action", "action_date", "company_id", "contact_id", "contact_name", "contact_email", "envelope_fingerprint", "envelope_documents", "envelope_download", "signature_fingerprint", "client_ip" ] } } } }, "responses": { "200": { "description": "Acknowledge receipt" } } } }, "add-template": { "post": { "summary": "Template added", "description": "This webhook is triggered when a new template is added to the account. It includes basic information about the template, including its title and fingerprint.\n", "operationId": "receiveAddTemplateWebhook", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "action": { "type": "string", "description": "The action taken. Defaults to `add-template`.", "example": "add-template" }, "action_date": { "type": "string", "format": "date-time", "description": "The UTC timestamp of when the template was added", "example": "2025-08-07T12:36:56+00:00" }, "company_id": { "type": "integer", "description": "The ID of the company that added the template", "example": 64034 }, "template_fingerprint": { "type": "string", "description": "A string identifying the newly added template", "example": "584ea8b41b0d4c17a96b967433b211e6" }, "template_title": { "type": "string", "description": "The title of the added template", "example": "Signable Contract" }, "template_page_total": { "type": "integer", "description": "The number of pages in the template", "example": 5 }, "template_pages": { "type": "array", "description": "An array of page metadata (if available)", "items": { "type": "object" } }, "template_thumbnails": { "type": "array", "description": "An array of thumbnail URLs (if available)", "items": { "type": "string", "format": "uri" } }, "client_ip": { "type": "string", "format": "ipv4", "description": "The IP address from which the template was added", "example": "203.0.113.150" } }, "required": [ "action", "action_date", "company_id", "template_fingerprint", "template_title", "template_page_total", "template_pages", "template_thumbnails", "client_ip" ] } } } }, "responses": { "200": { "description": "Acknowledge receipt" } } } }, "add-contact": { "post": { "summary": "Contact added", "description": "This webhook is triggered when a new contact is added to the account. It includes basic information about the contact and the company that added them.\n", "operationId": "receiveAddContactWebhook", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "action": { "type": "string", "description": "The action taken. Defaults to `add-contact`.", "example": "add-contact" }, "action_date": { "type": "string", "format": "date-time", "description": "The UTC timestamp of when the contact was added", "example": "2025-08-07T12:41:52+00:00" }, "company_id": { "type": "integer", "description": "The ID of the company that added the contact", "example": 64034 }, "contact_id": { "type": "integer", "description": "The ID of the newly added contact", "example": 17499057 }, "contact_name": { "type": "string", "description": "The name of the contact", "example": "Abby" }, "contact_email": { "type": "string", "format": "email", "description": "The email address of the contact", "example": "abby@signable.co.uk" }, "client_ip": { "type": "string", "format": "ipv4", "description": "The IP address from which the contact was added", "example": "203.0.113.150" } }, "required": [ "action", "action_date", "company_id", "contact_id", "contact_name", "contact_email", "client_ip" ] } } } }, "responses": { "200": { "description": "Acknowledge receipt" } } } }, "add-user": { "post": { "summary": "User added", "description": "This webhook is triggered when a new user is added to the account. It includes identifying information about the user and their assigned role.\n", "operationId": "receiveAddUserWebhook", "tags": [ "Webhook Events" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "action": { "type": "string", "description": "The action taken. Defaults to `add-user`.", "example": "add-user" }, "action_date": { "type": "string", "format": "date-time", "description": "The UTC timestamp of when the user was added", "example": "2025-08-07T13:03:39+00:00" }, "company_id": { "type": "integer", "description": "The ID of the company the user was added to", "example": 215769 }, "user_id": { "type": "integer", "description": "The ID of the new user", "example": 840786 }, "user_name": { "type": "string", "description": "The name of the new user", "example": "Abby" }, "user_email": { "type": "string", "format": "email", "description": "The email address of the new user", "example": "abby@signable.co.uk" }, "role": { "type": "string", "description": "The assigned role of the new user", "example": "user" }, "client_ip": { "type": "string", "format": "ipv4", "description": "The IP address from which the user was added", "example": "203.0.113.150" } }, "required": [ "action", "action_date", "company_id", "user_id", "user_name", "user_email", "role", "client_ip" ] } } } }, "responses": { "200": { "description": "Acknowledge receipt" } } } } }, "paths": { "/companies": { "get": { "summary": "List sub-accounts", "description": "Returns a paginated list of sub-accounts associated with the Partner account.\n\nThis endpoint is only available to Signable Partners.\n", "operationId": "getCompanies", "x-contract-group": "CONTRACT:READ:PARTNER", "tags": [ "Partners" ], "parameters": [ { "$ref": "#/components/parameters/OffsetParam" }, { "$ref": "#/components/parameters/LimitParam" } ], "responses": { "200": { "description": "Successful response containing a list of sub-accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyListResponse" }, "examples": { "success": { "$ref": "#/components/examples/CompanyListResponseExample" } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidAuth": { "summary": "Invalid authentication", "value": { "http": 401, "code": 10002, "message": "Authentication failed. Please enter the correct API Key and password." } } } } } } } }, "post": { "summary": "Create a sub-account", "description": "Creates a new sub-account under the Partner account.\n\nThis endpoint is only available to Signable Partners.\n", "operationId": "createCompany", "x-contract-group": "CONTRACT:WRITE:PARTNER", "tags": [ "Partners" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyCreateRequest" }, "examples": { "success": { "$ref": "#/components/examples/CompanyCreateRequestExample" } } } } }, "responses": { "200": { "description": "Sub-account successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyCreateResponse" }, "examples": { "success": { "$ref": "#/components/examples/CompanyCreateResponseExample" } } } } }, "400": { "description": "Invalid sub-account create request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingCompanyName": { "summary": "Missing company_name", "value": { "http": 400, "code": 10350, "message": "The company name is missing. To be able to create a new company, you must provide a name." } }, "missingUserEmail": { "summary": "Missing user_email", "value": { "http": 400, "code": 10351, "message": "The user email is missing. To be able to create a new company, you must provide a user email." } }, "missingUserName": { "summary": "Missing user_name", "value": { "http": 400, "code": 10352, "message": "The user name is missing. To be able to create a new company, you must provide a user name." } }, "duplicateUserEmail": { "summary": "Duplicate user_email", "value": { "http": 400, "code": 10353, "message": "The user email already exists, please use another." } } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidAuth": { "summary": "Invalid authentication", "value": { "http": 401, "code": 10002, "message": "Authentication failed. Please enter the correct API Key and password." } } } } } } } } }, "/companies/{company_id}": { "get": { "summary": "Get a sub-account", "description": "Returns details about a specific sub-account associated with the Partner account.\n\nThis endpoint is only available to Signable Partners.\n", "operationId": "getCompany", "x-contract-group": "CONTRACT:READ:PARTNER", "tags": [ "Partners" ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Unique identifier of the sub-account.", "schema": { "type": "string", "example": "196735" } } ], "responses": { "200": { "description": "Details of the requested sub-account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyGetResponse" }, "examples": { "success": { "$ref": "#/components/examples/CompanyGetResponseExample" } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidAuth": { "summary": "Invalid authentication", "value": { "http": 401, "code": 10002, "message": "Authentication failed. Please enter the correct API Key and password." } } } } } } } }, "put": { "summary": "Update a sub-account", "description": "Updates details of a specific sub-account associated with the authenticated Partner account.\n\nThis endpoint is only available to Signable Partners.\n", "operationId": "updateCompany", "x-contract-group": "CONTRACT:WRITE:PARTNER", "tags": [ "Partners" ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Unique identifier of the sub-account to update.", "schema": { "type": "string", "example": "214821" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyUpdateRequest" }, "examples": { "success": { "$ref": "#/components/examples/CompanyUpdateRequestExample" } } } } }, "responses": { "200": { "description": "Sub-account updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyUpdateResponse" }, "examples": { "success": { "$ref": "#/components/examples/CompanyUpdateResponseExample" } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidAuth": { "summary": "Invalid authentication", "value": { "http": 401, "code": 10002, "message": "Authentication failed. Please enter the correct API Key and password." } } } } } }, "404": { "description": "Sub-account not found under the authenticated Partner account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "companyNotFound": { "summary": "Company does not exist under Partner account", "value": { "http": 404, "code": 10355, "message": "The company ID you have provided doesn't exist under your account." } } } } } } } }, "delete": { "summary": "Delete a sub-account", "description": "Permanently deletes a sub-account (company) from the Partner account.\n\nThis operation is irreversible and can only be performed by Signable Partners.\n", "operationId": "deleteCompany", "x-contract-group": "CONTRACT:WRITE:PARTNER", "tags": [ "Partners" ], "parameters": [ { "name": "company_id", "in": "path", "required": true, "description": "Unique identifier of the sub-account to delete.", "schema": { "type": "string", "example": "214821" } } ], "responses": { "200": { "description": "Sub-account deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDeleteResponse" }, "examples": { "success": { "$ref": "#/components/examples/CompanyDeleteResponseExample" } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidAuth": { "summary": "Invalid authentication", "value": { "http": 401, "code": 10002, "message": "Authentication failed. Please enter the correct API Key and password." } } } } } }, "404": { "description": "Sub-account not found under the authenticated Partner account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "companyNotFound": { "summary": "Company does not exist under Partner account", "value": { "http": 404, "code": 10355, "message": "The company ID you have provided doesn't exist under your account." } } } } } } } } }, "/usage": { "get": { "summary": "View usage for all sub-accounts", "description": "Retrieves usage data for all sub-accounts under a Partner account, including current and previous period comparisons.\nThis endpoint is only available to Signable Partners.\n", "operationId": "getCompaniesUsage", "x-contract-group": "CONTRACT:READ:PARTNER", "tags": [ "Partners" ], "parameters": [ { "$ref": "#/components/parameters/OffsetParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "name": "calendar", "in": "query", "required": false, "deprecated": true, "description": "Determines how usage periods are calculated. Defaults to `0`. Set to `1` to return usage periods aligned to calendar months. Set to `0` to return usage periods aligned to the billing cycle.\n", "schema": { "type": "integer", "enum": [ 0, 1 ], "example": 1 } } ], "responses": { "200": { "description": "Usage data successfully returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerUsageResponse" }, "examples": { "success": { "$ref": "#/components/examples/PartnerUsageResponseExample" } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidAuth": { "summary": "Invalid authentication", "value": { "http": 401, "code": 10002, "message": "Authentication failed. Please enter the correct API Key and password." } } } } } } } } }, "/envelopes": { "get": { "summary": "List envelopes", "description": "Returns a paginated list of envelopes. You can filter by envelope status or search by title using optional query parameters.\n", "operationId": "listEnvelopes", "x-contract-group": "CONTRACT:READ:STANDARD", "tags": [ "Envelopes" ], "parameters": [ { "$ref": "#/components/parameters/OffsetParam" }, { "$ref": "#/components/parameters/LimitParam" }, { "in": "query", "name": "envelope_status", "schema": { "type": "string", "enum": [ "processing", "failed", "draft", "sent", "signed", "cancelled", "expired", "rejected", "verify" ] }, "description": "Filter by a single envelope status. [See Envelope status values for more info →](../../envelope-status)" }, { "in": "query", "name": "q", "schema": { "type": "string" }, "description": "Case-insensitive keyword filter on the envelope title. Matches partial words. Null values return unfiltered results.\n" } ], "responses": { "200": { "description": "A paginated list of envelopes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeListResponse" }, "examples": { "envelopeList": { "$ref": "#/components/examples/EnvelopeListResponseExample" } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidAuth": { "summary": "Invalid authentication", "value": { "http": 401, "code": 10002, "message": "Authentication failed. Please enter the correct API Key and password.", "company": null, "url": "https://developer.signable.co.uk/errors/error-10002", "detail": null } } } } } } } }, "post": { "summary": "Create envelope (and send or save as draft)", "description": "Creates a new envelope and attaches documents using one of the methods listed below.\n\n**Option 1 - Upload or link a document directly in the request body**\n\n**Option 2 - Reference a single Signable template**\n\n**Option 3 - Reference multiple Signable templates**\n\n**Note ⚠️**: Unless `is_draft` is set to `true`, the envelope is queued for sending after it is created. When `is_draft` is `true`, the envelope is saved as a draft and is not sent.\n", "operationId": "sendEnvelope", "x-contract-group": "CONTRACT:WRITE:STANDARD", "tags": [ "Envelopes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Send Doc Request", "required": [ "envelope_title", "envelope_parties", "envelope_documents" ], "properties": { "envelope_title": { "type": "string", "description": "Title of the envelope.", "example": "Ashbrook Road 10/06/25" }, "user_id": { "type": "integer", "description": "ID of the user sending the envelope. If omitted, it won’t be linked to a user and email notifications will be sent to the company email address.\n", "example": 838180 }, "envelope_redirect_url": { "type": "string", "format": "uri", "description": "Where to redirect the signer after completion. Defaults to Signable’s confirmation page if not provided.\n", "example": "https://www.example.com" }, "envelope_all_at_once_enabled": { "type": "boolean", "description": "If true, sends to all parties at once. If false, sends sequentially (one-at-a-time).\n", "example": false }, "envelope_requires_otp": { "type": "boolean", "description": "Enables one-time-password (OTP) signing for all signers. Requires `party_mobile`.\nThis field has been deprecated in place of OTP per party, see envelope_parties[].party_mobile for more information.\n", "example": true, "deprecated": true }, "envelope_password_protect": { "type": "boolean", "description": "Enables password protection. System generates a password or use `party_password` per party.\n", "example": false }, "envelope_auto_expire_hours": { "type": "integer", "minimum": 12, "description": "Number of hours before the envelope expires automatically.", "example": 144 }, "envelope_auto_remind_hours": { "type": "integer", "minimum": 12, "description": "Frequency in hours for automatic reminder emails to signers.", "example": 72 }, "envelope_meta": { "type": "object", "description": "Custom metadata stored alongside the envelope.", "additionalProperties": true, "example": { "internal_id": "ABC123", "VIP": false } }, "is_draft": { "type": "boolean", "default": false, "description": "Determines whether the envelope is created as a draft. When `true`, the envelope is saved without being queued for sending and can later be sent using [Send a draft envelope](openapi/envelopes/senddraftenvelope). When `false` or omitted, the envelope is queued for sending after it is created. Set this to `true` when creating an envelope for the [Embedded Sending](guides/embedded-sending/embedded-sending) flow.\n", "example": false }, "envelope_parties": { "type": "array", "description": "List of parties involved in the envelope.\nEach party can be a signer or a copy recipient.\nIf `envelope_all_at_once_enabled` is set to `false`, signers will be notified sequentially based on the order they appear in this array.\nCopy recipients (with role `copy`) are notified only after all signers have completed their actions.\n", "items": { "type": "object", "required": [ "party_name", "party_email", "party_role" ], "properties": { "party_name": { "type": "string", "description": "Full name of the party.", "example": "Abby Signers" }, "party_email": { "type": "string", "format": "email", "description": "Email address of the party.", "example": "abby@signable.co.uk" }, "party_role": { "type": "string", "description": "Role tag corresponding to tags in the document, or 'copy' for non-signing parties. Signer tags **must** start with the string `signer`.\n", "example": "signer1" }, "party_message": { "type": "string", "description": "Optional message included in the email sent to the party.", "example": "Please sign as soon as you can." }, "party_mobile": { "type": "string", "description": "Mobile number in E.164 format. Provide this for a signing party to require one-time-password (OTP) verification for that party. Do not provide this for copy recipients.", "example": "+447712345678" }, "party_password": { "type": "string", "description": "Custom password for accessing the envelope (used only if `envelope_password_protect` is true).", "example": "secret123" } } } }, "envelope_documents": { "type": "array", "description": "List of documents to be sent in the envelope. Each record must either include a URL to the file, or a combination of base64-encoded content and filename.", "items": { "oneOf": [ { "type": "object", "title": "Document URL", "required": [ "document_title", "document_url" ], "properties": { "document_title": { "type": "string", "description": "Title of the document for internal use and audit trail.", "example": "Test Agreement" }, "document_url": { "type": "string", "format": "uri", "description": "URL to the hosted document (PDF, Word, or Excel).", "example": "https://yellow-della-30.tiiny.site/Tenancy-Contract-2025-v2.pdf" } } }, { "type": "object", "title": "Base64 file", "required": [ "document_title", "document_file_content", "document_file_name" ], "properties": { "document_title": { "type": "string", "description": "Title of the document for internal use and audit trail.", "example": "Test Agreement" }, "document_file_content": { "type": "string", "format": "byte", "description": "Base64-encoded file content.", "example": "JVBERi0xLjQKJdPr6...Zgo2MDE3MwolJUVPRgo=" }, "document_file_name": { "type": "string", "description": "Filename with extension, only `.pdf`, `.docx` or `.xlsx` are accepted.", "example": "contract.pdf" } } } ] } } } }, { "type": "object", "title": "Send Template Request", "required": [ "envelope_title", "envelope_parties", "envelope_documents" ], "properties": { "envelope_title": { "type": "string", "description": "Title of the envelope.", "example": "Melbourne Road 23/06/25" }, "user_id": { "type": "integer", "description": "ID of the user sending the envelope. If omitted, it won’t be linked to a user and email notifications will be sent to the company email address.\n", "example": 819622 }, "envelope_redirect_url": { "type": "string", "format": "uri", "description": "Where to redirect the signer after completion. Defaults to Signable’s confirmation page if not provided.\n", "example": "https://www.example.com" }, "envelope_all_at_once_enabled": { "type": "boolean", "description": "If true, sends to all parties at once. If false, sends sequentially (one-at-a-time).\n", "example": true }, "envelope_requires_otp": { "type": "boolean", "description": "Enables one-time-password (OTP) signing for all signers. Requires `party_mobile`.\nThis field has been deprecated in place of OTP per party, see envelope_parties[].party_mobile for more information.\n", "example": true, "deprecated": true }, "envelope_password_protect": { "type": "boolean", "description": "Enables password protection. System generates a password or use `party_password` per party.\n", "example": false }, "envelope_auto_expire_hours": { "type": "integer", "description": "Number of hours until the envelope expires.", "example": 144 }, "envelope_auto_remind_hours": { "type": "integer", "description": "Frequency in hours to send signer reminders.", "example": 72 }, "envelope_meta": { "type": "object", "description": "Custom metadata stored alongside the envelope.", "additionalProperties": true, "example": { "internal_id": "ABC123", "VIP": false } }, "is_draft": { "type": "boolean", "default": false, "description": "Defines if the created envelope is a draft envelope that will not be sent. This is used for the embedded sending flow.\n", "example": false }, "envelope_parties": { "type": "array", "description": "List of parties involved in the envelope. Each party can be a signer or a copy recipient. If `envelope_all_at_once_enabled` is set to `false`, signers will be notified sequentially based on the order they appear in this array. Copy recipients (with role `copy`) are notified only after all signers have completed their actions.\n", "items": { "type": "object", "required": [ "party_name", "party_email", "party_role", "party_id" ], "properties": { "party_name": { "type": "string", "example": "Alex Mitchell" }, "party_email": { "type": "string", "format": "email", "example": "abby+alex@signable.co.uk" }, "party_id": { "type": "string", "description": "ID of the party as defined in the template.", "example": "20748256" }, "party_role": { "type": "string", "enum": [ "signer", "copy" ], "description": "Role in the document.", "example": "signer" }, "party_message": { "type": "string", "description": "Optional message included in the email sent to the party.", "example": "Hello Alex, Please review and sign." }, "party_mobile": { "type": "string", "description": "Mobile number in E.164 format. Provide this for a signing party to require one-time-password (OTP) verification for that party. Do not provide this for copy recipients.", "example": "+447712345678" }, "party_password": { "type": "string", "description": "Custom password for accessing the envelope (used only if `envelope_password_protect` is true).", "example": "secret123" } } } }, "envelope_documents": { "type": "array", "items": { "type": "object", "required": [ "document_title", "document_template_fingerprint" ], "properties": { "document_title": { "type": "string", "example": "TC 2025 v2" }, "document_template_fingerprint": { "type": "string", "description": "Unique identifier of the Signable template to use.", "example": "28f9add86f25028df2eee9adee866aba" }, "document_merge_fields": { "type": "array", "description": "Values to populate merge fields within the template.", "items": { "type": "object", "required": [ "field_id", "field_value" ], "properties": { "field_id": { "type": "string", "description": "ID of the merge field as defined in the template.", "example": "454958773" }, "field_value": { "type": "string", "description": "Text value to populate the merge field in the envelope.", "example": "Note that breakables are not included in rent cost" } } } } } } } } }, { "type": "object", "title": "Send Multiple Templates Request", "required": [ "envelope_title", "envelope_parties", "envelope_documents" ], "properties": { "envelope_title": { "type": "string", "description": "Title of the envelope.", "example": "Barnsley Road 21/04/25" }, "user_id": { "type": "integer", "description": "ID of the user sending the envelope. If omitted, it won’t be linked to a user and email notifications will be sent to the company email address.\n", "example": 819622 }, "envelope_redirect_url": { "type": "string", "format": "uri", "description": "Where to redirect the signer after completion. Defaults to Signable’s confirmation page if not provided.\n", "example": "https://www.example.com" }, "envelope_all_at_once_enabled": { "type": "boolean", "description": "If true, sends to all parties at once. If false, sends sequentially (one-at-a-time).\n", "example": true }, "envelope_requires_otp": { "type": "boolean", "description": "Enables one-time-password (OTP) signing for all signers. Requires `party_mobile`.\nThis field has been deprecated in place of OTP per party, see envelope_parties[].party_mobile for more information.\n", "example": true, "deprecated": true }, "envelope_password_protect": { "type": "boolean", "description": "Enables password protection. System generates a password or use `party_password` per party.\n", "example": false }, "envelope_auto_expire_hours": { "type": "integer", "description": "Number of hours until the envelope expires.", "example": 144 }, "envelope_auto_remind_hours": { "type": "integer", "description": "Frequency in hours to send signer reminders.", "example": 72 }, "envelope_meta": { "type": "object", "description": "Custom metadata stored alongside the envelope.", "additionalProperties": true, "example": { "internal_id": "ABC123", "VIP": false } }, "is_draft": { "type": "boolean", "default": false, "description": "Defines if the created envelope is a draft envelope that will not be sent. This is used for the embedded sending flow.\n", "example": false }, "envelope_parties": { "type": "array", "description": "List of parties involved in the envelope. Each party can be a signer or a copy recipient. If `envelope_all_at_once_enabled` is set to `false`, signers will be notified sequentially based on the order they appear in this array. Copy recipients (with role `copy`) are notified only after all signers have completed their actions.\n", "items": { "type": "object", "required": [ "party_name", "party_email", "party_role", "party_documents" ], "properties": { "party_name": { "type": "string", "example": "Alex Mitchell" }, "party_email": { "type": "string", "format": "email", "example": "abby+alex@signable.co.uk" }, "party_documents": { "description": "A list of documents that this party is assigned to within the envelope. Signing parties are assigned one or more documents. Copy recipients (with role `copy`) are not assigned documents and must send an empty array.\n", "oneOf": [ { "title": "Signing Party", "type": "array", "minItems": 1, "description": "For signing parties, an array of one or more document assignments.\n", "items": { "type": "object", "required": [ "party_id", "document_template_fingerprint" ], "properties": { "party_id": { "type": "string", "description": "The unique ID of the party as defined in the associated Signable template. This is used to map the envelope party to their role in a specific document.\n", "example": "20748256" }, "document_template_fingerprint": { "type": "string", "description": "The fingerprint of the document template the party should be assigned to. This allows fine-grained control over which parties are included in which documents when sending from a multi-document template.\n", "example": "28f9add86f25028df2eee9adee866aba" } } } }, { "title": "Copy Party", "type": "array", "maxItems": 0, "description": "For copy recipients (role `copy`), an empty array (`[]`).\n" } ] }, "party_role": { "type": "string", "enum": [ "signer", "copy" ], "description": "Role in the document.", "example": "signer" }, "party_message": { "type": "string", "description": "Optional message included in the email sent to the party.", "example": "Hello Alex, Please review and sign." }, "party_mobile": { "type": "string", "description": "Mobile number in E.164 format. Provide this for a signing party to require one-time-password (OTP) verification for that party. Do not provide this for copy recipients.", "example": "+447712345678" }, "party_password": { "type": "string", "description": "Custom password for accessing the envelope (used only if `envelope_password_protect` is true).", "example": "secret123" } } } }, "envelope_documents": { "type": "array", "items": { "type": "object", "required": [ "document_title", "document_template_fingerprint" ], "properties": { "document_title": { "type": "string", "example": "TC 2025 v2" }, "document_template_fingerprint": { "type": "string", "description": "Unique identifier of the Signable template to use.", "example": "28f9add86f25028df2eee9adee866aba" }, "document_merge_fields": { "type": "array", "description": "Values to populate merge fields within the template.", "items": { "type": "object", "required": [ "field_id", "field_value" ], "properties": { "field_id": { "type": "string", "description": "ID of the merge field as defined in the template.", "example": "454958773" }, "field_value": { "type": "string", "description": "Text value to populate the merge field in the envelope.", "example": "Note that breakables are not included in rent cost" } } } } } } } } } ] }, "examples": { "with_document": { "$ref": "#/components/examples/EnvelopeSendDocRequestExample" }, "with_template": { "$ref": "#/components/examples/EnvelopeSendTemplateRequestExample" }, "with_template_multiple": { "$ref": "#/components/examples/EnvelopeSendTemplateMultipleRequestExample" } } } } }, "responses": { "202": { "description": "Envelope successfully created and queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeSendResponse" }, "examples": { "with_document": { "$ref": "#/components/examples/EnvelopeSendDocResponseExample" }, "with_template": { "$ref": "#/components/examples/EnvelopeSendTemplateResponseExample" }, "with_template_multiple": { "$ref": "#/components/examples/EnvelopeSendTemplateMultipleResponseExample" } } } } }, "400": { "description": "Invalid envelope send request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidRequest": { "summary": "Invalid request", "value": { "http": 400, "code": 10250, "message": "The envelope could not be sent. Please check your request and try again.", "company": null, "url": "https://developers.signable.app/errors/envelope-errors", "detail": null } } } } } } } } }, "/envelopes/{envelope_fingerprint}/send": { "post": { "summary": "Send a draft envelope", "description": "Sends a draft envelope as part of the [Embedded Sending](/guides/embedded-sending/embedded-sending) flow. The envelope must have a status of `draft`.\n", "operationId": "sendDraftEnvelope", "x-contract-group": "CONTRACT:READ:STANDARD", "tags": [ "Envelopes" ], "parameters": [ { "name": "envelope_fingerprint", "in": "path", "required": true, "description": "Unique identifier of the envelope.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Details of the envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeDetailResponse" }, "examples": { "envelopeDetails": { "$ref": "#/components/examples/EnvelopeGetResponseExample" } } } } } } } }, "/envelopes/{envelope_fingerprint}": { "get": { "summary": "Get envelope details", "description": "Returns the full details of a specific envelope, including document data, party information, field data, and envelope history.\n", "operationId": "getEnvelope", "x-contract-group": "CONTRACT:READ:STANDARD", "tags": [ "Envelopes" ], "parameters": [ { "name": "envelope_fingerprint", "in": "path", "required": true, "description": "Unique identifier of the envelope.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Details of the requested envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeDetailResponse" }, "examples": { "envelopeDetails": { "$ref": "#/components/examples/EnvelopeGetResponseExample" } } } } } } }, "delete": { "summary": "Delete an envelope", "description": "Deletes an envelope. Only available for envelopes in `draft`, `signed`, `expired` or `cancelled` status. No notification email is sent to signers when an envelope is deleted.\n", "operationId": "deleteEnvelope", "x-contract-group": "CONTRACT:WRITE:STANDARD", "tags": [ "Envelopes" ], "parameters": [ { "name": "envelope_fingerprint", "in": "path", "required": true, "description": "The unique identifier of the envelope.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Envelope successfully deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeDeleteResponse" }, "examples": { "success": { "$ref": "#/components/examples/EnvelopeDeleteResponseExample" } } } } } } } }, "/envelopes/{envelope_fingerprint}/remind": { "put": { "summary": "Send envelope reminder", "description": "Sends a reminder email to all outstanding signing parties for the specified envelope. If automatic reminders are enabled, this also resets the countdown timer for the next scheduled reminder.\n", "operationId": "remindEnvelope", "x-contract-group": "CONTRACT:WRITE:STANDARD", "tags": [ "Envelopes" ], "parameters": [ { "name": "envelope_fingerprint", "in": "path", "required": true, "description": "The unique identifier of the envelope to remind signers for.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reminder successfully triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeRemindResponse" }, "examples": { "success": { "$ref": "#/components/examples/EnvelopeRemindResponseExample" } } } } }, "400": { "description": "Envelope cannot be reminded in its current status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "wrongStatus": { "summary": "Envelope is not active", "value": { "http": 400, "code": 10275, "message": "The envelope you are trying to remind doesn't have the correct status. The envelope can't be complete and must still be active." } } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidAuth": { "summary": "Invalid authentication", "value": { "http": 401, "code": 10002, "message": "Authentication failed. Please enter the correct API Key and password." } } } } } }, "404": { "description": "Envelope not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unknownEnvelope": { "summary": "Unknown or inaccessible envelope", "value": { "http": 404, "code": 10253, "message": "The envelope does not exist. Have you used the correct envelope fingerprint?" } } } } } } } } }, "/envelopes/{envelope_fingerprint}/cancel": { "put": { "summary": "Cancel an envelope", "description": "Cancels a `sent` envelope. A cancellation email will be sent to all signing parties, and the envelope will no longer be available for signing.\n", "operationId": "cancelEnvelope", "x-contract-group": "CONTRACT:WRITE:STANDARD", "tags": [ "Envelopes" ], "parameters": [ { "name": "envelope_fingerprint", "in": "path", "required": true, "description": "The unique identifier of the envelope to cancel.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Envelope successfully cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeCancelResponse" }, "examples": { "success": { "$ref": "#/components/examples/EnvelopeCancelResponseExample" } } } } }, "400": { "description": "Envelope cannot be cancelled in its current status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "wrongStatus": { "summary": "Envelope is not active", "value": { "http": 400, "code": 10274, "message": "The envelope you are trying to cancel doesn't have the correct status. The envelope can't be complete and must still be active.", "company": null, "url": "http://developer.signable.co.uk/errors/error-10274", "detail": null } } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidAuth": { "summary": "Invalid authentication", "value": { "http": 401, "code": 10002, "message": "Authentication failed. Please enter the correct API Key and password.", "company": null, "url": "https://developer.signable.co.uk/errors/error-10002", "detail": null } } } } } }, "404": { "description": "Envelope not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "unknownEnvelope": { "summary": "Unknown or inaccessible envelope", "value": { "http": 404, "code": 10253, "message": "The envelope does not exist. Have you used the correct envelope fingerprint?", "company": null, "url": "https://developers.signable.app/errors/envelope-errors", "detail": null } } } } } } } } }, "/envelopes/{envelope_fingerprint}/expire": { "put": { "summary": "Expire an envelope", "description": "Expires a `sent` envelope, preventing any further signing interaction. No notification email is sent to signers when an envelope expires.\n", "operationId": "expireEnvelope", "x-contract-group": "CONTRACT:WRITE:STANDARD", "tags": [ "Envelopes" ], "parameters": [ { "name": "envelope_fingerprint", "in": "path", "required": true, "description": "The unique identifier of the envelope.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Envelope successfully expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeExpireResponse" }, "examples": { "success": { "$ref": "#/components/examples/EnvelopeExpireResponseExample" } } } } } } } }, "/envelopes/{envelope_fingerprint}/parties/{party_id}": { "patch": { "summary": "Update an envelope party", "description": "Updates an envelope party email address and/or title.\n\n⚠️ **Note:** Maximum 5 successful updates in total per party (in any combination of email and title).\n", "operationId": "updateEnvelopeParty", "x-contract-group": "CONTRACT:WRITE:STANDARD", "tags": [ "Envelopes" ], "parameters": [ { "name": "envelope_fingerprint", "in": "path", "required": true, "description": "The unique identifier of the envelope containing the party.", "schema": { "type": "string", "example": "584ea8b41b0d4c17a96b967433b211e6" } }, { "name": "party_id", "in": "path", "required": true, "description": "The unique ID of the party to update.", "schema": { "type": "integer", "example": 1234567 } } ], "requestBody": { "required": true, "description": "At least one of `party_email` or `party_title` must be provided and must differ from the current value.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopePartyUpdateRequest" }, "examples": { "default": { "$ref": "#/components/examples/EnvelopePartyUpdateRequestExample" } } } } }, "responses": { "200": { "description": "Party updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopePartyUpdateResponse" }, "examples": { "default": { "$ref": "#/components/examples/EnvelopePartyUpdateResponseExample" } } } } } } } }, "/templates": { "get": { "summary": "List templates", "description": "Retrieves a paginated list of all templates available in your account.\n", "operationId": "listTemplates", "x-contract-group": "CONTRACT:READ:STANDARD", "tags": [ "Templates" ], "parameters": [ { "$ref": "#/components/parameters/OffsetParam" }, { "$ref": "#/components/parameters/LimitParam" } ], "responses": { "200": { "description": "Templates list returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatesListResponse" }, "examples": { "default": { "$ref": "#/components/examples/TemplatesListResponseExample" } } } } } } } }, "/templates/{template_fingerprint}": { "get": { "summary": "Get template", "description": "Retrieves metadata and configuration for a single template.", "operationId": "getTemplate", "x-contract-group": "CONTRACT:READ:STANDARD", "tags": [ "Templates" ], "parameters": [ { "name": "template_fingerprint", "in": "path", "required": true, "description": "The unique fingerprint of the template", "schema": { "type": "string", "example": "b786a173554cc06371248caf0b250704" } } ], "responses": { "200": { "description": "Template details returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateGetResponse" }, "examples": { "default": { "$ref": "#/components/examples/TemplateGetResponseExample" } } } } } } }, "delete": { "summary": "Delete a template", "description": "Deletes a template by its fingerprint.", "operationId": "deleteTemplate", "x-contract-group": "CONTRACT:WRITE:STANDARD", "tags": [ "Templates" ], "parameters": [ { "name": "template_fingerprint", "in": "path", "required": true, "description": "The unique fingerprint of the template to delete", "schema": { "type": "string", "example": "e0b3a9cbd4a6ff2cb57cfca161a39309" } } ], "responses": { "200": { "description": "Template deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDeleteResponse" }, "examples": { "default": { "$ref": "#/components/examples/TemplateDeleteResponseExample" } } } } } } } }, "/contacts": { "get": { "summary": "List contacts", "description": "Retrieves a paginated list of all contacts. Use `offset` and `limit` query parameters to control pagination.\n", "operationId": "listContacts", "x-contract-group": "CONTRACT:READ:STANDARD", "tags": [ "Contacts" ], "parameters": [ { "$ref": "#/components/parameters/OffsetParam" }, { "$ref": "#/components/parameters/LimitParam" } ], "responses": { "200": { "description": "Contact list returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsListResponse" }, "examples": { "default": { "$ref": "#/components/examples/ContactsListResponseExample" } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingOrBlankAuth": { "summary": "Missing or blank authentication", "value": { "http": 401, "code": 10004, "message": "Authentication failed. Either the API Key or password was blank." } }, "invalidAuth": { "summary": "Invalid authentication", "value": { "http": 401, "code": 10002, "message": "Authentication failed. Please enter the correct API Key and password." } } } } } } } }, "post": { "summary": "Create a contact", "description": "Adds a new contact to your contact list. Invalid `contact_email` values are currently returned as the same error used for a missing email address.\n", "operationId": "createContact", "x-contract-group": "CONTRACT:WRITE:STANDARD", "tags": [ "Contacts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreateRequest" }, "examples": { "default": { "$ref": "#/components/examples/ContactCreateRequestExample" } } } } }, "responses": { "200": { "description": "Contact created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreateResponse" }, "examples": { "default": { "$ref": "#/components/examples/ContactCreateResponseExample" } } } } }, "400": { "description": "Invalid contact create request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingContactName": { "summary": "Missing contact_name", "value": { "http": 400, "code": 10050, "message": "The contact name is missing. To be able to create a new contact, you must provide a name." } }, "missingBody": { "summary": "Missing request body", "value": { "http": 400, "code": 10050, "message": "The contact name is missing. To be able to create a new contact, you must provide a name." } }, "malformedJson": { "summary": "Malformed JSON", "value": { "http": 400, "code": 10050, "message": "The contact name is missing. To be able to create a new contact, you must provide a name." } }, "missingContactEmail": { "summary": "Missing contact_email", "value": { "http": 400, "code": 10051, "message": "The contact email is missing. To be able to create a new contact, you must provide an email address." } }, "invalidContactEmail": { "summary": "Invalid contact_email", "value": { "http": 400, "code": 10051, "message": "The contact email is missing. To be able to create a new contact, you must provide an email address." } }, "duplicateContactEmail": { "summary": "Duplicate contact_email", "value": { "http": 400, "code": 10059, "message": "Unable to add a new contact as a contact already exists with this email address." } } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingOrBlankAuth": { "summary": "Missing or blank authentication", "value": { "http": 401, "code": 10004, "message": "Authentication failed. Either the API Key or password was blank." } }, "invalidAuth": { "summary": "Invalid authentication", "value": { "http": 401, "code": 10002, "message": "Authentication failed. Please enter the correct API Key and password." } } } } } } } } }, "/contacts/{contact_id}": { "get": { "summary": "Get a contact", "description": "Retrieves details of a single contact by `contact_id`.", "operationId": "getContact", "x-contract-group": "CONTRACT:READ:STANDARD", "tags": [ "Contacts" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "The unique ID of the contact", "schema": { "type": "integer", "example": 17224150 } } ], "responses": { "200": { "description": "Contact details returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactGetResponse" }, "examples": { "default": { "$ref": "#/components/examples/ContactGetResponseExample" } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingOrBlankAuth": { "summary": "Missing or blank authentication", "value": { "http": 401, "code": 10004, "message": "Authentication failed. Either the API Key or password was blank." } }, "invalidAuth": { "summary": "Invalid authentication", "value": { "http": 401, "code": 10002, "message": "Authentication failed. Please enter the correct API Key and password." } } } } } }, "404": { "description": "Contact not found, or route not found for a non-numeric contact ID", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "$ref": "#/components/schemas/RouteNotFoundResponse" } ] }, "examples": { "contactNotFound": { "summary": "Unknown, deleted, or wrong-account contact", "value": { "http": 404, "code": 10053, "message": "The contact does not exist. Have you used the correct contact ID?" } }, "nonNumericContactId": { "summary": "Non-numeric contact_id", "value": { "message": "The route v1/contacts/abc could not be found." } } } } } } } }, "put": { "summary": "Update a contact", "description": "Updates a contact's name or email address. The API supports partial updates: send `contact_name`, `contact_email`, or both.\n", "operationId": "updateContact", "x-contract-group": "CONTRACT:WRITE:STANDARD", "tags": [ "Contacts" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "integer", "example": 17224150 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdateRequest" }, "examples": { "default": { "$ref": "#/components/examples/ContactUpdateRequestExample" } } } } }, "responses": { "200": { "description": "Contact updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdateResponse" }, "examples": { "default": { "$ref": "#/components/examples/ContactUpdateResponseExample" } } } } }, "400": { "description": "Invalid contact update request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingBody": { "summary": "Missing request body", "value": { "http": 400, "code": 10054, "message": "Both the contact name and contact email are missing. Please make sure at least one of them are provided." } }, "malformedJson": { "summary": "Malformed JSON", "value": { "http": 400, "code": 10054, "message": "Both the contact name and contact email are missing. Please make sure at least one of them are provided." } } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingOrBlankAuth": { "summary": "Missing or blank authentication", "value": { "http": 401, "code": 10004, "message": "Authentication failed. Either the API Key or password was blank." } }, "invalidAuth": { "summary": "Invalid authentication", "value": { "http": 401, "code": 10002, "message": "Authentication failed. Please enter the correct API Key and password." } } } } } }, "404": { "description": "Contact not found, or route not found for a non-numeric contact ID", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "$ref": "#/components/schemas/RouteNotFoundResponse" } ] }, "examples": { "contactNotFound": { "summary": "Unknown or wrong-account contact", "value": { "http": 404, "code": 10053, "message": "The contact does not exist. Have you used the correct contact ID?" } }, "nonNumericContactId": { "summary": "Non-numeric contact_id", "value": { "message": "The route v1/contacts/abc could not be found." } } } } } } } }, "delete": { "summary": "Delete a contact", "description": "Deletes a contact by their `contact_id`.", "operationId": "deleteContact", "x-contract-group": "CONTRACT:WRITE:STANDARD", "tags": [ "Contacts" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "integer", "example": 17224150 } } ], "responses": { "200": { "description": "Contact deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDeleteResponse" }, "examples": { "default": { "$ref": "#/components/examples/ContactDeleteResponseExample" } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingOrBlankAuth": { "summary": "Missing or blank authentication", "value": { "http": 401, "code": 10004, "message": "Authentication failed. Either the API Key or password was blank." } }, "invalidAuth": { "summary": "Invalid authentication", "value": { "http": 401, "code": 10002, "message": "Authentication failed. Please enter the correct API Key and password." } } } } } }, "404": { "description": "Contact not found, or route not found for a non-numeric contact ID", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "$ref": "#/components/schemas/RouteNotFoundResponse" } ] }, "examples": { "contactNotFound": { "summary": "Unknown, already deleted, or wrong-account contact", "value": { "http": 404, "code": 10053, "message": "The contact does not exist. Have you used the correct contact ID?" } }, "nonNumericContactId": { "summary": "Non-numeric contact_id", "value": { "message": "The route v1/contacts/abc could not be found." } } } } } } } } }, "/contacts/{contact_id}/envelopes": { "get": { "summary": "List envelopes for a contact", "description": "Returns a paginated list of all envelopes that the contact is a recipient of. Each envelope includes basic metadata such as its current status, timestamps, and optional signed PDF link.\n", "operationId": "listContactEnvelopes", "x-contract-group": "CONTRACT:READ:STANDARD", "tags": [ "Contacts" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "The unique ID of the contact", "schema": { "type": "integer", "example": 17225983 } }, { "$ref": "#/components/parameters/OffsetParam" }, { "$ref": "#/components/parameters/LimitParam" } ], "responses": { "200": { "description": "List of envelopes the contact is associated with", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEnvelopesListResponse" }, "examples": { "default": { "$ref": "#/components/examples/ContactEnvelopesListResponseExample" } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingOrBlankAuth": { "summary": "Missing or blank authentication", "value": { "http": 401, "code": 10004, "message": "Authentication failed. Either the API Key or password was blank." } }, "invalidAuth": { "summary": "Invalid authentication", "value": { "http": 401, "code": 10002, "message": "Authentication failed. Please enter the correct API Key and password." } } } } } }, "404": { "description": "Contact has no envelopes, or route not found for a non-numeric contact ID", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "$ref": "#/components/schemas/RouteNotFoundResponse" } ] }, "examples": { "noContactEnvelopes": { "summary": "Unknown or wrong-account contact", "value": { "http": 404, "code": 10060, "message": "This contact hasn't been sent any envelopes." } }, "nonNumericContactId": { "summary": "Non-numeric contact_id", "value": { "message": "The route v1/contacts/abc/envelopes could not be found." } } } } } } } } }, "/users": { "get": { "summary": "List users", "description": "Retrieves a paginated list of all users in your account. You can control pagination using the `offset` and `limit` query parameters.\n", "operationId": "listUsers", "x-contract-group": "CONTRACT:READ:STANDARD", "tags": [ "Users" ], "parameters": [ { "$ref": "#/components/parameters/OffsetParam" }, { "$ref": "#/components/parameters/LimitParam" } ], "responses": { "200": { "description": "Users list returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsersListResponse" }, "examples": { "default": { "$ref": "#/components/examples/UsersListResponseExample" } } } } } } }, "post": { "summary": "Create a user", "description": "Adds a new user to your account. You must provide the user’s name, email address, and their role ID.\n", "operationId": "createUser", "x-contract-group": "CONTRACT:WRITE:STANDARD", "tags": [ "Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCreateRequest" }, "examples": { "default": { "$ref": "#/components/examples/UserCreateRequestExample" } } } } }, "responses": { "200": { "description": "User created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCreateResponse" }, "examples": { "default": { "$ref": "#/components/examples/UserCreateResponseExample" } } } } } } } }, "/users/{user_id}": { "get": { "summary": "Get a user", "description": "Retrieves the details of a single user by their unique `user_id`. The response includes the user's name, email, role, and timestamps.\n", "operationId": "getUser", "x-contract-group": "CONTRACT:READ:STANDARD", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "The unique ID of the user to retrieve", "schema": { "type": "integer", "example": 836499 } } ], "responses": { "200": { "description": "User details returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserGetResponse" }, "examples": { "default": { "$ref": "#/components/examples/UserGetResponseExample" } } } } } } }, "put": { "summary": "Update a user", "description": "Updates a user by `user_id`.\n\nSupports partial updates. You can send `user_name`, `user_email`, or both. You can also include `role_id`.\n\nYou must provide at least one of `user_name` or `user_email`.\n\nIf you omit a field, its existing value is preserved.\n", "operationId": "updateUser", "x-contract-group": "CONTRACT:WRITE:STANDARD", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "The unique ID of the user to update", "schema": { "type": "integer", "example": 837154 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdateRequest" }, "examples": { "userNameOnly": { "$ref": "#/components/examples/UserUpdateRequestUserNameOnlyExample" }, "userEmailOnly": { "$ref": "#/components/examples/UserUpdateRequestUserEmailOnlyExample" }, "userNameAndUserEmail": { "$ref": "#/components/examples/UserUpdateRequestNameAndEmailExample" }, "fullPayload": { "$ref": "#/components/examples/UserUpdateRequestExample" } } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdateResponse" }, "examples": { "default": { "$ref": "#/components/examples/UserUpdateResponseExample" } } } } }, "400": { "description": "Invalid request. For example, sending `role_id` on its own returns error code `10104` because at least one of `user_name` or `user_email` must also be supplied.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "http": { "type": "integer", "example": 400 }, "code": { "type": "integer", "example": 10104 }, "message": { "type": "string", "example": "The user name and email are missing. Please make sure at least one of them is provided." } } }, "examples": { "roleIdOnly": { "$ref": "#/components/examples/UserUpdateRoleOnlyErrorExample" } } } } } } }, "delete": { "summary": "Delete a user", "description": "Removes a user from your account using their `user_id`. The response confirms the deletion and includes the user's basic details.\n", "operationId": "deleteUser", "x-contract-group": "CONTRACT:WRITE:STANDARD", "tags": [ "Users" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "The unique ID of the user to delete", "schema": { "type": "integer", "example": 837154 } } ], "responses": { "200": { "description": "User deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDeleteResponse" }, "examples": { "default": { "$ref": "#/components/examples/UserDeleteResponseExample" } } } } } } } }, "/webhooks": { "get": { "summary": "List webhooks", "description": "Retrieves a paginated list of all webhooks currently registered to receive event notifications. Supports offset and limit for pagination. Webhooks include metadata about creation, update, and suspension state.\n", "operationId": "listWebhooks", "x-contract-group": "CONTRACT:READ:STANDARD", "tags": [ "Webhooks" ], "parameters": [ { "name": "offset", "in": "query", "required": false, "description": "Pagination offset", "schema": { "type": "integer", "example": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Number of webhooks to return", "schema": { "type": "integer", "example": 10 } } ], "responses": { "200": { "description": "Successfully returned a list of webhooks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListResponse" }, "examples": { "default": { "$ref": "#/components/examples/WebhookListResponseExample" } } } } } } }, "post": { "summary": "Create a webhook", "description": "Registers a new webhook that will be triggered when a specific event occurs. You must provide a valid `webhook_url` and a supported `webhook_type`. The created webhook will immediately be eligible to receive matching notifications.\n", "operationId": "createWebhook", "x-contract-group": "CONTRACT:WRITE:STANDARD", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequest" }, "examples": { "default": { "$ref": "#/components/examples/WebhookRequestExample" } } } } }, "responses": { "200": { "description": "Webhook successfully created", "headers": { "Location": { "description": "The URL of the newly created webhook resource", "schema": { "type": "string", "format": "uri" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPostResponse" }, "examples": { "createdWebhook": { "$ref": "#/components/examples/WebhookPostResponseExample" } } } } } } } }, "/webhooks/{webhook_id}": { "get": { "summary": "Get a webhook", "description": "Retrieves details of a specific webhook by its unique `webhook_id`. The response includes the current status and metadata of the webhook.\n", "operationId": "getWebhook", "x-contract-group": "CONTRACT:READ:STANDARD", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "description": "The ID of the webhook to retrieve", "schema": { "type": "integer", "example": 152691 } } ], "responses": { "200": { "description": "Webhook details returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookGetResponse" }, "examples": { "default": { "$ref": "#/components/examples/WebhookGetResponseExample" } } } } } } }, "put": { "summary": "Update a webhook", "description": "Updates the webhook identified by `webhook_id`. The request body may include `webhook_url`, `webhook_type`, or both.\n", "operationId": "updateWebhook", "x-contract-group": "CONTRACT:WRITE:STANDARD", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "description": "The ID of the webhook to update", "schema": { "type": "integer", "example": 152691 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdateRequest" }, "examples": { "webhookUrlOnly": { "$ref": "#/components/examples/WebhookUpdateRequestUrlOnlyExample" }, "webhookTypeOnly": { "$ref": "#/components/examples/WebhookUpdateRequestTypeOnlyExample" }, "bothFields": { "$ref": "#/components/examples/WebhookUpdateRequestBothExample" } } } } }, "responses": { "200": { "description": "Webhook updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPutResponse" }, "examples": { "updated": { "$ref": "#/components/examples/WebhookPutResponseExample" } } } } } } }, "delete": { "summary": "Delete a webhook", "description": "Deletes the webhook identified by `webhook_id`. Once removed, the webhook will no longer receive event notifications.\n", "operationId": "deleteWebhook", "x-contract-group": "CONTRACT:WRITE:STANDARD", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "description": "The ID of the webhook to delete", "schema": { "type": "integer", "example": 152691 } } ], "responses": { "200": { "description": "Webhook successfully deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeleteResponse" }, "examples": { "deleted": { "$ref": "#/components/examples/WebhookDeleteResponseExample" } } } } } } } }, "/branding": { "get": { "summary": "Get branding settings", "description": "Returns your company's current branding settings, including any uploaded logo and primary colour. These settings control how Signable emails and signing pages appear to your signers.\n", "operationId": "getBranding", "x-contract-group": "CONTRACT:READ:STANDARD", "tags": [ "Branding" ], "responses": { "200": { "description": "Branding settings returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingResponse" }, "examples": { "default": { "$ref": "#/components/examples/BrandingResponseExample" } } } } } } }, "put": { "summary": "Update branding settings", "description": "Update your account's branding settings. This includes the logo and the primary colour used on emails and signing pages.\n", "operationId": "updateBranding", "x-contract-group": "CONTRACT:WRITE:STANDARD", "tags": [ "Branding" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingPutRequest" }, "examples": { "default": { "$ref": "#/components/examples/BrandingPutRequestExample" } } } } }, "responses": { "200": { "description": "Branding updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingPutResponse" }, "examples": { "default": { "$ref": "#/components/examples/BrandingPutResponseExample" } } } } } } } }, "/branding/emails": { "get": { "summary": "List branding emails", "operationId": "getBrandingEmails", "x-contract-group": "CONTRACT:READ:STANDARD", "tags": [ "Branding" ], "responses": { "200": { "description": "A list of branding email templates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingEmailsResponse" }, "examples": { "success": { "$ref": "#/components/examples/BrandingEmailsResponseExample" } } } } } } } }, "/branding/emails/{branding_email_type}": { "get": { "summary": "Get a branding email", "description": "Retrieves a single branding email template", "operationId": "getSingleBrandingEmail", "x-contract-group": "CONTRACT:READ:STANDARD", "tags": [ "Branding" ], "parameters": [ { "name": "branding_email_type", "in": "path", "required": true, "description": "The type of branding email to retrieve", "schema": { "type": "string", "enum": [ "email-cancelled", "email-rejected", "email-reminder", "email-reminder-password", "email-send", "email-send-password", "email-signed", "email-widget-verify" ], "example": "email-cancelled" } } ], "responses": { "200": { "description": "A single branding email template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingEmailSingleResponse" }, "examples": { "success": { "$ref": "#/components/examples/BrandingEmailSingleResponseExample" } } } } } } }, "put": { "summary": "Update a branding email", "description": "You can include variables like `{company name}` and `{contract title}` in your email body to personalise content. [See the full list of supported variables →](../email-variables)\n", "operationId": "updateBrandingEmail", "x-contract-group": "CONTRACT:WRITE:STANDARD", "tags": [ "Branding" ], "parameters": [ { "name": "branding_email_type", "in": "path", "required": true, "description": "The type of branding email to update", "schema": { "type": "string", "enum": [ "email-cancelled", "email-rejected", "email-reminder", "email-reminder-password", "email-send", "email-send-password", "email-signed", "email-widget-verify" ], "example": "email-cancelled" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingEmailPutRequest" }, "examples": { "default": { "$ref": "#/components/examples/BrandingEmailPutRequestExample" } } } } }, "responses": { "200": { "description": "Branding email successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingEmailPutResponse" }, "examples": { "default": { "$ref": "#/components/examples/BrandingEmailPutResponseExample" } } } } } } } }, "/settings": { "get": { "summary": "Get company settings", "description": "Your Signable account settings control how documents are delivered, signed, and managed across your team.\nThis section of the API lets you retrieve and update your company's signing preferences, email notification rules, signature formats, and more—giving you full control over how your documents behave.\nSettings can be accessed via the API or in the Signable web app under Company Settings > [Preferences](https://signable.app/company-settings/preferences).\n", "operationId": "listSettings", "x-contract-group": "CONTRACT:READ:STANDARD", "tags": [ "Settings" ], "responses": { "200": { "description": "Company settings returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsResponse" }, "examples": { "default": { "$ref": "#/components/examples/SettingsResponseExample" } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingAuth": { "summary": "Missing authentication", "value": { "http": 401, "code": 10002, "message": "Authentication failed. Please enter the correct API Key and password." } }, "invalidAuth": { "summary": "Invalid authentication", "value": { "http": 401, "code": 10002, "message": "Authentication failed. Please enter the correct API Key and password." } } } } } } } }, "put": { "summary": "Update company settings", "description": "Update your company's settings. If no valid update can be applied, the API returns the current settings without making changes.\n", "operationId": "updateSettings", "x-contract-group": "CONTRACT:WRITE:STANDARD", "tags": [ "Settings" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSettingsRequest" }, "examples": { "default": { "$ref": "#/components/examples/SettingsPutRequestExample" } } } } }, "responses": { "200": { "description": "Settings updated successfully, or current settings returned when no update is applied.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSettingsResponse" }, "examples": { "updated": { "$ref": "#/components/examples/SettingsPutResponseExample" } } } } }, "400": { "description": "Invalid settings update request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidAcceptedSignatureFormat": { "summary": "Invalid setting_signature_format_accepted", "value": { "http": 400, "code": 10651, "message": "The signature format you have passed in isn't valid. It must be either 'drawn', 'typed' or 'upload'" } } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingAuth": { "summary": "Missing authentication", "value": { "http": 401, "code": 10002, "message": "Authentication failed. Please enter the correct API Key and password." } }, "invalidAuth": { "summary": "Invalid authentication", "value": { "http": 401, "code": 10002, "message": "Authentication failed. Please enter the correct API Key and password." } } } } } } } } }, "/embed-sessions": { "post": { "summary": "Create an embed session", "description": "Creates a new embed session for a given draft envelope.\n", "operationId": "createEmbedSession", "tags": [ "Embed Sessions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedSessionPostRequest" } } } }, "responses": { "201": { "description": "Details of the newly created embed session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbedSessionPostResponse" } } } } } } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic", "description": "Authenticate using HTTP Basic Authentication. Use your API key as the username and the password can be anything. For ease of use we recommend \"x\".\n" } }, "parameters": { "OffsetParam": { "name": "offset", "in": "query", "required": false, "description": "The index of the first envelope to retrieve.", "schema": { "type": "integer", "example": 0, "default": 0 } }, "LimitParam": { "name": "limit", "in": "query", "required": false, "description": "The maximum number of envelopes to return. If more than `50` is requested, `10` will be returned instead.\n", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } } }, "schemas": { "Company": { "type": "object", "description": "Represents an individual sub-account created under a Partner account.", "required": [ "company_id", "company_name", "company_email", "company_api_key", "company_created" ], "properties": { "company_id": { "type": "string", "example": "196735", "description": "Unique identifier for the sub-account." }, "company_name": { "type": "string", "example": "ExampleSubAccount_1", "description": "The display name of the sub-account." }, "company_email": { "type": "string", "format": "email", "example": "abby+1@signable.co.uk", "description": "The registered email address associated with the sub-account." }, "company_api_key": { "type": "string", "example": "9c66b129752046***********", "description": "The API key used to authenticate as this sub-account." }, "company_created": { "type": "string", "format": "date-time", "example": "2024-09-03T09:03:12+0000", "description": "The date and time when the sub-account was created." } } }, "CompanyListResponse": { "type": "object", "description": "Represents a paginated list of sub-accounts associated with a Partner account.", "required": [ "http", "offset", "limit", "total_companies", "companies" ], "properties": { "http": { "type": "integer", "example": 200, "description": "HTTP status code indicating the result of the API request." }, "offset": { "type": "integer", "example": 0, "description": "The number of items skipped before starting to collect the result set." }, "limit": { "type": "integer", "example": 10, "description": "The maximum number of sub-accounts returned in the current response." }, "total_companies": { "type": "string", "example": "2", "description": "The total number of sub-accounts available to the authenticated Partner." }, "companies": { "type": "array", "description": "A list of sub-accounts returned in the current response.", "items": { "$ref": "#/components/schemas/Company" } } } }, "ErrorResponse": { "type": "object", "required": [ "http", "code", "message" ], "additionalProperties": false, "properties": { "http": { "type": "integer", "example": 400 }, "code": { "type": "integer", "example": 10050 }, "message": { "type": "string", "example": "The request could not be completed." }, "company": { "type": [ "string", "null" ], "example": null }, "url": { "type": [ "string", "null" ], "example": "https://developer.signable.co.uk/errors/error-10002" }, "detail": { "type": [ "string", "null" ], "example": null } } }, "CompanyCreateRequest": { "type": "object", "required": [ "company_name", "user_name", "user_email" ], "properties": { "company_name": { "type": "string", "example": "Example Inc", "description": "The name of the new sub-account." }, "user_name": { "type": "string", "example": "Abby Signs", "description": "The full name of the initial user for the sub-account." }, "user_email": { "type": "string", "format": "email", "example": "abby@example.com", "description": "The email address of the user to be created within the sub-account." } } }, "CompanyCreateResponse": { "type": "object", "required": [ "http", "message", "href", "company_id", "company_name", "company_email", "api_key", "user_id", "user_name", "user_email", "user_href", "company_added" ], "properties": { "http": { "type": "integer", "example": 200, "description": "HTTP status code indicating the result of the request." }, "message": { "type": "string", "example": "Example Inc has been added as a company", "description": "A confirmation message." }, "href": { "type": "string", "format": "uri", "example": "https://api.signable.co.uk/v1/companies/214821", "description": "URL to the newly created sub-account resource." }, "company_id": { "type": "string", "example": "214821", "description": "Unique identifier of the newly created sub-account." }, "company_name": { "type": "string", "example": "Example Inc", "description": "Name of the newly created sub-account." }, "company_email": { "type": "string", "format": "email", "example": "abby@example.com", "description": "Registered email address for the sub-account." }, "api_key": { "type": "string", "example": "9c66b129752046***********", "description": "API key associated with the sub-account." }, "user_id": { "type": "string", "example": "838931", "description": "ID of the user created within the sub-account." }, "user_name": { "type": "string", "example": "Abby Signs", "description": "Full name of the user created in the sub-account." }, "user_email": { "type": "string", "format": "email", "example": "abby@example.com", "description": "Email address of the created user." }, "user_href": { "type": "string", "format": "uri", "example": "https://api.signable.co.uk/v1/users/838931", "description": "URL to the created user resource." }, "company_added": { "type": "string", "format": "date-time", "example": "2025-07-21T08:16:51+0000", "description": "Timestamp when the sub-account was created." } } }, "CompanyUsage": { "type": "object", "description": "Represents document usage for a sub-account in a specific month and year.", "properties": { "month": { "type": "string", "example": "July", "description": "The calendar month this usage relates to." }, "year": { "type": "string", "example": "2025", "description": "The year this usage relates to." }, "sent": { "type": "string", "example": "1", "description": "The number of documents sent during the specified month." } } }, "CompanyGetResponse": { "allOf": [ { "type": "object", "required": [ "http" ], "properties": { "http": { "type": "integer", "description": "HTTP status code of the response.", "example": 200 } } }, { "$ref": "#/components/schemas/Company" }, { "type": "object", "required": [ "company_usage" ], "properties": { "company_usage": { "type": "array", "description": "Monthly usage summary for the sub-account.", "items": { "$ref": "#/components/schemas/CompanyUsage" } } } } ] }, "CompanyUpdateRequest": { "type": "object", "description": "Payload to update a sub-account. At least one property must be provided.", "properties": { "company_name": { "type": "string", "example": "Apple Tree Ltd", "description": "New name of the sub-account." }, "company_email": { "type": "string", "format": "email", "example": "abby@appletree.com", "description": "New email address of the sub-account." } }, "anyOf": [ { "required": [ "company_name" ] }, { "required": [ "company_email" ] } ] }, "CompanyUpdateResponse": { "type": "object", "required": [ "http", "message", "href", "company_id", "company_name", "company_email", "company_updated" ], "properties": { "http": { "type": "integer", "example": 200, "description": "HTTP status code indicating the result of the request." }, "message": { "type": "string", "example": "Apple Tree Ltd has been updated.", "description": "Confirmation message indicating the update was successful." }, "href": { "type": "string", "format": "uri", "example": "https://api.signable.co.uk/v1/company/214821", "description": "URL to the updated sub-account resource." }, "company_id": { "type": "integer", "example": 214821, "description": "Unique identifier of the updated sub-account." }, "company_name": { "type": "string", "example": "Apple Tree Ltd", "description": "Updated name of the sub-account." }, "company_email": { "type": "string", "format": "email", "example": "abby@appletree.com", "description": "Updated email address of the sub-account." }, "company_updated": { "type": "string", "format": "date-time", "example": "2025-07-21T08:30:27+0000", "description": "Timestamp of when the sub-account was last updated." } } }, "CompanyDeleteResponse": { "type": "object", "required": [ "http", "message", "company_id", "company_name", "company_email" ], "properties": { "http": { "type": "integer", "example": 200, "description": "HTTP status code indicating the result of the request." }, "message": { "type": "string", "example": "Apple Tree Ltd has been removed.", "description": "Confirmation message indicating that the sub-account has been deleted." }, "company_id": { "type": "string", "example": "214821", "description": "Identifier of the deleted sub-account." }, "company_name": { "type": "string", "example": "Apple Tree Ltd", "description": "Name of the deleted sub-account." }, "company_email": { "type": "string", "format": "email", "example": "abby@appletree.com", "description": "Email address of the deleted sub-account." } } }, "PartnerUsageSummary": { "type": "object", "required": [ "company_id", "company_name", "current_usage", "previous_usage", "company_created" ], "properties": { "company_id": { "type": "string", "example": "196735", "description": "Unique identifier of the sub-account." }, "company_name": { "type": "string", "example": "ExampleSubAccount_1", "description": "Name of the sub-account." }, "current_usage": { "type": "string", "example": "1", "description": "Number of documents sent in the current reporting period." }, "previous_usage": { "type": "string", "example": "6", "description": "Number of documents sent in the previous reporting period." }, "company_created": { "type": "string", "format": "date-time", "example": "2024-09-03T09:03:12+0000", "description": "Timestamp when the sub-account was created." } } }, "PartnerUsageResponse": { "type": "object", "required": [ "http", "offset", "limit", "total_companies", "current_start_date", "current_end_date", "previous_start_date", "previous_end_date", "companies" ], "properties": { "http": { "type": "integer", "example": 200, "description": "HTTP status code of the response." }, "offset": { "type": "integer", "example": 0, "description": "Number of sub-accounts skipped before the returned result set." }, "limit": { "type": "integer", "example": 10, "description": "Maximum number of sub-accounts returned in the response." }, "total_companies": { "type": "string", "example": "2", "description": "Total number of sub-accounts available." }, "current_start_date": { "type": "string", "format": "date-time", "example": "2024-12-01T00:00:00+0000", "description": "Start of the current reporting period." }, "current_end_date": { "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00+0000", "description": "End of the current reporting period." }, "previous_start_date": { "type": "string", "format": "date-time", "example": "2024-11-01T00:00:00+0000", "description": "Start of the previous reporting period." }, "previous_end_date": { "type": "string", "format": "date-time", "example": "2024-12-01T00:00:00+0000", "description": "End of the previous reporting period." }, "companies": { "type": "array", "description": "List of usage stats per sub-account.", "items": { "$ref": "#/components/schemas/PartnerUsageSummary" } } } }, "EnvelopeUnsignedSummary": { "type": "object", "required": [ "envelope_fingerprint", "envelope_title", "envelope_status", "envelope_redirect_url", "envelope_created", "envelope_sent", "envelope_processed", "envelope_all_at_once_enabled", "envelope_requires_otp" ], "properties": { "envelope_fingerprint": { "type": "string", "description": "Unique identifier for the envelope.", "example": "584ea8b41b0d4c17a96b967433b211e6" }, "envelope_title": { "type": "string", "description": "The title of the envelope.", "example": "Another Test" }, "envelope_status": { "type": "string", "description": "Current status of the envelope. [See Envelope status values for more info →](../../envelope-status)", "enum": [ "processing", "failed", "draft", "sent", "signed", "cancelled", "expired", "rejected", "verify" ], "example": "draft" }, "envelope_redirect_url": { "type": [ "string", "null" ], "description": "Redirect URL after signing. If no redirect is set, this may be null or an empty string \"\".", "example": "https://www.example.com" }, "envelope_created": { "type": "string", "format": "date-time", "description": "Timestamp when the envelope was created (ISO 8601).", "example": "2025-07-07T11:30:27+0000" }, "envelope_sent": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the envelope was sent. Null if not yet sent.", "example": null }, "envelope_processed": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the envelope was processed. Null if not yet processed.", "example": null }, "envelope_all_at_once_enabled": { "type": "boolean", "description": "If true, the envelope is sent to all parties at the same time. If false, the envelope is sent to parties one at a time, starting with the first.\nFor more info on \"One at a time\" signing sequence, see [Setting the signing sequence](https://help.signable.app/article/191-setting-the-signing-sequence)\n", "example": true }, "envelope_requires_otp": { "type": "boolean", "description": "Indicates whether one or more parties on this envelope require one-time-password (OTP) verification. Check each party's `party_mobile_last4` value to see which parties require OTP.\nFor more info on OTPs, see [Enabling Two-Factor Authentication for Signers](https://help.signable.app/article/208-adding-a-one-time-password-to-an-envelope)\n", "example": false } } }, "EnvelopePartyBase": { "type": "object", "required": [ "party_id", "party_title", "party_mobile_last4", "party_password" ], "properties": { "party_id": { "type": "string", "description": "Unique identifier for the party in the envelope.", "example": "45631119" }, "party_title": { "type": "string", "description": "Label for the party, typically their name.", "example": "Abby Signable" }, "party_mobile_last4": { "type": [ "string", "null" ], "description": "Last 4 digits of the party's mobile number. A non-null value indicates OTP verification is required for this party.\n", "example": null }, "party_password": { "type": [ "string", "null" ], "description": "Password assigned for accessing the envelope, if applicable.", "example": "Test123" } } }, "EnvelopeParty": { "allOf": [ { "$ref": "#/components/schemas/EnvelopePartyBase" } ] }, "EnvelopeSignedSummary": { "allOf": [ { "$ref": "#/components/schemas/EnvelopeUnsignedSummary" }, { "type": "object", "description": "Summary information about a signed envelope.", "required": [ "envelope_parties" ], "properties": { "envelope_parties": { "type": "array", "items": { "$ref": "#/components/schemas/EnvelopeParty" } }, "envelope_signed_pdf": { "type": [ "string", "null" ], "format": "uri", "description": "Present when the envelope is signed. Returns a PDF file for single-document envelopes, or a ZIP file containing PDFs for multi-document envelopes.", "example": "https://api.signableapi.com/shareable/envelope?t=71afe41f-b99f-42e7-9a06-7f4070df010f" } } } ] }, "EnvelopeListResponse": { "type": "object", "required": [ "http", "offset", "limit", "total_envelopes", "envelopes" ], "properties": { "http": { "type": "integer", "description": "HTTP status code of the response.", "example": 200 }, "offset": { "type": "integer", "description": "The index of the first envelope in the result set.", "example": 0 }, "limit": { "type": "integer", "description": "The number of envelopes returned in this response.", "example": 10 }, "total_envelopes": { "type": "string", "description": "The total number of envelopes matching the query.", "example": "3" }, "envelopes": { "type": "array", "items": { "$ref": "#/components/schemas/EnvelopeSignedSummary" } } } }, "EnvelopeSendResponse": { "type": "object", "required": [ "http", "message", "href", "envelope_title", "envelope_fingerprint", "envelope_queued", "envelope_parties" ], "properties": { "http": { "type": "integer", "description": "HTTP status code indicating success.", "example": 202 }, "message": { "type": "string", "description": "A human-readable message confirming the envelope is queued.", "example": "Your envelope with title Ashbrook Road 10/06/25 will be processed and sent out." }, "href": { "type": "string", "format": "uri", "description": "URL to retrieve envelope details.", "example": "https://api.signable.co.uk/v1/envelopes/584ea8b41b0d4c17a96b967433b211e6" }, "envelope_title": { "type": "string", "description": "Title of the envelope that was submitted.", "example": "Ashbrook Road 10/06/25" }, "envelope_fingerprint": { "type": "string", "description": "Unique identifier (hash) for the envelope.", "example": "584ea8b41b0d4c17a96b967433b211e6" }, "envelope_signing_embed": { "type": "string", "description": "An embeddable HTML `\n" }, "envelope_password_protect": { "type": "boolean", "description": "Indicates if password protection was enabled on the envelope.", "example": false }, "envelope_requires_otp": { "type": "boolean", "description": "Indicates whether one or more parties require one-time-password verification. Check each party's `party_mobile_last4` value to see which parties require OTP.\n", "example": true }, "envelope_redirect_url": { "type": "string", "format": "uri", "description": "URL the signer will be redirected to after completing the envelope.", "example": "https://www.example.com" }, "envelope_queued": { "type": "string", "format": "date-time", "description": "Timestamp when the envelope was successfully queued.", "example": "2025-07-16T09:58:21+0000" }, "envelope_all_at_once_enabled": { "type": "boolean", "description": "Whether the envelope was sent to all parties simultaneously (`true`) or sequentially (`false`).", "example": false }, "envelope_parties": { "type": "array", "description": "List of parties associated with the envelope, including signer and copy recipients.", "items": { "type": "object", "properties": { "party_id": { "type": "string", "description": "Unique identifier for the party.", "example": "45831671" }, "party_title": { "type": "string", "description": "Name of the party.", "example": "Alex Mitchell" }, "party_mobile_last4": { "type": [ "string", "null" ], "description": "Last 4 digits of the party's mobile number. A non-null value indicates OTP verification is required for this party.\n", "example": "5678" }, "party_password": { "type": [ "string", "null" ], "description": "Password for party access if password protection was enabled.", "example": null } } } } } }, "EnvelopeDetailParty": { "allOf": [ { "$ref": "#/components/schemas/EnvelopePartyBase" }, { "type": "object", "required": [ "contact_id", "contact_email", "party_status", "party_signature_type", "party_role" ], "properties": { "contact_id": { "type": "string", "description": "ID of the contact linked to the party.", "example": "17225983" }, "contact_email": { "type": "string", "description": "Email address of the party.", "example": "abby@signable.co.uk" }, "party_status": { "type": "string", "enum": [ "pending", "in progress", "signed" ], "description": "Status of the party's signing progress.", "example": "in progress" }, "party_signature_type": { "type": "string", "description": "Indicates how the party will sign the envelope. Only `remote` value is supported.", "const": "remote", "example": "remote" }, "party_role": { "type": "string", "enum": [ "signer", "copy" ], "description": "Role of the party, they are either a signer or they are copied into the document with read-only permission.", "example": "signer" } } } ] }, "EnvelopeField": { "type": "object", "required": [ "field_id", "field_title", "field_type", "field_value", "party_id" ], "properties": { "field_id": { "type": "string", "description": "Unique identifier for the field.", "example": "452902787" }, "field_title": { "type": "string", "description": "The label or title of the field.", "example": "First Name" }, "field_type": { "type": "string", "enum": [ "text", "date", "checkbox", "upload", "dropdown" ], "description": "Type of the field. Signature fields are not returned.", "example": "text" }, "field_value": { "type": "string", "description": "Value filled in the field. May be empty. For `upload` fields, this contains a temporary uploaded file URL. Upload URLs are valid for 24 hours; after they expire, make another API request to retrieve fresh download links.", "example": "Abby Sackson" }, "party_id": { "type": "string", "description": "ID of the party this field is assigned to.", "example": "45631119" }, "field_merge": { "type": [ "string", "null" ], "description": "Merge field label used to pre-fill values.", "example": "Sender Name" } } }, "EnvelopeDocument": { "type": "object", "required": [ "document_fingerprint", "document_title", "document_page_total", "document_pdf_url", "document_thumbnails", "document_pages", "document_fields" ], "properties": { "document_fingerprint": { "type": "string", "description": "Unique identifier for the document.", "example": "8ab4248168761318178b5c747c643a27" }, "document_title": { "type": "string", "description": "Title of the document.", "example": "Sample Tenancy Contract" }, "document_page_total": { "type": "string", "description": "Total number of pages in the document.", "example": "2" }, "document_pdf_url": { "type": "string", "format": "uri", "description": "Direct download link to the original PDF.", "example": "https://docs.signable.co.uk/original/8ab4248168761318178b5c747c643a27.pdf" }, "document_thumbnails": { "type": "array", "description": "List of thumbnail image URLs for the document pages.", "items": { "type": "string", "format": "uri" }, "example": [ "https://docs.signable.co.uk/small/8ab4248168761318178b5c747c643a27-0.jpg", "https://docs.signable.co.uk/small/8ab4248168761318178b5c747c643a27-1.jpg" ] }, "document_pages": { "type": "array", "description": "List of full-size image URLs for the document pages.", "items": { "type": "string", "format": "uri" }, "example": [ "https://docs.signable.co.uk/large/8ab4248168761318178b5c747c643a27-0.jpg", "https://docs.signable.co.uk/large/8ab4248168761318178b5c747c643a27-1.jpg" ] }, "document_fields": { "type": "array", "description": "List of fields assigned to parties in the document.", "items": { "$ref": "#/components/schemas/EnvelopeField" } }, "document_signed_pdf": { "type": [ "string", "null" ], "format": "uri", "description": "Direct download link to the signed PDF (if the envelope is signed).", "example": "https://api.signableapi.com/shareable/envelope?t=71afe41f-b99f-42e7-9a06-7f4070df010f" } } }, "EnvelopeHistoryEvent": { "type": "object", "required": [ "history_detail", "history_ip", "history_user_agent", "history_date" ], "properties": { "history_detail": { "type": "string", "description": "Description of the event that occurred.", "example": "Sent the envelope to Abby Signable (abby@signable.co.uk) for signing" }, "history_ip": { "type": "string", "description": "IP address from where the action was triggered.", "example": "147.147.97.34" }, "history_user_agent": { "type": "string", "description": "Browser or device info from where the event occurred.", "example": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/137.0.0.0 Safari/537.36" }, "history_date": { "type": "string", "format": "date-time", "description": "Date and time when the event occurred.", "example": "2025-07-08T15:02:48+0000" } } }, "EnvelopeDetailResponse": { "allOf": [ { "$ref": "#/components/schemas/EnvelopeUnsignedSummary" }, { "type": "object", "required": [ "http", "envelope_parties", "envelope_documents", "envelope_history" ], "properties": { "http": { "type": "integer", "description": "HTTP status code of the response.", "example": 200 }, "envelope_parties": { "type": "array", "items": { "$ref": "#/components/schemas/EnvelopeDetailParty" } }, "envelope_documents": { "type": "array", "items": { "$ref": "#/components/schemas/EnvelopeDocument" } }, "envelope_signed_pdf": { "type": [ "string", "null" ], "format": "uri", "description": "Present when the envelope is signed. Returns a PDF file for single-document envelopes, or a ZIP file containing PDFs for multi-document envelopes.", "example": "https://api.signableapi.com/shareable/envelope?t=71afe41f-b99f-42e7-9a06-7f4070df010f" }, "envelope_history": { "type": "array", "items": { "$ref": "#/components/schemas/EnvelopeHistoryEvent" } }, "envelope_meta": { "type": "object", "description": "Optional metadata to associate with the envelope. These key-value pairs are stored by Signable and returned in the response and all envelope related webhooks. Useful for attaching internal IDs, status flags, tags, or any contextual information relevant to your system.\n", "additionalProperties": true, "example": { "internal_id": "ABC123", "VIP": false } } } } ] }, "EnvelopeDeleteResponse": { "type": "object", "required": [ "http", "message", "envelope_fingerprint", "envelope_title", "envelope_status" ], "properties": { "http": { "type": "integer", "example": 200, "description": "HTTP status code of the response." }, "message": { "type": "string", "example": "The envelope has been deleted", "description": "Human-readable confirmation message." }, "envelope_fingerprint": { "type": "string", "example": "584ea8b41b0d4c17a96b967433b211e6", "description": "Unique identifier for the deleted envelope." }, "envelope_title": { "type": "string", "example": "Industrial Contract", "description": "Title of the envelope at the time of deletion." }, "envelope_status": { "type": "string", "const": "deleted", "description": "The new status of the envelope after deletion.", "example": "deleted" } } }, "EnvelopeRemindResponse": { "type": "object", "required": [ "http", "message", "envelope_fingerprint", "envelope_title", "envelope_all_at_once_enabled" ], "properties": { "http": { "type": "integer", "example": 200, "description": "HTTP status code of the response." }, "message": { "type": "string", "example": "The signing parties for this envelope have been reminded.", "description": "Human-readable status message." }, "envelope_fingerprint": { "type": "string", "example": "584ea8b41b0d4c17a96b967433b211e6", "description": "Unique fingerprint of the envelope." }, "envelope_title": { "type": "string", "example": "17 John Street Tenancy Contract - 25th Jun 2025", "description": "The title of the envelope at the time of the reminder." }, "envelope_all_at_once_enabled": { "type": "boolean", "example": true, "description": "Indicates if the envelope is configured for all-at-once signing." } } }, "EnvelopeCancelResponse": { "type": "object", "required": [ "http", "message", "envelope_fingerprint", "envelope_title", "envelope_status", "envelope_processed" ], "properties": { "http": { "type": "integer", "example": 200, "description": "HTTP status code of the response." }, "message": { "type": "string", "example": "The envelope has been cancelled", "description": "Human-readable confirmation message." }, "envelope_fingerprint": { "type": "string", "example": "584ea8b41b0d4c17a96b967433b211e6", "description": "Unique identifier for the cancelled envelope." }, "envelope_title": { "type": "string", "example": "Contract Settlement", "description": "Title of the envelope at the time of cancellation." }, "envelope_status": { "type": "string", "const": "cancelled", "description": "The new status of the envelope after cancellation.", "example": "cancelled" }, "envelope_processed": { "type": "string", "format": "date-time", "example": "2025-07-14T13:34:34+0000", "description": "Timestamp when the cancellation was processed." } } }, "EnvelopeExpireResponse": { "type": "object", "required": [ "http", "message", "envelope_fingerprint", "envelope_title", "envelope_status" ], "properties": { "http": { "type": "integer", "example": 200, "description": "HTTP status code of the response." }, "message": { "type": "string", "example": "The envelope has been expired", "description": "Human-readable confirmation message." }, "envelope_fingerprint": { "type": "string", "example": "584ea8b41b0d4c17a96b967433b211e6", "description": "Unique identifier for the expired envelope." }, "envelope_title": { "type": "string", "example": "Test Envelope", "description": "Title of the envelope at the time of expiration." }, "envelope_status": { "type": "string", "const": "expired", "description": "The new status of the envelope after expiration.", "example": "expired" } } }, "EnvelopePartyUpdateRequest": { "type": "object", "required": [], "properties": { "party_email": { "type": "string", "format": "email", "description": "The new email address for the party.\n", "example": "abby+updated@signable.co.uk" }, "party_title": { "type": "string", "description": "The new title for the party.\n", "example": "Abby" } } }, "EnvelopePartyUpdateResponse": { "type": "object", "properties": { "http": { "type": "integer", "description": "HTTP status code of the response.", "example": 200 }, "party_id": { "type": "integer", "description": "The unique ID of the updated party.", "example": 1234567 }, "party_title": { "type": "string", "description": "The updated title of the party.", "example": "Abby" }, "party_email": { "type": "string", "format": "email", "description": "The updated email address of the party.", "example": "abby+updated@signable.co.uk" }, "party_role": { "type": "string", "description": "The role of the party in the envelope.", "example": "signer" } } }, "MergeField": { "type": "object", "properties": { "field_id": { "type": "string", "description": "Internal field identifier.", "example": "450927743" }, "field_merge": { "type": "string", "description": "A short label for the merge field, shown to the sender during the \"Add fields & preview\" step when preparing an envelope for sending.\n", "example": "Name of Sender" }, "field_type": { "type": "string", "description": "This will always be `text`, due to merge functionality only being available for text field type.", "const": "text", "example": "text" } } }, "TemplateParty": { "type": "object", "properties": { "party_id": { "type": "string", "example": "20459705" }, "party_name": { "type": "string", "example": "Party" }, "party_merge_fields": { "type": "array", "description": "Template fields that can optionally be pre-filled with text by the sender to personalise the document before sending.\n\n- If a merge field is filled in during sending, it will appear as read-only for the signer.\n- If left empty, the signer associated with the party ID in this object will be able to complete the field themselves.\n", "items": { "$ref": "#/components/schemas/MergeField" } } } }, "TemplateSummary": { "type": "object", "properties": { "template_id": { "type": "string", "description": "Internal identifier.", "example": "53690003" }, "template_fingerprint": { "type": "string", "description": "The unique ID used to identify this template.", "example": "b786a173554cc06371248caf0b250704" }, "template_title": { "type": "string", "description": "The name of the template.", "example": "Sample Contract" }, "template_page_total": { "type": "string", "description": "The total number of pages in the template.", "example": "1" }, "template_in_progress": { "type": "string", "description": "The number of envelopes currently in progress that use this template.", "example": "3" }, "template_parties_total": { "type": "string", "description": "The number of signing parties included in the template.", "example": "1" }, "template_widget_url": { "type": "string", "format": "uri", "description": "The direct URL to the hosted signing widget for this template.", "example": "https://sign.signable.app/#/widget/VG7Tsd3y6X" }, "template_widget_embed": { "type": "string", "description": "A script snippet for embedding the signing widget into a webpage.", "example": "" }, "template_pdf_url": { "type": "string", "format": "uri", "description": "A direct link to download the original uploaded PDF used in the template.", "example": "https://docs.signable.co.uk/original/b786a173554cc06371248caf0b250704.pdf" }, "template_thumbnails": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "An array of URLs to thumbnail images for each page of the template." }, "template_pages": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "An array of URLs to full-size images of each page in the template." }, "template_uploaded": { "type": "string", "format": "date-time", "description": "The date and time the template was uploaded (in ISO 8601 format).", "example": "2025-07-01T08:40:38+0000" }, "template_parties": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateParty" }, "description": "A list of the parties assigned to the template, including the merge fields linked to each party." } } }, "TemplatesListResponse": { "type": "object", "properties": { "http": { "type": "integer", "example": 200 }, "offset": { "type": "integer", "example": 0 }, "limit": { "type": "integer", "example": 10 }, "total_templates": { "type": "string", "example": "1" }, "templates": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateSummary" } } } }, "TemplateGetResponse": { "allOf": [ { "type": "object", "properties": { "http": { "type": "integer", "example": 200 } } }, { "$ref": "#/components/schemas/TemplateSummary" } ] }, "TemplateDeleteResponse": { "type": "object", "properties": { "http": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Sample Tenancy Contract has been removed from your template list." }, "template_id": { "type": "string", "example": "53890528" }, "tempate_fingerprint": { "type": "string", "example": "e0b3a9cbd4a6ff2cb57cfca161a39309" }, "tempate_title": { "type": "string", "example": "Sample Tenancy Contract" } } }, "Contact": { "type": "object", "properties": { "contact_id": { "type": "string", "example": "17224073" }, "contact_name": { "type": "string", "example": "Buffy The Vampire Slayer" }, "contact_email": { "type": "string", "format": "email", "example": "buffy@sunnydale.com" }, "contact_outstanding_documents": { "type": "string", "example": "0" }, "contact_created": { "type": "string", "format": "date-time", "example": "2025-07-07T09:54:08+0000" } } }, "ContactsListResponse": { "type": "object", "properties": { "http": { "type": "integer", "example": 200 }, "offset": { "type": "integer", "example": 0 }, "limit": { "type": "integer", "example": 50 }, "total_contacts": { "type": "string", "example": "3" }, "next": { "type": "string", "format": "uri", "description": "Returned when another page of contacts is available.", "example": "https://api.signable.co.uk/v1/contacts?offset=50&limit=50" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } } }, "ContactCreateRequest": { "type": "object", "required": [ "contact_name", "contact_email" ], "properties": { "contact_name": { "type": "string", "example": "Hanz Zimmer" }, "contact_email": { "type": "string", "format": "email", "example": "hanz.zimmer@music.com" } } }, "ContactCreateResponse": { "type": "object", "properties": { "http": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Hanz Zimmer has been added to your contact list." }, "href": { "type": "string", "format": "uri", "example": "https://api.signable.co.uk/v1/contacts/17224150" }, "contact_id": { "type": "string", "example": "17224150" }, "contact_name": { "type": "string", "example": "Hanz Zimmer" }, "contact_email": { "type": "string", "format": "email", "example": "hanz.zimmer@music.com" }, "contact_created": { "type": "string", "format": "date-time", "example": "2025-07-07T09:57:39+0000" } } }, "ContactGetResponse": { "type": "object", "properties": { "http": { "type": "integer", "example": 200 }, "contact_id": { "type": "integer", "example": 17224150 }, "contact_name": { "type": "string", "example": "Hanz Zimmer" }, "contact_email": { "type": "string", "format": "email", "example": "hanz.zimmer@music.com" }, "contact_outstanding_documents": { "type": "string", "example": "0" }, "contact_created": { "type": "string", "format": "date-time", "example": "2025-07-07T09:57:39+0000" } } }, "RouteNotFoundResponse": { "type": "object", "required": [ "message" ], "additionalProperties": false, "properties": { "message": { "type": "string", "example": "The route v1/contacts/abc could not be found." } } }, "ContactUpdateRequest": { "type": "object", "description": "Provide at least one of `contact_name` or `contact_email`. The API accepts partial updates.\n", "anyOf": [ { "required": [ "contact_name" ] }, { "required": [ "contact_email" ] } ], "properties": { "contact_name": { "type": "string", "example": "Nemo" }, "contact_email": { "type": "string", "description": "Email address to store for the contact.", "example": "nemo@coralreef.com" } } }, "ContactUpdateResponse": { "type": "object", "properties": { "http": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Nemo has been updated in your contact list." }, "href": { "type": "string", "format": "uri", "example": "https://api.signable.co.uk/v1/contacts/17224150" }, "contact_id": { "type": "integer", "example": 17224150 }, "contact_name": { "type": "string", "example": "Nemo" }, "contact_email": { "type": "string", "format": "email", "example": "nemo@coralreef.com" }, "contact_updated": { "type": "string", "format": "date-time", "example": "2025-07-07T09:59:25+0000" } } }, "ContactDeleteResponse": { "type": "object", "properties": { "http": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Nemo has been removed from your contact list." }, "contact_id": { "type": "integer", "example": 17224150 }, "contact_name": { "type": "string", "example": "Nemo" }, "contact_email": { "type": "string", "format": "email", "example": "nemo@coralreef.com" } } }, "ContactEnvelopeSummary": { "type": "object", "properties": { "envelope_fingerprint": { "type": "string", "example": "584ea8b41b0d4c17a96b967433b211e6" }, "envelope_title": { "type": "string", "example": "Another Test" }, "envelope_status": { "type": "string", "description": "Current status of the envelope. [See Envelope status values for more info →](../../envelope-status)", "enum": [ "processing", "failed", "draft", "sent", "signed", "cancelled", "expired", "rejected", "verify" ], "example": "draft" }, "envelope_created": { "type": "string", "format": "date-time", "example": "2025-07-07T11:30:27+0000" }, "envelope_sent": { "type": [ "string", "null" ], "format": "date-time", "example": null }, "envelope_processed": { "type": [ "string", "null" ], "format": "date-time", "example": null }, "envelope_signed_pdf": { "type": [ "string", "null" ], "format": "uri", "description": "Returned when a signed PDF link is available.", "example": "https://api.signableapi.com/shareable/envelope?t=403cebcc-60ec-4cc2-b7d6-753fb7d5c662" } } }, "ContactEnvelopesListResponse": { "type": "object", "properties": { "http": { "type": "integer", "example": 200 }, "offset": { "type": "integer", "example": 0 }, "limit": { "type": "integer", "example": 10 }, "total_envelopes": { "type": "string", "example": "3" }, "envelopes": { "type": "array", "items": { "$ref": "#/components/schemas/ContactEnvelopeSummary" } } } }, "User": { "type": "object", "properties": { "user_id": { "type": "string", "example": "836499" }, "role_id": { "type": "string", "example": "3" }, "user_name": { "type": "string", "example": "Abby Loves Signable" }, "user_email": { "type": "string", "format": "email", "example": "abby+010725@signable.co.uk" }, "user_added": { "type": "string", "format": "date-time", "example": "2025-07-01T08:40:38+0000" }, "user_last_updated": { "type": "string", "format": "date-time", "example": "2025-07-07T07:57:54+0000" } } }, "UsersListResponse": { "type": "object", "properties": { "http": { "type": "integer", "example": 200 }, "offset": { "type": "integer", "example": 0 }, "limit": { "type": "integer", "example": 50 }, "total_users": { "type": "string", "description": "Total number of users (returned as a string)", "example": "2" }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } } }, "UserCreateRequest": { "type": "object", "required": [ "user_name", "user_email", "role_id" ], "properties": { "user_name": { "type": "string", "example": "Abby Example" }, "user_email": { "type": "string", "format": "email", "example": "abby+example@wearedom.com" }, "role_id": { "type": "string", "enum": [ "1", "2", "3" ], "description": "Role assigned to the user:\n- \"1\" = User\n- \"2\" = Admin\n- \"3\" = Super-Admin\n", "example": "2" } } }, "UserCreateResponse": { "type": "object", "properties": { "http": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Abby Example has been added to your user list." }, "href": { "type": "string", "format": "uri", "example": "https://api.signable.co.uk/v1/users/837146" }, "user_id": { "type": "string", "example": "837146" }, "role_id": { "type": "string", "enum": [ "1", "2", "3" ], "description": "Role assigned to the user:\n- \"1\" = User\n- \"2\" = Admin\n- \"3\" = Super-Admin\n", "example": "1" }, "user_name": { "type": "string", "example": "Abby Example" }, "user_email": { "type": "string", "format": "email", "example": "abby+example@wearedom.com" }, "user_added": { "type": "string", "format": "date-time", "example": "2025-07-07T08:06:49+0000" } } }, "UserGetResponse": { "type": "object", "properties": { "http": { "type": "integer", "example": 200 }, "user_id": { "type": "integer", "example": 836499 }, "role_id": { "type": "string", "enum": [ "1", "2", "3" ], "description": "Role assigned to the user:\n- \"1\" = User\n- \"2\" = Admin\n- \"3\" = Super-Admin\n", "example": "3" }, "user_name": { "type": "string", "example": "Abby Loves Signable" }, "user_email": { "type": "string", "format": "email", "example": "abby+010725@signable.co.uk" }, "user_added": { "type": "string", "format": "date-time", "example": "2025-07-01T08:40:38+0000" }, "user_last_updated": { "type": "string", "format": "date-time", "example": "2025-07-07T07:57:54+0000" } } }, "UserUpdateRequest": { "type": "object", "description": "Supplying `role_id` on its own is not valid.", "properties": { "user_name": { "type": "string", "example": "Abby Smith", "description": "New name for the user." }, "user_email": { "type": "string", "format": "email", "example": "abby+jackson@signable.co.uk", "description": "New email address for the user." }, "role_id": { "type": "string", "enum": [ "1", "2", "3" ], "description": "Role assigned to the user:\n- \"1\" = User\n- \"2\" = Admin\n- \"3\" = Super-Admin\n", "example": "1" } }, "anyOf": [ { "required": [ "user_name" ] }, { "required": [ "user_email" ] } ] }, "UserUpdateResponse": { "type": "object", "properties": { "http": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Abby Smith has been updated in your user list." }, "href": { "type": "string", "format": "uri", "example": "https://api.signable.co.uk/v1/users/837154" }, "user_id": { "type": "integer", "example": 837154 }, "role_id": { "type": "string", "enum": [ "1", "2", "3" ], "example": "1" }, "user_name": { "type": "string", "example": "Abby Smith" }, "user_email": { "type": "string", "format": "email", "example": "abby+jackson@signable.co.uk" }, "user_updated": { "type": "string", "format": "date-time", "example": "2025-07-07T08:38:54+0000" } } }, "UserDeleteResponse": { "type": "object", "properties": { "http": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Abby Smith has been removed from your user list." }, "user_id": { "type": "integer", "example": 837154 }, "role_id": { "type": "string", "enum": [ "1", "2", "3" ], "description": "Role previously assigned to the deleted user:\n- \"1\" = User\n- \"2\" = Admin\n- \"3\" = Super-Admin\n", "example": "1" }, "user_email": { "type": "string", "format": "email", "example": "abby+jackson@signable.co.uk" }, "user_name": { "type": "string", "example": "Abby Smith" } } }, "WebhookListItem": { "type": "object", "required": [ "webhook_id", "webhook_url", "webhook_type", "webhook_created", "webhook_updated", "webhook_suspended" ], "properties": { "webhook_id": { "type": "string", "description": "Unique identifier of the webhook", "example": "132223" }, "webhook_url": { "type": "string", "format": "uri", "description": "The URL to which webhook events are sent", "example": "https://example.com" }, "webhook_type": { "type": "string", "description": "The type of event the webhook listens for", "enum": [ "send-envelope", "signed-envelope", "cancelled-envelope", "rejected-envelope", "bounced-envelope", "add-user", "add-contact", "opened-envelope", "add-template", "all", "signed-envelope-complete", "verify-envelope-widget", "signed-envelope-widget", "send-envelope-failed" ], "example": "send-envelope" }, "webhook_created": { "type": "string", "format": "date-time", "description": "Timestamp when the webhook was created", "example": "2025-06-23T17:15:01+0000" }, "webhook_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the webhook was last updated", "example": null }, "webhook_suspended": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the webhook was suspended (or null if active)", "example": null } } }, "WebhookListResponse": { "type": "object", "required": [ "http", "offset", "limit", "total_webhooks", "webhooks" ], "properties": { "http": { "type": "integer", "example": 200 }, "offset": { "type": "integer", "example": 10 }, "limit": { "type": "integer", "example": 10 }, "total_webhooks": { "type": "string", "example": "44" }, "next": { "type": "string", "format": "uri", "example": "https://api.signable.co.uk/v1/webhooks?offset=10&limit=10" }, "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookListItem" } } } }, "WebhookRequest": { "type": "object", "required": [ "webhook_url", "webhook_type" ], "properties": { "webhook_url": { "type": "string", "format": "uri", "description": "The callback URL where webhook events will be sent.", "example": "https://example.com" }, "webhook_type": { "type": "string", "description": "The event type to subscribe to.\n", "enum": [ "send-envelope", "signed-envelope", "cancelled-envelope", "rejected-envelope", "bounced-envelope", "add-user", "add-contact", "opened-envelope", "add-template", "all", "signed-envelope-complete", "verify-envelope-widget", "signed-envelope-widget", "send-envelope-failed" ], "example": "send-envelope" } } }, "WebhookPostResponse": { "type": "object", "required": [ "http", "message", "href", "webhook_id", "webhook_url", "webhook_type", "webhook_created" ], "properties": { "http": { "type": "integer", "description": "HTTP status code", "example": 200 }, "message": { "type": "string", "description": "Confirmation message about the webhook creation", "example": "The webhook (https://example.com) has been created" }, "href": { "type": "string", "format": "uri", "description": "API resource URL for the newly created webhook", "example": "https://api.signable.co.uk/v1/webhooks/152691" }, "webhook_id": { "type": "string", "description": "Unique identifier for the created webhook", "example": "152691" }, "webhook_url": { "type": "string", "format": "uri", "description": "The callback URL registered for the webhook", "example": "https://example.com" }, "webhook_type": { "type": "string", "description": "The event type the webhook is subscribed to", "enum": [ "send-envelope", "signed-envelope", "cancelled-envelope", "rejected-envelope", "bounced-envelope", "add-user", "add-contact", "opened-envelope", "add-template", "all", "signed-envelope-complete", "verify-envelope-widget", "signed-envelope-widget", "send-envelope-failed" ], "example": "all" }, "webhook_created": { "type": "string", "format": "date-time", "description": "The timestamp when the webhook was created", "example": "2025-06-23T17:15:01+0000" } } }, "WebhookGetResponse": { "type": "object", "required": [ "http", "webhook_id", "webhook_url", "webhook_type", "webhook_created", "webhook_updated", "webhook_suspended" ], "properties": { "http": { "type": "integer", "description": "HTTP status code", "example": 200 }, "webhook_id": { "type": "integer", "description": "Unique identifier of the webhook", "example": 152691 }, "webhook_url": { "type": "string", "format": "uri", "description": "The URL to which webhook events are sent", "example": "https://example.com" }, "webhook_type": { "type": "string", "description": "Type of event the webhook listens for", "enum": [ "send-envelope", "signed-envelope", "cancelled-envelope", "rejected-envelope", "bounced-envelope", "add-user", "add-contact", "opened-envelope", "add-template", "all", "signed-envelope-complete", "verify-envelope-widget", "signed-envelope-widget", "send-envelope-failed" ], "example": "all" }, "webhook_created": { "type": "string", "format": "date-time", "description": "Timestamp when the webhook was created", "example": "2025-06-23T17:15:01+0000" }, "webhook_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Timestamp when the webhook was last updated", "example": null }, "webhook_suspended": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the webhook is currently suspended", "example": null } } }, "WebhookUpdateRequest": { "type": "object", "description": "Payload to update a webhook. Provide `webhook_url`, `webhook_type`, or both.", "properties": { "webhook_url": { "type": "string", "format": "uri", "description": "The callback URL where webhook events will be sent.", "example": "https://example.com" }, "webhook_type": { "type": "string", "description": "The event type to subscribe to.\n", "enum": [ "send-envelope", "signed-envelope", "cancelled-envelope", "rejected-envelope", "bounced-envelope", "add-user", "add-contact", "opened-envelope", "add-template", "all", "signed-envelope-complete", "verify-envelope-widget", "signed-envelope-widget", "send-envelope-failed" ], "example": "send-envelope" } }, "anyOf": [ { "required": [ "webhook_url" ] }, { "required": [ "webhook_type" ] } ] }, "WebhookPutResponse": { "type": "object", "required": [ "http", "message", "href", "webhook_id", "webhook_secret", "webhook_url", "webhook_type", "webhook_updated" ], "properties": { "http": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "The webhook with ID 152691 has been updated" }, "href": { "type": "string", "format": "uri", "example": "https://api.signable.co.uk/v1/webhooks/152691" }, "webhook_id": { "type": "integer", "example": 152691 }, "webhook_secret": { "type": "string", "description": "Secret used to verify webhook payload signatures.", "example": "whsec_example_redacted" }, "webhook_url": { "type": "string", "format": "uri", "example": "https://abby-example.com" }, "webhook_type": { "type": "string", "enum": [ "send-envelope", "signed-envelope", "cancelled-envelope", "rejected-envelope", "bounced-envelope", "add-user", "add-contact", "opened-envelope", "add-template", "all", "signed-envelope-complete", "verify-envelope-widget", "signed-envelope-widget", "send-envelope-failed" ], "example": "all" }, "webhook_updated": { "type": "string", "format": "date-time", "example": "2025-06-24T09:32:55+0000" } } }, "WebhookDeleteResponse": { "type": "object", "required": [ "http", "message", "webhook_id", "webhook_url", "webhook_type" ], "properties": { "http": { "type": "integer", "description": "HTTP status code", "example": 200 }, "message": { "type": "string", "description": "Descriptive message confirming the webhook was removed", "example": "The webhook (https://abby-example.com) has been removed from your account." }, "webhook_id": { "type": "integer", "description": "Unique identifier of the deleted webhook", "example": 152691 }, "webhook_url": { "type": "string", "format": "uri", "description": "The URL of the deleted webhook", "example": "https://abby-example.com" }, "webhook_type": { "type": "string", "description": "Type of event the deleted webhook was subscribed to", "enum": [ "send-envelope", "signed-envelope", "cancelled-envelope", "rejected-envelope", "bounced-envelope", "add-user", "add-contact", "opened-envelope", "add-template", "all", "signed-envelope-complete", "verify-envelope-widget", "signed-envelope-widget", "send-envelope-failed" ], "example": "all" } } }, "BrandingResponse": { "type": "object", "required": [ "http", "branding_logo", "branding_colour" ], "properties": { "http": { "type": "integer", "description": "HTTP status code", "example": 200 }, "branding_logo": { "type": [ "string", "null" ], "format": "uri", "description": "A public URL to your uploaded logo (shown on emails and signing pages). Returns `null` if no logo is uploaded.\n", "example": "https://www.signable.co.uk/signable.png" }, "branding_colour": { "type": [ "string", "null" ], "description": "The primary hex colour used for branding emails and signing pages.\nReturns `null` if no branding colour is set.\n", "example": "#0095E6" } } }, "BrandingPutRequest": { "type": "object", "properties": { "branding_logo_url": { "type": [ "string", "null" ], "format": "uri", "description": "A public URL to your logo. This will be shown on emails and the signing page. Set to `null` to remove the current logo.\n", "example": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png" }, "branding_colour": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "The hex colour code (e.g. `#0095E6`) used for branded emails and signing pages.\n", "example": "#558caa" } }, "required": [ "branding_logo_url", "branding_colour" ] }, "BrandingPutResponse": { "type": "object", "required": [ "http", "message", "branding_logo", "branding_colour" ], "properties": { "http": { "type": "integer", "description": "HTTP status code", "example": 200 }, "message": { "type": "string", "description": "A success message confirming the update", "example": "Branding options have been updated." }, "branding_logo": { "type": [ "string", "null" ], "format": "uri", "description": "The final logo URL now active for your account. Will be `null` if none is set.\n", "example": "https://assets.signable.co.uk/company-logo/213690-1751360856.png" }, "branding_colour": { "type": "string", "description": "The hex code now being used for branding emails and signing pages. Will be `null` if none is set.\n", "example": "#558CAA" } } }, "BrandingEmail": { "type": "object", "required": [ "branding_email_type", "branding_email_subject", "branding_email_content", "branding_email_content_plain", "branding_email_updated" ], "properties": { "branding_email_type": { "type": "string", "description": "Type of the branding email template", "enum": [ "email-cancelled", "email-rejected", "email-reminder", "email-reminder-password", "email-send", "email-send-password", "email-signed", "email-widget-verify" ], "example": "email-cancelled" }, "branding_email_subject": { "type": "string", "description": "Subject line with variables", "example": "{company name} has cancelled a document" }, "branding_email_content": { "type": "string", "description": "HTML version of the email template", "example": "..." }, "branding_email_content_plain": { "type": "string", "description": "Plain text version of the email", "example": "{company name} has cancelled the {contract title} document." }, "branding_email_updated": { "type": "string", "format": "date-time", "description": "Last updated timestamp (ISO 8601)", "example": "2025-07-01T08:40:38+0000" } } }, "BrandingEmailsResponse": { "type": "object", "required": [ "http", "branding_emails" ], "properties": { "http": { "type": "integer", "example": 200 }, "branding_emails": { "type": "array", "items": { "$ref": "#/components/schemas/BrandingEmail" } } } }, "BrandingEmailSingleResponse": { "allOf": [ { "type": "object", "required": [ "http" ], "properties": { "http": { "type": "integer", "example": 200 } } }, { "$ref": "#/components/schemas/BrandingEmail" } ] }, "BrandingEmailPutRequest": { "type": "object", "description": "Request to update branding email attributes.", "properties": { "branding_email_subject": { "type": "string", "description": "The subject line for the email", "example": "{company name} has cancelled a test document" }, "branding_email_content": { "type": "string", "description": "The HTML content of the email", "example": "..." }, "branding_email_content_plain": { "type": "string", "description": "The plain text content of the email", "example": "Your document from {company name} has been cancelled." } } }, "BrandingEmailPutResponse": { "type": "object", "required": [ "http", "message", "branding_email_type", "branding_email_subject", "branding_email_content", "branding_email_content_plain", "branding_email_updated" ], "properties": { "http": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "email-cancelled email has been updated." }, "branding_email_type": { "type": "string", "enum": [ "email-cancelled", "email-rejected", "email-reminder", "email-reminder-password", "email-send", "email-send-password", "email-signed", "email-widget-verify" ], "example": null }, "branding_email_subject": { "type": "string", "example": "{company name} has cancelled a test document" }, "branding_email_content": { "type": "string", "description": "HTML version of the updated email", "example": "\n...\n\n" }, "branding_email_content_plain": { "type": "string", "description": "Plain text version of the updated email", "example": "A document previously sent...\n" }, "branding_email_updated": { "type": "string", "format": "date-time", "example": "2025-07-02T11:44:32+0000" } } }, "SettingsFields": { "type": "object", "description": "Common company settings shared across settings GET and PUT operations.", "properties": { "setting_signature_more_info": { "type": "boolean", "description": "If enabled, the signature will display the signer name and timestamp under each signature block on the generated Envelope PDF.\n", "example": true }, "setting_signature_format_default": { "type": "string", "description": "Which signature format is offered by default. Accepted values: `drawn`, `typed`, or `upload`.\n", "example": "typed" }, "setting_signature_format_accepted": { "type": "string", "description": "Comma-separated list of signature formats your account accepts. Valid values: `drawn`, `typed`, `upload`.\n", "example": "typed,drawn,upload" }, "setting_email_pdf_attach": { "type": "boolean", "description": "If enabled, a PDF copy of the envelope will be attached to emails sent to recipients. If disabled, recipients must instead use a link in the email to view and download the envelope.\n", "example": true }, "setting_email_pdf_attach_sender": { "type": "boolean", "description": "If enabled, a PDF copy of the signed envelope will be attached to the sign-complete notification email sent to your company email address. If disabled, the envelope must be downloaded from the app.\n", "example": true }, "setting_email_envelope_open": { "type": "boolean", "description": "If enabled, an email notification will be sent when someone opens the envelope.\n", "example": true }, "setting_email_main_email": { "type": "boolean", "description": "If enabled, notifications (signed, rejected, cancelled) are sent to your company’s main email address.\n", "example": true }, "setting_email_return_address_user": { "type": "boolean", "description": "If enabled, the \"Return Email\" will be set to the user who sent the envelope, rather than the main company email. If disabled, the \"Return Email\" will be set to your main company email address. Regardless of this property, emails will always be sent from document@signable.co.uk.\n", "example": true }, "setting_signing_consumer_regulations_act": { "type": "boolean", "description": "Enables [Consumer Contract Regulations 2013 compliance](http://www.legislation.gov.uk/uksi/2013/3134/pdfs/uksi_20133134_en.pdf) for your account. Only set this to 'Yes' if you believe that you need this enabled. This setting will change some of the terminology on the signing page to become compliant with this Act.\n", "example": false }, "setting_signing_tooltips": { "type": "boolean", "deprecated": true, "description": "If enabled, tooltip hints will be shown when a signer attempts to sign a document.\n", "example": false }, "setting_signing_questions": { "type": "boolean", "description": "If enabled, signers can send you questions or comments directly from the signing page.\n", "example": true }, "setting_pdf_audit_trail_hide": { "type": "boolean", "description": "If enabled, all party email addresses and mobile numbers will be hidden on the signing page and PDF certificate audit trail.\n", "example": true }, "setting_all_at_once_default": { "type": "boolean", "description": "If enabled, envelopes are sent to all parties simultaneously by default (all-at-once signing). If disabled, envelopes are sent to the first party only (one-at-a-time signing). Default is `true`.\n", "example": true } } }, "SettingsResponse": { "allOf": [ { "type": "object", "properties": { "http": { "type": "integer", "example": 200 } } }, { "$ref": "#/components/schemas/SettingsFields" } ] }, "UpdateSettingsRequest": { "allOf": [ { "$ref": "#/components/schemas/SettingsFields" } ] }, "UpdateSettingsResponse": { "allOf": [ { "type": "object", "properties": { "http": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "Signable Ltd settings have been updated." }, "href": { "type": "string", "format": "uri", "example": "https://api.signable.co.uk/v1/companies/32275" }, "company_id": { "type": "string", "example": "32275" }, "company_name": { "type": "string", "example": "Signable Ltd" } } }, { "$ref": "#/components/schemas/SettingsFields" } ] }, "EmbedSessionPostRequest": { "type": "object", "additionalProperties": false, "required": [ "fingerprint", "type", "config" ], "properties": { "fingerprint": { "type": "string", "description": "Unique identifier for the resource.", "example": "8ab4248168761318178b5c747c643a27" }, "type": { "type": "string", "enum": [ "envelope" ], "description": "Type of resource to create an embed session for. Currently, only `envelope` is supported." }, "config": { "type": "object", "description": "Configuration for the embed session, used to control which components are displayed and how they behave.\n", "required": [ "components" ], "properties": { "components": { "type": "array", "minItems": 1, "description": "The components to display within the embed session.", "items": { "type": "object", "required": [ "type", "version" ], "properties": { "type": { "type": "string", "enum": [ "document_setup" ], "description": "The type of component to display. Currently, only `document_setup` is supported." }, "version": { "type": "string", "description": "The version of the component to display. Currently, only `1` is supported.", "example": "1" } } } } } } } }, "EmbedSessionPostResponse": { "type": "object", "required": [ "http", "uuid", "session_url", "expires_at" ], "properties": { "http": { "type": "integer", "description": "HTTP status code of the response.", "example": 201 }, "uuid": { "type": "string", "format": "uuid", "description": "Unique identifier for the created embed session.", "example": "86fc0eac-ba4b-49fd-b6b2-98b64e51063c" }, "session_url": { "type": "string", "format": "uri", "description": "URL used to access the newly created embed session. The session token embedded in the URL is **valid for 2 minutes** from creation. After the token expires, the URL can no longer be used.\n", "example": "http://embed.signable.app/auth?session_token=9fec3d8c5fd2185e1f3d9ce7a64db570cc9a2e28" }, "expires_at": { "type": "integer", "format": "int64", "description": "Time at which the embed session token expires, expressed as the number of seconds since the Unix epoch.", "example": 1765208503 } } } }, "examples": { "CompanyListResponseExample": { "summary": "An example paginated list of sub-accounts.", "value": { "http": 200, "offset": 0, "limit": 10, "total_companies": "2", "companies": [ { "company_id": "196735", "company_name": "ExampleSubAccount_1", "company_email": "abby+1@signable.co.uk", "company_api_key": "9c66b129752046***********", "company_created": "2024-09-03T09:03:12+0000" }, { "company_id": "196737", "company_name": "ExampleSubAccount_2", "company_email": "abby+2@signable.co.uk", "company_api_key": "1v64g56ds98577***********", "company_created": "2024-09-03T09:08:49+0000" } ] } }, "CompanyCreateRequestExample": { "summary": "Example create sub-account request", "value": { "company_name": "Example Inc", "user_name": "Abby Signs", "user_email": "abby@example.com" } }, "CompanyCreateResponseExample": { "summary": "Example response for successfully creating a sub-account", "value": { "http": 200, "message": "Example Inc has been added as a company", "href": "https://api.signable.co.uk/v1/companies/214821", "company_id": "214821", "company_name": "Example Inc", "company_email": "abby@example.com", "api_key": "9c66b129752046***********", "user_id": "838931", "user_name": "Abby Signs", "user_email": "abby@example.com", "user_href": "https://api.signable.co.uk/v1/users/838931", "company_added": "2025-07-21T08:16:51+0000" } }, "CompanyGetResponseExample": { "summary": "An example paginated list of a single sub-account.", "value": { "http": 200, "company_id": 196735, "company_name": "ExampleSubAccount_1", "company_email": "abby+1@signable.co.uk", "company_api_key": "9c66b129752046***********", "company_created": "2024-09-03T09:03:12+0000", "company_usage": [ { "month": "July", "year": "2025", "sent": "1" } ] } }, "CompanyUpdateRequestExample": { "summary": "Example update sub-account request", "value": { "company_name": "Apple Tree Ltd", "company_email": "abby@appletree.com" } }, "CompanyUpdateResponseExample": { "summary": "Example response for updating a sub-account", "value": { "http": 200, "message": "Apple Tree Ltd has been updated.", "href": "https://api.signable.co.uk/v1/company/214821", "company_id": 214821, "company_name": "Apple Tree Ltd", "company_email": "abby@appletree.com", "company_updated": "2025-07-21T08:30:27+0000" } }, "CompanyDeleteResponseExample": { "summary": "Example response for successful deletion", "value": { "http": 200, "message": "Apple Tree Ltd has been removed.", "company_id": 214821, "company_name": "Apple Tree Ltd", "company_email": "abby@appletree.com" } }, "PartnerUsageResponseExample": { "summary": "Example usage data across 2 sub-accounts", "value": { "http": 200, "offset": 0, "limit": 10, "total_companies": "2", "current_start_date": "2025-07-01T00:00:00+0000", "current_end_date": "2025-08-01T00:00:00+0000", "previous_start_date": "2025-06-01T00:00:00+0000", "previous_end_date": "2025-07-01T00:00:00+0000", "companies": [ { "company_id": "196735", "company_name": "ExampleSubAccount_1", "current_usage": "1", "previous_usage": "0", "company_created": "2024-09-03T09:03:12+0000" }, { "company_id": "196737", "company_name": "ExampleSubAccount_2", "current_usage": "6", "previous_usage": "15", "company_created": "2024-09-03T09:08:49+0000" } ] } }, "EnvelopeListResponseExample": { "summary": "An example paginated list of envelopes", "value": { "http": 200, "offset": 0, "limit": 10, "total_envelopes": "3", "envelopes": [ { "envelope_fingerprint": "584ea8b41b0d4c17a96b967433b211e6", "envelope_title": "Another Test", "envelope_status": "draft", "envelope_redirect_url": "", "envelope_created": "2025-07-07T11:30:27+0000", "envelope_sent": null, "envelope_processed": null, "envelope_all_at_once_enabled": true, "envelope_requires_otp": false, "envelope_parties": [ { "party_id": "45583378", "party_title": "Abby Test", "party_mobile_last4": null, "party_password": null } ] }, { "envelope_fingerprint": "84b6334b5e5249a78e7ae3f4bba33068", "envelope_title": "2nd Test", "envelope_status": "signed", "envelope_redirect_url": "", "envelope_created": "2025-07-07T11:27:44+0000", "envelope_sent": "2025-07-07T11:29:31+0000", "envelope_processed": "2025-07-07T11:30:09+0000", "envelope_all_at_once_enabled": true, "envelope_requires_otp": false, "envelope_parties": [ { "party_id": "45583236", "party_title": "Abby Test", "party_mobile_last4": null, "party_password": null } ], "envelope_signed_pdf": "https://api.signableapi.com/shareable/envelope?t=03cbb315-4f68-400d-a5cc-c2884996d061" }, { "envelope_fingerprint": "2a965d809ca943fb98ca71d3c7c98af5", "envelope_title": "Test Envelope", "envelope_status": "signed", "envelope_redirect_url": "", "envelope_created": "2025-07-07T10:30:02+0000", "envelope_sent": "2025-07-07T11:26:20+0000", "envelope_processed": "2025-07-07T11:27:20+0000", "envelope_all_at_once_enabled": true, "envelope_requires_otp": false, "envelope_parties": [ { "party_id": "45583038", "party_title": "Jane Doe", "party_mobile_last4": null, "party_password": null } ], "envelope_signed_pdf": "https://api.signableapi.com/shareable/envelope?t=1ea41464-40ae-4638-b004-5ca1c8143318" } ] } }, "EnvelopeSendDocRequestExample": { "summary": "Example send envelope (using document) request", "value": { "envelope_title": "Singer Road 23/06/25", "user_id": 838180, "envelope_redirect_url": "https://www.example.com", "envelope_all_at_once_enabled": false, "envelope_password_protect": false, "envelope_auto_expire_hours": 144, "envelope_auto_remind_hours": 72, "envelope_meta": { "internal_id": "ABC123", "VIP": false }, "envelope_parties": [ { "party_name": "Alex Mitchell", "party_email": "abby+alex@signable.co.uk", "party_role": "signer2", "party_message": "Hello Alex, Please review and sign", "party_mobile": "+447712345678" }, { "party_name": "Abby Signers", "party_email": "abby@signable.co.uk", "party_role": "signer1", "party_message": "Hello, Please sign pronto!", "party_mobile": "+447712345678" }, { "party_name": "Spectator", "party_email": "abby+spectator@signable.co.uk", "party_role": "copy", "party_message": "Hello Alex, Please have a read" }, { "party_name": "Tim Matthews", "party_email": "abby@signable.co.uk", "party_role": "signer3", "party_message": "Hello, Please sign pronto!", "party_mobile": "+447712345678" } ], "envelope_documents": [ { "document_url": "https://yellow-della-30.tiiny.site/Tenancy-Contract-2025-v2.pdf", "document_title": "Test Agreement" }, { "document_title": "Validation Contract", "document_file_name": "ValidationContract.pdf", "document_file_content": "JVBERi0xLjQKJdPr6...Zgo2MDE3MwolJUVPRgo=" } ] } }, "EnvelopeSendTemplateRequestExample": { "summary": "Example send envelope (using single template) request", "value": { "envelope_title": "Melbourne Road 23/06/25", "user_id": 819622, "envelope_redirect_url": "https://www.example.com", "envelope_all_at_once_enabled": true, "envelope_password_protect": false, "envelope_auto_expire_hours": 144, "envelope_auto_remind_hours": 72, "envelope_meta": { "internal_id": "ABC123", "VIP": false }, "envelope_parties": [ { "party_name": "Alex Mitchell", "party_email": "abby+alex@signable.co.uk", "party_id": "20748256", "party_role": "signer", "party_message": "Hello Alex, Please review and sign", "party_mobile": "+447712345678" }, { "party_name": "Abby Signers", "party_email": "abby@signable.co.uk", "party_id": "20748255", "party_role": "signer", "party_message": "Hello, Please sign pronto!", "party_mobile": "+447712345678" }, { "party_name": "Spectator", "party_email": "abby+spectator@signable.co.uk", "party_id": "20750393", "party_role": "copy", "party_message": "Hello Maisy, Please have a read" } ], "envelope_documents": [ { "document_title": "TC 2025 v2", "document_template_fingerprint": "28f9add86f25028df2eee9adee866aba", "document_merge_fields": [ { "field_id": "454958773", "field_value": "Note that breakables are not included in rent cost" } ] } ] } }, "EnvelopeSendTemplateMultipleRequestExample": { "summary": "Example send envelope (using multiple templates) successful response", "value": { "envelope_title": "Barnsley Road 21/04/25", "user_id": 819622, "envelope_redirect_url": "https://www.example.com", "envelope_all_at_once_enabled": true, "envelope_password_protect": false, "envelope_auto_expire_hours": 144, "envelope_auto_remind_hours": 72, "envelope_meta": { "internal_id": "ABC123", "VIP": false }, "envelope_parties": [ { "party_name": "Alex Mitchell", "party_email": "abby+alex@signable.co.uk", "party_role": "signer", "party_message": "Hello Alex, Please review and sign", "party_mobile": "+447712345678", "party_documents": [ { "party_id": "20748256", "document_template_fingerprint": "28f9add86f25028df2eee9adee866aba" } ] }, { "party_name": "Abby Signers", "party_email": "abby@signable.co.uk", "party_role": "signer", "party_message": "Hello, Please sign pronto!", "party_mobile": "+447712345678", "party_documents": [ { "party_id": "20748265", "document_template_fingerprint": "88d2c9e8dc4a69ce1cd97ac1684f3e45" }, { "party_id": "20748255", "document_template_fingerprint": "28f9add86f25028df2eee9adee866aba" } ] }, { "party_name": "Spectator", "party_email": "abby+spectator@signable.co.uk", "party_role": "copy", "party_message": "Hello Maisy, Please have a read", "party_documents": [] } ], "envelope_documents": [ { "document_title": "TC 2025 v2", "document_template_fingerprint": "28f9add86f25028df2eee9adee866aba", "document_merge_fields": [ { "field_id": "454958773", "field_value": "Note that breakables are not included in rent cost" } ] }, { "document_title": "TC 2025 v3", "document_template_fingerprint": "88d2c9e8dc4a69ce1cd97ac1684f3e45" } ] } }, "EnvelopeSendDocResponseExample": { "summary": "Example send envelope (using document) successful response", "value": { "http": 202, "message": "Your envelope with title Singer Road 23/06/25 will be processed and sent out.", "href": "https://api.signable.co.uk/v1/envelopes/584ea8b41b0d4c17a96b967433b211e6", "envelope_title": "Singer Road 23/06/25", "envelope_fingerprint": "584ea8b41b0d4c17a96b967433b211e6", "envelope_password_protect": false, "envelope_requires_otp": true, "envelope_redirect_url": "https://www.example.com", "envelope_queued": "2025-07-16T14:39:02+0000", "envelope_all_at_once_enabled": false, "envelope_parties": [ { "party_id": "45849370", "party_title": "Alex Mitchell", "party_mobile_last4": "5678", "party_password": null }, { "party_id": "45849371", "party_title": "Abby Signers", "party_mobile_last4": "5678", "party_password": null }, { "party_id": "45849372", "party_title": "Spectator", "party_mobile_last4": null, "party_password": null }, { "party_id": "45849373", "party_title": "Tim Matthews", "party_mobile_last4": "5678", "party_password": null } ] } }, "EnvelopeSendTemplateResponseExample": { "summary": "Example send envelope (using single template) successful response", "value": { "http": 202, "message": "Your envelope with title Melbourne Road 23/06/25 will be processed and sent out.", "href": "https://api.signable.co.uk/v1/envelopes/584ea8b41b0d4c17a96b967433b211e6", "envelope_title": "Melbourne Road 23/06/25", "envelope_fingerprint": "584ea8b41b0d4c17a96b967433b211e6", "envelope_signing_embed": "", "envelope_password_protect": false, "envelope_redirect_url": "https://www.example.com", "envelope_queued": "2025-07-16T16:30:23+0000", "envelope_all_at_once_enabled": true, "envelope_requires_otp": true, "envelope_parties": [ { "party_id": "45855081", "party_title": "Alex Mitchell", "party_mobile_last4": "5678", "party_password": null }, { "party_id": "45855082", "party_title": "Abby Signers", "party_mobile_last4": "5678", "party_password": null }, { "party_id": "45855083", "party_title": "Spectator", "party_mobile_last4": null, "party_password": null } ] } }, "EnvelopeSendTemplateMultipleResponseExample": { "summary": "Example send envelope (using multiple templates) successful response", "value": { "http": 202, "message": "Your envelope with title Barnsley Road 21/04/25 will be processed and sent out.", "href": "https://api.signable.co.uk/v1/envelopes/584ea8b41b0d4c17a96b967433b211e6", "envelope_title": "Barnsley Road 21/04/25", "envelope_fingerprint": "584ea8b41b0d4c17a96b967433b211e6", "envelope_signing_embed": "\n", "envelope_password_protect": false, "envelope_redirect_url": "https://www.example.com", "envelope_queued": "2025-07-17T13:42:35+0000", "envelope_all_at_once_enabled": true, "envelope_requires_otp": true, "envelope_parties": [ { "party_id": "45880606", "party_title": "Alex Mitchell", "party_mobile_last4": "5678", "party_password": null }, { "party_id": "45880607", "party_title": "Abby Signers", "party_mobile_last4": "5678", "party_password": null }, { "party_id": "45880608", "party_title": "Spectator", "party_mobile_last4": null, "party_password": null } ] } }, "EnvelopeGetResponseExample": { "summary": "Example envelope details response", "value": { "http": 200, "envelope_fingerprint": "584ea8b41b0d4c17a96b967433b211e6", "envelope_title": "17 John Street Tenancy Contract - 25th Jun 2025", "envelope_status": "sent", "envelope_redirect_url": null, "envelope_created": "2025-07-08T14:58:54+0000", "envelope_sent": "2025-07-08T15:02:49+0000", "envelope_processed": null, "envelope_all_at_once_enabled": true, "envelope_requires_otp": false, "envelope_parties": [ { "party_id": "45631119", "party_title": "Abby Signable", "party_mobile_last4": null, "party_password": "Test123", "contact_id": "17225983", "contact_email": "abby@signable.co.uk", "party_status": "in progress", "party_signature_type": "remote", "party_role": "signer" }, { "party_id": "45631121", "party_title": "Sabby", "party_mobile_last4": null, "party_password": null, "contact_id": "17241370", "contact_email": "abby+010725@signable.co.uk", "party_status": "in progress", "party_signature_type": "remote", "party_role": "signer" }, { "party_id": "45631122", "party_title": "Bristol Solicitors", "party_mobile_last4": null, "party_password": null, "contact_id": "17241371", "contact_email": "test@example.com", "party_status": "pending", "party_signature_type": "remote", "party_role": "copy" } ], "envelope_documents": [ { "document_fingerprint": "78c54190abc34179919e6c2197465926", "document_title": "Sample Tenancy Contract", "document_page_total": "2", "document_pdf_url": "https://docs.signable.co.uk/original/78c54190abc34179919e6c2197465926.pdf", "document_thumbnails": [ "https://docs.signable.co.uk/small/78c54190abc34179919e6c2197465926-0.jpg", "https://docs.signable.co.uk/small/78c54190abc34179919e6c2197465926-1.jpg" ], "document_pages": [ "https://docs.signable.co.uk/large/78c54190abc34179919e6c2197465926-0.jpg", "https://docs.signable.co.uk/large/78c54190abc34179919e6c2197465926-1.jpg" ], "document_fields": [ { "field_id": "452902787", "field_title": "First Name", "field_type": "text", "field_value": "Abby Sackson", "party_id": "45631119", "field_merge": "Sender Name" }, { "field_id": "452902789", "field_title": "Date please", "field_type": "date", "field_value": "", "party_id": "45631119", "field_merge": null }, { "field_id": "452902790", "field_title": "Passport Copy", "field_type": "upload", "field_value": "https://api.signable.co.uk/download/field/N2I5YmZhMGU0NDAzMGFmMGFhZTZiYmVmODRmYWMxOTA6NTGvATg5MjE1?expires=1779373241&signature=a569a4b52ef1e3c2d47bf9d0c0de2642fc86da851ad936cb2aa090e568b8b102", "party_id": "45631119", "field_merge": null } ], "document_signed_pdf": "https://api.signableapi.com/shareable/document?t=03cbb315-4f68-400d-a5cc-c2884996d061" }, { "document_fingerprint": "2cbd40997bc64c1c9b700d80471723b9", "document_title": "Sample Contract", "document_page_total": "1", "document_pdf_url": "https://docs.signable.co.uk/original/2cbd40997bc64c1c9b700d80471723b9.pdf", "document_thumbnails": [ "https://docs.signable.co.uk/small/2cbd40997bc64c1c9b700d80471723b9-0.jpg" ], "document_pages": [ "https://docs.signable.co.uk/large/2cbd40997bc64c1c9b700d80471723b9-0.jpg" ], "document_fields": [ { "field_id": "452902797", "field_title": "Print Name", "field_type": "text", "field_value": "", "party_id": "45631119", "field_merge": null }, { "field_id": "452902798", "field_title": "Full Address", "field_type": "text", "field_value": "", "party_id": "45631119", "field_merge": null } ] } ], "envelope_history": [ { "history_detail": "Envelope generated by Abby Loves Signable", "history_ip": "147.147.97.34", "history_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/137.0.0.0 Safari/537.36", "history_date": "2025-07-08T14:58:54+0000" }, { "history_detail": "Document generated with fingerprint 78c54190abc34179919e6c2197465926", "history_ip": "147.147.97.34", "history_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/137.0.0.0 Safari/537.36", "history_date": "2025-07-08T14:58:55+0000" }, { "history_detail": "Document generated with fingerprint 2cbd40997bc64c1c9b700d80471723b9", "history_ip": "147.147.97.34", "history_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/137.0.0.0 Safari/537.36", "history_date": "2025-07-08T14:58:55+0000" }, { "history_detail": "Sent the envelope to Abby Signable (abby@signable.co.uk) for signing", "history_ip": "147.147.97.34", "history_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/137.0.0.0 Safari/537.36", "history_date": "2025-07-08T15:02:48+0000" }, { "history_detail": "Sent the envelope to Sabby (abby+010725@signable.co.uk) for signing", "history_ip": "147.147.97.34", "history_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/137.0.0.0 Safari/537.36", "history_date": "2025-07-08T15:02:49+0000" }, { "history_detail": "Document emailed to abby@signable.co.uk", "history_ip": "", "history_user_agent": "", "history_date": "2025-07-08T15:02:49+0000" }, { "history_detail": "Document emailed to abby+010725@signable.co.uk", "history_ip": "", "history_user_agent": "", "history_date": "2025-07-08T15:02:49+0000" }, { "history_detail": "Abby Signable opened the document email.", "history_ip": "66.249.93.102", "history_user_agent": "Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)", "history_date": "2025-07-09T08:37:19+0000" }, { "history_detail": "Sabby opened the document email.", "history_ip": "66.249.93.98", "history_user_agent": "Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)", "history_date": "2025-07-09T08:37:19+0000" }, { "history_detail": "Sent Abby Signable a reminder to sign the document.", "history_ip": "", "history_user_agent": "", "history_date": "2025-07-13T15:03:15+0000" }, { "history_detail": "Sent Sabby a reminder to sign the document.", "history_ip": "", "history_user_agent": "", "history_date": "2025-07-13T15:03:15+0000" }, { "history_detail": "Document emailed to abby@signable.co.uk", "history_ip": "", "history_user_agent": "", "history_date": "2025-07-13T15:03:15+0000" }, { "history_detail": "Document emailed to abby+010725@signable.co.uk", "history_ip": "", "history_user_agent": "", "history_date": "2025-07-13T15:03:15+0000" } ], "envelope_meta": { "internal_id": "ABC123", "VIP": false } } }, "EnvelopeDeleteResponseExample": { "summary": "Envelope deleted successfully", "value": { "http": 200, "message": "The envelope has been deleted", "envelope_fingerprint": "584ea8b41b0d4c17a96b967433b211e6", "envelope_title": "Test Envelope", "envelope_status": "deleted" } }, "EnvelopeRemindResponseExample": { "summary": "Reminder email triggered", "value": { "http": 200, "message": "The signing parties for this envelope have been reminded.", "envelope_fingerprint": "584ea8b41b0d4c17a96b967433b211e6", "envelope_title": "17 John Street Tenancy Contract - 25th Jun 2025", "envelope_all_at_once_enabled": true } }, "EnvelopeCancelResponseExample": { "summary": "Envelope cancelled successfully", "value": { "http": 200, "message": "The envelope has been cancelled", "envelope_fingerprint": "584ea8b41b0d4c17a96b967433b211e6", "envelope_title": "Contract Settlement", "envelope_status": "cancelled", "envelope_processed": "2025-07-14T13:34:34+0000" } }, "EnvelopeExpireResponseExample": { "summary": "Envelope expired successfully", "value": { "http": 200, "message": "The envelope has been expired", "envelope_fingerprint": "584ea8b41b0d4c17a96b967433b211e6", "envelope_title": "Industrial Contract", "envelope_status": "expired", "envelope_processed": "2025-07-14T14:37:34+0000" } }, "EnvelopePartyUpdateRequestExample": { "summary": "Update party email and title", "value": { "party_email": "abby+updated@signable.co.uk", "party_title": "Abby" } }, "EnvelopePartyUpdateResponseExample": { "summary": "Successful party update response", "value": { "http": 200, "party_id": 1234567, "party_title": "Abby", "party_email": "abby+updated@signable.co.uk", "party_role": "signer" } }, "TemplatesListResponseExample": { "summary": "Example template list response", "value": { "http": 200, "offset": 0, "limit": 10, "total_templates": "2", "templates": [ { "template_id": "53890528", "template_fingerprint": "e0b3a9cbd4a6ff2cb57cfca161a38309", "template_title": "Sample Tenancy Contract", "template_page_total": "2", "template_in_progress": "0", "template_parties_total": "1", "template_widget_url": "https://sign.signable.app/#/widget/YzVsBQ5Dyj", "template_widget_embed": "", "template_pdf_url": "https://docs.signable.co.uk/original/e0b3a9cbd4a6ff2cb57cfca161a38309.pdf", "template_thumbnails": [ "https://docs.signable.co.uk/small/e0b3a9cbd4a6ff2cb57cfca161a38309-0.jpg", "https://docs.signable.co.uk/small/e0b3a9cbd4a6ff2cb57cfca161a38309-1.jpg" ], "template_pages": [ "https://docs.signable.co.uk/large/e0b3a9cbd4a6ff2cb57cfca161a38309-0.jpg", "https://docs.signable.co.uk/large/e0b3a9cbd4a6ff2cb57cfca161a38309-1.jpg" ], "template_uploaded": "2025-07-07T15:49:43+0000", "template_parties": [ { "party_id": "20576938", "party_name": "Signer 1" } ] }, { "template_id": "53690003", "template_fingerprint": "b786a173554cc06371248caf0b250704", "template_title": "Sample Contract", "template_page_total": "1", "template_in_progress": "3", "template_parties_total": "1", "template_widget_url": "https://sign.signable.app/#/widget/", "template_widget_embed": "", "template_pdf_url": "https://docs.signable.co.uk/original/b786a173554cc06371248caf0b250704.pdf", "template_thumbnails": [ "https://docs.signable.co.uk/small/b786a173554cc06371248caf0b250704-0.jpg" ], "template_pages": [ "https://docs.signable.co.uk/large/b786a173554cc06371248caf0b250704-0.jpg" ], "template_uploaded": "2025-07-01T08:40:38+0000", "template_parties": [ { "party_id": "20459705", "party_name": "Party", "party_merge_fields": [ { "field_id": "450927743", "field_merge": "Name of Sender", "field_type": "text" } ] } ] } ] } }, "TemplateGetResponseExample": { "summary": "Example template details response", "value": { "http": 200, "template_id": "53690003", "template_fingerprint": "b786a173554cc06371248caf0b250704", "template_title": "Sample Contract", "template_page_total": "1", "template_in_progress": "3", "template_parties_total": "1", "template_widget_url": "https://sign.signable.app/#/widget/YzVsBQ5Dyj", "template_widget_embed": "", "template_pdf_url": "https://docs.signable.co.uk/original/b786a173554cc06371248caf0b250704.pdf", "template_thumbnails": [ "https://docs.signable.co.uk/small/b786a173554cc06371248caf0b250704-0.jpg" ], "template_pages": [ "https://docs.signable.co.uk/large/b786a173554cc06371248caf0b250704-0.jpg" ], "template_uploaded": "2025-07-01T08:40:38+0000", "template_parties": [ { "party_id": "20459705", "party_name": "Party", "party_merge_fields": [ { "field_id": "450927743", "field_merge": "Name of Sender", "field_type": "text" } ] } ] } }, "TemplateDeleteResponseExample": { "summary": "Example template deletion confirmation", "value": { "http": 200, "message": "Sample Tenancy Contract has been removed from your template list.", "template_id": "53890528", "tempate_fingerprint": "e0b3a9cbd4a6ff2cb57cfca161a38309", "tempate_title": "Sample Tenancy Contract" } }, "ContactsListResponseExample": { "summary": "Paginated list of contacts", "value": { "http": 200, "offset": 0, "limit": 50, "total_contacts": "100", "next": "https://api.signable.co.uk/v1/contacts?offset=50&limit=50", "contacts": [ { "contact_id": "17224073", "contact_name": "Buffy The Vampire Slayer", "contact_email": "buffy@sunnydale.com", "contact_outstanding_documents": "0", "contact_created": "2025-07-07T09:54:08+0000" }, { "contact_id": "17224050", "contact_name": "Jane Doe", "contact_email": "jane@example.com", "contact_outstanding_documents": "0", "contact_created": "2025-07-07T09:52:54+0000" }, { "contact_id": "17224044", "contact_name": "Jo Bloggs", "contact_email": "jo@example.com", "contact_outstanding_documents": "0", "contact_created": "2025-07-07T09:52:32+0000" } ] } }, "ContactCreateRequestExample": { "summary": "Example create contact request", "value": { "contact_name": "Hanz Zimmer", "contact_email": "hanz.zimmer@music.com" } }, "ContactCreateResponseExample": { "summary": "Example create contact response", "value": { "http": 200, "message": "Hanz Zimmer has been added to your contact list.", "href": "https://api.signable.co.uk/v1/contacts/17224150", "contact_id": "17224150", "contact_name": "Hanz Zimmer", "contact_email": "hanz.zimmer@music.com", "contact_created": "2025-07-07T09:57:39+0000" } }, "ContactGetResponseExample": { "summary": "Example get contact response", "value": { "http": 200, "contact_id": 17224150, "contact_name": "Hanz Zimmer", "contact_email": "hanz.zimmer@music.com", "contact_outstanding_documents": "0", "contact_created": "2025-07-07T09:57:39+0000" } }, "ContactUpdateRequestExample": { "summary": "Example update contact request", "value": { "contact_name": "Nemo", "contact_email": "nemo@coralreef.com" } }, "ContactUpdateResponseExample": { "summary": "Example update contact response", "value": { "http": 200, "message": "Nemo has been updated in your contact list.", "href": "https://api.signable.co.uk/v1/contacts/17224150", "contact_id": 17224150, "contact_name": "Nemo", "contact_email": "nemo@coralreef.com", "contact_updated": "2025-07-07T09:59:25+0000" } }, "ContactDeleteResponseExample": { "summary": "Example delete contact response", "value": { "http": 200, "message": "Nemo has been removed from your contact list.", "contact_id": 17224150, "contact_name": "Nemo", "contact_email": "nemo@coralreef.com" } }, "ContactEnvelopesListResponseExample": { "summary": "Envelopes associated with a contact", "value": { "http": 200, "offset": 0, "limit": 10, "total_envelopes": "3", "envelopes": [ { "envelope_fingerprint": "584ea8b41b0d4c17a96b967433b211e6", "envelope_title": "Another Test", "envelope_status": "draft", "envelope_created": "2025-07-07T11:30:27+0000", "envelope_sent": null, "envelope_processed": null }, { "envelope_fingerprint": "584ea8b41b0d4c17a96b967433b211e6", "envelope_title": "2nd Test", "envelope_status": "signed", "envelope_created": "2025-07-07T11:27:44+0000", "envelope_sent": "2025-07-07T11:29:31+0000", "envelope_processed": "2025-07-07T11:30:09+0000", "envelope_signed_pdf": "https://api.signableapi.com/shareable/envelope?t=403cebcc-60ec-4cc2-b7d6-753fb7d5c632" }, { "envelope_fingerprint": "584ea8b41b0d4c17a96b967433b211e6", "envelope_title": "Test Envelope", "envelope_status": "signed", "envelope_created": "2025-07-07T10:30:02+0000", "envelope_sent": "2025-07-07T11:26:20+0000", "envelope_processed": "2025-07-07T11:27:20+0000", "envelope_signed_pdf": "https://api.signableapi.com/shareable/envelope?t=3dd2069d-4a61-4c9e-99c8-9dfc737eb150" } ] } }, "UsersListResponseExample": { "summary": "Paginated user list", "value": { "http": 200, "offset": 0, "limit": 50, "total_users": "2", "users": [ { "user_id": "836499", "role_id": "3", "user_name": "Abby Loves Signable", "user_email": "abby+010725@signable.co.uk", "user_added": "2025-07-01T08:40:38+0000", "user_last_updated": "2025-07-07T07:57:54+0000" }, { "user_id": "837142", "role_id": "1", "user_name": "Sabby", "user_email": "abby+sabby@signable.co.uk", "user_added": "2025-07-07T07:58:38+0000", "user_last_updated": "2025-07-07T07:58:44+0000" } ] } }, "UserCreateRequestExample": { "summary": "Example user creation request", "value": { "user_name": "Abby Example", "user_email": "abby+example@wearedom.com", "role_id": "2" } }, "UserCreateResponseExample": { "summary": "Example successful user creation response", "value": { "http": 200, "message": "Abby Example has been added to your user list.", "href": "https://api.signable.co.uk/v1/users/837146", "user_id": "837146", "role_id": "2", "user_name": "Abby Example", "user_email": "abby+example@wearedom.com", "user_added": "2025-07-07T08:06:49+0000" } }, "UserGetResponseExample": { "summary": "Single user response", "value": { "http": 200, "user_id": 836499, "role_id": "3", "user_name": "Abby Loves Signable", "user_email": "abby+010725@signable.co.uk", "user_added": "2025-07-01T08:40:38+0000", "user_last_updated": "2025-07-07T07:57:54+0000" } }, "UserUpdateRequestUserNameOnlyExample": { "summary": "Update a user name only", "value": { "user_name": "Abby Smith" } }, "UserUpdateRequestUserEmailOnlyExample": { "summary": "Update a user email only", "value": { "user_email": "abby+jackson@signable.co.uk" } }, "UserUpdateRequestNameAndEmailExample": { "summary": "Update a user name and email", "value": { "user_name": "Abby Smith", "user_email": "abby+jackson@signable.co.uk" } }, "UserUpdateRequestExample": { "summary": "Update user details", "value": { "user_name": "Abby Smith", "user_email": "abby+jackson@signable.co.uk", "role_id": "1" } }, "UserUpdateResponseExample": { "summary": "Successful user update", "value": { "http": 200, "message": "Abby Smith has been updated in your user list.", "href": "https://api.signable.co.uk/v1/users/837154", "user_id": 837154, "role_id": "1", "user_name": "Abby Smith", "user_email": "abby+jackson@signable.co.uk", "user_updated": "2025-07-07T08:38:54+0000" } }, "UserUpdateRoleOnlyErrorExample": { "summary": "Role-only update request is rejected", "value": { "http": 400, "code": 10104, "message": "The user name and email are missing. Please make sure at least one of them is provided." } }, "UserDeleteResponseExample": { "summary": "User deletion confirmation", "value": { "http": 200, "message": "Abby Smith has been removed from your user list.", "user_id": 837154, "role_id": "1", "user_email": "abby+jackson@signable.co.uk", "user_name": "Abby Smith" } }, "WebhookListResponseExample": { "summary": "Paginated list of webhooks", "value": { "http": 200, "offset": 10, "limit": 10, "total_webhooks": "44", "next": "https://api.signable.co.uk/v1/webhooks?offset=10&limit=10", "webhooks": [ { "webhook_id": "132223", "webhook_url": "https://mylovelyendpointfortesting.free.beeceptor.com", "webhook_type": "all", "webhook_created": "2019-01-29T18:22:05+0000", "webhook_suspended": "2024-07-11T12:21:12+0000", "webhook_updated": "2024-07-11T12:21:12+0000" }, { "webhook_id": "133097", "webhook_url": "https://webhook.site/e9f2c61c-98ec-4277-bef8-cf6bca506583", "webhook_type": "send-envelope", "webhook_created": "2019-07-29T14:20:40+0000", "webhook_suspended": "2024-07-11T12:10:22+0000", "webhook_updated": "2024-07-11T12:10:22+0000" }, { "webhook_id": "133203", "webhook_url": "https://webhook.site/1b225ac0-703d-4d91-ab35-751034157ace", "webhook_type": "cancelled-envelope", "webhook_created": "2019-08-22T08:38:35+0000", "webhook_suspended": "2024-07-17T08:48:02+0000", "webhook_updated": "2024-07-17T08:48:02+0000" } ] } }, "WebhookRequestExample": { "summary": "Example of a webhook request payload", "value": { "webhook_url": "https://example.com/webhook", "webhook_type": "send-envelope" } }, "WebhookPostResponseExample": { "summary": "Example response after creating a webhook", "value": { "http": 200, "message": "The webhook (https://example.com) has been created", "href": "https://api.signable.co.uk/v1/webhooks/152691", "webhook_id": "152691", "webhook_url": "https://example.com", "webhook_type": "all", "webhook_created": "2025-06-23T17:15:01+0000" } }, "WebhookGetResponseExample": { "summary": "Example of a single webhook fetched by ID", "value": { "http": 200, "webhook_id": 152691, "webhook_url": "https://example.com", "webhook_type": "all", "webhook_created": "2025-06-23T17:15:01+0000", "webhook_updated": null, "webhook_suspended": null } }, "WebhookUpdateRequestUrlOnlyExample": { "summary": "Example of updating only the webhook URL", "value": { "webhook_url": "https://example.com/updated-webhook" } }, "WebhookUpdateRequestTypeOnlyExample": { "summary": "Example of updating only the webhook type", "value": { "webhook_type": "signed-envelope" } }, "WebhookUpdateRequestBothExample": { "summary": "Example of updating both the webhook URL and webhook type", "value": { "webhook_url": "https://example.com/updated-webhook", "webhook_type": "signed-envelope" } }, "WebhookPutResponseExample": { "summary": "Example response from updating a webhook", "value": { "http": 200, "message": "The webhook with ID 152691 has been updated", "href": "https://api.signable.co.uk/v1/webhooks/152691", "webhook_id": 152691, "webhook_secret": "whsec_example_redacted", "webhook_url": "https://abby-example.com", "webhook_type": "all", "webhook_updated": "2025-06-24T09:32:55+0000" } }, "WebhookDeleteResponseExample": { "summary": "Example response after deleting a webhook", "value": { "http": 200, "message": "The webhook (https://abby-example.com) has been removed from your account.", "webhook_id": 152691, "webhook_url": "https://abby-example.com", "webhook_type": "all" } }, "BrandingResponseExample": { "summary": "Example branding configuration", "value": { "http": 200, "branding_logo": "https://www.signable.co.uk/signable.png", "branding_colour": "#0095E6" } }, "BrandingPutRequestExample": { "summary": "Example branding update request", "value": { "branding_logo_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png", "branding_colour": "#558caa" } }, "BrandingPutResponseExample": { "summary": "Branding successfully updated", "value": { "http": 200, "message": "Branding options have been updated.", "branding_logo": "https://assets.signable.co.uk/company-logo/213690-1751360856.png", "branding_colour": "#558CAA" } }, "BrandingEmailsResponseExample": { "summary": "Example branding emails response", "value": { "http": 200, "branding_emails": [ { "branding_email_type": "email-cancelled", "branding_email_subject": "{company name} has cancelled a document", "branding_email_content": "\n\n \n \n \n
\n \n \n \n \n \n \n \n
\n \n \"{company\n \n
\n

A document previously sent to you has been cancelled

\n

{company name} has cancelled the {contract title} document.

\n

Kind regards, Signable

\n
\n
\n\n", "branding_email_content_plain": "A document previously sent to you has been cancelled\n\n{company name} has cancelled the {contract title} document.\n\nKind regards,\nSignable\n\nhttps://www.signable.co.uk\n", "branding_email_updated": "2025-07-01T08:40:38+0000" }, { "branding_email_type": "email-rejected", "branding_email_subject": "{contract title} document rejected", "branding_email_content": "...", "branding_email_content_plain": "A document you signed has been rejected...", "branding_email_updated": "2025-07-01T08:40:38+0000" }, { "branding_email_type": "email-reminder", "branding_email_subject": "{company name} has sent you a document to sign", "branding_email_content": "...", "branding_email_content_plain": "{company name} has sent you the document {contract title} to sign online...", "branding_email_updated": "2025-07-01T08:40:38+0000" }, { "branding_email_type": "email-reminder-password", "branding_email_subject": "{company name} has sent you a document to sign", "branding_email_content": "...", "branding_email_content_plain": "{company name} has also requested this document be password protected...", "branding_email_updated": "2025-07-01T08:40:38+0000" }, { "branding_email_type": "email-send", "branding_email_subject": "{company name} has sent you a document to sign", "branding_email_content": "...", "branding_email_content_plain": "{client name}, you have been sent a document to sign...", "branding_email_updated": "2025-07-01T08:40:38+0000" }, { "branding_email_type": "email-send-password", "branding_email_subject": "{company name} has sent you a document to sign", "branding_email_content": "...", "branding_email_content_plain": "{client name}, you've been sent a secure document...", "branding_email_updated": "2025-07-01T08:40:38+0000" }, { "branding_email_type": "email-signed", "branding_email_subject": "Document signed confirmation", "branding_email_content": "...", "branding_email_content_plain": "You have successfully signed {contract title}...", "branding_email_updated": "2025-07-01T08:40:38+0000" }, { "branding_email_type": "email-widget-verify", "branding_email_subject": "Verify your signed document with {company name}", "branding_email_content": "...", "branding_email_content_plain": "Please verify your email address to complete signing of {contract title}...", "branding_email_updated": "2025-07-01T08:40:38+0000" } ] } }, "BrandingEmailSingleResponseExample": { "summary": "Example single branding email response", "value": { "http": 200, "branding_email_type": "email-cancelled", "branding_email_subject": "{company name} has cancelled a document", "branding_email_content": "\n\n \n \n \n
\n \n \n \n \n \n \n \n
\n \n \"{company\n \n
\n

A document previously sent to you has been cancelled

\n

{company name} has cancelled the {contract title} document.

\n

Kind regards, Signable

\n
\n
\n\n", "branding_email_content_plain": "A document previously sent to you has been cancelled\n\n{company name} has cancelled the {contract title} document.\n\nKind regards,\nSignable\n\nhttps://www.signable.co.uk\n", "branding_email_updated": "2025-07-01T08:40:38+0000" } }, "BrandingEmailPutRequestExample": { "summary": "Update branding email", "value": { "branding_email_subject": "{company name} has cancelled a test document", "branding_email_content": "\n\n \n \n \n
\n \n \n \n \n \n \n \n
\n \n \"{company\n \n
\n

A document previously sent to you has been cancelled

\n

\n {company name} has cancelled the {contract title} document.\n

\n

\n Kind regards, Signable\n

\n
\n
\n
\n\n", "branding_email_content_plain": "A test document previously sent to you has been cancelled\r\n\r\n{company name} has cancelled the {contract title} document.\r\n\r\nKind regards,\r\nSignable\r\n\r\nhttps://www.signable.co.uk" } }, "BrandingEmailPutResponseExample": { "summary": "Updated branding email response", "value": { "http": 200, "message": "email-cancelled email has been updated.", "branding_email_type": "email-cancelled", "branding_email_subject": "{company name} has cancelled a test document", "branding_email_content": "\n\n \n \n \n
\n \n \n \n \n \n \n \n
\n \n \"{company\n \n
\n

A document previously sent to you has been cancelled

\n

\n {company name} has cancelled the {contract title} document.\n

\n

Kind regards, Signable

\n
\n
\n
\n\n", "branding_email_content_plain": "A test document previously sent to you has been cancelled\r\n\r\n{company name} has cancelled the {contract title} document.\r\n\r\nKind regards,\r\nSignable\r\n\r\nhttps://www.signable.co.uk", "branding_email_updated": "2025-07-02T11:44:32+0000" } }, "SettingsResponseExample": { "summary": "Example company settings response", "value": { "http": 200, "setting_signature_more_info": true, "setting_signature_format_accepted": "typed,drawn,upload", "setting_signature_format_default": "typed", "setting_email_pdf_attach": true, "setting_email_pdf_attach_sender": true, "setting_email_envelope_open": true, "setting_email_main_email": true, "setting_email_return_address_user": true, "setting_signing_consumer_regulations_act": false, "setting_signing_tooltips": false, "setting_signing_questions": true, "setting_pdf_audit_trail_hide": true, "setting_all_at_once_default": false } }, "SettingsPutRequestExample": { "summary": "Example of an update company settings request payload", "value": { "setting_signature_more_info": true, "setting_signature_format_accepted": "typed,drawn,upload", "setting_signature_format_default": "typed", "setting_email_pdf_attach": true, "setting_email_pdf_attach_sender": true, "setting_email_envelope_open": true, "setting_email_main_email": true, "setting_email_return_address_user": true, "setting_signing_consumer_regulations_act": false, "setting_signing_tooltips": false, "setting_signing_questions": true, "setting_pdf_audit_trail_hide": true, "setting_all_at_once_default": false } }, "SettingsPutResponseExample": { "summary": "A successful update of company settings", "value": { "http": 200, "message": "Signable Ltd settings have been updated.", "href": "https://api.signable.co.uk/v1/companies/32275", "company_id": "32275", "company_name": "Signable Ltd", "setting_signature_more_info": true, "setting_signature_format_accepted": "typed,drawn,upload", "setting_signature_format_default": "typed", "setting_email_pdf_attach": true, "setting_email_pdf_attach_sender": true, "setting_email_envelope_open": true, "setting_email_main_email": true, "setting_email_return_address_user": true, "setting_signing_consumer_regulations_act": false, "setting_signing_tooltips": true, "setting_signing_questions": false, "setting_pdf_audit_trail_hide": true, "setting_all_at_once_default": false } } } } }