API Documentation

Please consider that any endpoint is subject to changes

Please when integrating consider that Flanks can add fields to any endpoint, all changes will be documented in the Changelog page

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
ACCOUNTS	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/transaction POST v0/bank/credentials/investment/detail
LIABILITIES	POST v0/bank/credentials/liability POST v0/bank/credentials/liability/transaction
MIFID	POST v0/bank/credentials/mifid/raw
IDENTITY	POST v0/bank/credentials/auth
CARDS	POST v0/bank/credentials/card POST v0/bank/credentials/card/transaction
LINK CODES	GET v0/platform/link POST v0/platform/link
ENTITY	GET v0/bank/available
ALL	POST v0/bank/credentials/all
HOLDERS	POST v0/bank/credentials/holder
LIST CREDENTIALS TOKENS	POST v0/bank/credentials/list

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 and the credentials_token in the request body.

You can download the collection here:

AUTHENTICATION

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

To authenticate, you must provide the client_id and client_secret for your App.

GET OAUTH TOKEN

POST https://api.flanks.io/v0/token

This endpoint allows you to retrieve an OAuth Token to use in your API calls.

Headers

Name	Type	Description
Content-Type*	string	Must be application/json

Request Body

Name	Type	Description
client_id*	string	CLIENT_ID of your App created via Platform
client_secret*	string	CLIENT_SECRET of your App created via Platform
grant_type*	string	Must be client_credentials

200

{
    "access_token": "<ACCESS TOKEN>",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "<LIST OF SCOPES>",
}

CREDENTIALS

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

CREDENTIALS STATUS

POST 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.

Headers

Name	Type	Description
Content-type	string	Must be application/json
Authorization	string	Oauth2 token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN

Request Body

Name	Type	Description
credentials_token	string	Token that identifies the bank account credentials of certain user.

200

{
    "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",
    "time": str "HH:MM",
    "errored": {
            "product": {
                "auth": bool,
                "account": bool,
                "card": bool,
                "portfolio": bool,
                "investment": bool,
                "liability": bool,
                "holders": bool,
                "mifid": bool,
            },
            "transaction": {
                "account": bool,
                "card": bool,
                "investment": bool,
                "investmentincome": bool,
                "liability": bool,
            }
        },
    "created": {
            "product": {
                "auth": bool,
                "account": bool,
                "card": bool,
                "portfolio": bool,
                "investment": bool,
                "liability": bool,
                "holders": bool,
                "mifid": bool,
            },
            "transaction": {
                "account": bool,
                "card": bool,
                "investment": bool,
                "investmentincome": bool,
                "liability": bool,
            }
        },
}

• pending: it will be false when the initial extraction process has finished, with or without errors.

• blocked: it will be set to true if the credentials does not allow to login to the website

• reset_token: it will have value different to null if the account is blocked or you force it with the PUT request to the same endpoint

• sca_token: if will have a value different to null if the account needs SCA (a.k.a. 2FA)

• last_transaction_date: it the date of the last transactions retrieved

• name: is the bank identifier

• created_at_timestamp: timestamp when the credential_token was created

• last_update: is the day when the last extraction finished

• time: is the hour when the last extraction finished (in UTC)

• last_update_timestamp: day and time when the last extraction finiched (in UTC)

• errored: in case of error indicates to which data affects the error

• created: each field will be set to true when the extraction of the data finishes (with or without error)

So if you do not need all the information we recommend to poll this endpoint using the specific created fields you need.

FORCE USER SCA, TRANSACTION OR CREDENTIALS RESET

PUT https://api.flanks.io/v0/bank/credentials/status

Headers

Name	Type	Description
Content-type	string	Must be application/json
Authorization	string	Oauth2 token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN

Request Body

Name	Type	Description
force	string	must be sca, reset or transaction
credentials_token	string	Token that identifies the bank account credentials of certain user

200 Returned value will be the updated value.

{
    "sca_token": str
}
--------------------------------------------------------
{
    "transaction_token": str
}
--------------------------------------------------------
{
    "reset_token": str
}

400

{
    "error": "Missing fields <LIST_OF_MISSING_FIELDS>"
}
--------------------------------------------------------
{
    "error": "force field must be transaction or sca or reset"
}

This method allows you to force different flows for the credentials.

Note that this will require user interaction. Using this method will prevent the credentials to be automatically updated.

If force parameter is sca it will set the sca_token and it wait for a successful sca login interactin and then will update the data.

If force parameter is reset it will set the reset_token and it will allow you to update user online banking credentials maintaining the same credentials_token. This is usefull when the user changes their credentials.

If force parameter is transaction it will enable the transaction_token flow, which enables Flanks to go backwards more than 90 days in account transactions.

DELETE CREDENTIALS TOKEN

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

This endpoint allows you to delete credentials related to the given credentials_token from Flanks System.

Headers

Name	Type	Description
Content-Type	string	Must be application/json
Authorization	string	Oauth2 token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN

Request Body

Name	Type	Description
credentials_token	string	Token that identifies the bank account credentials of certain user.

200

{
    "message": "Successfully deleted"
}

Once the credentials_token is deleted it is not posible to retrieve the extracted data and Flanks will delete everything related to this credentials_token (meaning the credentials and all the stored data)

AGGREGATION

Aggregation is the process by which you can extract data from online banking entity website, such as transactions, accounts, cards, portfolios, investments and liabilitites.

PORTFOLIOS

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

This method returns the portfolio retrived associated to the given credentials_token

Headers

Name	Type	Description
Authorization	string	OAuth token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Content-type	string	Must be application/json

Request Body

Name	Type	Description
credentials_token	string	credentials_token that identifies user entity credentials

200

[
    {
        "name": str,
        "type": str,
        "currency": str,
        "_id": str,
        "refValores": str,
        "refAccount": str,
        "owners": [str,str...],
        "balance": float,
        "entity": str,
        "external_id": str
    }
]

• name: portfolio name set by the "entity".

• type: type of portfolio depends on the investments it contains, if it contains several types it will be marked as MIX otherwise it will follow the table in Portfolio Types
• currency: Currency of the product. Follow the ISO 4217.

• _id: uniqueID of the product, is a uniqueID based on the user credentials_token and the refValores number.

• refValores*: Number of the investments accounts from the entity. In some case the portfolio can be cancelled and the data not accessible.

• refAccount*: IBAN of main cash account related to the portfolio

• refAccounts*: IBAN of all cash account related to the portfolio.

• owners: List of the holders of the portfolio.

• balance: Current valuation of the portfolio on the currency.

• entity: Name of the entity where the credentials belongs to.

• external_id*: Same as the _id field, but it is based on the external_id associated on the user credentials_token instead of the credentials_token. In case there is no external_id for the user, the value of this field is null

• updated_at_timestamp: last time when the portfolio was seen and the information was refreshed

*Can be null

INVESTMENTS

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

This method returns the investments information retrieved for the given credentials_token

Headers

Name	Type	Description
Authorization	string	OAuth token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Content-type	string	Must be application/json

Request Body

Name	Type	Description
credentials_token	string	credentials_token that identifies user entity credentials.Ft

200

[
    {
        "_id": str,
        "external_id": str,
        "name": str,
        "isin": str,
        "cusip": str,
        "symbol": str,
        "entity": str,
        "type": str ["VI"|"FI"|"F"|"PP"|"ETF"|"L"|"O"|"DV"|"BP"|"AEP"],
        "sybtype": str,
        "amount": float,
        "balance": float,
        "currency": str,
        "portfolio_id": str, 
        "detail": {
            "field1": str,
            "field2": str,
        },
        "cost": float,
        "is_nominal": bool,
        "cnmv": {
            "isin": str,
            "gestora": str,
            "cif_gestora": str,
            "depositaria": str,
            "cif_depositaria": str,
            "num_registro_gestora": str,
            "num_registro_depositaria": str
        },
        "dgs": {
            "gestora": str,
            "cif_gestora": str,
        },
        "initial_date":str, "YYYY-MM-DD" 
        "performance": float,
        "performance_detail": {
            "MTD": float,
            "QTD": float,
            "HalfYear": float,
            "YTD": float,
            "Yearly": float,
            "InitialToDate": float,
            "InitialToDateYearly": float
        },
        "valuation_date":str, "YYYY-MM-DD"
        "expiration_date": str, "YYYY-MM-DD"
        "analytics": {
            "risk": float, 
            "sharpe_ratio": float,
            "beta_ratio": float,
            "tracking_error_ratio": float,
            "volatility": float,
            "PER": float,
            "ROE": float,
            "PES": float,
            "EPS": float 
            "ROA": float
        },
        "interest": {
            "rate": float,
            "benchmark": str,
        },
        "market": str,
        "operating_market": str,
        "capital_gain": float,
        "accrued_interest": float,
        "price_ex_cupon": float
        "leverage": int,
        "country_model":[
            {
                "country": "BR",
                "issuer": str,
                "code": str,
            }, // Example for Brazil
            {
                "country": "MX",
                "emisora": str,
                "serie": str,
                "bmv": str,
            }, // Example for Mexico
        ],
        "placing_bank": str
    },
]

• _id: unique ID of the product, based on the user credentials_token and the ISIN number.

• name: General name of the product.

• isin: General identification number, if the product has other identifiers they will be included in this field.

• cusip*: Nine-digit alphanumeric code that identifies a North American financial security.

• symbol*: Market symbol of the product in case that the product is equity.

• entity: Name of the entity where the credentials belongs to.

• amount: Number of shares the user has on this product.

• balance: Valuation of the investment using the currency of the product.

• currency: Currency of the product. Follows the ISO 4217.

• portfolio_id: Flanks identifier that can be linked with the _id of the /portfolios call.

• detail: This field will return some public information of the product. We can link your product with information sources like MorningStar or Bloomberg.

• external_id*: Same as the _id field, but it is based on the external_id associated on the user credentials_token instead of the credentials_token. In case there is no external_id for the user, the value of this field is null.

• cost*: Investment cost at time of purchase.

• is_nominal: Indicates if amount is nominal is in participations or in nominal.

• cnmv*: This field will be included only if the product is a Fund (investment type F) and is registered with the cnmv.

  • isin: General identification number (the same as in the previous ISIN field)

  • gestora*: Name of the investment management company

  • cif_gestora*: CIF (tax identification code) of the investment management company

  • depositaria*: Name of the investment custodian company

  • cif_depositaria*: CIF (tax identification code) of the investment custodian company

  • num_registro_gestora*: CNMV code of the investment management company

  • num_registro_depositaria*: CNMV code of the investment custodian company

• dgs*: This field will be included if the product is a Pension Plan

  • gestora*: Name of the investment management company

  • cif_gestora*: CIF (tax identification code) of the investment management company

• initial_date*: Date of first buy, suscription or switch was realized.

• valuation_date*: Date where balance was calculated, if given by the bank.

• expiration_date*: For fixed-income investments (type FI) is the maturity date

• performance*: Those issues dealing with the amount and value of money, wealth, debt, and investment. The performance is a decimal number expressed as per unit. An example would be a performance of 0.2, which in percentage would be 20%.

• performance_detail*: The performance detail are taken over 1, not percentage.

  • MTD: performance from the last month

  • QTD: performance from the last 3 months

  • Halfyear: performance from the last 6 months

  • YTD: performance in the current year

  • Yearly: performance from the last 12 months

  • InitialToDate: performance since the begining

  • InitialToDateYearly: performance since the begining annualized

• analytics*: The ratios are taken over 1, not percentage.

  • risk: Value at risk (only funds and PP)

  • sharpe_ratio: is commonly used to gauge the performance of an investment by adjusting for its risk (only funds and PP)

  • beta_ratio: Beta is a measure of a stock's volatility in relation to the overall market

  • tracking_error_ratio: Tracking error is a measure of financial performance that determines the difference between the return fluctuations of an investment portfolio and the return fluctuations of a chosen benchmark (only funds and PP)

  • volatility: statistical measure of the dispersion of returns for a given security or market index

  • PER: ratio of a company's share stock price to the company's earnings per share (Only VI and ETF)

  • ROE: Return to equity (Only VI and ETF)

  • PES: Price to Earnings (Only VI and ETF)

  • EPS: Earning per share (Only VI and ETF)

  • ROA: Return on Asset (Only VI and ETF)

• interest*: Interest rating information for the investment

  • rate*: Value at rate in percentage

  • benchmark*: Benchmark name for the rate value. If it is null, the rate will be fixed.

• market*: ISO MIC code (ISO 10383)

• operating_market*: ISO Operating MIC code (ISO 10383)

• capital_gain*: A capital gain is an increase in the value of an asset or investment resulting from the price appreciation of the asset or investment

• accrued_interest*: accrued interest refers to the amount of interest that has been incurred, as of a specific date, on a loan or other financial obligation but has not yet been paid out. Accrued interest can either be in the form of accrued interest revenue, for the lender, or accrued interest expense, for the borrower. Is a number over 1 not percentage.

• price_ex_cupon*: is the present discounted value of future cash stream generated by a bond. It refers to the sum of the present values of all likely coupon payments plus the present value of the par value at maturity.

• type: Investment type. See types available in Investment Types
• subtype*: Investment subtype. See subtypes available in Investment Subtypes
• leverage*: leverage of the investment.

• country_model: List of objects with product data whose content varies depending on the given country. If not available, the list will be empty. This field aggregates data for the countries listed in the table below:

Country	Fields
Brazil	country: Country of the code - "BR" issuer: Entity issuing the product. code: unique identifier for product
Mexico	country: Country of the code - "MX" emisora: the company or institution that issues the product in the mexican market serie: reference to the different types of assets emitted by the same emisora bmv: operational codification of securities transactions reported by the Mexican Stock Exchange folio: folio order number

• placing_bank*: for deposits is the bank where the money is placed

• updated_at_timestamp: last time when the investment was seen and the information was refreshed

*Can be null

INVESTMENTS TRANSACTIONS

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

This method returns the investment transactions associated to the investments retrieved for given credentials_token

Headers

Name	Type	Description
Authorization	string	OAuth token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Content-type	string	Must be application/jsonA

Request Body

Name	Type	Description
credentials_token	string	credentials_token that identifies user entity credentials.

200

{
	"accountDest": str,
	"accrued_interest": float,
	"amount": float,
	"amountDest": float,
	"balance": float,
	"commission": float,
	"commissionDest": float,
	"commission_detail": {
		"ITF": float,
		"broker": float,
		"canon": float,
		"entity": float,
		"fx": float,
	},
	"currency": str,
	"currencyDest": str,
	"description": str,
	"entity": str,
	"exchange": float,
	"expenses": float,
	"expenses_detail": {
		"custody": float,
		"financial": float,
		"iva": float,
		"liquidation": float,
	},
	"external_id": str,
	"investment_id": str,
	"isin": str,
	"isinDest": str,
	"leverage": float,
	"netCash": float,
	"netCashDest": float,
	"operationDate": str,
	"origin_gain": {
		"date": str,
		"value": float
	},
	"origin_gain_detail": list,
	"originalCurrency": str,
	"pair_transaction_id": str,
	"refAccountIBAN": str,
	"refValos": str,
	"referenceCurrency": str,
	"retention": float,
	"retention_detail": {
		"destination": float,
		"origin": float,
	},
	"symb": str ["+","-"],
	"symbDest": str,
	"transaction_id": str,
	"type": str,
	"unitPrice": float,
	"unitPriceDest": float,
	"valueDate": str,
	"valueDateDest": str,
	"_id":str
}

• accountDest*: for funds transfer (type 4 and symb "-") is the refvalores of the portfolio receiving the transfer

• accrued_interest*: total quantity of accrued interest in buy and sells of fixed-income asset in

• amount: Number of shares involved on the investment_transaction, it will be negative or positive depending on the investment type.

• amountDest*: for funds transfer (type 4 and symb "-") is the number of titles in the counterpart transaction

• balance*: Number of accumulated shares after the transaction.

• commission*: commission of the transaction.

• commissionDest*: for funds transfer (type 4 and symb "-") is the commission in the counterpart transaction

• commission_detail: commission breakdown, composed by:

  • entity*

  • broker*

  • canon* (characteristics or qualities which a good tax system should possess)

  • ITF* (International Trade and Finance)

  • fx* (foreign exchange commission).

• currency: Currency, same as investment currency. Follows the ISO 4217. All quantities of the transaction are given in this currency.

• currencyDest*: for funds transfer (type 4 and symb "-") is the currency in the counterpart transaction

• description: Concept of the investment_transaction, it will appear standardized on the type field.

• entity: entity name of the associated credentials.

• exchange: multiplier to convert between investment currency and portfolio currency. 1 unit of investment currency is equivalent to "exchange" units of portfolio currency. It's 1.0 if both currencies are equal.

• exchangeToPaymentCurrency: multiplier to convert between investment currency and payment currency. 1 unit of investment currency is equivalent to "exchangeToTransactionCurrency" units of transaction currency. It's 1.0 if both currencies are equal.

• exchangeToTransactionCurrency: multiplier to convert between investment currency and transaction currency. 1 unit of investment currency is equivalent to "exchangeToTransactionCurrency" units of transaction currency. It's 1.0 if both currencies are equal.

• expenses*: expense is the cost associated to the operation

• expenses_detail: expense is the cost of operations that a company incurs to generate revenue. The expenses details are:

  • custody*

  • iva*

  • financial*

  • liquidation*

• external_id*: Same as the _id field, but it is based on the external_id associated on the user credentials_token instead of the credentials_token. In case there is no external_id for the user, the value of this field is null.

• investment_id: Flanks id of the investment, it can be linked with the /investment response.

• isin: ISIN or DGS of the product related to the transaction.

• isinDest*: for funds transfer (type 4 and symb "-") is the isin number in the counterpart transaction

• leverage*: if applies is the leverage of the transaction

• netCash: net cost of the transaction.

• netCashDest*: for funds transfer (type 4 and symb "-") is the cash quantity in the counterpart transaction

• operationDate: Date when the investment_transaction was ordered.

• order_id*: id identifier of the order belonging the transaction, given by the bank.

• origin_gain: total amount of gain accumulated

• origin_gain_detail*: is a list of dictionaries. The keys of the dictionaries are the same as in origin gain. Origin gain detail is the historical data of each transfer.

• originalCurrency: original investment currency value.

• pair_transaction_id*: for forex transactions. Relates pair transactions.

• paymentCurrency: is the currency of the account where the transaction was settled.

• refAccountIBAN*: IBAN of the associated current account of the portfolio that contains the investment related to the transaction.

• referenceCurrency: currency reference of the portfolio that contains the investment related to the transaction.

• refValos*: contract of the portfolio containing the investment related to the transaction.

• retention*: total retention of the transaction.

• retention_detail*: retention breakdown, composed by origin and destination retention. Values inside can be null.

• reversal_type*: type of the transaction reverted, only if type is "28".

• symb: indicates if the transaction increases (+) or decreases (-) the number of participations or titles.

• symbDest*: for funds transfer (type 4 and symb "-") is the symb field ('+') in the counterpart transaction

• transaction_id*: id identifier for the transactions given by the bank.

• transactionCurrency: currency in which transaction values were reported. Follows the ISO 4217.

• unitPrice: price of the participations or titles at the moment of the transaction

• type: Standard type of the investment_transaction, you will find all the operations that we have in the table here

• unitPriceDest*: for funds transfer (type 4 and symb "-") is the price of titles in the counterpart transaction

• valueDate: Date when the investment_transaction was effective.

• valueDateDest*: for funds transfer (type 4 and symb "-") is valueDate in the counterpart transaction

• _id: Unique identification of the operation.

• country_model: List of objects with product data whose content varies depending on the given country. If not available, the list will be empty. This field aggregates data for the countries listed in the table below:

Country	Fields
Brazil	country: Country of the code - "BR" issuer: Entity issuing the product. code: unique identifier for product
Mexico	country: Country of the code - "MX" emisora: the company or institution that issues the product in the mexican market serie: reference to the different types of assets emitted by the same emisora bmv: operational codification of securities transactions reported by the Mexican Stock Exchange tasa_rendimiento: string folio_transaction: transaction id number folio: folio order number

*Can be null

Type values can and will be added over time

ACCOUNTS

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

This endpoint allows you to get the cash accounts associated to a given credentials_token.

Headers

Name	Type	Description
Content-Type	string	Must be application/json
Authorization	string	Oauth2 token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN

Request Body

Name	Type	Description
webhook	string	Webhook are used if you want to run this function in a regular basis.
query	string	Query use for searching on account, all information on Quickstart Query Engine.
credentials_token	string	Token that identifies the bank account credentials of certain user.

200

{
    "iban": str,
    "entity": str,
    "alias": str,
    "balance": float,
    "currency": str,
    "description": str,
    "isOwner": boolean,
    "numOwners": int,
    "owners": [str, str...],
    "_id": str,
    "external_id": str
}

• iban: IBAN code of the account.

• entity: entity identifier.

• alias: account alias if present, otherwise it will be same as the IBAN.

• balance: balance of the account.

• currency: ISO currency code of the account.

• description*: description

• isOwner*: indicates if credentials owner is owner of account.

• numOwners: number of owner with role Titular.

• owners: holders list.

• _id: unique identifier for the account, created by Flank's System.

• external_id*: Same as the _id field, but it is based on the external_id associated on the user credentials_token instead of the credentials_token. In case there is no external_id for the user, the value of this field is null.

• type: Account type, see more in Account types
• updated_at_timestamp: last time when the account was seen and the information was refreshed

* Can be null

ACCOUNTS TRANSACTIONS

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

This endpoint allows to you to get the cash transactions retrieved for the credentials_token specified. It supports pagination, that is, you can use some parameters to limit the results of the response.

Query Parameters

Name	Type	Description
page_size	integer	Sets the number of elements per page.
page	integer	Identifies the page number you want to get.

Headers

Name	Type	Description
Content-Type	string	Must be application/json
Authorization	string	Oauth2 token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN

Request Body

Name	Type	Description
webhook	object	Webhooks are used if you want to run this function on a regular basis.
credentials_token	string	Token that identifies the bank account credentials of certain user.
query	object	Query used for searching on account, all information in Quickstart Query Engine.

200

{
  "_id": str,
  "external_id": str,
  "entity": 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,
  "transaction_id": str,
  "transfer": {
    "beneficiary": str,
    "ibanBeneficiary": str,
    "ibanOrdenant": str,
    "ordenant": str
  },
  "norma43": str
}

• _id: Unique ID of the cash transaction.

• account_id: Unique ID of the cash account. Usually the IBAN.

• entity: Name of the entity where the credentials belongs to.

• balance*: Cash balance after the transaction.

• amount: Total cash amount of the transaction.

• entity: Bank where credentials_token belongs to.

• cardNumber*: cardNumber in the case that are a transactions done by card.

• category*: category of the movement set by the bank.

• flanks_category: flanks category classification as indicated in Data Types.

• type: flanks transactions classification as indicated in Data Types.

• currency: currency of the transaction.

• operationDate: Operation when the transaction was ordered.

• valueDate: Date when the operation was received.

• description: Concept of the transaction.

• transaction_id*: id identifier for the transactions given by the bank.

• transfer.beneficiary*: Name of the beneficiary in case there are a cash transfer.

• transfer.ibanBeneficiary*: IBAN of the beneficiary cash account.

• transfer.ibanOrdenant*: IBAN of the payer.

• transfer.ordenant*: Name of the payer.

• external_id*: Same as the _id field, but it is based on the external_id associated on the user credentials_token instead of the credentials_token. In case there is no external_id for the user, the value of this field is null.

• norma43*: Norma 43 code as indicated in Data Types.

• order_id*: id identifier of the order belonging the transaction, given by the bank.

• pair_transaction_id*: for forex transactions. Relates pair transactions, will contain _id of the related account transaction

*Can be null

Query Object

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

IDENTITY

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

This endpoint allows you to retrieve all personal information related to a given credentials_token.

Headers

Name	Type	Description
Content-Type	string	Must be application/json
Authorization	string	Oauth2 token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN

Request Body

Name	Type	Description
webhook	object	Webhooks are used if you want to use this call on a regular basis.
query	object	Object used for searching, all information in Quickstart Query Engine.
credentials_token	string	Token that identifies the bank account credentials of certain user.

200 For security reasons, fields birthDate, streetNumber, identityDocument and contactInfo inner fields values are replaced with '*'.

{
    "_id": str,
    "name": str,
    "fullName": str,
    "surname1":  str,
    "surname2":  str,
    "birthDate": str "YYYYY-MM-DD",
    "address": {
        "streetType": str,
        "streetName": str,
        "streetNumber": str,
        "city": str,
        "zipCode": str,
        "state": str,
        "country": str, # Following iso 3166
    },
    "contactInfo": [
        {
            "type": str ["phone" | "email" ],
            "value": str,
        }, ...
    ],
    "identityDocument": str,
    "gender":  str ["male" | "female"],
    "occupation":  str,
    "sector":  str
}

• _id: same as credentials token identifying online banking credentials.

• name*: first name of the owner of the online banking credentials.

• surname1*: first surname of the owner of the online banking credentials.

• surname2*: last name of the owner of the online banking credentials.

• fullName*: complete name of the owner of the online banking credentials.

• birthDate*: date of birth of the owner of the online banking credentials.

• address*: postal address for the owner of the bank access. Any of the values inside can be null.

• contactInfo*: email and/or phone contact information.

• identityDocument*: document number.

• gender*: can be male or female

• occupation*: job category of the owner of the online banking credentials, see types in Occupation field
• sector*: laboral sector of the owner of the online banking credentials. Standarized type listed inSector field

* Can be null

LIABILITIES

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

This method returns, if available, the associated liabilities for the given credentials_token

Headers

Name	Type	Description
Authorization	string	OAuth token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Content-type	string	Must be application/json

200

[
    {
        "name": str,
        "type": "Credit",
        "balance": float,
        "currency": str,
        "availableBalance": float,
        "openingDate": str "YYYY-MM-DD",
        "expirationDate": str "YYYY-MM-DD",
        "entity": str,
        "_id": str,
        "external_id": str,
        "periodicity": str,
        "subtype": str,
        "interest": {
            "rate": float,
            "benchmark": str,
            "spread": str,
            "type": str, ["fixed" | "variable"]
        },
        "contractNumber": str
    },
    ...
]
----------------------------------------------------------------------------
[
    {
        "name": str,
        "type": "Loan",
        "balance": float,
        "currency": str,
        "initialCapital": float,
        "initialCapitalCurrency": str,
        "openingDate": str "YYYY-MM-DD",
        "expirationDate": str "YYYY-MM-DD",
        "entity": str,
        "_id": str,
        "external_id": str,
        "periodicity": str,
        "subtype": str,
        "interest": {
            "rate": float,
            "benchmark": str,
            "spread": str,
            "type": str, ["fixed" | "variable"]
        },
        "contractNumber": str
    },
    ...
]
----------------------------------------------------------------------------
[
    {
        "name": str,
        "type": "Confirming",
        "balance": float,
        "currency": str,
        "openingDate": str "YYYY-MM-DD",
        "expirationDate": str "YYYY-MM-DD",
        "entity": str,
        "_id": str,
        "external_id": str,
        "limit": float,
        "periodicity": str,
        "subtype": str,
        "interest": {
            "rate": float,
            "benchmark": str,
            "spread": str,
            "type": str, ["fixed" | "variable"]
        },
        "contractNumber": str
    },
    ...
]

• name: liability name

• type: see types here

• balance: amount to return

• contractNumber*: contract identifier obtained from the financial institution website

• currency: ISO currency of the liability

• availableBalance*: in case of credit amount not consumed.

• openingDate*: date of opening liability contract

• expirationDate*: finish date for the liability contract

• _id: unique identifier for the liability

• initialCapital*: initial amount

• initialCapitalCurrency: currency of the inicial amount

• interest*: information about product interest

  • benchmark*: benchmark name for the rate value

  • rate*: interest rate, which is the percentage of the principal amount that a lender charges a borrower for the use of money.

  • spread*: the difference between two interest rates, such as the interest rate a financial institution pays for funds and the interest rate it charges for lending those funds to borrowers. (The spread represents the financial institution's profit margin and is also used to evaluate the risk of lending.)

  • type*: if present the values can be fixed or variable

• entity: entity name

• external_id*: Same as the _id field, but it is based on the external_id associated on the user credentials_token instead of the credentials_token. In case there is no external_id for the user, the value of this field is null.

• limit*: Available when type = "Confirming". The maximum amount of the liability contract

• periodicity*: Payment periodicity of the liability. (daily, monthly, quarterly, annually, biannually).

• subtype*: see subtypes here

• updated_at_timestamp: last time when the liability was seen and the information was refreshed

* Can be null

LIABILITIES TRANSACTIONS

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

Headers

Name	Type	Description
Authorization*	String	OAuth token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Content-type	String	Must be application/json

Request Body

Name	Type	Description
credentials_token*	String	credentials_tokenthat identifies user entity credentials.

200: OK

[
    {
        "amount": float,
        "currencyAmount": str,
        "balance": float,
        "currencyBalance": str,
        "description": str,
        "operationDate": str "YYYY-MM-DD",
        "valueDate": str "YYYY-MM-DD",
        "liability_id": str,
        "credit_account": str,
        "interest": float,
        "commission": float,
        "external_id": str,
        "_id": str,
        "type": str,
        "entity": str,
    }
]

• _id: unique identifier for the liability

• entity: Name of the entity where the credentials belongs to.

• amount: Total cash amount of the transaction.

• currencyAmount: ISO currency of the amount

• balance: Pending balance after the transaction

• currencyBalance: ISO currency of the balance

• description: Concept of the transaction.

• operationDate: Date when the transaction was ordered.

• valueDate: Date when the transaction was received

• liability_id: Unique ID of the liability.

• credit_account*: current account associated with the transaction

• interest*: interest amount associated with the operation

• commission*: the transaction fee

• external_id*: Same as the _id field, but it is based on the external_id associated on the user credentials_token instead of the credentials_token. In case there is no external_id for the user, the value of this field is null.

• type: liability transaction type. See reference in Liability Transaction Types
• transaction_id*: id identifier for the transactions given by the bank.

• pair_transaction_id*: for forex transactions. Relates pair transactions.

• order_id*: id identifier of the order belonging the transaction, given by the bank.

MIFID

POST https://api.flanks.io/v0/bank/credencial/mifid/raw

This method returns entity mifid questions and user answers.

Headers

Name	Type	Description
Authorization	string	OAuth token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Content-type	string	Must be application/json

Request Body

Name	Type	Description
credentials_token	string	credentials_token that identifies user entity credentials

200

[
    {
        "_id": int,
        "question": str,
        "answer": [
            str, ..., str
        ],
    },
    ...
]

Can be an empty list

CARDS

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

This endpoint allows you to retrieve the information associated to a credit or debit card.

Headers

Name	Type	Description
Content-Type	string	Must be application/json
Authorization	string	Oauth2 token that identifies your company in Flanks system. Format: Bearer OAUT_TOKEN

Request Body

Name	Type	Description
webhook	object	Webhooks are used if you want to use this call on a regular basis.
query	object	Object using for filtering, all information in Quickstart Query Engine.
credentials_token	string	Token that identifies the bank account credentials of certain user.

200 For security reasons, only the last 4-digits of card's pan are displayed, the other ones will be replaced with '*'.

[
    {
        "_id" : str,
        "external_id": str,
        "product": str,
        "contractNumber": str,
        "pan": str,
        "emissionDate": str "YYYY-MM-DD",
        "expirationDate": str "YYYY-MM-DD",
        "availableBalance": float,
        "cardType": str,
        "entity": str,
    }, ...
]

• _id: unique ID for the card.

• external_id*: Same as the _id field, but it is based on the external_id associated on the user credentials_token instead of the credentials_token. In case there is no external_id for the user, the value of this field is null.

• entity: Name of the entity where the credentials belongs to.

• product*: product description.

• contractNumber*: contract number associated to the card.

• pan: pan number of the card. Only the last four digits will be unmasked (*******1234)

• emissionDate*: emission date of the card.

• expirationDate*: date of card expiration.

• availableBalance*: in case of credit amount not consumed.

• cardType: will be credit or debit

• updated_at_timestamp: last time when the card was seen and the information was refreshed

* Can be null

CARDS TRANSACTIONS

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

This endpoint allows to retrieve all transactions associated to the cards associate to the credentials_token specified. You can filter the transaction returned for a given card through using in query object.

Headers

Name	Type	Description
Content-Type	string	Must be application/json
Authorization	string	Oauth2 token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN

Request Body

Name	Type	Description
webhook	object	Webhooks are used if you want to use this call on a regular basis.
query	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	string	Token that identifies the bank account credentials of certain user.

200

[
    {
        "_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,
        "external_id": str,
        "entity": str,
    }, ...
]

• _id: unique ID for the transaction.

• card_id: unique ID for the card used to make the transaction

• operationDate: Date of operation when the transaction was ordered.

• valueDate: Date when the operation was received.

• amount: Total cash amount of the transaction.

• commission*: commission fee of the transaction.

• currency: currency of the transaction.

• shop*: shop name or transaction description.

• category*: category of the movement set by the bank.

• entity: Flanks api entity identifier

• external_id*: Same as the _id field, but it is based on the external_id associated on the user credentials_token instead of the credentials_token. In case there is no external_id for the user, the value of this field is null.

ALL DATA OF A CREDENTIALS

POST https://api.flanks.io/v0/bank/credentials/all

This method displays all information on Flanks system associated to the credentials_token given.

Headers

Name	Type	Description
Content-Type	string	Must be application/json
Authorization	string	Oauth2 token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN

Request Body

Name	Type	Description
credentials_token	array	List of credentials_token to retrieve its information. It can be also a single string containing the token.

200 The response contains all the products of the credentials_token given, following Flanks schema on every type of field.

{
    "cards": [],
    "accounts": [],
    "portfolios": [],
    "fixedIncome": [],
    "funds": [
        {
            "accrued_interest": float,
            "amount": float,
            ...
            "transaction": []
        }
    ],
    "liabilities": [],
    "pensionPlans": [],
    "stocks": [],
    "etfs": [],
    "deposits": [],
    "others": [],
    "identity": [],
    "liquidity": [],
    "cryptoCurrencies": [],
    "contractForDifferences": [],
    "derivatives": [],
    "bankProducts": [],
    "alternativeEmergingProducts": []
}

This endpoint will return all the data available at the moment of the request without considering the credentials status. This mean that you must check the credentials status endpoint in order to understand what an empty array field means.

Eg. accounts = [] could mean:

1. Flanks is retrieving data

   The credentials/status response field created.product.account is equal to false.

2. Flanks had an error

   The credentials/status response field created.product.account is equal to true and errored.product.account is equal to true.

3. The credentials does not have accounts contracted The credentials/status response field created.product.account is equal to true and errored.product.account is equal to false.

• cards: information regarding cards including owners (with relation) and transactions for each card.

• accounts: response of /credentials/account including owners (with relation) and its associated transactions.

• portfolios: response of /portfolio including owners (with relation).

• fidexIncome: investments of type FI with its transactions.

• funds: investments of type F with its transactions.

• liabilities: response of /credentials/liability including owners (with relation) and its associated transactions.

• pensionPlans: investments of type PP with its transactions.

• stocks: response of /investment filtered by investment.type equals to VI with its transactions.

• etfs: investments of type ETF with its transactions.

• deposits: actually empty as the deposit will be included under the key "bankProducts".

• others: investments of type O with its transactions.

• identity: response of credentials/auth.

• liquidity: investments of type L with its transactions.

• cryptoCurrencies: investments of type C with its transactions.

• contractForDifferences: investments of type CFD with its transactions.

• derivatives: investments of type DV with its transactions.

• bankProducts: investments of type BP with its transactions.

• alternativeEmergingProducts: investments of type AEP with its transactions.

• updated_at_timestamp: last time when a product was seen and the information was refreshed

HOLDERS

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

This method returns all holders associated with the given credentials_token. Portfolios, accounts, cards and liabilities are the products that have associated holders.

Headers

Name	Type	Description
Authorization	string	OAuth token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Content-type	string	Must be application/json

Request Body

Name	Type	Description
credentials_token	string	Token that identifies the bank account credentials of certain user.

200

[
    {
        "product_name": str,
        "name": str,
        "rel": str,
        "product_id": str
    },
    ...
]

• product_name: General name of the product.

• name: Holder name.

• product_id: _id corresponding to the returned in /account, /card, /portfolio or /liability

• rel: Holder relation, see more in

• external_id*: Only for technology provider case. In case there is no alias for the user, the value of this field is null.

* Can be null

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:

pageAPI Platform

GET UNUSED LINK CODES

GET https://api.flanks.io/v0/platform/link

Query Parameters

Name	Type	Description
link_token	string	The TOKENthat identifies a Link

Headers

Name	Type	Description
Authorization	string	OAuth2 token that identifies your company in Flanks API. Format: Bearer OAUTH_TOKEN
Content-Type	string	Must be application/json

200 List of unused link codes associated to the App with the give client_id.

[
    {
        "code": "<LINK_CODE>",
        "extra": {},
        "link_token": "<LINK_TOKEN>",
    },
    {
        "code": "<LINK_CODE>",
        "extra": {
            "<EXTRA_PARAMETER_1>": "<PARAMETER_1_VALUE>",
            ...
            "<EXTRA_PARAMETER_N>": "<PARAMETER_N_VALUE>",
         },
        "link_token": "<LINK_TOKEN>",
    },
    ...
]

This endpoint allows you to retrieve all your yet unused link_codes.

Filter can be used in this endpoint, the filter will be a query parameter of the GET request: - link_token: unique identifier for a link. If no filter is used, all the pending codes of the company will be retrieved.

Also with every code there will be the extra dict. The keys and values corresponds to the extra parameters added to the link. And contains the link_token from which it was connected You can then exchange those link_codes for a credentials_token (see below).

EXCHANGE LINK CODE FOR CREDENTIALS TOKEN

POST https://api.flanks.io/v0/platform/link

Headers

Name	Type	Description
Authorization	string	OAuth2 token that identifies your company in Flanks API. Format: Bearer OAUTH_TOKEN
Content-Type	string	Must be application/json

Request Body

Name	Type	Description
code	string	The link_code received as a parameter in a redirect URI, or retrieved via the GET LINK CODES endpoint.

200 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>",
    },
    "link_token": "<LINK_TOKEN>"
}

202 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 Provided none or invalid credentials. Check your Bearer token.

{
    "error": "Invalid credentials"
}

500 Internal error. Make suer this code has not been already used.

{
    "error": "<DESCRIPTIVE_ERROR_CODE>"
}

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.

ENTITIES

GET https://api.flanks.io/v0/bank/available

Headers

Name	Type	Description
Authorization	string	Oauth2 token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN

200

[
    {
        "id": str,
        "name": str,
        "cif": str,
        "alwaysManualRefresh": bool
    },
    ...
]

This endpoint returns the available entities enabled for your company in Flanks system.

• id: Flanks internal financial entity identifier

• name: Financial entity name

• cif: Entity VAT number

• alwaysManualRefresh: is set to true when the entity ask for 2FA on every login

LIST CREDENTIALS TOKENS

POST https://api.flanks.io/v0/bank/credentials/list

List all the existing credentials

Headers

Name	Type	Description
Authorization*	String	Oauth2 token that identifies your company in Flanks system. Format: Bearer OAUTH_TOKEN
Content-Type*	String	Must be application/json

200: OK

{
    "items": [
        {
            "credentials_token": str,
            "external_id": [ null | str ],
            "bank": str,
            "status": {
                "pending": bool,
                "blocked": bool,
                "reset_token": [ null | str ],
                "last_transaction_date": str "YYYY-MM-DD",
                "sca_token": [ null | str ],
                "transaction_token": [ null | str ],
                "name": str,
                "last_update": str "YYYY-MM-DD",
                "time": str "HH:MM",
                "last_update_timestamp": int,
                "created_at_timestamp": int,
                "errored": {
                    "product": {
                        "auth": bool,
                        "account": bool,
                        "card": bool,
                        "portfolio": bool,
                        "investment": bool,
                        "liability": bool,
                        "holders": bool,
                        "mifid": bool
                    },
                    "transactions": {
                        "account": bool,
                        "card": bool,
                        "investment": bool,
                        "investmentincome": bool,
                        "liability": bool
                    }
                },
                "created": {
                    "product": {
                        "auth": bool,
                        "account": bool,
                        "card": bool,
                        "portfolio": bool,
                        "investment": bool,
                        "liability": bool,
                        "holders": bool,
                        "mifid": bool
                    },
                    "transactions": {
                        "account": bool,
                        "card": bool,
                        "investment": bool,
                        "investmentincome": bool,
                        "liability": bool
                    }
                }
            }
        },
        ...
    ]
}

This endpoint return the list of active credentials_token existing in Flanks system for your company environment at the moment of the request.

• credentials_token: Id associated on the user, reviewToken overview for more information

• external_id*: Same as the _id field, but it is based on the external_id associated on the user credentials_token instead of the credentials_token. In case there is no external_id for the user, the value of this field is null

• bank: Name of the entity where the credentials belongs to.

• status: Review CREDENTIALS STATUS for more information *Can be null

REQUEST ENCRYPTION

All Flanks APIs use TLS on top of the HTTP connection to provide point-to-point encryption and ensure the content of any intercepted request remains secret.

However, sometimes there’s a need to provide an extra layer of encryption. For example, if a request must pass through different internal systems and you don’t want those systems to have access to the request content. This may be the case if one component has the Flanks access_key and acts as a “proxy” for other components, but does not need to know the content of the requests.

For this, Flanks uses JSON Web Encryption, or JWE. JWE’s are a special kind of JSON Web Tokens (JWT)

Encrypted Requests with JWE

JSON Web Encryption (JWE) represents encrypted content using JSON-based data structures. It is a standardized protocol and many programming languages have tooling to generate, decrypt and validate them.

• The sender generates the original message (OM) as a JSON string

• The sender obtains a public key (PK) from Flanks

• Then, it generates a Content Encryption Key (CEK), a single-use symmetric only for the request.

• Then, a JWE is assembled:

  • The original message (OM) is encrypted using the CEK

  • The CEK is itself encrypted using the public key (PK)

This ensures that the content is only accessible for whoever has the private key corresponding to the public key (PK) used in the generation of the JWE.

Flanks Public Key Set

The public keys accepted by Flanks are published using a standard format, JSON Web Key Set, which is a JSON file with a list of JSON Web Keys (JWK). This file is meant for automatic consumption and it’s always available at:

https://api.flanks.io/.well-known/jwks.json

All the keys present there can be used to encrypt a JWE at the moment of consumption.

Sending a JWE to Flanks

All the requests to our APIs accept the application/json format. You can choose to send a JWE instead for any request.

To send a JWE, you need to:

• Choose one of the available public keys from flanks’ JWKS

• Generate the JWE token (in compact form) from your original content

• Send a request with the JWE as the body and setting the header "Content-Type": "application/jose"

Python Example

import json
import requests
from jwcrypto import jwe, jwk


# Original content, as JSON string
original_conent = json.dumps({})


# Get Flanks' public keys and select one
r = requests.get("https://api.flanks.io/.well-known/jwks.json")
jwks = jwk.JWKSet.from_json(r.text)
public_key = list(jwks)[0]


# Generate the JWE object
protected_header = {
   "alg": "RSA-OAEP-256",
   "enc": "A256CBC-HS512",
   "typ": "JWE",
   # This will instruct the receiver to use this specific key to
   # decrypt the JWE
   "kid": public_key.kid,
}
jwe_obj = jwe.JWE(
   original_conent,
   recipient=public_key,
   protected=protected_header,
)
# The JWE in JWT compact format
encrypted_content = jwe_obj.serialize(compact=True)


# Send the request to Flanks
r = requests.post(
   "https://api.flanks.io/any-endpoint",
   headers={
       # Signal the content is a JWT (JWE)
       "Content-Type": "application/jose",
       # Authentication works the same way
       "Authorization": "Bearer YOUR_ACCESS_TOKEN",
   },
   data=encrypted_content,
)