API Documentation

The BankConv REST API lets you convert bank statement PDFs to structured data programmatically. Upload a PDF, poll for results, and download JSON or CSV — all with a simple API key.

Base URL: https://bankconv.com/api/v1

Authentication

All requests require a team API key sent as a Bearer token:

Authorization: Bearer sk_live_your_api_key_here

API keys are scoped to your team. Generate them from your team settings. The full key is shown once at creation — store it securely.

Quick start

1. Upload and convert

curl -X POST https://bankconv.com/api/v1/conversions \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -F "[email protected]"

Response:

{
  "data": {
    "id": "9a8b7c6d-...",
    "status": "processing",
    "pages_count": 3,
    "created_at": "2026-04-07T12:00:00Z",
    "input": {
      "filename": "bank-statement.pdf",
      "pages_count": 3
    }
  }
}

2. Poll for status

curl https://bankconv.com/api/v1/conversions/9a8b7c6d-... \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Poll until status is completed or failed.

3. Download results

JSON (default):

curl https://bankconv.com/api/v1/conversions/9a8b7c6d-.../download \
  -H "Authorization: Bearer sk_live_your_api_key_here"

CSV:

curl https://bankconv.com/api/v1/conversions/9a8b7c6d-.../download?format=csv \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -o statement.csv

Endpoints

Conversions

Method	Endpoint	Description
POST	/conversions	Upload PDF and start conversion
GET	/conversions	List conversions (paginated)
GET	/conversions/{id}	Get conversion status and results
GET	/conversions/{id}/download	Download results as JSON or CSV
DELETE	/conversions/{id}	Delete a conversion

Credits

Method	Endpoint	Description
GET	/credits	Check your credit balance
GET	/credits/usage	View usage for the current period

Upload and convert

POST /conversions

Send a multipart/form-data request with the PDF file.

Parameter	Type	Required	Description
file	file	Yes	PDF file (max 30 MB)
password	string	No	Password for protected PDFs

List conversions

GET /conversions

Parameter	Type	Default	Description
page	integer	1	Page number
per_page	integer	15	Results per page (max 100)
status	string	—	Filter: pending, processing, completed, failed
sort	string	-created_at	Sort field (prefix - for descending)

Download results

GET /conversions/{id}/download

Parameter	Type	Default	Description
format	string	json	Output format: json or csv

The JSON response includes all extracted pages with their blocks (tables, text, etc.) and the original HTML representation.

Check credits

GET /credits

{
  "data": {
    "total": 500,
    "remaining": 342,
    "bonus": 50
  }
}

Response format

Successful responses are wrapped in a data key:

{
  "data": { ... }
}

Paginated responses include a meta key:

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 72
  }
}

Errors follow a consistent structure:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits. You have 2 remaining but need 5.",
    "status": 422
  }
}

Error codes

Code	Status	Description
unauthenticated	401	Missing or invalid API key
not_found	404	Resource does not exist
validation_error	422	Invalid request parameters
insufficient_credits	422	Not enough credits for conversion
not_ready	422	Conversion is still processing
gone	410	Conversion expired per data retention policy
rate_limited	429	Too many requests

Rate limiting

Requests are limited to 60 per minute per API key. Rate limit status is included in response headers:

• X-RateLimit-Limit — requests allowed per window
• X-RateLimit-Remaining — requests remaining
• Retry-After — seconds until the limit resets (on 429 responses)

Credits and billing

Each page of a converted PDF costs one credit. Credits are tied to your team subscription plan:

Plan	Pages / month
Starter	500
Professional	1,000
Business	5,000

The API requires sufficient credits for the entire document — partial conversions are not supported. If you don't have enough credits, the request returns a 422 insufficient_credits error.

Manage your subscription and billing from the dashboard.

Data retention

Converted documents are automatically deleted based on your team's data retention policy (24, 48, or 72 hours). After expiration, download requests return 410 Gone.

Password-protected PDFs

To convert a password-protected PDF, include the password parameter:

curl -X POST https://bankconv.com/api/v1/conversions \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -F "[email protected]" \
  -F "password=my_pdf_password"