How to create notification rules and receive notifications

This article explains the details of how to create notification rules and what notifications will be sent by finAPI for the respective rules.

Preliminary Note: Push notifications are available only when your client is set up for an automatic batch update of your user's accounts.

Each notification triggered by a notification rule identifies itself via a callback handle. The callback handle is an ID of a notification rule that is provided by the client/user that creates the notification rule. It can be used for identifying an instance of a rule, e.g. with "Balance < 0".

There are different kinds of notification rules. The kind of a rule is depicted by the 'triggerEvent'.
The trigger event specifies what data you have to pass when creating a rule (specifically, the contents of the 'params' field), on which events finAPI will send notifications to your client application, as well as what data is contained in those notifications.

The specifics of the different trigger events are explained in the following.

triggerEvent = NEW_ACCOUNT_BALANCE
triggerEvent = NEW_TRANSACTIONS
triggerEvent = BANK_LOGIN_ERROR
triggerEvent = FOREIGN_MONEY_TRANSFER
triggerEvent = LOW_ACCOUNT_BALANCE
triggerEvent = HIGH_TRANSACTION_AMOUNT
triggerEvent = CATEGORY_CASH_FLOW
triggerEvent = NEW_TERMS_AND_CONDITIONS
Unique contraints / error messages

 
"triggerEvent = NEW_ACCOUNT_BALANCE" 

Rules with this trigger event cause finAPI to send notifications whenever the balance has changed for one or several of the user's bank accounts during an automatic update. The 'params' field is optional for this kind of rule. If not specified, then it means that finAPI will send a (single) notification message to your client application when at least one of the user's accounts has a new balance as a result of the automatic update. The message will contain data about each account where the balance has changed (details on what the message looks like below). If you do specify the 'params' field, then it must represent the following JSON object:

{
   "accountIds": String
}

The 'accountIds' field can contain a string of one or more (comma-separated) identifiers of the user's accounts. The effect of specifying this field is that finAPI will send a (single) notification message only when one or several of the specified accounts got a new balance as a result of the automatic update. If the balance changed for only other accounts which you did not specify in the parameter, then no notification will be sent. Note that when you want to receive separate notifications for the individual accounts, you would have to create several rules, each having another account identifier specified in the 'accountIds' field.

The notification messages that finAPI will send based on this kind of rule will look like this:

{
    "notificationRuleId": Number,
    "triggerEvent": "NEW_ACCOUNT_BALANCE",
    "callbackHandle": String,
    "balanceChanges": [{
"accountId":Number, "accountName": String, // encrypted "accountNumber": String, // encrypted "accountIban": String, // encrypted "bankName": String,
"bankConnectionName": String, // encrypted "details":String
}, ...]
}

• balanceChanges contains an item for each account where the balance changed
• details will only be set if the rule was created with includeDetails=true. In this case, it will contain an encrypted string that you will have to decrypt using your client's data decryption key, and which will - once decrypted - represent the following JSON object:

{
    "accountNumber": String,
    "iban": String,
    "accountName": String,
"bankConnectionName": String, "oldBalance": Number, "newBalance": Number, "balanceChange": Number }

to the top



triggerEvent = NEW_TRANSACTIONS

Rules with this trigger event cause finAPI to send notifications whenever new transactions have been downloaded for one or several of the user's bank accounts during an automatic update. The 'params' field is optional for this kind of rule. If notspecified, then it means that finAPI will send a (single) notification message to your client application when at least one of the user's accounts has new transactions as a result of the automatic update. The message will contain data about each account that has new transactions (details on what the message looks like below). If you do specify the 'params' field, then it must represent the following JSON object:

{
    "accountIds": String,
    "maxTransactionsCount": Number
}

The 'accountIds' field can contain a string of one or more (comma-separated) identifiers of the user's accounts. The effect of specifying this field is that finAPI will send a (single) notification message only when one or several of the specified accounts got new transactions as a result of the automatic update. If new transactions were download only for other accounts which you did not specify in the parameter, then no notification will be sent. Note that when you want to receive separate notifications for the individual accounts, you would have to create several rules, each having another account identifier specified in the 'accountIds' field. The 'maxTransactionsCount' field specifies how many of the new transactions should be included at most in the notification message (this is only relevant if you create the rule with includeDetails=true). The field can have a value between 0 and 100, and defaults to 100 if not specified.

The notification messages that finAPI will send based on this kind of rule will look like this:

{
    "notificationRuleId": Number,
    "triggerEvent": "NEW_TRANSACTIONS",
    "callbackHandle": String,
    "newTransactions": [{
        "accountId": Number,
        "accountName": String, // encrypted
        "accountNumber": String, // encrypted
        "accountIban": String, // encrypted 
        "bankName": String,
"bankConnectionName": String, // encrypted "newTransactionsCount": Number, "details": String }, ... ] }

• newTransactions contains an item for each account that got new transactions

• accountName: Contains an encrypted string that you will have to decrypt using your client's data decryption key.

• accountNumber: Contains an encrypted string that you will have to decrypt using your client's data decryption key.

• bankConnectionName: Contains an encrypted string that you will have to decrypt using your client's data decryption key.

• accountIban: Contains an encrypted string that you will have to decrypt using your client's data decryption key. Field may be null.

• details will only be set if the rule was created with includeDetails=true. In this case, it will contain an encrypted string that you will have to decrypt using your client's data decryption key, and which will - once decrypted - represent the following JSON object:

{
    "transactionDetails": [{
        "id": Number,
        "finapiBookingDate": String,
        "bankBookingDate": String,
        "amount": Number,
        "counterpartName": String,
        "purpose": String,
"isAdjustingEntry": Boolean // since finAPI v1.30.0
}, ... ] }

The 'transactionDetails' field contains a list of the new transactions (at most 'maxTransactionsCount'), each with its details. The transactions are ordered by bankBookingDate, descending.

to the top


triggerEvent = BANK_LOGIN_ERROR

Rules with this trigger event cause finAPI to send notifications whenever the automatic update could not update one or several of the user's bank connections because the login at the bank server failed. The 'params' field is optional for this kind of rule. If not specified, then it means that finAPI will send a (single) notification message to your client application when at least one of the user's bank connections could not get updated in the automatic update. The message will contain data about each bank connection that could not get updated (details on what the message looks like below). If you do specify the 'params' field, then it must represent the following JSON object:

{
    "bankConnectionIds": String
}

The 'bankConnectionIds' field must contain a string of one or more (comma-separated) identifiers of the user's bank connections. The effect of specifying this field is that finAPI will send a (single) notification message only when one or several of the specified connections could not get updated in the automatic update. If the update failed only for other connections which you did not specify in the parameter, then no notification will be sent. Note that when you want to receive separate notifications for the individual bank connections, you would have to create several rules, each having another bank connection identifier specified in the 'bankConnectionIds' field.

The notification messages that finAPI will send based on this kind of rule will look like this:

{
    "notificationRuleId": Number,
    "triggerEvent": "BANK_LOGIN_ERROR",
    "callbackHandle": String,
    "loginErrors": [{
        "bankConnectionId": Number,
        "bankName": String,
"bankConnectionName": String, // encrypted
"errorCode": String, "details": String }, ... ] }

• loginErrors contains an item for each bank connection where the login failed
• errorCode will either be "WRONG_CREDENTIALS", which means that the login failed because the stored credentials of the bank connection are incorrect, or it will not be set at all, which means that login failed for an unknown reason (e.g. timeout to the bank server or other technical problems)
• details will only be set if the rule was created with includeDetails=true. In this case, it will contain an encrypted string that you will have to decrypt using your client's data decryption key, and which will - once decrypted - represent the following JSON object:

{
    "errorMessage": String
}

The 'errorMessage' field contains the error message that the bank server sent when denying the login.

to the top



triggerEvent = FOREIGN_MONEY_TRANSFER

Rules with this trigger event cause finAPI to send notifications whenever new outgoing foreign transactions have been imported during an automatic update. An outgoing foreign transaction is a transaction where:
• the amount is negative
• the counterpart IBAN depicts a bank from a different country than the source account's bank
The 'params' field is optional for this kind of rule. If not specified, then it means that finAPI will send a (single) notification message to your client application when at least one of the user's accounts has a new outgoing foreign transaction after an automatic update. The message will contain data for each account where new outgoing foreign transactions were downloaded (details on what the message looks like below). If you do specify the 'params' field, then it must represent the following JSON object:

{
    "accountIds": String
}

The 'accountIds' field can contain a string of one or more (comma-separated) identifiers of the user's accounts. The effect of specifying this field is that finAPI will send a (single) notification message only when one or several of the specified accounts got new outgoing foreign transactions as a result of the automatic update. If new such transactions were received for only other accounts which you did not specify in the parameter, then no notification will be sent. Note that when you want to receive separate notifications for the individual accounts, you would have to create several rules, each having another account identifier specified in the 'accountIds' field.

The notification messages that finAPI will send based on this kind of rule will look like this:

{
    "notificationRuleId": Number,
    "triggerEvent": "FOREIGN_MONEY_TRANSFER",
    "callbackHandle": String,
    "newTransactions": [{
        "accountId": Number,
        "accountName": String, // encrypted
        "accountNumber": String, // encrypted
        "accountIban": String, // encrypted
        "bankName": String,
"bankConnectionName": String, // encrypted "transactionsCount": Number, "details": String }, ... ] }

• newTransactions contains an item for each account where at least one new outgoing foreign transaction has been imported

• accountName: Contains an encrypted string that you will have to decrypt using your client's data decryption key.

• accountNumber: Contains an encrypted string that you will have to decrypt using your client's data decryption key.

• accountIban: Contains an encrypted string that you will have to decrypt using your client's data decryption key. Field may be null.

• bankConnectionName: Contains an encrypted string that you will have to decrypt using your client's data decryption key. Field may be null.

• transactionsCount contains the number of new outgoing foreign transactions for the respective account

• details will only be set if the rule was created with includeDetails=true. In this case, it will contain an encrypted string that you will have to decrypt using your client's data decryption key, and which will - once decrypted - represent the following JSON object:

{
"transactionDetails": [
{
"id": Number, "finapiBookingDate": String, "bankBookingDate": String, "amount": BigDecimal, "counterpartName": String, "counterpartAccountNumber": String, "counterpartIban": String, "counterpartBlz": String, "counterpartBic": String, "purpose": String
},...
]
}

 

to the top


triggerEvent = LOW_ACCOUNT_BALANCE

Rules with this trigger event cause finAPI to send notifications whenever account's balance drops below the given balanceThreshold during an automatic update. The 'params' field is required for this kind of rule. It may contain two nested fields: 'accountIds' (optional) and 'balanceThreshold' (required). If the 'accountIds' is not specified, then finAPI will send a (single) notification message to your client application when at least one of user's accounts got a new balance, that is lower than the given 'balanceThreshold'. Field 'balanceThreshold' is required. If the account's balance drops below the value of this parameter, notification will be sent. The message will contain data about each account where the balance drops below the balanceThreshold (details on what the message looks like below). If you do specify the 'params' field, then it must represent the following JSON object:

{
    "accountIds": String,
    "balanceThreshold": BigDecimal
}

The 'accountIds' field can contain a string of one or more (comma-separated) identifiers of the user's accounts. The effect of specifying this field is that finAPI will send a (single) notification message only when one or several of the specified accounts got a balance below the given balanceThreshold as a result of the automatic update. If such a balance has received for only other accounts which you did not specify in the parameter, then no notification will be sent. Note that when you want to receive separate notifications for the individual accounts, you would have to create several rules, each having another account identifier specified in the 'accountIds' field.

The notification messages that finAPI will send based on this kind of rule will look like this:

{
    "notificationRuleId": Number,
    "triggerEvent": "LOW_ACCOUNT_BALANCE",
    "callbackHandle": String,
    "balanceThreshold": BigDecimal,
    "balanceChanges": [{
        "accountId":Number,
        "accountName": String, // encrypted
        "accountNumber": String, // encrypted
        "accountIban": String, // encrypted
        "bankName": String,  
"bankConnectionName": String, // encrypted "details":String }, ...] }

• balanceThreshold contains the value, that was set during notification rule creation
• balanceChanges contains an item for each account where the balance changed

• accountName: Contains an encrypted string that you will have to decrypt using your client's data decryption key.

• accountNumber: Contains an encrypted string that you will have to decrypt using your client's data decryption key.

• accountIban: Contains an encrypted string that you will have to decrypt using your client's data decryption key. Field may be null.

• bankConnectionName: Contains an encrypted string that you will have to decrypt using your client's data decryption key. Field may be null.

• details will only be set if the rule was created with includeDetails=true. In this case, it will contain an encrypted string that you will have to decrypt using your client's data decryption key, and which will - once decrypted - represent the following JSON object:

{
    "accountNumber": String,
    "iban": String,
    "accountName": String,
"bankConnectionName": String, "oldBalance": Number, "newBalance": Number, "balanceChange": Number }

to the top 


triggerEvent = HIGH_TRANSACTION_AMOUNT

Rules with this trigger event cause finAPI to send notifications whenever a new transaction with an absolute amount higher than or equals to the given 'absoluteAmountThreshold' have been imported during an automatic update. The 'params' field is required for this kind of rule. It may contain three nested fields: 'accountIds' (optional), 'absoluteAmountThreshold' (required) and 'maxTransactionsCount' (optional). If 'accountIds' is not specified, then finAPI will send a (single) notification message to your client application when at least one of the user's accounts have new transactions with an absolute amount higher than or equal to the given 'absoluteAmountThreshold'. If the absolute transaction's amount is higher than or equals to the 'absoluteAmountThreshold' then this transaction will be included into the notification details (if details are enabled for the rule). The 'maxTransactionsCount' field specifies how many of the transactions should be included at most in the notification message (this is only relevant if you create the rule with includeDetails=true). The field can have a value between 0 and 100, and defaults to 100 if not specified. The message will contain data about each account that got a transaction with an absolute amount higher than or equal to the given 'absoluteAmountThreshold' (details on what the message looks like below). The 'params' field must represent the following JSON object:

{
    "accountIds": String,
    "absoluteAmountThreshold": BigDecimal,
    "maxTransactionsCount": Number
}

The 'accountIds' field can contain a string of one or more (comma-separated) identifiers of the user's accounts. The effect of specifying this field is that finAPI will send a (single) notification message only when one or several of the specified accounts got new transactions with the above described criteria as a result of the automatic update. If such transactions have been received only for other accounts which you did not specify in the parameter, then no notification will be sent. Note that when you want to receive separate notifications for the individual accounts, you would have to create several rules, each having another account identifier specified in the 'accountIds' field.

The notification messages that finAPI will send based on this kind of rule will look like this:

{
    "notificationRuleId": Number,
    "triggerEvent": "HIGH_TRANSACTION_AMOUNT",
    "callbackHandle": String,
    "absoluteAmountThreshold": BigDecimal,
    "newTransactions": [{
        "accountId":Number,
        "accountName": String, // encrypted
        "accountNumber": String, // encrypted
        "accountIban": String, // encrypted
        "bankName": String,  
"bankConnectionName": String, // encrypted "newTransactionsCount": Number, "details": String }, ...] }

• absoluteAmountThreshold contains the value, that was set during the notification rule creation
• newTransactions contains an item for each account where new transactions have been imported which apply to the given criteria

• accountName: Contains an encrypted string that you will have to decrypt using your client's data decryption key.

• accountNumber: Contains an encrypted string that you will have to decrypt using your client's data decryption key.

• accountIban: Contains an encrypted string that you will have to decrypt using your client's data decryption key. Field may be null.

• bankConnectionName: Contains an encrypted string that you will have to decrypt using your client's data decryption key. Field may be null.

• details will only be set if the rule was created with includeDetails=true. In this case, it will contain an encrypted string that you will have to decrypt using your client's data decryption key, and which will - once decrypted - represent the following JSON object:

{
    "transactionDetails": [{
        "id": Number,
        "finapiBookingDate": String,
        "bankBookingDate": String,
        "amount": Number,
        "counterpartName": String,
        "purpose": String,
"isAdjustingEntry": Boolean // since finAPI v1.30.0
}, ... ] }

 

to the top


triggerEvent = CATEGORY_CASH_FLOW

Rules with this trigger event cause finAPI to send notifications whenever new transactions have been downloaded during an automatic update that have been categorized with a certain category. The 'params' field defines three fields: 'accountIds' (optional), 'categoryId' (required), and 'includeChildCategories' (optional). If 'accountIds' is not specified, then it means that finAPI will send a (single) notification message to your client application when at least one of the user's accounts has new transactions that have been categorized with the specified category. The message will contain data about each account that has new categorized transactions (details on what the message looks like below). The 'params' field must represent the following JSON object:

{
   "accountIds":String, // optional
   "categoryId":String,
   "includeChildCategories":Boolean // optional
}


If specified, the 'accountIds' field can contain a string of one or more (comma-separated) identifiers of the user's accounts. The effect of specifying this field is that finAPI will send a (single) notification message only when one or several of the specified accounts got new transactions that have been categorized with the specified category as a result of the automatic update. If new transactions were categorized only for other accounts which you did not specify in the parameter, then no notification will be sent. Note that when you want to receive separate notifications for the individual accounts, you would have to create several rules, each having another account identifier specified in the 'accountIds' field.
The 'categoryId' field specifies which category you want the notifications to be based on. With the field 'includeChildCategories' you can specify whether you want to get notified only about transactions with the exact category that you have specified (includeChildCategories=false), or whether you also want to get notified about transactions whose category is a sub-category of the specified category (includeChildCategories=true). If not specified, the default value of the includeChildCategories flag is 'true'. Note that if the specified categoryId already represents a sub-category, then the includeChildCategories field has no effect (as sub-categories cannot have further sub-categories).

The notification messages that finAPI will send based on this kind of rule will look like this:

{
   "notificationRuleId":Number,
   "triggerEvent":"CATEGORY_CASH_FLOW",
   "callbackHandle":String,
   "categoryId":Number,
   "categoryName":String,
   "includeChildCategories":Boolean,
   "categoryCashFlows":[
      {
        "accountId":Number,
        "accountName": String, // encrypted
        "accountNumber": String, // encrypted
        "accountIban": String, // encrypted
        "bankName": String, 
"bankConnectionName": String, // encrypted "details":String } ,... ] }

 
• categoryId is the specified category identifier.

• includeChildCategories depicts whether this notification may contain transactions of sub-categories of the specified category.

• categoryName will only be set if the rule was created with includeDetails=true, and will in this case contain the name of the specified category as an encrypted string that you must decrypt using your client's data decryption key.

• categoryCashFlows contains an item for each account that got new transactions that have been categorized with the specified category.

• accountName: Contains an encrypted string that you will have to decrypt using your client's data decryption key.

• accountNumber: Contains an encrypted string that you will have to decrypt using your client's data decryption key.

• accountIban: Contains an encrypted string that you will have to decrypt using your client's data decryption key. Field may be null.

• bankConnectionName: Contains an encrypted string that you will have to decrypt using your client's data decryption key. Field may be null.

• details will only be set if the rule was created with includeDetails=true. In this case, it will contain an encrypted string that you will have to decrypt using your client's data decryption key, and which will - once decrypted - represent the following JSON object:

 

{
   "transactions":[
      {
         "id":Number,
         "categoryId":Number,
         "categoryName":String,
         "finapiBookingDate":String,
         "bankBookingDate":String,
         "amount":Number,
         "counterpartName":String,
         "purpose":String
      }
      ,...
   ]
}

The 'transactions' field contains a list of the new transactions that have been categorized with the specified category (or one of its sub-categories, if the 'includeChildCategories' flag is 'true'), each with its details. The transactions are ordered by bankBookingDate, descending.

 

to the top 


triggerEvent = NEW_TERMS_AND_CONDITIONS

Rules with this trigger event cause finAPI to send notifications whenever finAPI's automatic batch update detects that it cannot update the bank connections of a user because there are new terms and conditions that the user has not yet accepted. This kind of rule does not specify any additional 'params' or 'details'.

The notification messages that finAPI will send based on this kind of rule will look like this:

{
    "notificationRuleId": Number,
    "triggerEvent": "NEW_TERMS_AND_CONDITIONS",
    "callbackHandle": String
}

 


Unique contraints / error messages

The 'params' field is an optional field which you can use to specify one or more accountIds or bankConnectionIds. 
The accountIds / bankConnectionIds field is unique meaning you can´t create one trigger event more than once for the same parameters (exception: trigger event CATEGORY_CASH_FLOW, see below).
If you try to create a second notification rule with the same parameters an error message is shown "Notification rule with given parameters already exists."

The accountIds field is unique for the following trigger events:

  • NEW_ACCOUNT_BALANCE
  • NEW_TRANSACTIONS
  • FOREIGN_MONEY_TRANSFER
  • LOW_ACCOUNT_BALANCE
  • HIGH_TRANSACTION_AMOUNT
  • for trigger event CATEGORY_CASH_FLOW the accountIds field is unique in combinition with one categoryId (surely you can create several CATEGORY_CASH_FLOW notification rules for one account with several categoryIds)

The bankConnectionIds field is unique for the following trigger event:

  • BANK_LOGIN_ERROR

 

Please note that it is still possible to have more than one rule for one account.
Here is an example:

  • Creation of a trigger event "NEW_ACCOUNT_BALANCE" without any parameters.
  • Creation of a 2nd trigger event "NEW_ACCOUNT_BALANCE" with one specified accountId (123)
  • Creation of a 3rd trigger event "NEW_ACCOUNT_BALANCE" with two specified accountIds (123, 124)
  • All trigger events are created
  • -> whenever the balance changes for accountId 123 three notifications are sent!
    There is no priority setting or overwriting of rules!

 

to the top

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk