{ "openapi": "3.0.0", "info": { "title": "Document Generation API", "description": "API for generating documents based on templates and user data.", "version": "1.0.0" }, "servers": [ { "url": "/", "description": "API Server" } ], "paths": { "/api/document-generation/generate": { "post": { "tags": [ "Document Generation" ], "summary": "Generate a document based on the provided request data", "description": "This endpoint processes the document generation request, validates the input, computes the summary, and returns the generated document as a downloadable file.", "operationId": "generateDocument", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/GenerateDocumentRequestSchema" } }, "application/json": { "schema": { "$ref": "#/components/schemas/GenerateDocumentRequestSchema" } } } }, "responses": { "202": { "description": "Generation job accepted and queued. Poll GET /api/document-generation/status/{job_id} or listen for the document_generation.completed webhook to obtain the download URL.", "content": { "application/json": { "schema": { "properties": { "job_id": { "description": "Unique ID for this generation job. Use it to poll for status.", "type": "string" }, "status": { "description": "Always 'in_progress' at submission time.", "type": "string", "example": "in_progress" } }, "type": "object" } } } }, "422": { "description": "Validation error occurred.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "The validation error message.", "type": "string" } }, "type": "object" } } } }, "500": { "description": "An error occurred while processing the request.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "A generic error message.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/document-generation/status/{job_id}": { "get": { "tags": [ "Document Generation" ], "summary": "Get the status of a single generation job", "description": "Returns the current status and, once completed, a temporary download URL valid for 72 hours.", "operationId": "generationStatus", "parameters": [ { "name": "job_id", "in": "path", "description": "The job_id returned by POST /generate.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationHistoryItem" } } } }, "404": { "description": "Job not found." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/document-generation/history": { "get": { "tags": [ "Document Generation" ], "summary": "List generation history with optional filters", "description": "Returns a paginated list of document generation jobs. Each job includes file details and a temporary download URL (when the file is still available). Files are deleted 72 hours after generation unless saved via /api/files/save.", "operationId": "generationHistory", "parameters": [ { "name": "job_id", "in": "query", "description": "Filter by a specific job_id.", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status.", "required": false, "schema": { "type": "string", "enum": [ "in_progress", "completed", "failed", "expired" ] } }, { "name": "template_id", "in": "query", "description": "Filter by template unique_id.", "required": false, "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "description": "Filter jobs created on or after this date (YYYY-MM-DD).", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "Filter jobs created on or before this date (YYYY-MM-DD).", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "per_page", "in": "query", "description": "Results per page (1-100, default 20).", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page number.", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paginated list of generation jobs.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GenerationHistoryItem" } }, "meta": { "properties": { "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 5 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 97 } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/document-merge/merge": { "post": { "tags": [ "Document Merge" ], "summary": "Merge multiple documents into a single file", "description": "This endpoint merges multiple documents into a single file in the specified format and returns a temporary URL to the merged file.", "operationId": "mergeDocuments", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/MergeDocumentRequestSchema" } }, "application/json": { "schema": { "$ref": "#/components/schemas/MergeDocumentRequestSchema" } } } }, "responses": { "200": { "description": "Documents merged successfully. The response contains a temporary URL to the merged file, valid for 72 hours.", "content": { "application/json": { "schema": { "properties": { "url": { "description": "A temporary URL to the merged file hosted on the file server. This URL expires in 72 hours.", "type": "string" } }, "type": "object" } } } }, "422": { "description": "Validation error occurred.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "The validation error message.", "type": "string" } }, "type": "object" } } } }, "500": { "description": "An error occurred while processing the request.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "A generic error message.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/files": { "get": { "tags": [ "Files" ], "summary": "List files and folders for the authenticated user", "operationId": "e9c1f66551b66d42835e54f5fa40c777", "parameters": [ { "name": "id", "in": "query", "description": "Parent folder id to list (optional)", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of files and folders", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserFile" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/files/save": { "post": { "tags": [ "Files" ], "summary": "Save a generated document to permanent file storage", "operationId": "e7d243d672df9875cb3b17a45e54b04c", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "job_id" ], "properties": { "job_id": { "description": "The job_id returned from the document generation endpoint.", "type": "string", "example": "bd95b875-78f7-4bc6-b5cf-96bf520ac317" }, "folder_id": { "description": "ID of the folder to save into. Omit or null for root folder.", "type": "integer", "example": null, "nullable": true }, "filename": { "description": "Optional custom filename (only applies to single-file jobs). Defaults to the generated filename.", "type": "string", "example": "contract_signed.pdf", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Files saved successfully. For multi-file jobs, all individual files are saved.", "content": { "application/json": { "schema": { "properties": { "saved": { "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 42 }, "name": { "type": "string", "example": "document.pdf" }, "path": { "type": "string", "example": "files/697b8720bd994/document.pdf" } }, "type": "object" } }, "count": { "description": "Number of files saved.", "type": "integer", "example": 1 } }, "type": "object" } } } }, "404": { "description": "Job or file not found" }, "410": { "description": "File has expired and been deleted" }, "422": { "description": "Validation error" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/files/download/{id}": { "get": { "tags": [ "Files" ], "summary": "Get a temporary download URL for a file", "operationId": "892fe78310f054d266b7856349221ebe", "parameters": [ { "name": "id", "in": "path", "description": "ID of the file to download", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Temporary download URL", "content": { "application/json": { "schema": { "properties": { "url": { "type": "string", "example": "https://s3.amazonaws.com/bucket/files/5/document.pdf?X-Amz-..." }, "expires_at": { "type": "string", "format": "date-time", "example": "2025-01-02T12:00:00Z" } }, "type": "object" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Invalid id" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthenticated" } }, "type": "object" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Unauthorized file access" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "File not found" } }, "type": "object" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Failed to generate download link" } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/image-generation/generate": { "post": { "tags": [ "Image Generation" ], "summary": "Generate images", "description": "Starts an asynchronous image generation job. Provide a template ID, field mapping, and data (either as inline JSON or a CSV/XLSX file upload). The job processes in the background. Use webhooks or poll the job status endpoint to know when it completes. Each image costs 1 credit. Maximum 2000 images per job.", "operationId": "generateImages", "requestBody": { "description": "Use application/json for inline data or multipart/form-data for file uploads.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ImageGenerationRequest" } } } }, "responses": { "200": { "description": "Job started successfully.", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Image generation job started. You will receive a webhook when it completes." }, "job_id": { "type": "integer", "example": 42 }, "total_images": { "type": "integer", "example": 10 }, "credits_required": { "type": "integer", "example": 10 } }, "type": "object" } } } }, "400": { "description": "Bad request (empty data, too many rows, template has no placeholders).", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Data file is empty." } }, "type": "object" } } } }, "401": { "description": "Unauthenticated." }, "402": { "description": "Insufficient credits.", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Insufficient credits. Need 10, have 5." }, "credits_required": { "type": "integer", "example": 10 }, "credits_available": { "type": "integer", "example": 5 } }, "type": "object" } } } }, "404": { "description": "Template not found.", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Template not found." } }, "type": "object" } } } }, "422": { "description": "Validation error (missing field mapping, invalid data columns).", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Missing field mapping for placeholders: Full_Name, Title" }, "template_placeholders": { "type": "array", "items": { "type": "string" } }, "data_columns": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "500": { "description": "Server error." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/image-generation/jobs/{id}": { "get": { "tags": [ "Image Generation" ], "summary": "Get job status", "description": "Returns the current status of an image generation job. When the job is completed, the response includes a signed download URL valid for 24 hours. When failed, it includes the error message.", "operationId": "getImageGenerationJobStatus", "parameters": [ { "name": "id", "in": "path", "description": "The image generation job ID.", "required": true, "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "Job status retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageGenerationJobStatus" } } } }, "401": { "description": "Unauthenticated." }, "404": { "description": "Job not found.", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Job not found." } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/image-generation/jobs/{id}/download": { "get": { "tags": [ "Image Generation" ], "summary": "Download job output", "description": "Returns a signed download URL for the completed job's ZIP file. The URL is valid for 24 hours. The ZIP contains all generated PNG images.", "operationId": "downloadImageGenerationJob", "parameters": [ { "name": "id", "in": "path", "description": "The image generation job ID.", "required": true, "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "Download URL generated.", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "download_url": { "description": "Signed URL to download the ZIP file. Valid for 24 hours.", "type": "string" }, "expires_at": { "description": "Expiry time of the download URL.", "type": "string", "format": "date-time" } }, "type": "object" } } } }, "400": { "description": "Job is not completed or has no output.", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Job is not completed yet or has no output." } }, "type": "object" } } } }, "401": { "description": "Unauthenticated." }, "404": { "description": "Job not found.", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Job not found." } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/image-templates": { "get": { "tags": [ "Image Templates" ], "summary": "List image templates", "description": "Returns all saved image templates for the authenticated user, including their placeholder names and types.", "operationId": "listImageTemplates", "responses": { "200": { "description": "Templates retrieved successfully.", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "templates": { "type": "array", "items": { "$ref": "#/components/schemas/ImageTemplate" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated. Invalid or missing API key." } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/image-templates/{id}": { "get": { "tags": [ "Image Templates" ], "summary": "Get image template details", "description": "Returns a single image template with full placeholder details including font, position, and size properties.", "operationId": "getImageTemplate", "parameters": [ { "name": "id", "in": "path", "description": "The image template ID.", "required": true, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Template retrieved successfully.", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "template": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Certificate Template" }, "width": { "type": "integer", "example": 1920 }, "height": { "type": "integer", "example": 1080 }, "placeholders": { "type": "array", "items": { "$ref": "#/components/schemas/ImageTemplatePlaceholderFull" } }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated." }, "404": { "description": "Template not found.", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Template not found." } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/signature-requests": { "get": { "tags": [ "E-Signatures" ], "summary": "List signature requests", "description": "Returns a paginated list of all e-signature requests for the authenticated user.", "operationId": "listSignatureRequests", "parameters": [ { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "draft", "sent", "partially_signed", "completed", "declined", "expired", "cancelled" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Paginated list of signature requests", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SignatureRequestResponse" } }, "meta": { "properties": { "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 3 }, "total": { "type": "integer", "example": 52 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "E-Signatures" ], "summary": "Send an existing document for signing", "description": "Send any PDF for e-signature without generating it through ActiveMerge. Provide either a publicly accessible URL to the PDF or the job_id of a previously generated document.", "operationId": "createSignatureRequest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "document_url": { "description": "Publicly accessible URL to a PDF. Required if job_id is not provided.", "type": "string", "format": "url", "example": "https://yourstorage.com/contracts/nda-v3.pdf", "nullable": true }, "job_id": { "description": "job_id from a previous document generation. Required if document_url is not provided.", "type": "string", "example": "018e9f2a-3b7c-7000-8c4d-1e2f3a4b5c6d", "nullable": true }, "signers": { "description": "List of signers. Literal values only — no {{Column}} references.", "type": "array", "items": { "$ref": "#/components/schemas/StandaloneSignerInput" } }, "title": { "type": "string", "example": "NDA — Acme Corp", "nullable": true }, "message": { "type": "string", "example": "Please review and sign.", "nullable": true }, "expires_days": { "type": "integer", "example": 14, "nullable": true }, "sequential": { "type": "boolean", "example": false, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Signature request created and sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureRequestResponse" } } } }, "403": { "description": "E-signature add-on not active" }, "422": { "description": "Validation error or document could not be retrieved" }, "500": { "description": "Failed to send to signing provider" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/signature-requests/{id}": { "get": { "tags": [ "E-Signatures" ], "summary": "Get a signature request", "description": "Returns the full detail of a signature request including all signers and their individual signing URLs.", "operationId": "getSignatureRequest", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the signature request", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Signature request detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureRequestResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/signature-requests/{id}/cancel": { "post": { "tags": [ "E-Signatures" ], "summary": "Cancel a signature request", "description": "Cancels an in-progress signing request. Cannot be called on requests that are already completed, declined, expired, or cancelled.", "operationId": "cancelSignatureRequest", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the signature request", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request cancelled", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "cancelled" } }, "type": "object" } } } }, "404": { "description": "Not found" }, "422": { "description": "Request is already in a terminal state", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "This signing request is already completed and cannot be cancelled." } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/signature-requests/{id}/download": { "get": { "tags": [ "E-Signatures" ], "summary": "Download the signed document", "description": "Streams the completed signed PDF. Only available when the signature request status is 'completed'.", "operationId": "downloadSignedDocument", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the signature request", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "PDF file stream", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Not found or signed document not yet available" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/templates": { "get": { "tags": [ "Templates" ], "summary": "List all templates for the authenticated user", "operationId": "d9fe6360534ff132cfc611ee39f73547", "responses": { "200": { "description": "List of templates", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/templates/{id}/placeholders": { "get": { "tags": [ "Templates" ], "summary": "Get placeholders from a template", "operationId": "183ca39eaffb388270a3436098b35c70", "parameters": [ { "name": "id", "in": "path", "description": "Unique ID of the template", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of placeholders", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Template not found" } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/user/credits": { "get": { "tags": [ "User" ], "summary": "Returns the credits details for the authenticated user.", "description": "Get the remaining credits for the authenticated user.", "operationId": "getUserCredits", "responses": { "200": { "description": "Successfully retrieved remaining credits", "content": { "application/json": { "schema": { "properties": { "total": { "type": "integer", "example": 50 }, "used": { "type": "integer", "example": 40 }, "left": { "type": "integer", "example": 10 } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/workflows": { "get": { "tags": [ "Workflows" ], "summary": "List all workflows for the authenticated user", "operationId": "3f82ed5bc563ea220c0671e827f26150", "responses": { "200": { "description": "List of workflows", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Workflow" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/workflows/generate": { "post": { "tags": [ "Workflows" ], "summary": "Generate documents for a workflow based on the provided request data", "description": "This endpoint processes the workflow generation request, validates the input, and returns the generated documents as downloadable files.", "operationId": "generateWorkflowDocuments", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "required": [ "workflow_id", "data", "format" ], "properties": { "workflow_id": { "description": "The unique ID of the workflow to be used for document generation.", "type": "string", "example": "workflow_abc123" }, "data": { "description": "An associative array of data to populate the template placeholders.", "type": "object", "example": { "placeholder1": "value1", "placeholder2": "value2" } }, "format": { "description": "The format of the documents to be generated (e.g., PDF, Original Format).", "type": "string", "enum": [ "pdf", "original" ], "example": "pdf" } }, "type": "object" } }, "application/json": { "schema": { "required": [ "workflow_id", "data", "format" ], "properties": { "workflow_id": { "description": "The unique ID of the workflow to be used for document generation.", "type": "string", "example": "workflow_abc123" }, "data": { "description": "An associative array of data to populate the template placeholders.", "type": "object", "example": { "placeholder1": "value1", "placeholder2": "value2" } }, "format": { "description": "The format of the documents to be generated (e.g., PDF, Original Format).", "type": "string", "enum": [ "pdf", "original" ], "example": "pdf" } }, "type": "object" } } } }, "responses": { "200": { "description": "Documents generated successfully. The response contains temporary URLs to the files, valid for 72 hours.", "content": { "application/json": { "schema": { "properties": { "url": { "description": "A temporary URL to the generated file hosted on the file server. This URL expires in 72 hours.", "type": "string" } }, "type": "object" } } } }, "422": { "description": "Validation error occurred.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "The validation error message.", "type": "string" } }, "type": "object" } } } }, "500": { "description": "An error occurred while processing the request.", "content": { "application/json": { "schema": { "properties": { "message": { "description": "A generic error message.", "type": "string" } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/workflows/{id}/placeholders": { "get": { "tags": [ "Workflows" ], "summary": "Get placeholders from a workflow", "operationId": "449124e587417f1bd370240d69e5ca0a", "parameters": [ { "name": "id", "in": "path", "description": "Unique ID of the workflow", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of placeholders", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "404": { "description": "Workflow not found", "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "example": "Workflow not found" } }, "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "GenerateDocumentRequestSchema": { "required": [ "template_id", "data", "format" ], "properties": { "template_id": { "description": "The unique ID of the template to be used for document generation.", "type": "string", "example": "abc123" }, "data": { "description": "An associative array of data to populate the template placeholders.", "type": "object", "example": { "ClientName": "Acme Corp", "ClientEmail": "legal@acme.com" } }, "format": { "description": "The format of the document to be generated.", "type": "string", "enum": [ "pdf", "docx", "pptx" ], "example": "pdf" }, "sign_config": { "oneOf": [ { "$ref": "#/components/schemas/SignConfigInput" } ], "nullable": true, "description": "Optional. When provided, the document is sent for e-signature immediately after generation." } }, "type": "object" }, "GenerationHistoryItem": { "properties": { "job_id": { "type": "string", "example": "bd95b875-78f7-4bc6-b5cf-96bf520ac317" }, "status": { "type": "string", "example": "completed" }, "file": { "type": "string", "example": "document.pdf", "nullable": true }, "files": { "type": "array", "items": { "type": "string" }, "example": [ "contract_1.pdf", "contract_2.pdf" ] }, "template_ids": { "type": "array", "items": { "type": "string" }, "example": [ "69a2ef89c3d92" ] }, "total_records": { "type": "integer", "example": 1 }, "processing_time": { "description": "Processing time in seconds.", "type": "integer", "example": 2, "nullable": true }, "download_url": { "description": "Temporary download URL, valid for 72 hours. Null if file has expired or job is not yet complete.", "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2026-04-05T16:17:36Z" }, "completed_at": { "type": "string", "format": "date-time", "example": "2026-04-05T16:17:38Z", "nullable": true } }, "type": "object" }, "MergeDocumentRequestSchema": { "required": [ "format" ], "properties": { "files": { "description": "An array of files to merge. When format is 'docx' or 'epub', all files must be .docx.", "type": "array", "items": { "type": "string", "format": "binary" } }, "file_urls": { "description": "Alternative to files for JSON clients such as Airtable Automations. Public HTTPS file URLs only; do not send both files and file_urls.", "type": "array", "items": { "type": "string", "format": "uri" } }, "format": { "description": "Output format. Use 'docx' or 'epub' to merge Word files without conversion. 'epub' requires Pandoc on the server.", "type": "string", "enum": [ "pdf", "docx", "epub" ], "example": "pdf" }, "output_filename": { "description": "Optional filename for the output file (without extension). Max 100 characters. Only applies to 'docx' and 'epub' formats.", "type": "string", "example": "my_merged_document" }, "page_break": { "description": "Insert an explicit page break between each merged document. Only applies to 'docx' and 'epub' formats.", "type": "boolean", "example": true }, "continuous_numbering": { "description": "Run page numbers continuously across all merged documents instead of restarting per section. Only applies to 'docx' and 'epub' formats.", "type": "boolean", "example": true }, "strip_headers_footers": { "description": "Use the first document's header and footer throughout, removing headers/footers from subsequent documents. Only applies to 'docx' and 'epub' formats.", "type": "boolean", "example": false } }, "type": "object" }, "UserFile": { "title": "UserFile", "required": [ "id", "name", "type", "path" ], "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "document.pdf" }, "type": { "type": "string", "example": "file" }, "path": { "type": "string", "example": "files/5/document.pdf" }, "size": { "type": "integer", "example": 12345 }, "parent_id": { "type": "integer", "example": null, "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00Z" } }, "type": "object" }, "ImageGenerationRequest": { "required": [ "template_id", "field_mapping" ], "properties": { "template_id": { "description": "The ID of the image template to use.", "type": "integer", "example": 1 }, "field_mapping": { "description": "Maps each template placeholder name to a data column name.", "type": "object", "example": { "Full_Name": "name", "Title": "job_title" } }, "data": { "description": "JSON array of data rows. Each row is an object with column names as keys. Provide either 'data' or 'data_file', not both.", "type": "array", "items": { "type": "object", "example": { "name": "John Doe", "job_title": "Engineer" } } }, "data_file": { "description": "A CSV or XLSX file upload. Provide either 'data_file' or 'data', not both.", "type": "string", "format": "binary" } }, "type": "object" }, "ImageGenerationJobStatus": { "properties": { "success": { "type": "boolean", "example": true }, "job_id": { "type": "integer", "example": 42 }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "example": "completed" }, "total_images": { "type": "integer", "example": 10 }, "completed_images": { "type": "integer", "example": 10 }, "credits_used": { "type": "integer", "example": 10 }, "download_url": { "description": "Signed download URL (only when status is completed). Expires in 24 hours.", "type": "string", "nullable": true }, "expires_at": { "description": "Expiry time of the download URL.", "type": "string", "format": "date-time", "nullable": true }, "error_message": { "description": "Error details (only when status is failed).", "type": "string", "nullable": true } }, "type": "object" }, "ImageTemplatePlaceholder": { "properties": { "name": { "type": "string", "example": "Full_Name" }, "type": { "type": "string", "enum": [ "text", "image" ], "example": "text" }, "default_value": { "type": "string", "example": "John Doe", "nullable": true } }, "type": "object" }, "ImageTemplatePlaceholderFull": { "properties": { "name": { "type": "string", "example": "Full_Name" }, "type": { "type": "string", "enum": [ "text", "image" ], "example": "text" }, "font_family": { "type": "string", "example": "Arial", "nullable": true }, "font_size": { "type": "integer", "example": 24, "nullable": true }, "font_color": { "type": "string", "example": "#000000", "nullable": true }, "default_value": { "type": "string", "example": "John Doe", "nullable": true }, "x_position": { "type": "number", "example": 100, "nullable": true }, "y_position": { "type": "number", "example": 200, "nullable": true }, "width": { "type": "number", "example": 300, "nullable": true }, "height": { "type": "number", "example": 50, "nullable": true } }, "type": "object" }, "ImageTemplate": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Certificate Template" }, "width": { "type": "integer", "example": 1920 }, "height": { "type": "integer", "example": 1080 }, "placeholders": { "type": "array", "items": { "$ref": "#/components/schemas/ImageTemplatePlaceholder" } }, "created_at": { "type": "string", "format": "date-time", "example": "2026-02-18T10:00:00+00:00" } }, "type": "object" }, "SignerResponse": { "properties": { "email": { "type": "string", "format": "email", "example": "jane@acme.com" }, "first_name": { "type": "string", "example": "Jane", "nullable": true }, "last_name": { "type": "string", "example": "Smith", "nullable": true }, "order": { "type": "integer", "example": 1 }, "status": { "type": "string", "enum": [ "pending", "sent", "viewed", "signed", "declined" ], "example": "sent" }, "signed_at": { "type": "string", "format": "date-time", "example": null, "nullable": true }, "signing_url": { "type": "string", "example": "https://app.activemerge.com/sign/aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789012345" } }, "type": "object" }, "SignatureRequestResponse": { "properties": { "id": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "enum": [ "draft", "sent", "partially_signed", "completed", "declined", "expired", "cancelled" ], "example": "sent" }, "title": { "type": "string", "example": "Service Agreement — Acme Corp" }, "message": { "type": "string", "example": null, "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-04-17T00:00:00+00:00" }, "sent_at": { "type": "string", "format": "date-time", "example": "2026-04-03T12:00:00+00:00", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "example": null, "nullable": true }, "signers": { "type": "array", "items": { "$ref": "#/components/schemas/SignerResponse" } }, "signed_document_url": { "description": "Populated when status is completed. Requires API-KEY header to download.", "type": "string", "example": null, "nullable": true } }, "type": "object" }, "SignerInput": { "required": [ "email" ], "properties": { "email": { "description": "Signer's email. Use {{ColumnName}} to reference a data field, or 'me' for the authenticated user.", "type": "string", "format": "email", "example": "{{ClientEmail}}" }, "first_name": { "description": "First name. Supports {{ColumnName}} and 'me'.", "type": "string", "example": "{{ClientFirstName}}", "nullable": true }, "last_name": { "description": "Last name. Supports {{ColumnName}} and 'me'.", "type": "string", "example": "{{ClientLastName}}", "nullable": true } }, "type": "object" }, "SignConfigInput": { "required": [ "signers" ], "properties": { "signers": { "description": "List of signers. Order in array determines signing order when sequential=true.", "type": "array", "items": { "$ref": "#/components/schemas/SignerInput" } }, "title": { "description": "Signing request title. Supports {{ColumnName}} references.", "type": "string", "example": "Agreement — {{ClientName}}", "nullable": true }, "message": { "description": "Optional message shown to signers.", "type": "string", "example": "Please review and sign.", "nullable": true }, "expires_days": { "description": "Days until signing links expire. Default: 30.", "type": "integer", "example": 14, "nullable": true }, "sequential": { "description": "When true, each signer is notified only after the previous has signed.", "type": "boolean", "example": false, "nullable": true } }, "type": "object" }, "StandaloneSignerInput": { "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "jane@acme.com" }, "first_name": { "type": "string", "example": "Jane", "nullable": true }, "last_name": { "type": "string", "example": "Smith", "nullable": true } }, "type": "object" }, "Template": { "title": "Template", "required": [ "id", "name", "path" ], "properties": { "id": { "type": "integer", "example": 1 }, "unique_id": { "type": "string", "example": "12345" }, "name": { "type": "string", "example": "Invoice Template" }, "path": { "type": "string", "example": "/storage/templates/invoice.docx" }, "user_id": { "type": "integer", "example": 5 }, "created_at": { "type": "string", "format": "date-time", "example": "2024-05-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-05-01T12:00:00Z" } }, "type": "object" }, "GenerateWorkflowRequestSchema": { "required": [ "workflow_id", "data", "format" ], "properties": { "workflow_id": { "description": "The unique ID of the workflow to be used for document generation.", "type": "string", "example": "workflow_abc123" }, "data": { "description": "An associative array of data to populate the template placeholders.", "type": "object", "example": { "placeholder1": "value1", "placeholder2": "value2" } }, "format": { "description": "The format of the documents to be generated (e.g., PDF, DOCX, PPTX).", "type": "string", "enum": [ "pdf", "docx", "pptx" ], "example": "pdf" } }, "type": "object" }, "Workflow": { "title": "Workflow", "required": [ "id", "name", "unique_id", "user_id" ], "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "My Workflow" }, "unique_id": { "type": "string", "example": "workflow_abc123" }, "user_id": { "type": "integer", "example": 5 }, "created_at": { "type": "string", "format": "date-time", "example": "2024-05-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-05-01T12:00:00Z" } }, "type": "object" } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "name": "API-KEY", "in": "header" } } }, "tags": [ { "name": "Document Generation", "description": "Document Generation" }, { "name": "Document Merge", "description": "Document Merge" }, { "name": "Files", "description": "Files" }, { "name": "Image Generation", "description": "Image Generation" }, { "name": "Image Templates", "description": "Image Templates" }, { "name": "E-Signatures", "description": "E-Signatures" }, { "name": "Templates", "description": "Templates" }, { "name": "User", "description": "User" }, { "name": "Workflows", "description": "Workflows" } ] }