API Documentation

Welcome to our API documentation.

API Access

The API is exclusively available for users with a Pro or Business plan.

Base URL

All requests should be made to:

https://api.convertbankstatement.io/

Authentication

All requests require an API token to be included in the request headers.

Headers

YOUR_API_TOKEN value is shown on your dashboard settings:

x-token: YOUR_API_TOKEN

Endpoints

Upload Bank Statement

Upload a PDF bank statement.

Method: POST

Endpoint: /upload/document

Content Type: multipart/form-data

Body Parameters:

document (binary file): PDF file of your bank statement

Response Example:

{
  "url": "STATEMENT_URL",
  "documentId": "123",
  "createdAt": "2024-03-20T10:00:00Z"
}

Convert Bank Statement

Convert an uploaded bank statement using the url received from the previous upload step.

Method: POST

Endpoint: /convert/document

Content Type: application/json

Body Parameters:

{
  "url": "STATEMENT_URL"
}

Response Examples:

success

failed

Check Conversion Status

Check the status of your bank statement conversion.

tip

The conversion is taking some time, it depends of your document and the number of pages. We recommend polling this API every 10 seconds until the status changes from null to success. Keep in mind that a scanned PDF conversion takes more time than a text-based PDF.

Method: GET

Endpoint: /status/document/:documentId

URL Parameters:

:documentId - The ID of the document to check (received from the previous conversion step)

Response Example:

{
  "documentId": "123",
  "url": "STATEMENT_URL",
  "status": "success"
}

Get CSV Transactions

Retrieve the converted transactions in raw CSV format once you got the success status from the step below.

Method: GET

Endpoint: /transactions/document/:documentId

URL Parameters:

:documentId - The ID of the document to retrieve transactions for (received from the previous conversion step)

Response Example:

{
  "documentId": "123",
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-20T10:00:00Z",
  "csvResult": "Date,Description,Amount\n2024-03-20,Salary Deposit,5000.00\n2024-03-19,Grocery Store,-85.50\n2024-03-18,Utility Bill,-120.00"
}

Get Remaining Credits

Retrieve the number of remaining credits for your account.

Method: GET

Endpoint: /user

Response Example:

{
  "credits": 100,
  "email": "user@example.com"
}

Response Status Codes

Status Code	Description
200	Request completed successfully
400	Invalid request parameters or missing required fields
403	Access denied or insufficient permissions
404	Requested resource not found
500	Internal server error occurred
666	System temporarily unavailable for maintenance
888	User account not found or inactive