{ "openapi": "3.1.0", "info": { "title": "BlockSign API", "description": "Authenticated API endpoints for uploading, configuring, inviting recipients to, signing, monitoring, and downloading BlockSign documents. Upload processing is asynchronous; clients must wait until processing is ready before inviting recipients. Signup and SSO, mandatory profile completion, email and SMS verification, Drop-In Mailbox ingestion, OCR-derived artifacts, speech/MP3, legal review, payment, and FES/QES identity onboarding are application-managed workflows and are not exposed as public API endpoints in this specification.", "contact": { "name": "BlockSign API Support", "email": "support@blocksign.io" }, "version": "1.2.0" }, "servers": [ { "url": "/", "description": "Current application server" }, { "url": "https://blocksign.io", "description": "Production Server" } ], "paths": { "/api/v1/documents": { "post": { "tags": [ "Agent API" ], "summary": "Upload a document for a signature request", "operationId": "uploadAgentDocument", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "202": { "description": "Document accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDocumentAccepted" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAuthenticationError" } } } }, "403": { "description": "Missing required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "422": { "description": "Invalid upload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentValidationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/documents/{uuid}": { "get": { "tags": [ "Agent API" ], "summary": "Get document processing status", "operationId": "getAgentDocument", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Document status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSignatureRequestStatus" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAuthenticationError" } } } }, "403": { "description": "Missing required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/signature-requests": { "post": { "tags": [ "Agent API" ], "summary": "Prepare a signature request without sending it", "operationId": "prepareAgentSignatureRequest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPrepareSignatureRequest" } } } }, "responses": { "201": { "description": "Draft prepared", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSignatureRequestStatus" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAuthenticationError" } } } }, "403": { "description": "Missing required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "409": { "description": "Document is not ready or is locked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "422": { "description": "Invalid request", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AgentValidationError" }, { "$ref": "#/components/schemas/AgentApiError" } ] } } } }, "502": { "description": "Downstream operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/signature-requests/{uuid}": { "get": { "tags": [ "Agent API" ], "summary": "Get signature request status", "operationId": "getAgentSignatureRequest", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Signature request status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSignatureRequestStatus" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAuthenticationError" } } } }, "403": { "description": "Missing required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "404": { "description": "Request not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/signature-requests/{uuid}/payment": { "get": { "tags": [ "Agent API" ], "summary": "Get payment status for a signature request", "operationId": "getAgentSignaturePayment", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Payment status and any outstanding amount", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAuthenticationError" } } } }, "403": { "description": "Missing required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "404": { "description": "Request not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Agent API" ], "summary": "Prepare payment for a signature request", "operationId": "prepareAgentSignaturePayment", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Payment status and checkout URL when payment is required", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAuthenticationError" } } } }, "403": { "description": "Missing required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "404": { "description": "Request not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/signature-requests/{uuid}/send": { "post": { "tags": [ "Agent API" ], "summary": "Explicitly send a prepared signature request", "operationId": "sendAgentSignatureRequest", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request sent or already sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSignatureRequestStatus" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAuthenticationError" } } } }, "403": { "description": "Missing required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "404": { "description": "Request not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "409": { "description": "Request cannot be sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "502": { "description": "Invitation dispatch failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/signature-requests/{uuid}/cancel": { "post": { "tags": [ "Agent API" ], "summary": "Cancel an open signature request", "operationId": "cancelAgentSignatureRequest", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSignatureRequestStatus" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAuthenticationError" } } } }, "403": { "description": "Missing required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "404": { "description": "Request not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "409": { "description": "Completed request cannot be cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "502": { "description": "Operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/signature-requests/{uuid}/audit-trail": { "get": { "tags": [ "Agent API" ], "summary": "Get the signature audit trail", "operationId": "getAgentSignatureAuditTrail", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Audit trail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAuditTrail" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAuthenticationError" } } } }, "403": { "description": "Missing required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "404": { "description": "Request not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "502": { "description": "Operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/signature-requests/{uuid}/document": { "get": { "tags": [ "Agent API" ], "summary": "Download the completed signed document", "operationId": "downloadAgentSignedDocument", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Signed PDF", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAuthenticationError" } } } }, "403": { "description": "Missing required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "404": { "description": "Request not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } }, "409": { "description": "Signed document not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApiError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/invite-for-sign": { "post": { "tags": [ "Documents" ], "summary": "Invite a user to sign a document", "description": "Invate a user\n\nInvites a user to sign a document.", "operationId": "2e78c03a612142687e0ff0ff1fdb98a2", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "uuid", "email" ], "properties": { "uuid": { "type": "string", "format": "uuid", "example": "72dcaac9-7398-408f-b4c0-c058d4a652ed" }, "email": { "type": "string", "format": "email", "example": "websinghajit@gmail.com" }, "firstname": { "type": "string", "example": "John" }, "lastname": { "type": "string", "example": "Doe" }, "page": { "description": "Page the signature is placed on, starting at 1. Omit page, x and y together to place the signature in the bottom right corner of the last page; page, x and y can only be set as a complete set.", "type": "integer", "example": 1 }, "x": { "description": "Distance from the left page edge in PDF points, measured from the top left corner of the signature rectangle.", "type": "number", "format": "float", "example": 100.5 }, "y": { "description": "Distance from the top page edge in PDF points, measured from the top left corner of the signature rectangle.", "type": "number", "format": "float", "example": 200.5 }, "signature_level": { "description": "Signature level: aes, fes or qes. Legacy values aesb, qesb and fes-eu are still accepted and normalised.", "type": "string", "example": "aes", "enum": [ "aes", "fes", "qes" ] }, "type": { "description": "Document type: signature or pod (proof of delivery)", "type": "string", "example": "signature", "enum": [ "signature", "pod" ] }, "callback_url": { "description": "Optional callback URL for status change notifications (signed, declined)", "type": "string", "format": "url", "example": "https://yourapp.com/webhook/document-status" } }, "type": "object" } } } }, "responses": { "200": { "description": "Invitation email sent successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "string", "example": "invitation email sent" }, "uuid": { "type": "string", "format": "uuid", "example": "72dcaac9-7398-408f-b4c0-c058d4a652ed" }, "email": { "type": "string", "format": "email", "example": "websinghajit@gmail.com" } }, "type": "object" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Invalid input data" } }, "type": "object" } } } }, "404": { "description": "User or document not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "User not found" } }, "type": "object" } } } }, "401": { "description": "User not authenticated" }, "402": { "description": "Payment required before invitations are sent" }, "409": { "description": "Document configuration is locked or processing is incomplete" }, "502": { "description": "Invitation email could not be sent" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/document/{uuid}/signature-level": { "put": { "tags": [ "Documents" ], "summary": "Set signature level for a document", "description": "Set signature level for a document", "operationId": "411a4a32c410b454ef409abd6b8fa541", "parameters": [ { "name": "uuid", "in": "path", "description": "Document UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "signature_level" ], "properties": { "signature_level": { "type": "string", "example": "aes", "enum": [ "aes", "fes", "qes" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Signature level updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "string", "example": "Signature level updated" }, "uuid": { "type": "string" }, "signature_level": { "type": "string" } }, "type": "object" } } } }, "400": { "description": "Invalid signature level" }, "404": { "description": "Document not found" }, "401": { "description": "User not authenticated" }, "409": { "description": "Signature level can no longer be changed" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/document/{uuid}/type": { "put": { "tags": [ "Documents" ], "summary": "Set document type (signature or pod)", "description": "Set document type", "operationId": "38aa6ae907006e0de2e8e31b003b67bf", "parameters": [ { "name": "uuid", "in": "path", "description": "Document UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type" ], "properties": { "type": { "type": "string", "example": "signature", "enum": [ "signature", "pod" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Document type updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "string", "example": "Document type updated" }, "uuid": { "type": "string" }, "type": { "type": "string" } }, "type": "object" } } } }, "400": { "description": "Invalid type" }, "404": { "description": "Document not found" }, "401": { "description": "User not authenticated" }, "409": { "description": "Document type can no longer be changed" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/document/{uuid}/callback-url": { "put": { "tags": [ "Documents" ], "summary": "Set callback URL for document status notifications", "description": "Set callback URL for a document", "operationId": "6ec51684f4123c9e53e74efd70944835", "parameters": [ { "name": "uuid", "in": "path", "description": "Document UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "callback_url" ], "properties": { "callback_url": { "type": "string", "format": "url", "example": "https://yourapp.com/webhook/document-status" } }, "type": "object" } } } }, "responses": { "200": { "description": "Callback URL updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "string", "example": "Callback URL updated" }, "uuid": { "type": "string" }, "callback_url": { "type": "string" } }, "type": "object" } } } }, "400": { "description": "Invalid callback URL" }, "404": { "description": "Document not found" }, "401": { "description": "User not authenticated" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/upload-document": { "post": { "tags": [ "Documents" ], "summary": "Upload a PDF document for asynchronous processing", "description": "Stores the original PDF and starts the document-processing pipeline. The accepted response does not mean the document is ready for invitations or signing. Poll status_url (or GET /api/documents/status with the returned UUID) until processing is ready. Internal processing may create page metadata, thumbnails, extracted/OCR text, analysis, and optional speech artifacts; those internal artifacts are not returned by this endpoint.", "operationId": "16af6a70a598e23e118260fc7a456c30", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "description": "PDF document file (only PDF format is accepted)", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "202": { "description": "Document stored and processing started", "content": { "application/json": { "schema": { "properties": { "success": { "type": "string", "example": "Document uploaded Successfully" }, "url": { "description": "Invitation configuration URL; use only after processing is ready", "type": "string", "format": "url", "example": "https://blocksign.io/invite/72dcaac9-7398-408f-b4c0-c058d4a652ed" }, "uuid": { "type": "string", "format": "uuid", "example": "72dcaac9-7398-408f-b4c0-c058d4a652ed" }, "status": { "type": "string", "example": "processing", "enum": [ "processing" ] }, "status_url": { "type": "string", "format": "url", "example": "https://blocksign.io/documents/72dcaac9-7398-408f-b4c0-c058d4a652ed/status" } }, "type": "object" } } } }, "400": { "description": "No document uploaded", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "No Document Uploaded" } }, "type": "object" } } } }, "415": { "description": "Invalid file format", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Upload only pdf document" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "User ID Does Not Exist" } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/delete-document": { "delete": { "tags": [ "Documents" ], "summary": "Delete a document", "description": "Allows authenticated users to delete a document by its UUID. If the document has not been signed, it is removed along with associated recipients and files.", "operationId": "300429cce91b66231df9bcd1d084ee64", "parameters": [ { "name": "uuid", "in": "query", "description": "The UUID of the document to be deleted", "required": true, "schema": { "type": "string", "format": "uuid", "example": "72dcaac9-7398-408f-b4c0-c058d4a652ed" } } ], "responses": { "200": { "description": "Document removed successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "string", "example": "Document Removed Successfully" }, "uuid": { "type": "string", "format": "uuid", "example": "72dcaac9-7398-408f-b4c0-c058d4a652ed" } }, "type": "object" } } } }, "400": { "description": "Invalid request or missing UUID", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Please select the uuid and it cannot be empty" } }, "type": "object" } } } }, "403": { "description": "Document cannot be deleted as it is signed", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Document is signed cannot be deleted" } }, "type": "object" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Document not found for uuid" } }, "type": "object" } } } }, "401": { "description": "User not authenticated", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "user is not authenticated" } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/download-document": { "get": { "tags": [ "Documents" ], "summary": "Download a signed document", "description": "Allows authenticated users to download a signed document using its UUID.", "operationId": "1c63064ec27ea82b3f5fefcbbe1ad967", "parameters": [ { "name": "uuid", "in": "query", "description": "The UUID of the signed document to be downloaded", "required": true, "schema": { "type": "string", "format": "uuid", "example": "72dcaac9-7398-408f-b4c0-c058d4a652ed" } } ], "responses": { "200": { "description": "Signed document download", "headers": { "Content-Disposition": { "description": "attachment; filename=document.pdf", "schema": { "type": "string" } }, "Content-Type": { "description": "application/pdf", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request or missing UUID", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Please select the uuid and it cannot be empty" } }, "type": "object" } } } }, "404": { "description": "Document not found or not signed", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Document is not signed with this uuid" } }, "type": "object" } } } }, "401": { "description": "User not authenticated", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "user is not authenticated" } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/download-invoice": { "get": { "tags": [ "Invoices" ], "summary": "Download an invoice", "description": "Allows an authenticated user to download an invoice using its UUID and ID.", "operationId": "13cb554b5a070250e00ba2f67b5f54ff", "parameters": [ { "name": "uuid", "in": "query", "description": "The UUID associated with the invoice", "required": true, "schema": { "type": "string", "format": "uuid", "example": "72dcaac9-7398-408f-b4c0-c058d4a652ed" } }, { "name": "id", "in": "query", "description": "The unique ID of the invoice", "required": true, "schema": { "type": "integer", "example": 101 } } ], "responses": { "200": { "description": "Invoice PDF file download", "headers": { "Content-Disposition": { "description": "attachment; filename=invoice.pdf", "schema": { "type": "string" } }, "Content-Type": { "description": "application/pdf", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request, missing UUID or ID", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Please select the uuid and it cannot be empty" } }, "type": "object" } } } }, "404": { "description": "Invoice not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Invoice is not found with this uuid and id" } }, "type": "object" } } } }, "401": { "description": "User not authenticated", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "user is not authenticated" } }, "type": "object" } } } }, "422": { "description": "Stored invoice path is invalid" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/documents": { "get": { "tags": [ "Documents" ], "summary": "List all documents", "description": "Retrieves a list of all documents belonging to the authenticated user.", "operationId": "f1a07916c6d51ec180fbfd24109a438c", "responses": { "200": { "description": "Successful retrieval of documents", "content": { "application/json": { "schema": { "properties": { "success": { "type": "string", "example": "List of all Documents" }, "documents": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "uuid": { "type": "string", "format": "uuid", "example": "72dcaac9-7398-408f-b4c0-c058d4a652ed" }, "name": { "type": "string", "example": "Sample Document" }, "status": { "type": "integer", "example": 1 }, "created_at": { "type": "string", "format": "date-time", "example": "2024-03-17T12:34:56Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-03-17T12:34:56Z" } }, "type": "object" } } }, "type": "object" } } } }, "404": { "description": "No document found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "No Document found" } }, "type": "object" } } } }, "401": { "description": "User not authenticated", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "user is not authenticated" } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/documents/status": { "get": { "tags": [ "Documents" ], "summary": "Get document status", "description": "Retrieves the status of a specific document belonging to the authenticated user.", "operationId": "fa601cf5ae5f7d35e9fdea046cd020bc", "parameters": [ { "name": "uuid", "in": "query", "description": "The UUID of the document.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "72dcaac9-7398-408f-b4c0-c058d4a652ed" } } ], "responses": { "200": { "description": "Successful retrieval of document status", "content": { "application/json": { "schema": { "properties": { "success": { "type": "string", "example": "List of all Documents" }, "documents": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 1 }, "uuid": { "type": "string", "format": "uuid", "example": "72dcaac9-7398-408f-b4c0-c058d4a652ed" }, "name": { "type": "string", "example": "Sample Document" }, "status": { "type": "integer", "example": 3 }, "created_at": { "type": "string", "format": "date-time", "example": "2024-03-17T12:34:56Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-03-17T12:34:56Z" } }, "type": "object" } } }, "type": "object" } } } }, "400": { "description": "Missing UUID parameter", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Please select the uuid and it cannot be empty." } }, "type": "object" } } } }, "404": { "description": "No document found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "No Document found." } }, "type": "object" } } } }, "401": { "description": "User not authenticated", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "user is not authenticated." } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/documents/signed_status": { "get": { "tags": [ "Documents" ], "summary": "Check if a document is signed", "description": "Checks whether a document associated with a given UUID and email has been signed.", "operationId": "e7e87f0bb47105afd4b1d73aebf73406", "parameters": [ { "name": "uuid", "in": "query", "description": "The UUID of the document.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "72dcaac9-7398-408f-b4c0-c058d4a652ed" } }, { "name": "email", "in": "query", "description": "The email address of the recipient.", "required": true, "schema": { "type": "string", "format": "email", "example": "websinghajit@gmail.com" } } ], "responses": { "200": { "description": "Document signed status", "content": { "application/json": { "schema": { "properties": { "success": { "type": "string", "example": "Document is signed" } }, "type": "object" } } } }, "400": { "description": "Missing UUID parameter", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Please select the uuid and it cannot be empty." } }, "type": "object" } } } }, "404": { "description": "Document not signed", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Document is Not Signed." } }, "type": "object" } } } }, "401": { "description": "User not authenticated", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "user is not authenticated." } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/documents/reminder": { "post": { "tags": [ "Documents" ], "summary": "Send a reminder email to a recipient", "description": "Sends a reminder email to a recipient for signing a document.", "operationId": "45113c8036006021f37e47d8a2014e5e", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "uuid", "email" ], "properties": { "uuid": { "description": "The UUID of the document.", "type": "string", "format": "uuid", "example": "72dcaac9-7398-408f-b4c0-c058d4a652ed" }, "email": { "description": "The email address of the recipient.", "type": "string", "format": "email", "example": "websinghajit@gmail.com" } }, "type": "object" } } } }, "responses": { "200": { "description": "Reminder email sent successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "string", "example": "Email to recipients sent successfully" }, "uuid": { "type": "string", "format": "uuid", "example": "72dcaac9-7398-408f-b4c0-c058d4a652ed" }, "email": { "type": "string", "format": "email", "example": "websinghajit@gmail.com" } }, "type": "object" } } } }, "400": { "description": "Missing or invalid parameters", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Please select the uuid and it cannot be empty." } }, "type": "object" } } } }, "404": { "description": "Document or recipient not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "No Document found with uuid." } }, "type": "object" } } } }, "401": { "description": "User not authenticated", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "user is not authenticated." } }, "type": "object" } } } }, "409": { "description": "Recipient has not been invited yet" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/sign_document": { "post": { "tags": [ "Documents" ], "summary": "Sign a document", "description": "Allows an authenticated user to sign a document by providing a valid UUID.", "operationId": "signDocument", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "uuid" ], "properties": { "uuid": { "description": "Unique identifier of the document", "type": "string", "example": "72dcaac9-7398-408f-b4c0-c058d4a652ed" }, "page": { "description": "Page number where the signature should be placed", "type": "integer", "example": 1 }, "x": { "description": "X-coordinate of the signature placement", "type": "integer", "example": 50 }, "y": { "description": "Y-coordinate of the signature placement", "type": "integer", "example": 100 } }, "type": "object" } } } }, "responses": { "200": { "description": "Document signed successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "string", "example": "document signed successfully." } }, "type": "object" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Please select the uuid and it cannot be empty." } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "user is not authenticated." } }, "type": "object" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "No Document found." } }, "type": "object" } } } }, "403": { "description": "Signing is not allowed for this recipient or document state" }, "422": { "description": "The recipient has no valid signature placement", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "enum": [ "signature_placement_required", "signature_placement_invalid" ] }, "message": { "type": "string" } }, "type": "object" } } } }, "503": { "description": "Signing service is unavailable" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/sign_as": { "post": { "tags": [ "Documents" ], "summary": "Sign a document for an invited recipient", "description": "Signs with a recipient token and an HMAC-authenticated request. The bearer API key is still required.", "operationId": "5cc937708f73f93e0d0e1fe7ed494c35", "parameters": [ { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "uuid", "email", "timestamp", "nonce", "sign_token" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "timestamp": { "type": "integer" }, "nonce": { "type": "string" }, "sign_token": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Document signed successfully" }, "400": { "description": "Required signing data is missing" }, "401": { "description": "HMAC, timestamp, nonce, or recipient token is invalid" }, "404": { "description": "Document or recipient not found" }, "409": { "description": "Recipient has already signed" }, "500": { "description": "Signing endpoint is misconfigured or failed unexpectedly" }, "503": { "description": "Signing failed and may be retried" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/mcp": { "post": { "tags": [ "Agent API" ], "summary": "Call the BlockSign MCP JSON-RPC server", "operationId": "callMcp", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcRequest" } } } }, "responses": { "200": { "description": "JSON-RPC response", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/McpJsonRpcSuccess" }, { "$ref": "#/components/schemas/McpJsonRpcError" } ] } } } }, "204": { "description": "Notification accepted" }, "400": { "description": "Malformed JSON-RPC request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcError" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAuthenticationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/mcp": { "post": { "tags": [ "Agent API" ], "summary": "Call the BlockSign MCP JSON-RPC server through the API prefix", "operationId": "callMcpThroughApiPrefix", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcRequest" } } } }, "responses": { "200": { "description": "JSON-RPC response", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/McpJsonRpcSuccess" }, { "$ref": "#/components/schemas/McpJsonRpcError" } ] } } } }, "204": { "description": "Notification accepted" }, "400": { "description": "Malformed JSON-RPC request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcError" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAuthenticationError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/signature-batches": { "post": { "tags": [ "Signature batches" ], "summary": "Create an AES signature batch", "operationId": "22be9fc6372bb053ae4755dafc2da1ed", "responses": { "201": { "description": "Batch created" }, "401": { "description": "API key is missing or invalid" }, "422": { "description": "Invalid upload or non-AES level" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/signature-batches/{batch}": { "get": { "tags": [ "Signature batches" ], "summary": "Get batch status", "operationId": "5631f7a7071bd9068c3b8adc9c6fa615", "parameters": [ { "name": "batch", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Batch status" }, "401": { "description": "API key is missing or invalid" }, "403": { "description": "Batch is not visible to this user" }, "404": { "description": "Batch not found" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/signature-batches/{batch}/fields/{field}/assignment": { "put": { "tags": [ "Signature batches" ], "summary": "Assign batch signer", "operationId": "090687e939082531c60acbff720ab8c0", "responses": { "200": { "description": "Assigned" }, "401": { "description": "API key is missing or invalid" }, "403": { "description": "Batch field is not editable by this user" }, "404": { "description": "Batch or field not found" }, "422": { "description": "Assignment data or signer is invalid" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/signature-batches/{batch}/execute": { "post": { "tags": [ "Signature batches" ], "summary": "Execute AES batch", "operationId": "d4d8940d5c2ea2689fa979dc231231ea", "responses": { "202": { "description": "Queued" }, "401": { "description": "API key is missing or invalid" }, "403": { "description": "Batch is not owned by this user" }, "404": { "description": "Batch or batch document not found" }, "409": { "description": "Batch was already executed or changed" }, "422": { "description": "Batch is not executable" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/signature-batches/{batch}/retry": { "post": { "tags": [ "Signature batches" ], "summary": "Retry failed batch items", "operationId": "48b17d2745c0922b52b3c04fad9a56df", "responses": { "202": { "description": "Queued" }, "401": { "description": "API key is missing or invalid" }, "403": { "description": "Batch is not owned by this user" }, "404": { "description": "Batch not found" }, "422": { "description": "Batch is not retryable" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/signature-batches/{batch}/archive": { "get": { "tags": [ "Signature batches" ], "summary": "Download completed batch archive", "operationId": "1c599531f2838983e6264a59b4908fdc", "responses": { "200": { "description": "ZIP archive" }, "401": { "description": "API key is missing or invalid" }, "403": { "description": "Batch is not visible to this user" }, "404": { "description": "Batch not found" }, "422": { "description": "Batch archive is not ready" }, "500": { "description": "Archive could not be created" } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "AgentApiError": { "required": [ "error" ], "properties": { "error": { "type": "string", "example": "not_found" }, "message": { "type": [ "string", "null" ] }, "required_scope": { "type": [ "string", "null" ] } }, "type": "object" }, "AgentAuthenticationError": { "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Invalid API key" } }, "type": "object" }, "AgentValidationError": { "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "AgentDocumentAccepted": { "required": [ "document_id", "filename", "status", "status_url" ], "properties": { "document_id": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "status": { "type": "string", "enum": [ "processing" ] }, "status_url": { "type": "string", "format": "uri" } }, "type": "object" }, "AgentSignerStatus": { "required": [ "email", "name", "status", "legal_regime", "signed_at" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "status": { "type": "string" }, "legal_regime": { "type": "string", "enum": [ "AUTO", "eIDAS", "ZertES" ] }, "signed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "AgentSignatureRequestStatus": { "required": [ "request_id", "document_id", "filename", "status", "processing_status", "signature_level", "sent_at", "completed", "signers", "document_url" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "document_id": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "status": { "type": "string" }, "processing_status": { "type": "string" }, "signature_level": { "type": "string", "enum": [ "aes", "fes", "qes" ] }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed": { "type": "boolean" }, "signers": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSignerStatus" } }, "document_url": { "type": [ "string", "null" ], "format": "uri" }, "sent_now": { "type": "integer", "minimum": 0 } }, "type": "object" }, "AgentPrepareSignatureRequest": { "required": [ "document_id", "signer_email", "signature_level", "page", "x", "y" ], "properties": { "document_id": { "type": "string", "format": "uuid" }, "signer_email": { "type": "string", "format": "email" }, "signer_firstname": { "type": [ "string", "null" ], "maxLength": 100 }, "signer_lastname": { "type": [ "string", "null" ], "maxLength": 100 }, "signature_level": { "type": "string", "enum": [ "aes", "AES", "fes", "FES", "qes", "QES" ] }, "legal_regime": { "type": [ "string", "null" ], "enum": [ "AUTO", "eIDAS", "ZertES", "eidas", "zertes" ] }, "page": { "description": "One-based PDF page number.", "type": "integer", "minimum": 1 }, "x": { "description": "Horizontal position in PDF units from the page left edge.", "type": "number", "minimum": 0 }, "y": { "description": "Vertical position in PDF units from the page top edge. Do not add browser, stacked-page, lower-left PDF, or signature-height offsets.", "type": "number", "minimum": 0 }, "width": { "description": "Visible signature width in PDF units. Defaults to 210.", "type": [ "number", "null" ], "exclusiveMinimum": 0 }, "height": { "description": "Visible signature height in PDF units. Defaults to 50.", "type": [ "number", "null" ], "exclusiveMinimum": 0 } }, "type": "object" }, "AgentAuditSignature": { "required": [ "email", "status", "invited_at", "signed_at", "declined_at", "level", "regime", "provider", "identity_method", "used_fasttrack" ], "properties": { "email": { "type": "string", "format": "email" }, "status": { "type": "string" }, "invited_at": { "type": [ "string", "null" ], "format": "date-time" }, "signed_at": { "type": [ "string", "null" ], "format": "date-time" }, "declined_at": { "type": [ "string", "null" ], "format": "date-time" }, "level": { "type": [ "string", "null" ] }, "regime": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ] }, "identity_method": { "type": [ "string", "null" ] }, "used_fasttrack": { "type": "boolean" } }, "type": "object" }, "AgentAuditTrail": { "required": [ "request_id", "created_at", "sent_at", "finalized_at", "status", "signatures" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "finalized_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/AgentAuditSignature" } } }, "type": "object" }, "WebhookPayload": { "title": "Webhook Payload", "description": "The payload sent to your callback URL when document status changes", "properties": { "event": { "description": "Event type identifier", "type": "string", "example": "document.status_changed" }, "document": { "properties": { "uuid": { "type": "string", "format": "uuid", "example": "d290f1ee-6c54-4b01-90e6-d701748f0851" }, "name": { "type": "string", "example": "Contract.pdf" }, "status": { "type": "string", "example": "signed", "enum": [ "signed", "declined", "canceled" ] }, "signature_level": { "type": [ "string", "null" ], "example": "aes", "enum": [ "aes", "fes", "qes" ] }, "type": { "type": [ "string", "null" ], "example": "signature", "enum": [ "signature", "pod" ] } }, "type": "object" }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-01-13T14:30:00+00:00" }, "signer": { "description": "Present only for 'signed' events", "properties": { "email": { "type": "string", "format": "email", "example": "signer@example.com" }, "name": { "type": "string", "example": "John Doe" } }, "type": [ "object", "null" ] }, "all_signed": { "description": "True if all recipients have signed (only for 'signed' events)", "type": "boolean", "example": true }, "declined_by": { "description": "Email of the person who declined (only for 'declined' events)", "type": [ "string", "null" ], "format": "email" } }, "type": "object" }, "WebhookHeaders": { "title": "Webhook Request Headers", "description": "Headers sent with webhook POST requests", "properties": { "Content-Type": { "type": "string", "example": "application/json" }, "User-Agent": { "type": "string", "example": "BlockSign-Webhook/1.0" }, "X-BlockSign-Event": { "type": "string", "example": "document.status_changed" } }, "type": "object" }, "McpJsonRpcRequest": { "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "method": { "type": "string", "example": "tools/call" }, "params": { "type": "object", "additionalProperties": true } }, "type": "object" }, "McpTextContent": { "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "type": "object" }, "McpToolCallResult": { "required": [ "content" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/McpTextContent" } }, "structuredContent": { "type": "object", "additionalProperties": true }, "isError": { "type": "boolean" } }, "type": "object" }, "McpToolDefinition": { "required": [ "name", "description", "inputSchema" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "additionalProperties": true } }, "type": "object" }, "McpInitializeResult": { "required": [ "protocolVersion", "capabilities", "serverInfo" ], "properties": { "protocolVersion": { "type": "string" }, "capabilities": { "type": "object", "additionalProperties": true }, "serverInfo": { "required": [ "name", "version" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" } }, "type": "object" } }, "type": "object" }, "McpToolsListResult": { "required": [ "tools" ], "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/McpToolDefinition" } } }, "type": "object" }, "McpPingResult": { "maxProperties": 0, "type": "object" }, "McpJsonRpcSuccess": { "required": [ "jsonrpc", "id", "result" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "result": { "oneOf": [ { "$ref": "#/components/schemas/McpInitializeResult" }, { "$ref": "#/components/schemas/McpToolsListResult" }, { "$ref": "#/components/schemas/McpToolCallResult" }, { "$ref": "#/components/schemas/McpPingResult" } ] } }, "type": "object" }, "McpJsonRpcError": { "required": [ "jsonrpc", "id", "error" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "null" } ] }, "error": { "required": [ "code", "message" ], "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true } }, "type": "object" } }, "type": "object" } }, "securitySchemes": { "ApiKeyAuth": { "type": "http", "description": "Enter your API key in the format (Bearer ). Get your API key from your profile settings.", "bearerFormat": "API Key", "scheme": "bearer" }, "security": [ { "sanctum": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Enter token in format (Bearer )" } } ] } }, "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Documents", "description": "Upload, process, configure, invite, sign, monitor, and download documents" }, { "name": "Agent API", "description": "Draft-first REST resources shared with MCP clients" }, { "name": "Signature batches", "description": "AES-only multi-document signature batches. FES and QES are rejected." }, { "name": "Invoices", "description": "Invoices" } ] }