2. REST API

Bank accounts and transactions can easily accessed via a RESTful web service with JSON objects.

 
2.1 Get List of Accounts

List all accounts that the user has chosen to share with your application.

Request: GET https://api.leanbank.com/rest/accounts

Required permissions: accounts=ro

Response:

JSON Field Type Description
accounts Array,
mandatory
Array of Account objects

Example request:

GET /rest/accounts HTTP/1.1

Example JSON response:

{
  "accounts": [
    {
      "account_id": "A1.1",
      "bank_id": "B1.1",
      "name": "Girokonto",
      "owner": "figo",
      "account_number": "4711951500",
      "bank_code": "90090042",
      "bank_name": "Demobank",
      "currency": "EUR",
      "iban": "DE67900900424711951500",
      "bic": "DEMODE01",
      "type": "Giro account",
      "icon": "https://api.leanbank.com/assets/accounts/demokonto.png",
      "status": {
        "code": 1,
        "sync_timestamp": "2013-04-11T19:16:00.000Z",
        "success_timestamp": "2013-04-11T19:16:00.000Z"
      }
    },
    {
      "account_id": "A1.2",
      "bank_id": "B1.1",
      "name": "Sparkonto",
      "owner": "figo",
      "account_number": "4711951501",
      "bank_code": "90090042",
      "bank_name": "Demobank",
      "currency": "EUR",
      "iban": "DE05900900424711951501",
      "bic": "DEMODE01",
      "type": "Savings account",
      "icon": "https://api.leanbank.com/assets/accounts/demokonto.png",
      "status": {
        "code": -1,
        "message": "Could not get transactions.",
        "sync_timestamp": "2013-04-11T19:16:00.000Z",
        "success_timestamp": "2013-04-11T15:16:00.000Z"
      }
    }
  ]
}
 
2.2 Get Account Details

Get information about a particular account.

Request: GET https://api.leanbank.com/rest/accounts/{account_id}

Required permissions: accounts=ro

URL Component Type Description
account_id String,
mandatory
Internal figo API account ID

Response:

JSON Field Type Description
account Object,
mandatory
Account object

Example request:

GET /rest/accounts/A1.1 HTTP/1.1

Example JSON response:

{
  "account_id": "A1.1",
  "bank_id": "B1.1",
  "name": "Girokonto",
  "owner": "figo",
  "auto_sync": False,
  "account_number": "4711951500",
  "bank_code": "90090042",
  "bank_name": "Demobank",
  "currency": "EUR",
  "iban": "DE67900900424711951500",
  "bic": "DEMODE01",
  "type": "Giro account",
  "icon": "https://api.leanbank.com/assets/accounts/demokonto.png",
  "status": {
    "code": 1,
    "sync_timestamp": "2013-04-11T19:16:00.000Z",
    "success_timestamp": "2013-04-11T19:16:00.000Z"
  }
}
 
2.3 Get Account Balance

Get balance of a particular account.

Request: GET https://api.leanbank.com/rest/accounts/{account_id}/balance

Required permissions: accounts=ro balance=ro

URL Component Type Description
account_id String,
mandatory
Internal figo API account ID

Response:

JSON Field Type Description
balance Number,
optional
Balance;
This field will be omitted if the balance is not yet known.
balance_date Timestamp,
optional
Date of balance;
This field will be omitted if the balance is not yet known.
credit_line Number,
optional
Credit line
monthly_spending_limit Number,
optional
User-defined spending limit
status Object,
mandatory
Sync Status object

Example request:

GET /rest/accounts/A1.1/balance HTTP/1.1

Example JSON response:

  {
    "balance": 3250.31,
    "balance_date": "2013-04-11T12:00:00.000Z",
    "status": {
      "code": 1,
      "sync_timestamp": "2013-04-11T19:16:00.000Z",
      "success_timestamp": "2013-04-11T19:16:00.000Z"
    }
  }
  
 
2.4 Get Account Transactions

Get transactions of a particular account.

Request: GET https://api.leanbank.com/rest/accounts/{account_id}/transactions

Required permissions: accounts=ro transactions=ro

URL Component Type Description
account_id String,
mandatory
Internal figo API account ID
URL Parameter Type Description
since String or Date,
optional
This parameter can either be a transaction ID or a date.
If this parameter is a figo API transaction ID, then the transactions which are newer than the referenced transaction will be returned in the response.
If this parameter is a date, then the transactions which were booked on or after this date will be returned in the response.
If this field is missing, all available transactions will be returned.
start_id String,
optional
Do only return transactions which were booked after the referenced transaction ID. The parameters start_id and count can be used to implement a pager.
count Number,
optional
Limit the number of returned transactions.
include_pending Boolean,
optional,
defaults to 0
Include all existing pending transactions in the response. Pending transactions are always included as a complete set, regardless of the since parameter. Before caching a copy of the pending transactions, all existing pending transactions for the same account must be removed in the local cache.

Response:

JSON Field Type Description
transactions Array,
mandatory
Array of Transaction objects
status Object,
mandatory
Sync Status object

Example request:

GET /rest/accounts/A1.1/transactions?since=2013-04-10&include_pending=1 HTTP/1.1

Example JSON response:

{
  "transactions": [
    {
      "transaction_id": "T1.1.25",
      "account_id": "A1.1",
      "name": "Rogers Shipping, Inc.",
      "account_number": "4711951501",
      "bank_code": "90090042",
      "bank_name": "Demobank",
      "amount": -17.90,
      "currency": "EUR",
      "booking_date": "2013-04-11T12:00:00.000Z",
      "value_date": "2013-04-11T12:00:00.000Z",
      "purpose": "Ihre Sendung 0815 vom 01.03.2012, Vielen Dank",
      "type": "Transfer",
      "booking_text": "Überweisung",
      "booked": false
    },
    {
      "transaction_id": "T1.1.24",
      "account_id": "A1.1",
      "name": "Dr. House Solutions GmbH",
      "account_number": "4711951501",
      "bank_code": "90090042",
      "bank_name": "Demobank",
      "amount": -300.00,
      "currency": "EUR",
      "booking_date": "2013-04-10T12:00:00.000Z",
      "value_date": "2013-04-10T12:00:00.000Z",
      "purpose": "Miete Vertragsnr. 12993",
      "type": "Direct debit",
      "booking_text": "Lastschrift",
      "booked": true
    }
  ],
  "status": {
    "code": 1,
    "sync_timestamp": "2013-04-11T19:16:00.000Z",
    "success_timestamp": "2013-04-11T19:16:00.000Z"
  }
}
 
2.5 Get All Transactions

Get transactions of all accounts that the user has chosen to share with your application.

Request: GET https://api.leanbank.com/rest/transactions

Required permissions: transactions=ro

URL Parameter Type Description
since String or Date,
optional
This parameter can either be a transaction ID or a date.
If this parameter is a figo API transaction ID, then the transactions which are newer than the referenced transaction will be returned in the response.
If this parameter is a date, then the transactions which were booked on or after this date will be returned in the response.
If this field is missing, all available transactions will be returned.
count Number,
optional,
defaults to 1000
Limit the number of returned transactions. In combination with the since parameter this can be used to paginate the result list.
include_pending Boolean,
optional,
defaults to 0
Include all existing pending transactions in the response. Pending transactions are always included as a complete set, regardless of the since parameter. Before caching a copy of the pending transactions, all existing pending transactions for the same account must be removed in the local cache.

Response:

JSON Field Type Description
transactions Array,
mandatory
Array of Transaction objects
status Object,
mandatory
Sync Status object; The error messages of all accounts will be concatenated to a single error message. For oldest timestamp of all accounts will be used.

Example request:

GET /rest/transactions?since=T1.2.14&include_pending=0 HTTP/1.1

Example JSON response:

{
  "transactions": [
    {
      "transaction_id": "T1.1.24",
      "account_id": "A1.1",
      "name": "Dr. House Solutions GmbH",
      "account_number": "4711951501",
      "bank_code": "90090042",
      "bank_name": "Demobank",
      "amount": -300.00,
      "currency": "EUR",
      "booking_date": "2013-04-10T12:00:00.000Z",
      "value_date": "2013-04-10T12:00:00.000Z",
      "purpose": "Miete Vertragsnr. 12993",
      "type": "Direct debit",
      "booking_text": "Lastschrift",
      "booked": true
    },
    {
      "transaction_id": "T1.2.15",
      "account_id": "A1.2",
      "name": "Girokonto",
      "account_number": "4711951500",
      "bank_code": "90090042",
      "bank_name": "Demobank",
      "amount": 200.00,
      "currency": "EUR",
      "booking_date": "2013-04-11T12:00:00.000Z",
      "value_date": "2013-04-11T12:00:00.000Z",
      "purpose": "Sparen",
      "type": "Standing order",
      "booking_text": "Dauerauftrag",
      "booked": true
    }
  ],
  "status": {
    "code": -1,
    "message": "Could not get transactions.",
    "sync_timestamp": "2013-04-11T19:16:00.000Z",
    "success_timestamp": "2013-04-11T15:16:00.000Z"
  }
}
 
2.6 Account Object

JSON Field Type Description
account_id String,
mandatory
Internal figo API account ID
bank_id String,
mandatory
Internal figo API bank ID
name String,
optional
Account name
owner String,
optional
Account owner
auto_sync Boolean,
optional
Whether this account is automatically synced or not
account_number String,
mandatory
Account number
bank_code String,
optional
Bank code
bank_name String,
optional
Bank name
currency String,
mandatory
Three-digit currency code
iban String,
optional
IBAN
bic String,
optional
BIC
type String,
optional
Account Type
icon String,
optional
Account icon URL
status Object,
mandatory
Sync Status object

Defined account types:

  • "Giro account"
  • "Savings account"
  • "Credit card"
  • "Loan account"
  • "PayPal"
  • "Unknown"
 
2.7 Transaction Object

JSON Field Type Description
transaction_id String,
mandatory
Internal figo API transaction ID
account_id String,
mandatory
Internal figo API account ID
name String,
optional
Name of originator or recipient
account_number String,
optional
Account number of originator or recipient
bank_code String,
optional
Bank code of originator or recipient
bank_name String,
optional
Bank name of originator or recipient
amount Number,
mandatory
Transaction amount
currency String,
mandatory
Three-digit currency code
booking_date Timestamp,
mandatory
Booking date
value_date Timestamp,
optional
Value date
purpose String,
optional
Purpose text
type String,
optional
Transaction Type
booking_text String,
optional
Booking text, as provided by the bank.
booked Boolean,
mandatory
A flag that indicates whether the transaction is booked or pending.

Defined transaction types:

  • "Transfer"
  • "Standing order"
  • "Direct debit"
  • "Salary or rent"
  • "Electronic cash"
  • "GeldKarte"
  • "ATM"
  • "Charges or interest"
  • "Unknown"
 
2.8 Sync Status Object

JSON Field Type Description
code Number,
mandatory
Internal figo API status code
message String,
optional
Human-readable error message. The figo API server tries to localize the message as requested by the Accept-Language HTTP header.
sync_timestamp Timestamp,
optional
Timestamp of last synchronization
success_timestamp Timestamp,
optional
Timestamp of last successful synchronization

Defined status codes:

Status Code Description
1 Success
-1 General error
-2 PIN error