Convert bank statement PDFs from your software.

Base URL

Send requests to the production API.

API requests go directly to the Bank Statement Converter server. Use this base URL from your backend, job runner, or internal automation.

https://api.bsconv.com

Authentication

Send a team API key as a Bearer token.

API keys are available from Dashboard > Settings. API access is only available on active paid subscriptions. Free dashboard preview allowance does not include API access. The full key is shown once when created, so store it securely and call the API from server-side code.

Authorization: Bearer bsc_live_your_api_key_here

Workflow

Submit a job, then poll for the result.

The API uses an asynchronous conversion flow so larger PDFs do not keep your request open. Submit a PDF, store the returned conversion id, then poll the detail endpoint until the status becomes done, payment_required, or failed. API conversions require enough monthly pages for the entire PDF before OCR starts. If the remaining allowance is not enough, no pages are processed.

Quick start

Upload a PDF, then poll the conversion.

curl -X POST https://api.bsconv.com/api/v1/conversions \
  -H "Authorization: Bearer bsc_live_your_api_key_here" \
  -F "file=@statement.pdf;type=application/pdf"

The create endpoint returns 202 Accepted with a queued conversion id. Poll the conversion detail endpoint for the final table output:

curl https://api.bsconv.com/api/v1/conversions/8c18ac0f-1522-47ca-9001-ae2a2d157330 \
  -H "Authorization: Bearer bsc_live_your_api_key_here"

When the conversion is done, download CSV or JSON output:

curl "https://api.bsconv.com/api/v1/conversions/8c18ac0f-1522-47ca-9001-ae2a2d157330/download?format=csv" \
  -H "Authorization: Bearer bsc_live_your_api_key_here" \
  -o statement.csv

Password-protected PDFs can include a document open password:

curl -X POST https://api.bsconv.com/api/v1/conversions \
  -H "Authorization: Bearer bsc_live_your_api_key_here" \
  -F "password=my_pdf_open_password" \
  -F "file=@statement.pdf;type=application/pdf"

Send only the PDF document open password. Do not send an online banking password, one-time code, or bank login credential.

Endpoints

Available API endpoints.

Convert

POST /api/v1/conversions

Send a multipart/form-data request from your server. Only PDF files are accepted. Uploads are limited to 50 MB.

Example queued response

{
  "code": 0,
  "msg": "Conversion queued. Poll the conversion detail endpoint for status and results.",
  "data": {
    "message": "Conversion queued. Poll the conversion detail endpoint for status and results.",
    "conversion": {
      "id": "8c18ac0f-1522-47ca-9001-ae2a2d157330",
      "status": "queued",
      "plan": "monthly_600",
      "message": "Conversion queued. Poll the conversion detail endpoint for status and results."
    }
  }
}

The queued response does not include OCR output yet. Fetch /api/v1/conversions/{id} until the stored result is available.

History

List and fetch recent conversions.

Use these endpoints when your application needs to show conversion status, reconnect a user to a recent job, or retrieve stored result JSON after the initial upload response.

GET /api/v1/conversions

curl https://api.bsconv.com/api/v1/conversions?limit=20 \
  -H "Authorization: Bearer bsc_live_your_api_key_here"

Optional query parameters: page, perPage, limit, and status. Status can be queued, running, done, payment_required, or failed.

{
  "code": 0,
  "msg": "success",
  "data": {
    "conversions": [
      {
        "id": "8c18ac0f-1522-47ca-9001-ae2a2d157330",
        "filename": "statement.pdf",
        "totalPages": 2,
        "processedPages": 2,
        "status": "done",
        "createdAt": "2026-05-28T08:30:00Z",
        "completedAt": "2026-05-28T08:31:14Z"
      }
    ],
    "pagination": {
      "page": 1,
      "perPage": 20,
      "total": 1,
      "totalPages": 1
    }
  }
}

GET /api/v1/conversions/{id}

curl https://api.bsconv.com/api/v1/conversions/8c18ac0f-1522-47ca-9001-ae2a2d157330 \
  -H "Authorization: Bearer bsc_live_your_api_key_here"

{
  "code": 0,
  "msg": "success",
  "data": {
    "conversion": {
      "id": "8c18ac0f-1522-47ca-9001-ae2a2d157330",
      "filename": "statement.pdf",
      "totalPages": 2,
      "processedPages": 2,
      "status": "done",
      "createdAt": "2026-05-28T08:30:00Z",
      "completedAt": "2026-05-28T08:31:14Z",
      "result": {
        "status": "done",
        "totalPages": 2,
        "allowedPages": 2,
        "lockedPages": 0,
        "tables": ["<table>...</table>"],
        "markdown": "## Page 1\n\n<table>...</table>",
        "batches": [
          {
            "batch": { "fromPage": 1, "toPage": 2, "pageCount": 2 },
            "pages": [
              {
                "page": 1,
                "markdown": "<table>...</table>",
                "tables": ["<table>...</table>"]
              }
            ]
          }
        ]
      }
    }
  }
}

The OCR result includes extracted table HTML in result.tables when table blocks are detected. result.tables is a flattened list for quick export, while result.batches[].pages[] preserves page numbers, page markdown, and page-level tables for review.

Download

Download completed conversion results.

Use the download endpoint after a conversion reaches done. CSV output is generated from the extracted HTML tables. JSON output returns the stored conversion result object.

GET /api/v1/conversions/{id}/download?format=csv

curl "https://api.bsconv.com/api/v1/conversions/8c18ac0f-1522-47ca-9001-ae2a2d157330/download?format=csv" \
  -H "Authorization: Bearer bsc_live_your_api_key_here" \
  -o statement.csv

GET /api/v1/conversions/{id}/download?format=json

curl "https://api.bsconv.com/api/v1/conversions/8c18ac0f-1522-47ca-9001-ae2a2d157330/download?format=json" \
  -H "Authorization: Bearer bsc_live_your_api_key_here" \
  -o conversion-result.json

If a conversion is still queued or running, the endpoint returns 40900. If no table rows are available for CSV, it also returns 40900 with a message explaining that CSV is unavailable.

DELETE /api/v1/conversions/{id}

curl -X DELETE https://api.bsconv.com/api/v1/conversions/8c18ac0f-1522-47ca-9001-ae2a2d157330 \
  -H "Authorization: Bearer bsc_live_your_api_key_here"

Use delete when your application no longer needs a conversion record. Retention cleanup also removes stored conversion data automatically after the configured retention window.

Account

Read plan entitlement and usage.

Use this endpoint to confirm API access, page limits, and current usage before submitting a larger batch of statements.

curl https://api.bsconv.com/api/v1/account \
  -H "Authorization: Bearer bsc_live_your_api_key_here"

{
  "code": 0,
  "msg": "success",
  "data": {
    "subject": {
      "id": "user:9f5f6b6e-8b3e-43fb-b58e-1f44ef7f2f73"
    },
    "entitlement": {
      "plan": "monthly_600",
      "pageLimit": 600,
      "apiEnabled": true,
      "periodEnd": "2026-06-28T08:00:00Z"
    },
    "usage": {
      "monthlyPagesUsed": 84,
      "monthlyPagesRemaining": 516
    }
  }
}

Responses

All API responses use the same envelope.

{
  "code": 0,
  "msg": "success",
  "data": {}
}

Successful JSON responses use code: 0. Non-zero code values are stable and can be used for application logic. msg explains the specific failure. File download responses return the file directly.

Conversion status values

Conversion result fields

API v1 requires full-document allowance, so new API conversions do not intentionally return partial table output. Page metadata remains available in result.batches[].pages[].page so your application can reconcile rows against original PDF pages.

Errors

Error responses include a code and message.

{
  "code": 40100,
  "msg": "API key is required. Use Authorization: Bearer <api_key>."
}

Limits

Usage follows your subscription allowance.

Rate limit headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1780051200

• API keys require an active paid subscription with API access enabled. Free users cannot call API v1.
• Only PDF uploads are accepted by /api/v1/conversions.
• PDF uploads are limited to 50 MB.
• Conversion submissions are limited to 10 requests per minute per API key.
• Status, history, and account reads are limited to 60 requests per minute per API key.
• Monthly page usage is counted against the API key owner's plan.
• The API requires enough remaining monthly pages for the full PDF. If the allowance is short, the conversion returns payment_required and no pages are OCRed.
• Password-protected PDFs require the correct document open password.
• Recent conversion records are available through /api/v1/conversions and /api/v1/conversions/{id}.
• Stored conversion records are short-lived and may be removed by retention cleanup. Delete records earlier with DELETE /api/v1/conversions/{id}.