Aggregation API

This API allows the retrieval of data associated with specific credentials. Each endpoint allows the retrieval of a specific kind of data from our Data Model.

Note

Please note that the data you will get from these endpoints is not necessarily the current version of the data in the financial entity. When you call the Aggregation API, we're always returning the last version of the data we've fetched and have in our database. The credentials need to be refreshed to get more recent data (this typically happens once a day).

Every endpoint requires a credentials_token parameter, identifying the credentials owning the data to retrieve. There is currently no way to request information for more than one credential at a time.

There are three main reasons why an endpoint for a specific type of data could not be returned:

The endpoint returns an empty list because there was no data to be retrieved from the original source.
The credentials have just been added and this specific kind of data is still not being retrieved. There's a common error response for this case.
There has been an error retrieving the data from the original source and we can't guarantee they are valid. This is usually a temporary state while we fix the problem. There's a common error response for this case.

Endpoints

Get Portfolios

Return all the portfolios for a specific credential.

https://api.flanks.io/v0/bank/credentials/portfolio

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Value
`credentials_token` *	String	Identifier for the credentials
`query`	Object	See Query Object
`ignore_data_error`	Bool	See Ignore Data Error

(*) Mandatory Parameters

Responses

200 OK

[
  {Portfolio1},
  {Portfolio2},
  ...
]

This endpoint returns a list of portfolios, each portfolio is an object with the keys described in the Data Model page.

See Common Error Responses

Get Investments

Return all the investments for a specific credential.

https://api.flanks.io/v0/bank/credentials/investment

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Value
`credentials_token` *	String	Identifier for the credentials
`query`	Object	See Query Object
`ignore_data_error`	Bool	See Ignore Data Error

(*) Mandatory Parameters

Responses

200 OK

[
  {Investment1},
  {Investment2},
  ...
]

This endpoint returns a list of investments, each investment is an object with the keys described in the Data Model page.

See Common Error Responses

Get Investment Transactions

Return all the investment transactions for a specific credential.

https://api.flanks.io/v0/bank/credentials/investment/transaction

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Value
`credentials_token` *	String	Identifier for the credentials
`query`	Object	See Query Object
`ignore_data_error`	Bool	See Ignore Data Error

(*) Mandatory Parameters

Responses

200 OK

[
  {InvestmentTransaction1},
  {InvestmentTransaction2},
  ...
]

This endpoint returns a list of investment transactions, each transaction is an object with the keys described in the Data Model page.

See Common Error Responses

Get Accounts

Return all the accounts for a specific credential.

https://api.flanks.io/v0/bank/credentials/account

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Value
`credentials_token` *	String	Identifier for the credentials
`query`	Object	See Query Object
`ignore_data_error`	Bool	See Ignore Data Error

(*) Mandatory Parameters

Responses

200 OK

[
  {Account1},
  {Account2},
  ...
]

This endpoint returns a list of accounts, each account is an object with the keys described in the Data Model page.

See Common Error Responses

Get Account Transactions

Return all the account transactions for a specific credential.

https://api.flanks.io/v0/bank/credentials/data

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Value
`credentials_token` *	String	Identifier for the credentials
`query`	Object	See Query Object
`ignore_data_error`	Bool	See Ignore Data Error

(*) Mandatory Parameters

Responses

200 OK

[
  {AccountTransaction1},
  {AccountTransaction2},
  ...
]

This endpoint returns a list of account transactions, each transaction is an object with the keys described in the Data Model page.

See Common Error Responses

Get Liabilities

Return all the liabilities for a specific credential.

https://api.flanks.io/v0/bank/credentials/liability

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Value
`credentials_token` *	String	Identifier for the credentials
`query`	Object	See Query Object
`ignore_data_error`	Bool	See Ignore Data Error

(*) Mandatory Parameters

Responses

200 OK

[
  {Liability1},
  {Liability2},
  ...
]

This endpoint returns a list of liabilities, each liability is an object with the keys described in the Data Model page.

See Common Error Responses

Get Liability Transactions

Return all the liability transactions for a specific credential.

https://api.flanks.io/v0/bank/credentials/liability/transaction

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Value
`credentials_token` *	String	Identifier for the credentials
`query`	Object	See Query Object
`ignore_data_error`	Bool	See Ignore Data Error

(*) Mandatory Parameters

Responses

200 OK

[
  {LiabilityTransaction1},
  {LiabilityTransaction2},
  ...
]

This endpoint returns a list of liability transactions, each transaction is an object with the keys described in the Data Model page.

See Common Error Responses

Get Cards

Return all the cards for a specific credential.

https://api.flanks.io/v0/bank/credentials/card

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Value
`credentials_token` *	String	Identifier for the credentials
`query`	Object	See Query Object
`ignore_data_error`	Bool	See Ignore Data Error

(*) Mandatory Parameters

Responses

200 OK

[
  {Card1},
  {Card2},
  ...
]

This endpoint returns a list of cards, each card is an object with the keys described in the Data Model page.

See Common Error Responses

Get Card Transactions

Return all the card transactions for a specific credential.

https://api.flanks.io/v0/bank/credentials/card/transaction

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Value
`credentials_token` *	String	Identifier for the credentials
`query`	Object	See Query Object
`ignore_data_error`	Bool	See Ignore Data Error

(*) Mandatory Parameters

Responses

200 OK

[
  {CardTransaction1},
  {CardTransaction2},
  ...
]

This endpoint returns a list of liability transactions, each transaction is an object with the keys described in the Data Model page.

See Common Error Responses

Get Identity

Return the identity information assigned to a specific credential.

https://api.flanks.io/v0/bank/credentials/auth/

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Value
`credentials_token` *	String	Identifier for the credentials
`query`	Object	See Query Object
`ignore_data_error`	Bool	See Ignore Data Error

(*) Mandatory Parameters

Responses

200 OK

{Identity}

This endpoint returns an object with the identity field with the keys described in the Data Model page.

See Common Error Responses

Get Holders

Return holder information for a specific credential.

https://api.flanks.io/v0/bank/credentials/holder

Headers

Header	Value
`Authorization`	`Bearer <access_token>` (See Authentication).
`Content-Type`	`application/json`

Body (JSON encoded)

Parameter	Type	Value
`credentials_token` *	String	Identifier for the credentials
`query`	Object	See Query Object
`ignore_data_error`	Bool	See Ignore Data Error

(*) Mandatory Parameters

Responses

200 OK

  [
    {Holder1},
    {Holder2},
    ...
  ]

This endpoint returns a list of holders, each holder is an object with the keys described in the Data Model page.

See Common Error Responses

Common Error Responses

400 Invalid JSON

{
    "error": {
      "code": "InvalidJSON",
      "message": "Invalid JSON"
    }
}

The body of the request is not a proper JSON.

400 Credentials Not Found

{
  "error": "You are not allowed to access to this credentials"
}

There is no credentials in our system identified by the provided credentials_token. Either the credentials_token is invalid or the credentials have been removed at some point.

400 Invalid Query

{
  "message": "Invalid query: <MESSAGE>",
  "error_code": 40001,
}

The query object provided is invalid. Please check Query Object for reference.

400 Data Error

{
  "message": "User data not available. Please try again later",
  "error_code": 20001,
}

There has been an error retrieving data from the original source. Other endpoints for the same credentials might have valid data. Check the Credentials Status documentation for a complete reference about the available data.

This error can be ignored by setting the ignore_data_error parameter described in Ignore Data Error

400 Data Not Ready

{
  "message": "Retrieving user data. Please try again in a moment.",
  "error_code": 20002,
}

We haven't completed the first data extraction of this kind of data for this credential. Other endpoints for the same credentials might have valid data. Check the Credentials Status documentation for a complete reference about the available data.

401 Invalid Credentials

{
    "error": "Invalid credentials"
}

The Authorization header is either empty or contains an invalid or expired access_token.

500 Internal Error

{
    "error": "Internal Error"
}

The server encountered an unexpected condition that prevented it from fulfilling the request.

Query Object

In each request, you are allowed to add a query field, in the request body, 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 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]
        ]
    }
}

Available filter fields

These are the fields that can be used to filter account transactions output.

_id
description
amount
operationDate
valueDate
category
currency
shop
account_id
card_id
investment_id
liability_id
portfolio_id

Ignore Data Error

When calling a specific endpoint you can add the ignore_data_error flag to return data eventhough it got errored. By default, it is set to false.

Check errored product

To check what endpoints of a specific credentials have errored data, you can use the following endpoint: Credential Status.

Last data available

To know when's the last time the data from a specific credentials has been refreshed, you can check the updated_at_timestamp field in the response.