{ "openapi": "3.1.0", "info": { "title": "Bank Statement Conversion API", "version": "1.0.0", "description": "Public conversion workflow for developers and AI agents. The OpenAPI document intentionally exposes only account capacity checks, uploads, status polling, and completed-file downloads." }, "servers": [ { "url": "https:\/\/bank-statement-conversion.com\/api" } ], "paths": { "\/user-status": { "get": { "operationId": "auth.getUserStatus", "summary": "Get user status for API calls (Google Sheets add-on)", "tags": [ "Auth" ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string", "const": "Unable to get user status" } }, "required": [ "success", "error" ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "remaining_credits": { "type": "integer" }, "remaining_daily_pages": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "remaining_premium_pages": { "anyOf": [ { "type": "object" }, { "type": "integer", "enum": [ 0 ] } ] }, "plan_type": { "type": "string" }, "shared_plan_info": { "type": [ "object", "null" ], "properties": { "is_shared": { "type": "boolean" }, "admin_name": { "type": "string" }, "admin_email": { "type": "string" }, "plan_type": { "type": "string" }, "added_on": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "is_shared", "admin_name", "admin_email", "plan_type", "added_on" ] }, "enterprise_plan_info": { "type": [ "object", "null" ], "properties": { "is_enterprise": { "type": "boolean" }, "organization_id": { "type": "integer" }, "organization_name": { "type": "string" }, "admin_name": { "type": "string" }, "admin_email": { "type": "string" }, "admin_user_id": { "type": "integer" }, "plan_type": { "type": "string" }, "added_on": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "is_enterprise", "organization_id", "organization_name", "admin_name", "admin_email", "admin_user_id", "plan_type", "added_on" ] }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] } }, "required": [ "success", "remaining_credits", "remaining_daily_pages", "remaining_premium_pages", "plan_type", "shared_plan_info", "enterprise_plan_info", "user" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/download\/{token}": { "get": { "operationId": "download.conversion", "summary": "Download a converted statement file", "tags": [ "Download" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object" } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "example": "" } }, "required": [ "message" ] } } } }, "500": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "example": "Error downloading file" } }, "required": [ "message" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/upload": { "post": { "operationId": "upload.uploadStatement", "tags": [ "Upload" ], "requestBody": { "description": "Multipart upload request for the public conversion workflow.", "required": true, "content": { "multipart\/form-data": { "schema": { "type": "object", "properties": { "statement[]": { "type": "array", "items": { "type": "string", "format": "binary", "description": "CSV, XLS, XLSX, PDF, image, or structured financial file bytes. For document_type=payment_file, upload CSV\/XLS\/XLSX payment rows. For document_type=positive_pay_file, upload CSV\/XLS\/XLSX check rows. For document_type=invoice, upload PDF invoices for UBL XML, Peppol BIS XML, XRechnung XML, or ZUGFeRD\/Factur-X hybrid PDF workflows." } }, "format": { "type": "string", "description": "Output format. For document_type=invoice use ubl_xml for UBL 2.1 XML, ubl_peppol for Peppol BIS XML, xrechnung_ubl for XRechnung XML, zugferd_pdf for ZUGFeRD hybrid PDF, or factur_x_pdf for Factur-X hybrid PDF. Use payment_nacha, payment_cpa005, payment_sepa_pain001, payment_bacs, payment_aba, or payment_nz when document_type is payment_file. Use positive_pay when document_type is positive_pay_file.", "enum": [ "csv", "excel", "json", "markdown", "qb_online", "qb_desktop", "xero", "ofx", "ofx_legacy", "qfx", "mt940", "mt940_moneybird", "camt053", "camt053_legacy", "camt053_moneybird", "camt053_netsuite", "camt053_sap_v2", "camt053_sap_v8", "camt053_business_central", "camt053_datev", "camt053_afas", "camt053_twinfield", "tally_xml", "bai2", "bai2_netsuite", "bai2_sap", "bai2_bank_x", "sage", "sage_cloud", "sage_intacct", "myob", "datev", "datev_accounting", "csv_clean", "ubl_xml", "ubl_peppol", "xrechnung_ubl", "zugferd_pdf", "factur_x_pdf", "payment_nacha", "payment_cpa005", "payment_sepa_pain001", "payment_bacs", "payment_aba", "payment_nz", "positive_pay" ], "example": "csv" }, "document_type": { "type": "string", "description": "Document category: bank_statement, invoice, receipt, payment_file, or positive_pay_file.", "enum": [ "bank_statement", "invoice", "receipt", "payment_file", "positive_pay_file" ], "default": "bank_statement" }, "separate_debit_credit": { "type": "boolean", "description": "Whether to separate debit and credit columns when supported.", "default": false }, "combine_files": { "type": "boolean", "description": "Whether to combine multiple uploaded files into one output when supported.", "default": false }, "payment_settings": { "type": "string", "description": "JSON settings for document_type=payment_file, including originator details, payment direction, sequence values, and format-specific setup fields." }, "payment_mapping": { "type": "string", "description": "Optional JSON column mapping for document_type=payment_file. Omit or pass an empty object to auto-detect columns." }, "positive_pay_settings": { "type": "string", "description": "JSON settings for document_type=positive_pay_file, including profile, delimiter, date format, amount format, extension, and fixed-width layout settings." }, "positive_pay_mapping": { "type": "string", "description": "Optional JSON column mapping for document_type=positive_pay_file. Omit or pass an empty object to auto-detect check row columns." }, "peppol_seller_endpoint_id": { "type": "string", "description": "Optional seller e-invoice endpoint ID for document_type=invoice when the selected invoice format needs routing metadata." }, "peppol_buyer_endpoint_id": { "type": "string", "description": "Optional buyer e-invoice endpoint ID for document_type=invoice when the selected invoice format needs routing metadata." }, "peppol_tax_category_code": { "type": "string", "description": "Optional invoice tax category override for generated e-invoice XML.", "enum": [ "S", "Z", "E", "AE", "O" ] } }, "required": [ "statement[]", "format" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "stage": { "type": "string", "const": "pending" }, "jobId": { "type": "string" }, "warning": { "type": "string" }, "password_protected_files": { "type": "array", "items": { "type": "string" } }, "unlock_tool_info": { "type": "object", "properties": { "message": { "type": "string", "const": "You can remove password protection for free using our PDF Password Removal tool." }, "url": { "type": "string" } }, "required": [ "message", "url" ] } }, "required": [ "stage", "jobId", "warning", "password_protected_files", "unlock_tool_info" ] }, { "type": "null" } ] } } } }, "422": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "All uploaded PDF files are password-protected and cannot be processed." ] } ] }, "password_protected_files": { "type": "array", "items": { "type": "string" } }, "unlock_tool_message": { "type": "string", "const": "You can remove the password protection for free using our PDF Password Removal tool." }, "unlock_tool_url": { "type": "string" } }, "required": [ "error", "password_protected_files", "unlock_tool_message", "unlock_tool_url" ] }, { "type": "object", "properties": { "message": { "type": "string" }, "feature": { "type": "string", "const": "mapped_accounting_export" }, "required_plan": { "type": "string", "enum": [ "Premium", "Business", "Enterprise" ] }, "current_plan": { "type": "string" }, "limit": { "type": [ "integer", "null" ], "enum": [ 0, 5, 100, 25, 50, 500, 150, null ] } }, "required": [ "message", "feature", "required_plan", "current_plan", "limit" ] }, { "type": "object", "properties": { "error": { "type": "string" }, "debug": { "type": "string" } }, "required": [ "error", "debug" ] } ] } } } }, "403": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string" }, "can_purchase_credits": { "type": "boolean" } }, "required": [ "error", "can_purchase_credits" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Access denied. Your access has been restricted due to a violation of our Terms of Service." }, "banned": { "type": "boolean" } }, "required": [ "error", "banned" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "Your account has been suspended. Please contact support for assistance at support@bank-statement-conversion.com" }, "suspended": { "type": "boolean" } }, "required": [ "error", "suspended" ] }, { "type": "object", "properties": { "error": { "type": "string", "const": "This embed widget is not authorized for this domain." } }, "required": [ "error" ] }, { "type": "object", "properties": { "message": { "type": "string" }, "feature": { "type": "string", "const": "mapped_accounting_export" }, "required_plan": { "type": "string", "enum": [ "Business", "Premium" ] }, "current_plan": { "type": "string" } }, "required": [ "message", "feature", "required_plan", "current_plan" ] }, { "type": "object", "properties": { "message": { "type": "string" }, "feature": { "type": "string", "const": "mapped_accounting_export" }, "required_plan": { "type": "string", "const": "Premium" }, "current_plan": { "type": "string" } }, "required": [ "message", "feature", "required_plan", "current_plan" ] }, { "type": "object", "properties": { "message": { "type": "string" }, "feature": { "type": "string", "const": "general_ledger_excel_column" }, "required_plan": { "type": "string", "const": "Starter" }, "current_plan": { "type": "string" } }, "required": [ "message", "feature", "required_plan", "current_plan" ] } ] } } } }, "429": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "This embed widget has exceeded its hourly conversion limit. Please try again later." } }, "required": [ "error" ] } } } }, "500": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "An unexpected error occurred during file upload." }, "debug": { "type": "string" } }, "required": [ "error", "debug" ] } } } }, "400": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "No files were uploaded." }, "debug": { "type": "object", "properties": { "has_file": { "type": "boolean" }, "files": { "type": "string" } }, "required": [ "has_file", "files" ] } }, "required": [ "error", "debug" ] } } } } } } }, "\/conversion-status\/{jobId}": { "get": { "operationId": "upload.checkJobStatus", "tags": [ "Upload" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "stage": { "type": "string" }, "success": { "type": "boolean" }, "previews": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "stage", "success", "previews" ] }, { "type": "object", "properties": { "": { "type": "array", "items": {} }, "stage": { "type": "string", "const": "complete" }, "success": { "type": "boolean" }, "error": { "type": "string" }, "message": {}, "previews": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ null, "stage", "success", "error", "message", "previews" ] }, { "type": "object", "additionalProperties": {} }, { "type": "object", "properties": { "stage": { "type": "string", "const": "not_found" }, "success": { "type": "boolean" }, "error": { "type": "string", "const": "Job not found" }, "previews": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "stage", "success", "error", "previews" ] } ] } } } } } } } }, "components": { "responses": { "AuthenticationException": { "description": "Unauthenticated", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } } }