1. Overview

Use our REST API if you need direct access to all of your transactions, bank accounts and settings.

When not to use the REST API

If you only want to get a notice as soon as new transactions were imported, we suggest to use our Push API because otherwise you need to pull frequently for new transactions when most of the time it's not necessary.

1.1 Setup

Authentification

As a first step you create a new API access token in Settings / API Access tokens The generated token can be created to access our REST API. The access token is transferred as the HTTP-Header "Authorization" like that:

Authorization: Token token=tb3vQwhAnJc2PNkusWvkgB4pA8wnVLpy7CXpEsz7jL

Endpoint

The base url for accessing our API is

https://www.bankimport.com/api/v1/

Return formats

Currently we support JSON & XML as return formats. Choosing between the format is simply done by appending the desired format to the final API call. For example: To get a list of all your imported banking accounts call:

https://www.bankimport.com/api/v1/bank-accounts.json
or
https://www.bankimport.com/api/v1/bank-accounts.xml
Our API defaults to response with JSON if you omit the desired response format.

2. Banking Accounts

To start using Bankimport you must link our system with your bank accounts.

2.1 Add a bank account

POST /api/v1/bank-account/hbci

You can use the following parameters to search for linked bank accounts:

Parameter Name Description
title Give your bank account a title for internal purposes.
hbci_bank_code Most often this is the bank code corresponding to your HBCI credentials. Sometimes on some banks you need to use another bank code. Please check the requirements and specifications of your bank if you are not able to connect succesfully with an otherwise correct bankcode.
username Your HBCI username which is used to login via HBCI into your online banking.
secret The PIN or password you use to login via HBCI into your online banking.
customer_number Optional HBCI credential. Some banks require to not only use a username but also request a customer number for the login.

2.2 Getting a list of your banking accounts

GET /api/v1/bank-accounts
Sample Response
{
  "bank_accounts": [
    {
      "id": 7856278,
      "account_number": "12345",
      "sub_account_number": "01",
      "last_update_at": "2013-04-28T12:13:22Z",
      "account_owner": "ACME Company Inc.",
      "currency": "EUR",
      "bank_name": "Deutsche Bank",
      "bank_code": "30070024",
      "balance": 24323.49,
      "access_type": "HBCI",
      "account_type": "Kontokorrentkonto",
      "iban": "DE04300700240001234501",
      "bic": "DEUTDEDBDUE"
    },
    {
      "id": 7856279,
      "account_number": "12345",
      "sub_account_number": "02",
      "last_update_at": "2013-04-28T12:16:22Z",
      "account_owner": "ACME Company Inc.",
      "currency": "EUR",
      "bank_name": "Deutsche Bank",
      "bank_code": "30070024",
      "balance": -5323.21,
      "access_type": "HBCI",
      "account_type": "SparCard",
      "iban": "DE04300700240001234502",
      "bic": "DEUTDEDBDUE"
    },
  ]
}
<?xml version="1.0" encoding="UTF-8"?>
<request>
</request>
Searching

If you have a lot of banking accounts, you can also search by using different criterias using additional GET parameters, like this:

GET /api/v1/bank-accounts?bank_code=30070024&balance_gt=0

You can use the following parameters to search for linked bank accounts:

Parameter Name Description
bank_code Only show bank accounts which matches this bank_code. You can omit the last digits for a broader search, like "bank_code=300" which will find all bank accounts whose bank codes starts with 300.
account_number Only return bank accounts whose account number starts with given value.
last_updated_after Expects a timestamp (e.g. "2013-05-20T20:18:00Z") and returns only bank accounts which were updated after the given date.
balance_min Expects a decimal value (e.g. "100.00") and returns bank accounts whose current balance is equal or higher than the given value
balance_max Expects a decimal value and returns bank accounts whose current balance is equal or lower than the given value

2.3 Getting details about a specifc bank account

If you only need information about a specific bank account, use our internal id to query only for this bank account.

GET /api/v1/bank-account/7856278

2.4 Force an update on banking accounts

All banking accounts are checked regularly for new transactions (if you activated this option in your account settings). Nonetheless you can force an update on any bank account. Please be aware that the update process is an asynchronous process. Hence you need to check if the update process finished using the GET /bank-accounts or GET /bank-account/xxxxx query.

POST /api/v1/bank-account/7856278/import
Sample Response
{
  "import": {
    "id": 343833,
    "bank_account_id": 7856278,
    "estimated_finish_date": "2013-05-23T14:39:52Z"
  }
}
<?xml version="1.0" encoding="UTF-8"?>
<request>
</request>

3. Transactions

You are using Bankimport most likely to gather information about your bank transactions. As you can imagine, accessing the transactions is read-only. You can either search globally (i.e. over all your bank accounts) or only for a specify bank account.

List (or search) globally
GET /api/v1/transactions
List (or search) within a bank account
GET /api/v1/bank-account/7856278/transactions
Query paramaters

Most likely you have thousands or more transactions already imported. Hence you can (and should) make use of your searching and paging functionality. We return a maximum of 1000 transactions per HTTP call. So make sure to respect the pagination information in our results.

A sample query would be:
GET /api/v1/transactions?page=1&order_by=account_date&status=completed

Available query parameters

Name Description
page Specify the page which you query. Defaults to 1.
limit You can limit the results. Defaults to 1000 (which is the maximum).
order_by You can use one of these values for ordering the results.
  • account_date
    sort ascending by accouting date (default)
  • account_date_desc
    sort descending by accounting date
  • imported_at
    sort ascending by import date
  • imported_at_desc
    sort descending by import date
status Most banks internally process all transactions at the late evening or night but show "pending" transactions during the day. Choose a status of:
  • any (default)
  • pending
  • completed
amount_min Return transactions whose amount is equal or higher than the given value
amount Return transactions whose amount matches exactly the given value.
amount_max Return transactions whose amount is lower or equal than the given value.
purpose Returns transactions whose purpose (text field returned by your bank) contains the given value (minimum: 3 chars).