Version 20180620-A

Getting Started

APIs

Prerequisites

Endpoints and access restrictions

Signing the payload of your requests

Finanda Smart Aggregation Service Status

Finanda Smart Aggregation REST APIs

initiateJob

continueJob

deleteJobResult

jobStatus

jobResults

institutesAvailability

getCredentialsSchema

Objects

checking-ILS

Account Record

Transaction Record

card

Account Record - External Credit Company

Transaction Record - External Credit Company

Account Record - Bank Internal

Transaction Record - Bank Internal

checking-foreign

Account Record

Transaction Record

savings

Account Record

loans

Account Record

Sub Loan Record

investments

Account Record

Portfolio Entry Record

Other

Message Record

Predefined Values

errorCode list

institute_code list

Account type list

card_company_finanda_code list

card_type_finanda_code list

card_club_finanda_code list

interest_type_finanda_code list

linkage_type_finanda_code list

Best Practices

Wrong Credential Errors

Messages We Present In MyFinanda Upon An Error

Frequency of jobStatus Calls

About Using The Service During Night Time

Checking Institutes availability before downloading data

Evaluating Finanda Smart Aggregation in the Sandbox

Sample (Javascript)

Finanda Smart Aggregation Assistant - Developer Utility

Appendix A: Mapping Institutes Credentials to API Parameters

Appendix B: Institutes Metadata

Changelog

Getting Started

Welcome to Finanda Smart Aggregation API document - the easy way to retrieve financial information.

This is a reference document and as such can be used in any order you prefer as long as you understand the concepts. If you are new to the Finanda Smart Aggregation API - the following steps will get you started using the API quickly and smoothly  as possible.

Step 1: Get your Finanda Smart Aggregation user details from your organization’s Finanda account administrator. Those details include:

Step 2: If you want to get some feeling of the API before you dive into implementation details, you might like to use our assistant page as explained in this section below. The assistant will allow you to run various APIs from your browser window and help you see examples of detailed api calls.

Step 3: Go over this API document thoroughly.

Step 4: Review the official Finanda Smart Aggregation reference project, available for you to download from our Github at https://github.com/finanda/Finanda-Smart-Aggregation-Reference-Project 

The reference project is written in Javascript using NodeJS, but it serves as a reference for using Finanda Smart Aggregation service. Even if your organization uses another language (such as Java, PHP or anything else) we still suggest you review this project (after all, the concepts are the same even if the language is not).

Step 5: Have fun implementing your application using the Finanda Smart Aggregation service. Questions? We are here to assist you! Just contact us via https://www.finanda.com/support/ 


APIs

Calls are done via HTTPS, using POST requests. Parameters are passed using standard HTTP format in the POST stream and must be URL encoded to ensure they are passed properly. Results are returned as a JSON object.

All API parameters are required unless indicated as optional.

 Prerequisites

All APIs involve a customerID parameter which is the identifier by which Finanda Smart Aggregation service identifies you when you access the API.

All APIs require you to sign the payloads of your requests with your customer secret key.

 Please refer to your Finanda’s account administrator for those values.

 Endpoints and access restrictions

To access the api use the following end-point using the https protocol: api.finanda.co.il

Access is limited to the list of IP addresses the customer provided during the registration to the service. This ensures that only requests coming from these IP addresses can use the api and access downloaded financial information originating from the customer.


 Signing the payload of your requests

The API in the cloud requires that you sign the payload of your requests using your customer secret key. You sign the payload using the sha256 algorithm.

To sign your payload follow these steps:

  1. To the payload of your request add the string "&finanda_key=SECRETKEY" where SECRETKEY is your customer secret key.
  2. Calculate the sha256 hash for the string of your payload with the secret key
  3. Revert to your original payload string and add "&signature=SHA256-HASH-VALUE" to it

Example

Assume that you are trying to call the jobStatus api call with the payload

customerID=a&jobID=c72359fa-55df-46a4-bacf-52a8d428275e 

And that  your customer secret key is secretKey

Feed the following to the sha256 algorithm:

customerID=a&jobID=c72359fa-55df-46a4-bacf-52a8d428275e&finanda_key=secretKey

Take the result and your final payload is now:

customerID=a&jobID=c72359fa-55df-46a4-bacf-52a8d428275e&signature=aefdaa6ed846bb9ae735b469b4e4d15ec15750a1b74474cad0b6e022f34c084c

And you can pass that payload for the api call.

 Finanda Smart Aggregation Service Status

As a service to our customers - the status of Finanda Smart Aggregation Service and institutes availability  is available on our website:

https://www.finanda.com/api/status/

Notice that your code is expected to test the service status periodically using the institutesAvailability API as explained in the Best Practices section


 Finanda Smart Aggregation REST APIs

initiateJob

Provide credentials and start a new download job

Request Parameters

instituteID

identifier for the institute we work against

uid

Part of the credentials[1]

pwd

Part of the credentials[2]

vcA

Part of the credentials[3]

vcB

Part of the credentials[4]

accountList

Optional - comma separated account numbers to download (if not defined, download all). Notice that these are the account-numbers of the parent accounts - child accounts for a downloaded account are retrieved (or ignored) based on the accountTypes parameter below[5]

accountTypes

Optional - comma separated account types to download from bank, according to the values of the account type list. If not defined, download all types.
Account type "checking-ILS" is always part of the downloaded data when handling bank website

startDate

Optional - in the format  "yyyy-mm-dd". If not defined, used 30 days before endDate. See  Remarks about the dates parameters below this table

endDate

Optional - in the format  "yyyy-mm-dd". If not defined, use the day of activation. See  Remarks about the dates parameters below this table

customerID

Your unique customer identifier

performClassification

true/false - if true, classification is performed

apiVersion

Optional - api version we are using. Default (if not specified) - 2018-02-01

 

Remarks about the dates parameters:

Response format

{success : true, requestID :..., jobID : …}

or

{success : false, requestID :..., errorMessage : …, errorCode: ...}

Limits

The API initiateJob is throughput limited to 50 jobs per second - ensure to space your job initiations accordingly.

[Hosted API customers: Limited only by your provisioned resources]


continueJob

Provide OTP and start a new download job

Request Parameters

jobID

The identifier of the job we want to continue

otp

The one-time-password

apiVersion

Optional - api version we are using. Default (if not specified) - 2018-02-01

Response format

{success : true, requestID :..., jobID : …}

or

{success : false, requestID :..., errorMessage : …, errorCode: ...}


deleteJobResult

Delete stored result information about the job (The job meta-data is kept for statistical uses)

Request Parameters

jobID

identifier for the job we want to delete

customerID

Unique customer identifier

apiVersion

Optional - api version we are using. Default (if not specified) - 2018-02-01

Response format

{ success : true, requestID :...}

or

{success : false, errorMessage : …, requestID :..., errorCode: ...}


jobStatus

Determine the job status.

Request Parameters

jobID

identifier for the job we enquire about

customerID

Unique customer identifier

apiVersion

Optional - api version we are using. Default (if not specified) - 2018-02-01

Response format

{success : false, errorMessage : …, requestID :..., errorCode: ...}

or

{success : true, jobEntry : …, requestID :...}

Where jobEntry will have the following fields: jobID, status, triggerDate, lastStatusDate and in case status is "failure", message will include the error message.

Status is one of the following strings:

jobResults

Retrieves the financial data downloaded by job.

Request Parameters

jobID

identifier for the job we want to get the results for

customerID

Unique customer identifier

apiVersion

Optional - api version we are using. Default (if not specified) - 2018-02-01

Response format

{success : false, errorMessage : …, requestID :... errorCode: ...}

or

{success : true, results : …, downloadTime : …, requestID :...,}

Where the results are the data that we return in the following format:

[AccountList] - An array of accounts and their data which will look like the following:

{AccountDescription : …, AccountType : …, Balance : …, Records : []}

A Records is an array of transaction entries, each one is in the format that we will define in the next section for each account type.

Notice: Jobs that finished successfully retain the results for 3 hours. After 3 hours the job results are scheduled for automatic removal from the system and will be removed as soon as the system is able to do so. You can remove the results earlier using the deleteJobResult api call.


institutesAvailability

Returns the availability of download programs to  retrieve data from financial institutions website.

Request Parameters

customerID

Unique customer identifier

apiVersion

Optional - api version we are using. Default (if not specified) - 2018-02-01

Response format

{success : false, errorMessage : …, requestID :..., errorCode: ...}}

or

{success : true, institutes: ..., requestID :...

Where institutes is an array of institutes, providing the institute-id and availability.


getCredentialsSchema

Returns the credentials schema for the different institutes.

Request Parameters

customerID

Unique customer identifier

apiVersion

Optional - api version we are using. Default (if not specified) - 2018-02-01

Response format

{success : false, errorMessage : …, requestID :...}

or

{success : true, credentialsSchema}

credentialsSchema is an array of entries for each financial institutions. For each one, the institute-code, description and type is returned, as well as the list of parameters needed as credentials to log into it. Each parameter will have a label, position (if you want to display these in a user-interface) and the parameter-name that will be needed in a call to initiateJob API

Notice the parameters attributes reflect what the institution website presents, both in respect to the label, the position (i.e. the order in which the parameters are presented), the maxLength attribute etc.


Objects

Here are the structures of objects that are created as a result of the download operation.

 checking-ILS

Account Record

{

        //required fields

type : "checking-ILS",                 //see account type list
        number : string,                         //the account number

balance : numeric,                 //current balance of the account
        institute_code : numeric,        //see institute_code list
        branch : string,        

transactions : array,                 //see below

client_type  : string,                 //"private" || "business"

//optional fields
        credit_limit : numeric                 //the account credit limit (MISGERET)

}

Transaction Record

{

        //required fields

        date : string,                         //ISO 8601 syntax (YYYY-MM-DD)

credit : numeric,  

debit : numeric,  

        description : string,

        //optional fields

        value_date : string,                 //ISO 8601 syntax (YYYY-MM-DD)

        reference : string,                 //reference (אסמכתה) provided for the
                                                //transaction

        reference2 : string,                 //secondary reference if applicable
                                                //(for example a remark associated with
                                                //the transaction)

        balance : numeric,                 //per transaction account balance

transaction_type : string,        //the bank type of transaction

executing_branch : string,

executing_bank : string,

institute_transaction_id: string,

finanda_category_id : string         //(*)

}


 card

Notice the account and transaction objects are defined both for external credit company and for bank internal card.

Account Record - External Credit Company

{

        //required fields

type : "card",                                 //see account type list
        number : string,                                 //the card last 4 digits

next_ils_billing_sum : numeric,         //(**)the next billing sum for
                                                        //this card
        institute_code : numeric,                 //see institute_code list

credit_limit : numeric,                         

card_type : string,                         //credit card type

transactions : array,                        //see below

        //optional fields

card_type_finanda_code : string,         //unified card_type

        linked_bank : string,                         //linked - bank
        linked_bank_finanda_code : string,        //linked_bank unified to
                                                        //institute_code

        linked_branch : string,                         //linked branch

        linked_account : string,                 //linked account

next_ils_billing_date : string,         //ISO 8601 syntax (YYYY-MM-DD)
        next_eur_billing_sum : numeric,         //(
**) the next billing sum for
                                                        //this card
        next_eur_billing_date : string,         //ISO 8601 syntax (YYYY-MM-DD)
        next_usd_billing_sum : numeric,
         //(**) the next billing sum for
                                                        //this card

        next_usd_billing_date : string,         //ISO 8601 syntax (YYYY-MM-DD)
        credit_used : numeric,                         //how much of the credit_limit
                                                        //was already used
        credit_available : numeric,                 //how much of the credit_limit is
                                                        //still available

card_company : string,                         //card network brand
        card_club : string,                        //the club (MOADON) this card
                                                        //belongs to. ";" symbol will be

//used if there is more than one
        //club associated with the card

        card_club_finanda_code : string         //unified card_club

}

Transaction Record - External Credit Company

{

        //required fields

date : string,                         //ISO 8601 syntax (YYYY-MM-DD)

value_date : string,                 //ISO 8601 syntax (YYYY-MM-DD)

payee_name : string,                 //the payee name (vendor)
                                                //provided to the transaction

billing_currency : string,         //ISO 4217

billing_sum : numeric,

purchase_currency: string,         //ISO 4217

purchase_sum : numeric,

        //optional fields

reference : string,                 //reference provided by the site for
                                                //the transaction such as
                                                //voucher number, remark etc.

reference2 : string,                 //additional detail provided by
                                                //the site if applicable
        current_payment : numeric,        //the current payment number for
                                                //multiple payments deal

total_payments : numeric,        //the total payments number for
                                                //multiple payments deal

institute_transaction_id : string,

finanda_category_id : string         //(*)

}

Account Record - Bank Internal

{

        //required fields

type : "card",                                 //see account type list

parent_account: string,                        //the main ILS checking account
                                                        //to which it belongs
        number : string,                                 //the card last 4 digits

next_ils_billing_sum : numeric,         //(**)the next billing sum for
                                                        //this card
        transactions : array,                        //see below

        //optional fields

credit_limit : numeric,                         

card_type : string,                         //credit card type if applicable

card_type_finanda_code : string,         //unified card_type
        
card_company : string,                         //card network brand

next_ils_billing_date : string,         //ISO 8601 syntax (YYYY-MM-DD)
        next_eur_billing_sum : numeric,         //(
**) the next billing sum for
                                                        //this card
        next_eur_billing_date : string,         //ISO 8601 syntax (YYYY-MM-DD)
        next_usd_billing_sum : numeric,         //(
**) the next billing sum for
                                                        //this card
        next_usd_billing_date : string,         //ISO 8601 syntax (YYYY-MM-DD)
        credit_used : numeric,                         //how much of the credit_limit
                                                        //was already used
        credit_available : numeric,                 //how much of the credit_limit is
                                                        //still available
        card_club : string,                        //the club (MOADON) this card
                                                        //belongs to
        card_club_finanda_code,: string         //unified card_club

download_error : string                         //(***)

}

Transaction Record - Bank Internal

{

        //required fields

payee_name : string,                 //the payee name (vendor)
                                                //provided to the transaction

        //optional fields

date : string,                         //ISO 8601 syntax (YYYY-MM-DD)
        
billing_sum : numeric,

billing_currency : string,         //ISO 4217

value_date : string,                 //ISO 8601 syntax (YYYY-MM-DD)
        value_month : string,                 //in the format YYYY-MM (will be
                                                //available only if value_date is not
                                                //not specified by the site)

purchase_currency: string,         //ISO 4217

purchase_sum : numeric

reference : string,                 //reference provided by the site for
                                                //the transaction such as
                                                //voucher number, remark etc.

reference2 : string,                 //additional detail provided by the
                                                //site if applicable
        current_payment : numeric,        //the current payment number for
                                                //multiple payments deal

total_payments : numeric,        //the total payments number for
                                                //multiple payments deal

institute_transaction_id : string,

finanda_category_id : string         //(*)

}


 checking-foreign

Account Record

{

        //required fields

type : "checking-foreign",        //see account type list
        parent_account: string,                //the main ILS checking account to
                                                //which it belongs
        balance : numeric,                 //current balance of the account
        currency : string,                        //ISO 4217

        converted_balance : numeric,         //current ILS balance of the account

transactions : array                 //see below

//optional fields

number : string,                         //the account number

        credit_limit : numeric                 //the account credit limit (MISGERET)
        description : string,
        
institute_account_type : string,        //the institute account type

download_error : string                 //(***)

}

Transaction Record

{

        //required fields

        date : string,                 //ISO 8601 syntax (YYYY-MM-DD)

credit : numeric,  

debit : numeric,  

        description : string,

        //optional fields

        value_date : string,         //ISO 8601 syntax (YYYY-MM-DD)

        reference : string,         //reference (אסמכתה) provided for the
                                        //transaction

        reference2 : string,        //secondary reference if applicable (for
                                        //example a remark associated with the
                                        //transaction
)

        balance : numeric,         //account balance after applying transaction

transaction_type : string,        //the bank type of transaction

executing_branch : string,

executing_bank : string,

institute_transaction_id: string,

finanda_category_id : string         //(*)

}


 savings

Account Record

{

        //required fields

type : "savings",                         //see account type list
        parent_account: string,                //the main ILS checking account to
                                                //which it belongs

        
principal_balance : numeric,

currency : string,                 //ISO 4217

        //optional fields

saving_type : string,

end_date : string,                 //ISO 8601 syntax (YYYY-MM-DD)

origination_date : string,        //ISO 8601 syntax (YYYY-MM-DD)

saving_institute_id : string,        //ID used for this saving by the
                                                //institute
        description : string,                 //the saving textual description
        linkage_type : string,
        expected_end_value : numeric,
        upcoming_exit_date :
 string,         //ISO 8601 syntax (YYYY-MM-DD)
        
upcoming_exit_value : numeric,
        interest_type : string,
        interest_rate : numeric,
        interest_description : string,
        interest_calculation_description : string,
        adjusted_interest_rate : numeric,
        nominal_interest_rate : numeric,
        value : numeric,
        value_date : string,                 //ISO 8601 syntax (YYYY-MM-DD)
        payment_date_description : string,

objective_balance : numeric,

download_error : string                 //(***)

}


 loans

Account Record

{

        //required fields

type : "loans",                 //see account type list
        parent_account: string,        //the main ILS checking account to which it
                                        //belongs or "not-detailed" in case the site
                                        //does not specify this information
        l
oan_type : string,

        //optional fields

loan_institute_id : string,

sub_loans : array                 //see below
        loan_total : numeric,

interest_type : string,
        interest_rate : numeric,
        interest_description : string,
        adjusted_interest_rate : numeric,
        nominal_interest_rate : numeric,
        linkage_type : string,

origination_date : string,                //ISO 8601 syntax (YYYY-MM-DD)

upcoming_payment_sum : numeric,

upcoming_payment_date : string,         //ISO 8601 syntax (YYYY-MM-DD)

previous_payment_sum : numeric,

previous_payment_date : string,         //ISO 8601 syntax (YYYY-MM-DD)
        payment_date_description : string,

end_date : string,                         //ISO 8601 syntax (YYYY-MM-DD)
        balance : numeric,

principal_balance : numeric,
        currency : string,                         //ISO 4217

early_termination_fee : numeric,

upcoming_exit_date : string,                 //ISO 8601 syntax (YYYY-MM-DD)

debit_account : string,

loan_name : string,

value_date : string,                         //ISO 8601 syntax (YYYY-MM-DD)

download_error : string                         //(***)

}

Sub Loan Record

{

//required fields
        loan_institute_id : string,

//optional fields

loan_type : string,

loan_total : numeric,

interest_type : string,
interest_rate : numeric,

interest_description : string,
adjusted_interest_rate : numeric,
nominal_interest_rate : numeric,
linkage_type : string,

origination_date : string,                 //ISO 8601 syntax (YYYY-MM-DD)

upcoming_payment_sum : numeric,

upcoming_payment_date : string,         //ISO 8601 syntax (YYYY-MM-DD)

previous_payment_sum : numeric,

previous_payment_date : string,         //ISO 8601 syntax (YYYY-MM-DD)

payment_date_description : string,

end_date : string,                         //ISO 8601 syntax (YYYY-MM-DD)
balance : numeric,

principal_balance : numeric,
currency : string,                         //ISO 4217

early_termination_fee : numeric,

upcoming_exit_date : string,                 //ISO 8601 syntax (YYYY-MM-DD)

loan_name : string,
        value_date : string,                         //ISO 8601 syntax (YYYY-MM-DD)

}


 investments

Account Record

{

        //required fields

type : "investments",         //see account type list
        parent_account: string,        //the main ILS checking account to which it
                                        //belongs

total_value : numeric,

securities : array         //see below

//optional fields

securities_count : numeric,
total_value_change : numeric,

total_percents_change : numeric,
portfolio_id: string,

portfolio_daily_value_change : numeric,

portfolio_daily_percents_change : numeric,

download_error : string                //(***)

}

Portfolio Entry Record

{

//required fields

entry_id: string,

quantity : numeric,  

price : numeric,  

value : numeric,  

        //optional fields

purchase_price : numeric,  

        security_name : string,

        return_percents : numeric,

        return_sum : numeric,

daily_value_change : numeric,

daily_percents_change : numeric,

stock_exchange_name : string,

stock_exchange_code : string,

security_currency : string,        //ISO 4217

}


 Other

Message Record

{

//required fields

Type : "message"         //this is a message record

message : string         //informational message

}

Message records provide additional metadata information. Available messages:
business-account-removed One or more business accounts were removed from the download results

(*) Classification  is only supplied when initiateJob call specifies performClassification=true

(**) For various card types the next billing sum may be 0 even if there are transactions
(***) download_error : If defined, we have had a download error specific to this account - which is a child account of an ILS Checking account. The data downloaded for the parent account was downloaded properly as may be data for other child-accounts of the same ILS checking account. There was a download error for the data of this specific child account - and the error text is included.

Child accounts that are downloaded without a problem will not have the download_error field.

Predefined Values

 errorCode list

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 

 institute_code list

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 

 Account type list

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 

 card_company_finanda_code list

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 

 card_type_finanda_code list

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 

 card_club_finanda_code list

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 

 interest_type_finanda_code list

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 

 linkage_type_finanda_code list

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 

Best Practices

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 

 Wrong Credential Errors

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 

 Messages We Present In MyFinanda Upon An Error

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 

 Frequency of jobStatus Calls

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 

 About Using The Service During Night Time

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 

 Checking Institutes availability before downloading data

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 

Evaluating Finanda Smart Aggregation in the Sandbox

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 

Sample (Javascript)

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 

Finanda Smart Aggregation Assistant - Developer Utility

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 

Appendix A: Mapping Institutes Credentials to API Parameters

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 

Appendix B: Institutes Metadata

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 

Changelog

The content of this section is only available to Finanda Smart Aggregation registered users. For additional details visit our website www.finanda.com 


[1]Use getCredentialsSchema API to know how to send credentials for each institution

[2] Same as footnote (1) above

[3] Same as footnote (1) above

[4] Same as footnote (1) above

[5] A parent-account is an ILS checking account that might have child-accounts (such as foreign-accounts, investments, loans, savings etc…) associated with it. When we download for a specific ILS checking account - we will also download all the child-accounts associated with this checking account (assuming they are not omitted from the accountTypes parameter)