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 |
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.
In order to use Flanks API, you need to authenticate yourself. This is done by the following endpoints, following the OAuth schema.
To authenticate, you must provide the
client_id
and client_secret for your App. Each App has one and only one valid grand type: password
or client_credentials
, which you selected when creating the App. You have to use the appropriate grant_type
for your application.Remember to user "api email" in username field (when using the
password
grant) to obtain API access_token.post
https://api.flanks.io
/v0/token
GET OAUTH TOKEN
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.
post
https://api.flanks.io
/v0/bank/credentials/status
CREDENTIALS STATUS
- pending: it will be true when the 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.
put
https://api.flanks.io
/v0/bank/credentials/status
FORCE USER SCA, TRANSACTION OR CREDENTIALS 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
https://api.flanks.io
/v0/bank/credentials
DELETE CREDENTIALS TOKEN
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 is the process by which you can extract data from online banking entity website, such as transactions, accounts, cards, portfolios, investments and liabilitites.
post
https://api.flanks.io
/v0/bank/credentials/portfolio
PORTFOLIOS
- 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
post
https://api.flanks.io
/v0/bank/credentials/investment
INVESTMENTS
- _id: unique ID of the product, is a unic ID 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.
- 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 number over 1.
- 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.
- leverage*: leverage of the investment.
- country_model: List of object per country with product data specific for the given country. If not available, the list will be empty
- country: Country of the code.
- issuer: Entity issuing the product.
- code: Unique identifier for product.
- 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
post
https://api.flanks.io
/v0/bank/credentials/investment/transaction
INVESTMENTS TRANSACTIONS
- 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 the entity, the broker, the canon (characteristics or qualities which a good tax system should possess), the ITF (International Trade and Finance) and the fx (foreign exchange commission). Values inside can be null
- currency: Currency of the transaction, 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.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 and liquidation. Values inside can be null
- 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.
- refAccountIBAN*: IBAN of the associated current account of the portfolio that contains the investment related to the transaction.
- refValos*: contract of the portfolio containing the investment related to the transaction.referenceCurrency: currency reference of the portfolio that contains 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.
- 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
- type: Standard type of the investment_transaction, you will find all the operations that we have in the table here
- transaction_id*: id identifier for the transactions given by the bank.
- unitPrice: price of the participations or titles at the moment of the transaction
- 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.
*Can be null
Type values can and will be added over time
post
https://api.flanks.io
/v0/bank/credentials/investment/detail
INVESTMENT DETAIL
This method returns the same information present in the "detail" field of the investment object. This information is extracted from different sources and the structure depends on the type of the product.
post
https://api.flanks.io
/v0/bank/credentials/account
CASH ACCOUNTS
- 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.
- updated_at_timestamp: last time when the account was seen and the information was refreshed
* Can be null
post
https://api.flanks.io
/v0/bank/credentials/data
ACCOUNTS TRANSACTIONS
- _id: Unique ID of the cash transaction.
- account_id: Unique ID of the cash account. Usually the IBAN.
- 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 movment set by the bank.
- 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.ibanPayer*: IBAN of the payer.
- transfer.payer*: 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.
- 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
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.
post
https://api.flanks.io
/v0/bank/credentials/auth
IDENTITY
- _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
orfemale
- 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
post
https://api.flanks.io
/v0/bank/credentials/liability
LIABILITIES
- name: liability name