API Documentation

On progress!

Flanks API Overview

Currently Flanks provides the following endpoints:

AUTHENTICATION

POST v0/token

CREDENTIALS

POST v0/bank/credentials/status

PUT v0/bank/credentials/status

DELETE v0/bank/credentials

AGGREGATION

POST v0/bank/credentials/data POST v0/bank/credentials/account

INVESTMENTS

POST v0/bank/credentials/portfolio

POST v0/bank/credentials/investment

POST v0/bank/credentials/investment/hist

LIABILITIES

POST v0/bank/credentials/liability

MIFID

POST v0/bank/credentials/mifid/raw

IDENTITY

POST v0/bank/credentials/auth

CARD

POST v0/bank/credentials/card

POST v0/bank/credentials/card/transaction

FILE HANDLING

POST v0/bank/credentials/upload

LINK CODES

GET v0/platform/link

POST v0/platform/link

ENTITY

GET v0/bank/available

Testing with Postman

We have created a Postman Collection with all the requests explained in this page, in order to test all the API methods.

In order to use the methods you must complete the fields accordingly following the documentation. In every request you should, at least, fill the Authorization header field with your Oauth2 access token.

You can download the collection here: Run in Postman

AUTHENTICATION

In order to use Flanks API, you need to authenticate yourself. This is done by the following endpoints, following the OAuth schema.

post
GET OAUTH TOKEN

https://api.flanks.io/v0/token
This endpoint allows you to retrieve an OAuth Token to use in your API calls.
Request
Response
Request
Headers
Content-Type
required
string
Must be application/json
Body Parameters
client_id
required
string
CLIENT_ID of your App created via Platform
client_secret
required
string
CLIENT_SECRET of your App created via Platform
username
required
string
Your Platform username
password
required
string
Your Platform password
grant_type
required
string
Must be password
Response
200: OK
{
"access_token": "<ACCESS TOKEN>",
"expires_in": 36000,
"token_type": "Bearer",
"scope": "<LIST OF SCOPES>",
"refresh_token": "<REFRESH TOKEN>"
}

post
REFRESH ACCESS TOKEN

https://api.flanks.io/v0/token
This section describes how to allow your developers to use refresh tokens to obtain new access tokens. Our service issues refresh tokens along with the access token, then we can implement the Refresh grant type described on this method.
Request
Response
Request
Path Parameters
Content-Type
required
string
Must be application/json
Body Parameters
client_secret
required
string
Introduce the client_secret of your application
client_id
required
string
Introduce the client_id of your application
refresh_token
required
string
Introduce your refresh_token
grant_type
required
string
Must be refresh_token
Response
200: OK
{
"access_token": "<ACCESS TOKEN>",
"expires_in": 36000,
"token_type": "Bearer",
"scope": "<LIST OF SCOPES>",
"refresh_token": "<REFRESH TOKEN>"
}

CREDENTIALS

In our system, Credentials is an entity that is linked to a company through its Oauth2 token. Each set of credentials correspond to a banking user. That means that a set of credentials has only one bank but can have multiple accounts and multiple associated products.

post
CREDENTIALS STATUS

https://api.flanks.io/v0/bank/credentials/status
This method allows to retrieve status of a credentials_token. Please visit, Using the Platform > Using links to connect to banks for sca_token and reset_token usage.
Request
Response
Request
Headers
Content-type
required
string
Must be application/json
Authorization
required
string
Oauth2 token that idenfies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Body Parameters
credentials_token
required
string
Token that identifies the bank account credentials of certain user.
Response
200: OK
Pending: If true, security checks are being done. So data will be available soon. Blocked: Indicates if the provided credentials are correct or access has been blocked. Reset_token: If not null, it allows to restore user password through Flanks Link querystring parameter. Sca_token: If not null, re-authorization is needed. It allows to reauthorize access to user financial data through Flanks Link querystring parameter. Last_transaction_date: It is the date of the last account transaction retrieved. Name: the name of the bank.
{
"pending": bool,
"blocked": bool,
"reset_token": [ null | str ],
"last_transaction_date": str "YYYY-MM-DD"
"sca_token": [ null | str ],
"name": str,
"last_update": str "YYYY-MM-DD"
}

put
FORCE USER TRANSACTION OR CREDENTIALS RESET

https://api.flanks.io/v0/bank/credentials/status
This method allows you to force the SCA flow in order to Flanks system to go backwards 90 days in account transaction. It will require user interaction though. If force parameter is reset it will allows you to update user entity credentials maintaining the same credentials_token.
Request
Response
Request
Headers
Content-type
required
string
Must be application/json
Authorization
required
string
Oauth2 token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Body Parameters
force
required
string
must be reset or transactions
credentials_token
required
string
Token that identifies the bank account credentials of certain user
Response
200: OK
Returned value will be the transaction_token or reset_token value.
{
"transaction_token": str
}
--------------------------------------------------------
{
"reset_token": str
}
400: Bad Request
{
"error": "Missing fields <LIST_OF_MISSING_FIELDS>"
}
--------------------------------------------------------
{
"error": "force field must be transaction or reset"
}

delete
DELETE CREDENTIALS TOKEN

https://api.flanks.io/v0/bank/credentials
This endpoint allows you to delete credentials from Flanks.
Request
Response
Request
Headers
Content-Type
required
string
Must be application/json
Authorization
required
string
Oauth2 token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Body Parameters
credentials_token
required
string
Token that identifies the bank account credentials of certain user.
Response
200: OK
{
"message": "Successfully deleted"
}

AGGREGATION

Aggregation is the process by which you can extract data from bank accounts such as transactions, accounts or credit card history.

post
GET PORTFOLIOS

https://api.flanks.io/v0/bank/credentials/portfolio
This method returns the portfolio description associated to the given credentials_token
Request
Response
Request
Headers
Authorization
required
string
OAuth token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Content-type
required
string
Must be application/json
Body Parameters
credentials_token
required
string
credentials_token that identifies user entity credentials
Response
200: OK
[
{
"name": "string",
"type": "string",
"currency": "string",
"_id": "string"
}
]

post
INVESTMENTS

https://api.flanks.io/v0/bank/credentials/investment
This method returns the investments information retrieved for the given credentials_token
Request
Response
Request
Headers
Authorization
required
string
OAuth token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Content-type
required
string
Must be application/json
Body Parameters
credentials_token
required
string
credentials_token that identifies user entity credentials.
Response
200: OK
[
{
"_id": "string"
"name": "string",
"isin": "string",
"symbol": "string",
"type": [VI | FI | F | PP | L | O],
"amount": float,
"balance": float,
"currency": "string",
"portfolio_id": "string",
"detail": {
"field1": "string",
"field2": "string",
},
},
...
]

post
INVESTMENT TRANSACTIONS

https://api.flanks.io/v0/bank/credentials/investment/transactions
This method returns the investment transactions associated to the given credentials_token
Request
Response
Request
Headers
Authorization
required
string
OAuth token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Content-type
required
string
Must be application/jsonA
Body Parameters
credentials_token
required
string
credentials_token that identifies user entity credentials.
Response
200: OK
{
"description": "string",
"type": "Venta",
"operationDate": "string" format YYYY-mm-dd,
"valueDate": "string" format YYYY-mm-dd,
"amount": float,
"balance": float,
"investment_id": "string",
"_id": "string"
},

post
GET ACCOUNT TRANSACTIONS

https://api.flanks.io/v0/bank/credentials/data
This endpoint allows to you to get the transactions of one specific credentials token. It supports pagination, that is, you can use some parameters to limit the results of the response.
Request
Response
Request
Headers
Content-Type
required
string
Must be application/json
Authorization
required
string
Oauth2 token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Query Parameters
page_size
optional
integer
Sets the number of elements per page.
page
optional
integer
Identifies the page number you want to get.
Body Parameters
webhook
optional
object
Webhook are used if you want to run this function on a regular basis.
credentials_token
required
string
Token that identifies the bank account credentials of certain user.
query
optional
object
Query used for searching on account, all information in Quickstart Query Engine.
Response
200: OK
{
"_id": str,
"account_id": str,
"amount": float,
"balance": float,
"entity": str,
"cardNumber": str,
"category": str,
"currency": str,
"operationDate": str "YYYY-MM-DD",
"valueDate": str "YYYY-MM-DD",
"description": str,
"productDescription": str,
"transfer": {
"beneficiary": str,
"ibanBeneficiary": str,
"ibanPayer": str,
"payer": str
}
}

post
GET ACCOUNT INFORMATION

https://api.flanks.io/v0/bank/credentials/account
This endpoint allows to you to get the accounts associated to a given credentials_token.
Request
Response
Request
Headers
Content-Type
required
string
Must be application/json
Authorization
required
string
Oauth2 token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Body Parameters
webhook
optional
string
Webhook are used if you want to run this function in a regular basis.
query
optional
string
Query use for searching on account, all information on Quickstart Query Engine.
credentials_token
required
string
Token that identifies the bank account credentials of certain user.
Response
200: OK
{
"iban": str,
"entity": str,
"alias": str,
"balance": float,
"currency": str,
"description": str,
"isOwner": boolean,
"numOwners": int,
"owners": array,
"_id": str,
}

Query Object

On query object you can set multiple filters for finding transactions in bank's account. For more info on query objects and its usage, refer to query engine documentation.

post
GET IDENTITY INFORMATION

https://api.flanks.io/v0/bank/credentials/auth
This endpoint allows you to retrieve all personal information related to a given credentials_token.
Request
Response
Request
Headers
Content-Type
required
string
Must be application/json
Authorization
required
string
Oauth2 token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Body Parameters
webhook
optional
object
Webhooks are used if you want to use this call on a regular basis.
query
optional
object
Object used for searching, all information in Quickstart Query Engine.
credentials_token
required
string
Token that identifies the bank account credentials of certain user.
Response
200: OK
{
"_id": str,
"name": str,
"fullName": str,
"birthDate": str "YYYYY-MM-DD",
"address": {
"streetType": str,
"streetName": str,
"streetNumber": str,
"city": str,
"zipCode": str,
"state": str,
"country": str,
},
"contactInfo": [
{
"type": str,
"value": str,
}, ...
],
"identityDocument": str,
"gender": str,
"occupation": str
}

post
LIABILITIES

https://api.flanks.io/v0/bank/credentials/liability
This method returns, if available, the associated liabilities for the fiven credentials_token
Request
Response
Request
Headers
Authorization
required
string
OAuth token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Content-type
required
string
Must be application/json
Response
200: OK
[
{
"name": "string",
"type": [ loan | credit ],
"balance": float,
"currency": "string",
"initialCapital": float,
"initialCapitalCurrency": "string",
"openingDate": "string" format YYYY-mm-dd,
"expirationDate": "string" format YYYY-mm-dd,
"_id": "string"
},
...
]

post
RETRIEVE USER MIFID

https://api.flanks.io/v0/bank/credentials/mifid/raw
This method returns entity mifid questions and user answers.
Request
Response
Request
Headers
Authorization
required
string
OAuth token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Content-type
required
string
Must be application/json
Body Parameters
credentials_token
required
string
credentials_token that identifies user entity credentials
Response
200: OK
[
{
"_id": int,
"question": str,
"answer": [
str, ..., str
],
},
...
]

post
GET CARDS INFORMATION

https://api.flanks.io/v0/bank/credentials/card
This endpoint allows you to retrieve the information associated to a credit or debit card.
Request
Response
Request
Headers
Content-Type
required
string
Must be application/json
Authorization
required
string
Oauth2 token that identifies your company in Flanks system. Format: Bearer OAUT_TOKEN
Body Parameters
webhook
optional
object
Webhooks are used if you want to use this call on a regular basis.
query
optional
object
Object using for filtering, all information in Quickstart Query Engine.
credentials_token
required
string
Token that identifies the bank account credentials of certain user.
Response
200: OK
[
{
"_id" : str,
"product": str,
"contractNumber": str,
"pan": str,
"emissionDate": str "YYYY-MM-DD",
"expirationDate": str "YYYY-MM-DD",
"availableBalance": float,
"cardType": str,
}, ...
]

post
GET CARDS TRANSACTION INFORMATION

https://api.flanks.io/v0/bank/credentials/card/transaction
This endpoint allows you to retrieve all transactions associated to a credit or debit card specified in query field.
Request
Response
Request
Headers
Content-Type
required
string
Must be application/json
Authorization
required
string
Oauth2 token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Body Parameters
webhook
optional
object
Webhooks are used if you want to use this call on a regular basis.
query
optional
object
Object used for filtering, all information in Quickstart Query Engine. If present, this field is used to filter the desired transactions. Otherwise, all transactions of all associated cards will be returned.
credentials_token
required
string
Token that identifies the bank account credentials of certain user.
Response
200: OK
[
{
"_id": str,
"card_id": str,
"operationDate": str "YYYY-MM-DD",
"valueDate": str "YYYY-MM-DD",
"amount": float,
"commission": float,
"currency": str,
"shop": str,
"category": str
}, ...
]

FILE HANDLING

Flanks provides several endpoints to help business banking users with file handling and management.

post
UPLOAD FILE

https://api.flanks.io/v0/bank/credentials/upload
This method allows you to upload a file to your (business) bank account.
Request
Response
Request
Headers
Authorization
required
string
OAuth2 token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Content-Type
required
string
Must be multipart/form-data
Form Data Parameters
type
required
string
The type of the file being uploaded. Currently, only 34.14 is supported.
file
required
string
The file to upload.
credentials_token
required
string
Token that identifies the bank account credentials of certain user.
Response
200: OK
File uploaded successfully
{
"message": "Successfully uploaded",
}
400: Bad Request
Missing fields
{
"error": "Missing fields: <LIST_OF_MISSING_FIELDS>",
}
415: Unsupported Media Type
Invalid Content-Type or file
{
"error": "Not matching body content type",
}
500: Internal Server Error
Unexpected error
{
"error": "<DESCRIPTIVE_ERROR_MESSAGE>",
}

After uploading a file, you will be able to sign it from the appropiate section on your business banking website.

Handling error 415: Unsupported Media Type

When uploading files, a 415 error may arise. There are several possible causes:

  • The Content-Type header is not set to multipart/form-data .

  • The multipart boundary is not correct: It is advisable to use a well-supported requests library in your desired language, as it will probably handle the multipart boundary for you. Other applications such as Postman also automatically provide the boundary when sending a multipart/form-data request. In some cases, it is advisable to avoid explicitly setting the Content-Type yourself and let those applications provide the correct headers.

  • The file content does not match the file extension. This error may arise when sending, for instance, a XML file ending with a .pdf extension.

LINK CODES

These endpoints allow you to interact with your links created via Flanks Platform.

Tip

You need to create an App and add a Link to it. Check the docs for more:

https://api.flanks.io/v0/platform/link?client_id={CLIENT_ID}
This endpoint allows you to retrieve all your yet unused link_codes associated to a given App. You can then exchange those link_codes for a credentials_token (see below).
Request
Response
Request
Headers
Authorization
required
string
OAuth2 token that identifies your company in Flanks API. Format: Bearer OAUTH_TOKEN
Content-Type
required
string
Must be application/json
Query Parameters
client_id
required
string
The CLIENT_ID of an App.
Response
200: OK
List of unused link codes associated to the App.
[
{
"code": "<LINK_CODE>",
},
{
"code": "<LINK_CODE>",
},
...
]

https://api.flanks.io/v0/platform/link
This endpoint allows you to exchange a link_code for a credentials_token. The code is one-use. Remember that you can set extra querystring parameters before sending a Link to your clients. These parameters will be available in this endpoint response, under the extra attribute. See Using the Platform for more information.
Request
Response
Request
Headers
Authorization
required
string
OAuth2 token that identifies your company in Flanks API. Format: Bearer OAUTH_TOKEN
Content-Type
required
string
Must be application/json
Body Parameters
code
required
string
The link_code received as a parameter in a redirect URI, or retrieved via the GET LINK CODES endpoint.
Response
200: OK
Successful retrieval. This code will be invalid from now on.
{
"message": "Successfully retrieved",
"credentials_token": "<END_USER_CREDENTIALS_TOKEN>",
"extra": {
"<EXTRA_PARAMETER_1>": "<PARAMETER_1_VALUE>",
"<EXTRA_PARAMETER_2>": "<PARAMETER_2_VALUE>",
}
}
202: Accepted
The token is not ready yet, i.e. security checks are being performed. Try again later.
{
"message": "Token is delayed during security checks",
"credentials_token": null,
}
401: Unauthorized
Provided none or invalid credentials. Check your Bearer token.
{
"error": "Invalid credentials"
}
500: Internal Server Error
Internal error. Make suer this code has not been already used.
{
"error": "<DESCRIPTIVE_ERROR_CODE>"
}

get
ENTITIES

https://api.flanks.io/v0/bank/available
This endpoint returns the available entities in Flanks system.
Request
Response
Request
Headers
Authorization
optional
string
Oaut2 token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Response
200: OK
[
{
"id": str,
"name": str,
"cif": str
},
...
]