Introduction
Welcome to the Bankhell API documentation. Our API allows you to seamlessly convert and manage bank statements and financial documents. This documentation covers the available endpoints, request parameters, response structures, and error handling.
The API is organized around RESTful principles and returns JSON-encoded responses. It uses standard HTTP response codes to indicate the success or failure of requests.
Authentication
All API requests must include your API key in the X-API-KEY header. API keys are specific to your account and should be kept secure.
Obtaining an API Key
You can generate API keys from the API Keys section of your dashboard. Each key can be enabled or disabled individually and has its own set of permissions.
API Key Security
Your API key carries the same privileges as your Bankhell account. Keep it secure:
- Do not embed API keys directly in code.
- Do not store API keys in files inside your application's source tree.
- Restrict API key use by IP address if possible.
- Use environment variables or a secrets management service.
Authentication Example
Include your API key in the X-API-KEY header:
Getting Started
Getting started with the Bankhell API is simple. Follow these steps to set up and make your first API request:
- Sign up for a Bankhell account if you haven't already.
- Generate an API key from your dashboard.
- Choose the programming language you want to work with.
- Make your first request following our examples below.
Workflow Overview
Upload and Convert a Document
Use the /api/convert endpoint to upload a bank statement or financial document for conversion.
Track Conversion Progress
Use the /api/jobs/{id} endpoint to track the progress of your conversion job.
Retrieve Converted Data
When the job is complete, retrieve your converted data from the job response.
Manage Multiple Jobs
Use the /api/jobs endpoint to list and manage all your conversion jobs.
API Endpoints
The Bankhell API provides endpoints for converting financial documents, tracking conversion jobs, and retrieving converted data. Below are detailed descriptions of each endpoint.
File Conversion
/api/convertUpload and convert a financial document to your desired format. Conversions are processed asynchronously, and you'll receive a job ID to track the progress.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
file | File | Required | The financial document to convert (PDF, JPEG, PNG, or text file) |
from | String | Required | Source format identifier (e.g., "bank-statement", "invoice", "receipt") |
to | Number | Required | Convert to identifier (e.g., "rest", "csv", "json", "quickbooks-online-csv", "xero-csv", "sage-csv", "ynab-csv", "mintimport-csv") |
Example Request
Response
1{
2 "success": true,
3 "message": "Conversion job created successfully",
4 "data": "550e8400-e29b-41d4-a716-446655440000"
5}List Jobs
/api/jobsRetrieve a list of conversion jobs for your account with optional filtering and pagination.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | Number | Optional | Number of jobs to return (default: 50, max: 100) |
offset | Number | Optional | Number of jobs to skip for pagination (default: 0) |
status | String | Optional | Filter jobs by status (e.g., "pending", "processing", "completed", "failed") |
Example Request
Response
1{
2 "jobs": [
3 {
4 "id": "550e8400-e29b-41d4-a716-446655440000",
5 "status": "completed",
6 "created_at": "2025-02-20T15:30:45Z",
7 "completed_at": "2025-02-20T15:31:12Z",
8 "filename": "bank_statement_feb.pdf",
9 "from": "bank_of_america",
10 "to": 3,
11 "download_url": "https://bankhell.com/api/download/file/550e8400-e29b-41d4-a716-446655440000"
12 },
13 {
14 "id": "663a1500-f32c-42e5-b826-557766551111",
15 "status": "processing",
16 "created_at": "2025-02-21T10:15:20Z",
17 "completed_at": null,
18 "filename": "credit_card_statement.pdf",
19 "from": "chase",
20 "to": 2,
21 "download_url": null
22 }
23 ],
24 "pagination": {
25 "total": 27,
26 "limit": 10,
27 "offset": 0
28 }
29}Retrieve Job
/api/jobs/{id}Retrieve detailed information about a specific conversion job, including its status and results if completed.
URL Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | UUID | Required | The unique identifier of the job to retrieve |
Example Request
Response
1{
2 "job": {
3 "id": "550e8400-e29b-41d4-a716-446655440000",
4 "status": "completed",
5 "created_at": "2025-02-20T15:30:45Z",
6 "completed_at": "2025-02-20T15:31:12Z",
7 "filename": "bank_statement_feb.pdf",
8 "from": "bank_of_america",
9 "to": "json",
10 "file_size": 1248576,
11 "converted_file_storage_path": "https://bankhell.com/api/download/file/550e8400-e29b-41d4-a716-446655440000"
12 }
13}Use Cases
The Bankhell API enables a wide range of financial document processing workflows. Here are some common use cases:
Automated Bookkeeping
Convert bank statements to structured formats for automatic import into bookkeeping software like QuickBooks, Xero, or FreshBooks, eliminating manual data entry.
Financial Analysis
Transform financial statements into structured data for trend analysis, spending patterns, or custom reporting systems.
Tax Preparation
Bulk convert financial documents for tax season, categorizing expenses and income automatically for tax filing software integration.
Financial Applications
Integrate bank statement conversion directly into financial applications or personal finance tools to provide users with seamless data import capabilities.
Example Implementation
This example demonstrates how to implement a complete workflow for converting multiple bank statements and tracking their progress:
Error Handling
The Bankhell API uses standard HTTP response codes to indicate the success or failure of requests. Error responses include a descriptive message to help you identify and resolve issues.
| Status Code | Description |
|---|---|
| 200 - OK | Request succeeded |
| 400 - Bad Request | Invalid request parameters or validation error |
| 401 - Unauthorized | Missing or invalid API key |
| 403 - Forbidden | Valid API key but insufficient permissions |
| 404 - Not Found | Requested resource not found |
| 429 - Too Many Requests | Rate limit exceeded |
| 500 - Server Error | Internal server error |
Error Response Format
All error responses follow this standard structure:
1{
2 "error": "Error message describing the issue",
3 "code": "error_code",
4 "details": {
5 "field": "The specific field that caused the error (if applicable)",
6 "reason": "More detailed explanation of the error"
7 }
8}Common Error Codes
| Error Code | Description |
|---|---|
| invalid_api_key | The API key provided is invalid or has expired |
| missing_parameter | A required parameter is missing from the request |
| invalid_parameter | A parameter has an invalid value |
| file_too_large | The uploaded file exceeds the maximum allowed size |
| unsupported_file_type | The file type is not supported for conversion |
| rate_limit_exceeded | You have exceeded your rate limit |
| job_not_found | The specified job ID does not exist |
| conversion_failed | The document conversion process failed |