Recurrence service
The Recurrence service is intended to detect recurrent expenses\incomes. Among other things this covers:
- Contract (rent, energy, telephone, internet, water, etc.)
- Insurance (medical, home, liability, travel, life, etc.)
- Subscriptions (streaming services, newspapers, magazines, etc.)
- Contributions (sports, associations, school fees, etc.)
- Taxes and charges (sewage costs, etc.)
- Customer-to-customer (money transfers, etc.)
- Income (salary, etc.)
Recurrence integration into Convert
Recurrence can be enabled on /convert by using the IncludeRecurrence flag in the headers of the request.
When set to true the Recurrence algorithm will be executed on the given transaction batch.
The Recurrence algorithm will only be executed if the Customer has the module enabled for Recurrence (Id 28).
When the IncludeRecurrence flag is enabled it will add 3 properties to each transaction that are recurrent:
-
RecurrenceSequence=> In which sequence the recurrence belongs in -
RecurrenceInterval=> Is a number that states how often it occurs in a given time period -
RecurrenceType=> The type of recurrence. The possible values are:-
0 => None
-
1 => Second
-
2 => Minute
-
3 => Hour
-
4 => Day
-
5 => Week
-
6 => Month
-
7 => Quarter
-
8 => Semester
-
9 => Year
-
So for example if a transaction has a RecurrenceInterval of 3 and a RecurrenceType of 6 it means the transaction reoccurs every 3 months.
When the recurrence succeeds a Quota event will be generated to indicate that the customer used the IncludeRecurrence flag.
Calling the Recurrence Service
Endpoint: https://linx.invers.nl:8100/api/linx/recurrence
Method: POST
Header: ApiKey: string (required)
X-Request-ID: string (required)
ClientId: string (optional)
InputHash: string (optional)
Options: int (optional) (default = 33)
Body: Data: byte[] (required)
Errors: 400, 403 or 500
Information
| Field | Type | Description |
|---|---|---|
| AccountsCount | Integer | Accounts count |
| Accounts | Array of AccountGroup | List of recurrence/anomaly categories grouped by accounts |
| Overview | FinancialOverview | Short financial overview about detected recurrences for all accounts |
FinancialOverview
| Field | Type | Description |
|---|---|---|
| TotalRecurrenceCategoriesCount | Integer | Recurrence categories count |
| TotalTypicalRecurrenceCategoriesCount | Integer | Typical recurrence categories count |
| TotalAtypicalRecurrenceCategoriesCount | Integer | Atypical recurrence categories count |
| TotalRecurrenceBeneficiaryGroupsCount | Integer | Recurrence groups count |
| TotalTypicalRecurrenceBeneficiaryGroupsCount | Integer | Typical recurrence groups count |
| TotalAtypicalRecurrenceBeneficiaryGroupsCount | Integer | Atypical recurrence groups count |
| TotalRecurrenceTransactionsCount | Integer | Recurrence transactions count |
| TotalTypicalRecurrenceTransactionsCount | Integer | Typical recurrence transactions count |
| TotalAtypicalRecurrenceTransactionsCount | Integer | Atypical recurrence transactions count |
| AnomaliesTransactionsCount | Integer | Anomaly transactions count |
| TotalRecurrenceIncome | Decimal | Total recurrence income |
| TotalRecurrenceExpense | Decimal | Total recurrence expense |
| TotalTypicalRecurrenceIncome | Decimal | Typical total recurrence income |
| TotalAtypicalRecurrenceIncome | Decimal | Atypical total recurrence income |
| TotalTypicalRecurrenceExpense | Decimal | Typical total recurrence exepense |
| TotalAtypicalRecurrenceExpense | Decimal | Atypical total recurrence expense |
| AverageMonthlyRecurrenceIncome | Decimal | Average recurrence income |
| AverageMonthlyRecurrenceExpense | Decimal | Average recurrence expense |
| AverageMonthlyTypicalRecurrenceIncome | Decimal | Typical average recurrence income |
| AverageMonthlyAtypicalRecurrenceIncome | Decimal | Atypical average recurrence income |
| AverageMonthlyTypicalRecurrenceExpense | Decimal | Typical average recurrence expense |
| AverageMonthlyAtypicalRecurrenceExpense | Decimal | Atypical average recurrence expense |
AccountGroup
| Field | Type | Description |
|---|---|---|
| Account | Account | Information about the account |
| Overview | FinancialOverview | Short financial overview about detected recurrences for this account |
| TypicalRecurrences | Array of CategoryGroups | List of typical recurrence categories for this account |
| AtypicalRecurrences | Array of CategoryGroups | List of atypical recurrence categories for this account |
| Anomalies | Array of CategoryGroups | List of anomaly categories for this account |
CategoryGroup
| Field | Type | Description |
|---|---|---|
| CategoryId | Integer | Category ID (when categorized) |
| CategoryName | String | Category name (when categorized) |
| ContractsCount | Integer | Contracts count for this category |
| TransactionsCount | Integer | Transactions count for this category |
| TotalAmount | Decimal | Total currency amount for this category |
| MonthlyAmount | Decimal | Monthly currency amount for this category |
| Contracts | Array of BeneficiaryGroups | List of contracts for this category |
BeneficiaryGroup
| Field | Type | Description |
|---|---|---|
| Beneficiary | Beneficiary | Information about the beneficiary |
| RecurrenceProperties | RecurrenceProperties | Recurrence properties (when recurrent) |
| TotalAmount | Decimal | Total currency amount for this contract |
| MonthlyAmount | Decimal | Monthly currency amount for this contract |
| FirstTransactionDate | DateTime | Earliest transaction date for this contract |
| LastTransactionDate | DateTime | Latest transaction date for this contract |
| TransactionsCount | Integer | Transactions count for this contract |
| Transactions | Array of Transactions | List of transactions for this contract |
Account
| Field | Type | Description |
|---|---|---|
| Country | String | Account's country |
| Name | String | Account's name |
| OriginalName | String | Account's original name |
| Identifier | String | Account's identifier |
| DenominationId | Integer | Account's denomination ID (when available) |
| SwiftCode | String | Account's Swift code |
| Bank | String | Account's bank |
| Number | String | Account's number |
| Formatted | String | Formatted account's number |
| IBan | String | Account's IBAN |
| BeginBalanceDate | DateTime | Beggining balance date (when available) |
| BeginBalance | Decimal | Beginning balance (when available) |
| EndBalanceDate | DateTime | Ending balance date (when available) |
| EndBalance | Decimal | Ending balance (when available) |
Beneficiary
| Field | Type | Description |
|---|---|---|
| Country | String | Beneficiary's country |
| Name | String | Beneficiary's name |
| OriginalName | String | Beneficiary's original name |
| Identifier | String | Beneficiary's identifier |
| DenominationId | Integer | Beneficiary's denomination ID (when available) |
RecurrenceProperties
| Field | Type | Description |
|---|---|---|
| Quality | Double | Quality of the result between 0 and 1 |
| PeriodUnit | Enum | None Month Quarter Semester Year |
| Period | Integer | Number of period units |
Transaction
| Field | Type | Description |
|---|---|---|
| BookDate | DateTime | Transaction's book date |
| InterestDate | DateTime | Transaction's interest date |
| TransactionDate | DateTime | Transaction's date |
| Amount | Decimal | Transaction's amount |
| Description | String | Transaction's description |
| OriginalDescription | String | Transaction's original description from the bank |
| ExternalTransactionId | String | Transaction's original ID from the bank |
Output (example)
{
"accountsCount": 1,
"accounts": [
{
"account": {
"country": "string",
"number": "string",
"formatted": "string",
"iBan": "string",
"beginBalanceDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
"beginBalance": 0.0,
"endBalanceDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
"endBalance": 0.0
},
"overview": {
"totalRecurrenceCategoriesCount": 1,
"totalTypicalRecurrenceCategoriesCount": 1,
"totalAtypicalRecurrenceCategoriesCount": 1,
"totalRecurrenceBeneficiaryGroupsCount": 1,
"totalTypicalRecurrenceBeneficiaryGroupsCount": 1,
"totalAtypicalRecurrenceBeneficiaryGroupsCount": 1,
"totalRecurrenceTransactionsCount": 1,
"totalTypicalRecurrenceTransactionsCount": 1,
"totalAtypicalRecurrenceTransactionsCount": 1,
"anomaliesTransactionsCount": 1,
"totalRecurrenceIncome": 0.0,
"totalRecurrenceExpense": 0.0,
"totalTypicalRecurrenceIncome": 0.0,
"totalAtypicalRecurrenceIncome": 0.0,
"totalTypicalRecurrenceExpense": 0.0,
"totalAtypicalRecurrenceExpense": 0.0,
"averageMonthlyRecurrenceIncome": 0.0,
"averageMonthlyRecurrenceExpense": 0.0,
"averageMonthlyTypicalRecurrenceIncome": 0.0,
"averageMonthlyAtypicalRecurrenceIncome": 0.0,
"averageMonthlyTypicalRecurrenceExpense": 0.0,
"averageMonthlyAtypicalRecurrenceExpense": 0.0
},
"typicalRecurrences": [
{
"categoryId": 1,
"categoryName": "string"
"beneficiaryGroupsCount": 1,
"transactionsCount": 1,
"totalAmount": 0.0,
"averageMonthlyAmount": 0.0,
"beneficiaryGroups": [
{
"beneficiary": {
"country": "string",
"name": "string",
"originalName": "string"
},
"recurrenceProperties": {
"quality": 1.0,
"periodUnit": "year",
"period": 1
},
"totalAmount": 0.0,
"averageMonthlyAmount": 0.0,
"firstTransactionDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
"lastTransactionDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
"transactionsCount": 1,
"transactions": [
{
"bookDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
"interestDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
"transactionDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
"amount": 0.0,
"description": "string",
"originalDescription": "string"
}
]
}
]
}
],
"atypicalRecurrences": [
{
"categoryId": 1,
"categoryName": "string"
"beneficiaryGroupsCount": 1,
"transactionsCount": 1,
"totalAmount": 0.0,
"averageMonthlyAmount": 0.0,
"beneficiaryGroups": [
{
"beneficiary": {
"country": "string",
"name": "string",
"originalName": "string"
},
"recurrenceProperties": {
"quality": 1.0,
"periodUnit": "year",
"period": 1
},
"totalAmount": 0.0,
"averageMonthlyAmount": 0.0,
"firstTransactionDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
"lastTransactionDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
"transactionsCount": 1,
"transactions": [
{
"bookDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
"interestDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
"transactionDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
"amount": 0.0,
"description": "string",
"originalDescription": "string"
}
]
}
]
}
],
"anomalies": [
{
"categoryId": 1,
"categoryName": "string"
"beneficiaryGroupsCount": 1,
"transactionsCount": 1,
"totalAmount": 0.0,
"averageMonthlyAmount": 0.0,
"beneficiaryGroups": [
{
"beneficiary": {
"country": "string",
"name": "string",
"originalName": "string"
},
"totalAmount": 0.0,
"averageMonthlyAmount": 0.0,
"firstTransactionDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
"lastTransactionDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
"transactionsCount": 1,
"transactions": [
{
"bookDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
"interestDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
"transactionDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
"amount": 0.0,
"description": "string",
"originalDescription": "string"
}
]
}
]
}
]
}
],
"overview": {
"totalRecurrenceCategoriesCount": 1,
"totalTypicalRecurrenceCategoriesCount": 1,
"totalAtypicalRecurrenceCategoriesCount": 1,
"totalRecurrenceBeneficiaryGroupsCount": 1,
"totalTypicalRecurrenceBeneficiaryGroupsCount": 1,
"totalAtypicalRecurrenceBeneficiaryGroupsCount": 1,
"totalRecurrenceTransactionsCount": 1,
"totalTypicalRecurrenceTransactionsCount": 1,
"totalAtypicalRecurrenceTransactionsCount": 1,
"anomaliesTransactionsCount": 1,
"totalRecurrenceIncome": 0.0,
"totalRecurrenceExpense": 0.0,
"totalTypicalRecurrenceIncome": 0.0,
"totalAtypicalRecurrenceIncome": 0.0,
"totalTypicalRecurrenceExpense": 0.0,
"totalAtypicalRecurrenceExpense": 0.0,
"averageMonthlyRecurrenceIncome": 0.0,
"averageMonthlyRecurrenceExpense": 0.0,
"averageMonthlyTypicalRecurrenceIncome": 0.0,
"averageMonthlyAtypicalRecurrenceIncome": 0.0,
"averageMonthlyTypicalRecurrenceExpense": 0.0,
"averageMonthlyAtypicalRecurrenceExpense": 0.0
}
}