API Documentation

Everything you need to convert between bank statement formats. A single REST API to parse, detect, and convert MT940, CAMT.053, OFX, CSV, and JSON.

Base URL https://api.finconvert.dev

Getting Started

FinConvert is a stateless REST API that converts between bank statement formats. Upload a file, specify the desired output format, and receive the converted file back — no data is stored.

Quick start in 3 steps

1 Get your API key from the dashboard (prefix: fc_live_ or fc_test_)
2 Send your bank statement to POST /v1/convert with the desired output format
3 Receive the converted file as a download

Authentication

Authenticated endpoints require an API key passed via the Authorization header.

Header Format	Example
`Authorization: Bearer <key>`	`Bearer fc_live_abc123...`
`Authorization: <key>`	`fc_live_abc123...`

Key prefixes: Production keys start with fc_live_, sandbox keys with fc_test_. Keep your keys secret — do not expose them in client-side code.

Example: authenticated request

curl -H "Authorization: Bearer fc_live_xxxxx" \
  https://api.finconvert.dev/v1/formats

Endpoints

POST /v1/convert Authenticated

Convert a bank statement file from one format to another. The input format is auto-detected unless explicitly specified. Returns the converted file as a download.

Parameters (multipart form)

Name	Type	Required	Description
`file`	File	Yes	The bank statement file to convert
`to`	String	Yes	Output format: `csv`, `json`, `camt053`, `ofx`
`from`	String	No	Input format (auto-detected if omitted): `mt940`, `camt053`

Response

Returns the converted file with appropriate Content-Type and Content-Disposition headers. The detected input format is available in the X-Detected-Format response header.

Request

curl -X POST https://api.finconvert.dev/v1/convert \
  -H "Authorization: Bearer fc_live_xxxxx" \
  -F "file=@bank-statement.mt940" \
  -F "to=csv" \
  -o converted.csv

POST /v1/parse Authenticated

Parse a bank statement file and return its structured data as JSON. Useful for extracting transaction data without converting to another file format.

Parameters (multipart form)

Name	Type	Required	Description
`file`	File	Yes	The bank statement file to parse
`from`	String	No	Input format (auto-detected if omitted)

Response

Request

curl -X POST https://api.finconvert.dev/v1/parse \
  -H "Authorization: Bearer fc_live_xxxxx" \
  -F "file=@bank-statement.mt940"

Response — 200 OK

{
  "format": "mt940",
  "statements": [
    {
      "accountId": "123456789",
      "statementNumber": "1",
      "openingBalance": {
        "date": "2026-01-01",
        "amount": 1500.00,
        "currency": "EUR"
      },
      "closingBalance": {
        "date": "2026-01-31",
        "amount": 2350.75,
        "currency": "EUR"
      },
      "transactions": [
        {
          "date": "2026-01-15",
          "amount": 850.75,
          "type": "credit",
          "description": "SALARY PAYMENT",
          "reference": "SAL-2026-01"
        }
      ]
    }
  ]
}

POST /v1/detect Public

Detect the format of a bank statement file without parsing or converting it. No authentication required.

Parameters (multipart form)

Name	Type	Required	Description
`file`	File	Yes	The bank statement file to identify

Request

curl -X POST https://api.finconvert.dev/v1/detect \
  -F "file=@bank-statement.mt940"

Response — 200 OK

{
  "format": "mt940",
  "formatName": "MT940 (SWIFT)"
}

GET /v1/formats Public

List all supported input and output formats. No authentication required.

Request

curl https://api.finconvert.dev/v1/formats

Response — 200 OK

{
  "input": ["mt940", "camt053"],
  "output": ["csv", "json", "camt053", "ofx"]
}

GET /v1/health Public

Health check endpoint. Returns the API status.

Request

curl https://api.finconvert.dev/v1/health

Response — 200 OK

{
  "status": "ok"
}

Rate Limits

Rate limits are applied per IP for public routes and per API key for authenticated routes.

Route Type	Limit	Window
Public endpoints	30 requests	1 minute
Authenticated endpoints	100 requests	1 minute

Response Headers

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the window
`X-RateLimit-Remaining`	Remaining requests in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

429 — Rate limit exceeded

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1711324800

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Try again in 42 seconds."
  }
}

Error Handling

All errors return a consistent JSON structure with an error object containing a machine-readable code and a human-readable message.

Error response format

{
  "error": {
    "code": "PARSE_ERROR",
    "message": "Failed to parse input file: unexpected tag at line 12"
  }
}

Error Codes

HTTP Status	Code	Description
`400`	`PARSE_ERROR`	Failed to parse the input file
`400`	`FORMAT_ERROR`	Failed to format the output file
`400`	`UNSUPPORTED_FORMAT`	The specified format is not supported
`401`	`UNAUTHORIZED`	Invalid or missing API key
`413`	`FILE_TOO_LARGE`	File exceeds the 10 MB limit
`429`	`RATE_LIMITED`	Too many requests — slow down

File Size Limits

The maximum file size for uploads is 10 MB. Files exceeding this limit receive a 413 response.

413 — Payload Too Large

{
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File size exceeds the 10 MB limit."
  }
}

Privacy note: FinConvert is stateless. Your files are processed in memory and never stored on disk. Data is discarded immediately after the response is sent.

Code Examples

Full working examples for converting a bank statement.

Convert MT940 to CSV

curl -X POST https://api.finconvert.dev/v1/convert \
  -H "Authorization: Bearer fc_live_xxxxx" \
  -F "file=@bank-statement.mt940" \
  -F "to=csv" \
  -o converted.csv

Convert with fetch (Node.js)

const form = new FormData()
form.append('file', fs.createReadStream('statement.mt940'))
form.append('to', 'json')

const response = await fetch('https://api.finconvert.dev/v1/convert', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer fc_live_xxxxx' },
  body: form,
})

const data = await response.json()

Convert with requests

import requests

with open('statement.mt940', 'rb') as f:
    response = requests.post(
        'https://api.finconvert.dev/v1/convert',
        headers={'Authorization': 'Bearer fc_live_xxxxx'},
        files={'file': f},
        data={'to': 'json'},
    )

data = response.json()

Ready to get started?

Join the waitlist to get your API key and start converting bank statements.

Join the Waitlist