{ "openapi": "3.0.3", "info": { "title": "DocuClipper API", "version": "1.0.0", "description": "DocuClipper extracts structured data from bank statements, invoices, receipts, tax forms, and check images.\n\nAgent workflow: upload \u2192 create job \u2192 wait for Succeeded \u2192 export JSON.\n\nAuth: Authorization: Bearer .", "x-ai-agent-summary": "Auth: Authorization: Bearer . Base URL: https://www.docuclipper.com/api/v1. Workflow: POST /protected/document (multipart field \"document\"), POST /protected/job, poll GET /protected/job/{id} until status==Succeeded (or use webhooks), then POST /protected/job/{id}/export with format=json." }, "servers": [ { "url": "https://www.docuclipper.com/api/v1", "description": "Production" }, { "url": "http://localhost:8080/api/v1", "description": "Local dev (default port)" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Documents" }, { "name": "Jobs" }, { "name": "Export" }, { "name": "Fraud" } ], "paths": { "/protected/document": { "post": { "tags": [ "Documents" ], "summary": "Upload a document (multipart)", "operationId": "uploadDocument", "parameters": [ { "name": "metadata", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "0", "1" ], "default": "0" }, "description": "Include metadata in response" }, { "name": "asyncProcessing", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Process document asynchronously" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "document": { "type": "string", "format": "binary" } }, "required": [ "document" ] } } } }, "responses": { "200": { "description": "Document uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadDocumentResponse" } } } }, "201": { "description": "Document uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadDocumentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/protected/document/uploads3": { "post": { "tags": [ "Documents" ], "summary": "Create a presigned S3 upload URL", "operationId": "createPresignedUploadUrl", "parameters": [ { "name": "expiresIn", "in": "query", "required": false, "schema": { "type": "integer", "default": 3600, "minimum": 1 }, "description": "URL expiration in seconds" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string" }, "mimetype": { "type": "string" }, "customerId": { "type": [ "string", "null" ] }, "password": { "type": [ "string", "null" ] }, "s3ETag": { "type": [ "string", "null" ] } }, "required": [ "filename", "mimetype" ] } } } }, "responses": { "200": { "description": "Presigned URL created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresignedUploadResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/protected/document/{documentId}/uploads3/complete": { "post": { "tags": [ "Documents" ], "summary": "Complete a presigned upload (no-op)", "operationId": "completePresignedUpload", "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Upload completion acknowledged", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/protected/document/{documentId}/downloads3": { "get": { "tags": [ "Documents" ], "summary": "Create a presigned S3 download URL", "operationId": "createPresignedDownloadUrl", "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "expiresIn", "in": "query", "required": false, "schema": { "type": "integer", "default": 3600, "minimum": 1 }, "description": "URL expiration in seconds" } ], "responses": { "200": { "description": "Presigned URL created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresignedDownloadResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/protected/job": { "post": { "tags": [ "Jobs" ], "summary": "Create an extraction job", "operationId": "createJob", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobRequest" } } } }, "responses": { "201": { "description": "Job created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "200": { "description": "Job created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/protected/job/{id}": { "get": { "tags": [ "Jobs" ], "summary": "Get job status", "operationId": "getJob", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/protected/job/{id}/export": { "post": { "tags": [ "Export" ], "summary": "Export extracted data (JSON)", "operationId": "exportJob", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRequest" } } } }, "responses": { "200": { "description": "Exported data (shape depends on jobType)", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BankStatementExport" }, { "$ref": "#/components/schemas/InvoiceExport" }, { "$ref": "#/components/schemas/FormExport" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/protected/document/{documentId}/fraudSignals": { "get": { "tags": [ "Fraud" ], "summary": "List fraud signals for a document", "operationId": "getFraudSignals", "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "minConfidence", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "maxConfidence", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "responses": { "200": { "description": "Fraud signals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudSignalsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/protected/document/{documentId}/fraudScore": { "get": { "tags": [ "Fraud" ], "summary": "Get fraud score for a document", "operationId": "getFraudScore", "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Fraud score", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudScoreResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "responses": { "BadRequest": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "additionalProperties": true }, "IdLike": { "description": "IDs may be numeric or stringified depending on client/runtime.", "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "Document": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/IdLike" }, "originalname": { "type": "string" }, "mimetype": { "type": "string" } }, "required": [ "id" ] }, "PdfInfo": { "type": "object", "properties": { "pageCount": { "type": "integer" } }, "required": [ "pageCount" ] }, "DocumentMetadata": { "type": "object", "additionalProperties": true }, "UploadDocumentResponse": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" }, "pdfInfo": { "$ref": "#/components/schemas/PdfInfo" }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentMetadata" } } }, "required": [ "document" ] }, "PresignedUploadResponse": { "type": "object", "properties": { "url": { "type": "string" }, "expiresIn": { "type": "integer" }, "document": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/IdLike" }, "s3Key": { "type": "string" }, "s3Path": { "type": "string" } }, "required": [ "id", "s3Key", "s3Path" ] } }, "required": [ "url", "expiresIn", "document" ] }, "PresignedDownloadResponse": { "type": "object", "properties": { "url": { "type": "string" }, "expiresIn": { "type": "integer" }, "document": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/IdLike" }, "originalname": { "type": "string" }, "mimetype": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "url", "expiresIn", "document" ] }, "CreateJobRequest": { "type": "object", "properties": { "jobName": { "type": "string", "description": "Required by API. Use empty string \"\" if you don't need a name." }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/IdLike" } }, "enableBankMode": { "type": "boolean", "description": "Set true for bank statements/check images. Typically omit jobType when using bank mode.", "default": true }, "jobType": { "type": "string", "description": "Use \"Invoice\" for invoices and \"Form\" for tax forms. Omit for bank mode.", "enum": [ "Invoice", "Form" ] }, "templateId": { "type": [ "string", "null" ], "description": "Optional template ID (not required for Form jobs)." } }, "required": [ "jobName", "documents" ] }, "Job": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/IdLike" }, "status": { "type": "string", "description": "Job status", "example": "Succeeded" } }, "required": [ "id", "status" ], "additionalProperties": true }, "ExportRequest": { "type": "object", "properties": { "jobType": { "type": "string", "enum": [ "FieldsToExcel1", "Invoice", "Form" ] }, "flattenTables": { "type": "boolean" }, "format": { "type": "string", "description": "Use \"json\" to receive JSON in the response.", "enum": [ "json", "csv" ] }, "selectedFieldNames": { "type": "array", "items": { "type": "string" }, "description": "For bank mode, commonly includes \"bankMode\"." }, "documentIds": { "type": "array", "items": { "$ref": "#/components/schemas/IdLike" } } }, "required": [ "jobType", "flattenTables" ] }, "BankStatementExport": { "type": "object", "description": "Keyed by documentId \u2192 account \u2192 bankMode. Transactions live at [documentId][account].bankMode.transactions[].", "additionalProperties": { "type": "object", "additionalProperties": true } }, "InvoiceExport": { "type": "object", "description": "Invoice extraction output keyed by documentId (shape varies by template and invoice layout).", "additionalProperties": true }, "FormExtractedItem": { "type": "object", "properties": { "rowNumber": { "type": "integer" }, "pageNumber": { "type": "integer" }, "form": { "type": "object", "description": "Dynamic key-value fields. Keys are the form labels; values are extracted strings.", "additionalProperties": { "type": "string" } } }, "required": [ "rowNumber", "pageNumber", "form" ] }, "FormExport": { "type": "object", "description": "Keyed by documentId \u2192 array of extracted forms. Each item includes rowNumber, pageNumber, and a dynamic key-value map in form.", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/FormExtractedItem" } } }, "FraudSignal": { "type": "object", "properties": { "id": { "type": "integer" }, "documentId": { "type": "integer" }, "period": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "confidence": { "type": "number" }, "details": { "type": [ "string", "null" ] }, "pageNumber": { "type": [ "integer", "null" ] }, "bbox": { "type": [ "object", "null" ], "additionalProperties": true }, "text": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "additionalProperties": true }, "DocumentFraudScore": { "type": "object", "properties": { "id": { "type": "integer" }, "documentId": { "type": "integer" }, "score": { "type": "number" }, "comment": { "type": "string" } }, "additionalProperties": true }, "FraudSignalsResponse": { "type": "object", "properties": { "total": { "type": "integer" }, "signals": { "type": "array", "items": { "$ref": "#/components/schemas/FraudSignal" } }, "score": { "anyOf": [ { "$ref": "#/components/schemas/DocumentFraudScore" }, { "type": "null" } ] } }, "required": [ "total", "signals" ] }, "FraudScoreResponse": { "type": "object", "properties": { "score": { "anyOf": [ { "$ref": "#/components/schemas/DocumentFraudScore" }, { "type": "null" } ] } }, "required": [ "score" ] } } } }