Quickstart

On progress

Overview

Introduction

With this quickstart guide, we have tried to make it as easy as possible to get up and running with Flanks.

If you have any questions along the way, please refer to: hello@flanks.io

We will start with an overview of Flanks and then jump start your integration with a step-by-step guide and code samples in Python and Node. If you would like to follow along (and test it out!), clone the quickstart repository for the complete example apps. You will want to sign up for free API keys to get started.

Running the walkthrough app

JS
PYTHON
git clone https://github.com/flanks-io/quickstart.git
cd quickstart/node
npm install
# Start the Quickstart with your API keys from the website
# https://flanks.io
OAUTH_TOKEN='CLIENT_ID' \
node index.js
# Go to http://localhost:8000

Platform Overview

To help you get oriented with Flanks API and what it can help you to do, let’s start by defining some basics:

API Keys

Key

Description

OAuth Token

An OAuth Token allows you to identify as your company with Flanks API in a secure way.

credentials_token

Allows you to identify an account associated with a certain company.

Though OAuth Token and credentials_token are the same across all environments, use our Sandbox and Development environments to build out and test your integration with simulated and live users, respectively. You will move over to our Production environment once you are ready to go live!

When using our test bank, use XXXXXXXXT as the username and XXXX for the password. The bank identifier is testbank . See the docs for more.

API environments

  • Sandbox: Stateful sandbox environment; use test credentials and build out and test your integration.

  • Development: Test your integration with live credentials; you will need to request access before you can move to our Development environment.

  • Production: Production API environment; all requests are billed.

Token overview

Most API requests interact with a credentials_token associated with a financial institution. A single end-user of your application might have accounts at different financial institutions.

Credit and depository accounts may also have transactions associated with them.

That credentials_token uniquely identify the account. You can use the credentials_token along with your OAuth Token to access products available for an account and make changes to it over time.

Read on for more information about each of our products and how you create and access data for an account.

Flanks Products

The simplest and the secure way to connect with our products is using Flanks Link you just need to initialize our Iframe on your platform. Our Iframe is full costumizable and in general it looks like this:

Bank selection screen
Bank login screen

Once the user has connected through our Iframe, everything necessary to operate with the data that the user has given his consent will be sent.

Accessing data

Once you create a credentials_token, you can then access data—such as transaction data, account information and routing numbers—using our API endpoints. You access data using the credentials_token, which is specific to your API keys and cannot be shared or used by any other API keys. By default, a credentials_token never expires, but it can rotate.

To integrate an existing architecture with the Flanks API, you might try using a table to store credentials_token and OAuthToken combinations that map to individual users in your system.

Products overview

Transactions

Clean transaction data going back as far as 24 months. Transaction data may include context such as geolocation, merchant, and category information.

Assets

Streamline borrower experiences by verifying assets, including account balances, transaction histories and account holder identity information.

Institution Coverage

As we noted above, a credentials_token represents accounts at a given financial institution, bank, or credit union. Flanks supports many of different institutions, and we are constantly working to add more. Though integration information does change, our API stays up-to-date with Flanks's latest institution coverage at all times and makes it easy for users to find their intended institution.

Because product coverage does vary by institution, we recommend initializing credentials_token with all the products that your integration will need.

Authentication

In order to interact with Flanks API, you need an OAuth Token.

Obtaining an OAuth Token is simple. First, you have to create an account at our Platform; from there, you can create an App. The steps are detailed here:

Then, you can use your app's CLIENT_ID and CLIENT_SECRET credentials to retrieve an OAuth Token using our Authentication endpoint:

That's it! You can now use your OAuth Token in your API calls.

Creating Credentials Token with Flank's Clients

Now that you have API keys and know the basics of the Flanks API, it is time to integrate with Flank's clients, which will handle credentials validation, multi-factor authentication, and error handling for each institution that we support.

Clients allow interact with the Flanks system in an easier and faster way. We currently have different clients that are integrated with the main important market languages. In our clients, previous validations are incorporated to save calls to the system and speed up the interaction with it.

Credentials creation code

Below are different examples of how a credentials can be created to obtain the credentials_token:

JS
PYTHON
const flanks = require('flanks');
flanks.createCredentials({
username: 'username',
password: 'password',
bank: 'bank',
}).then(response => {
console.log(response.data);
}).catch(err => {
console.error(err);
});

RESPONSE
{
"credentials_token": <YOUR_CREDENTIALS_TOKEN>,
"message": "Credentials created successfully"
}

Tip: With JavaScript, you can also use the new async/await keywords introduced in ES2017. Inside of an async function:

USING ASYNC/AWAIT
async function foo() {
try {
const response = await flanks.createCredentials({
username: '<USERNAME>',
password: '<PASSWORD>',
bank: '<BANK>',
});
console.log(response.data);
} catch (err) {
console.error(err);
}
}

Deleting credentials

To delete an existing credentials, simply use its associated credentials_token:

JS
PYTHON
flanks.deleteCredentials({
credentials_token: '<YOUR_CREDENTIALS_TOKEN>'
}).then(response => {
console.log(response);
}).catch(err => {
console.error(err);
});
// async version
async function foo() {
try {
const response = await flanks.deleteCredentials({ credentials_token: '<YOUR_CREDENTIALS_TOKEN>' });
console.log(response.data);
} catch (err) {
console.error(err);
}
}

Accessing Financial Data

Pulling data with Credentials Token

The securest way to obtain the financial information of an account is by using the credentials_token that was created in the previous section.

With the credentials_token you can perform any operation with this account without the need to enter passwords periodically.

JS
PYTHON
const flanks = require('flanks');
flanks.getAccountData({
credentials_token: '<CREDENTIALS_TOKEN>',
}).then(response => {
console.log(response.data);
}).catch(err => {
console.error(err);
});
Response
{
"account": {
"alias": "string",
"amount": {
"value": float,
"currency": "string"
},
"availability": "string",
"bank": "string",
"description": "string",
"iban": "string",
"isOwner": boolean,
"numOwners": int,
"owner": "string"
},
"amount": float,
"balance": float,
"bank": "string",
"cardNumber": "string",
"category": "string",
"currency": "string",
"dateOperation": "YYYY-MM-DD",
"dateValue": "YYYY-MM-DD",
"description": "string",
"expense": boolean,
"id": "string",
"productDescription": "string",
"service": "string",
"transfer": {
"beneficiary": "string",
"ibanBeneficiary": "string",
"ibanOrdenant": "string",
"ordenant": "string"
}
}

A faster but less secure way to access the financial data of a bank account is by using the credentials, instead of token, of the bank in each request.

JS
PYTHON
const flanks = require('flanks');
flanks.getAccountData({
username: 'username',
password: 'password',
bank: 'bank',
}).then(response => {
console.log(response.data);
}).catch(err => {
console.error(err);
});
Response
{
"account": {
"alias": "string",
"amount": {
"value": float,
"currency": "string"
},
"availability": "string",
"bank": "string",
"description": "string",
"iban": "string",
"isOwner": boolean,
"numOwners": int,
"owner": "string"
},
"amount": float,
"balance": float,
"bank": "string",
"cardNumber": "string",
"category": "string",
"currency": "string",
"dateOperation": "YYYY-MM-DD",
"dateValue": "YYYY-MM-DD",
"description": "string",
"expense": boolean,
"id": "string",
"productDescription": "string",
"service": "string",
"transfer": {
"beneficiary": "string",
"ibanBeneficiary": "string",
"ibanOrdenant": "string",
"ordenant": "string"
}
}

Query Engine

In each request you are allowed to add a query field, in request body, in order to filter the retrieved data.

Query syntax

{
"query": {
"fieldName1": [
"fieldQuery1",
"fieldQuery2",
// ...
"fieldQueryN"
],
// ...
"fieldNameN": [
// ...
]
}
}

For each field in the query, we introduce a list with a certain number of queries or filters. These filters act as a disjunction, as the query will return any object that matches at least one of these filters for each field.

Now, we specify the syntax for each field filter depending on the filter type.

String filter

A query on a string typed field should be a valid regular expression. In particular, any string is a valid regular expression that matches to that exact string, but more complex queries can be made using them.

For example:

{
"query": {
"description": [
"^TRANSFERENCIA.*", // matches all objects whose field "description" starts with "TRANSFERENCIA",
".*TRIVAGO.*" // matches all objects that contain the word TRIVAGO in the field "description"
"INGRESO CAJERO" // matches all objects whose field "description" is exactly "INGRESO CAJERO"
]
}
}

Ordered field filter

By ordered field, we mean any type of value where we can define a relationship of order, i.e. saying A is greater/lesser than B. In particular, these are meant to be applied to numbers and dates.

These filters, as of right now, accept the relationships "greater or equal than", and "lesser or equal than", and each query should be written as a dictionary whose keys can be "gte" or "lte" for each of the mentioned relationships respectively, and whose values should be of the same type of the queried field.

For example:

{
"query": {
"amount": [
{
"lte": 20,
"gte": 10
}, // matches all objects whose field "amount" is in the interval [10, 20]
{
"gte", 100
}, // matches all objects whose field "amount" is in the interval [100, inf]
{
"lte": -5
} // matches all objects whose field "amount" is in the interval [-inf, -5]
]
}
}

Webhooks Engine

In our system you can create a webhook in any request. To each part of the body of the product it will be possible to set a url (callback) and the period each time the request is made. For example:

{
"credentials_token": "credentials_token_value",
"query":{
"fieldName1": [
"fieldQuery1",
"fieldQuery2",
...
],
"fieldNameN": [
// ...
]
},
"webhook":{
"callback": < YOUR URL >,
"period": 10 //Every 10 minutes
}
}

All our requests can contain a query parameter that enables filtering the results on any field, be it a string, a number or a date. The general syntax of a query is as follows: