general
Overview
Salt Edge developed Data Enrichment Platform as part of Open Banking Gateway to help our clients deliver better products based on complex financial analysis, and thus improving the user experience, decreasing operational costs, and increasing the client base.
Data Enrichment Platform consists of the following components:
- Transaction Categorization API for assigning a category to personal and business transactions;
- Merchant Identification API for determining the merchant from the cluttered transaction description and providing detailed info on the identified merchant;
- Financial Insights - a report generated based on bank data using complex algorithms, provides institutions with financial behaviour profiles of their potential customers.
Errors
The API can return multiple errors for any operation, each having its meaning and usage.
Error attributes
class
string
The class of the error, one of the listed below
message
string
A message describing the error
documentation_url
string
A link for error documentation
request
object
The body of the request that caused the error
class
string
The class of the error, one of the listed below
message
string
A message describing the error
documentation_url
string
A link for error documentation
request
object
The body of the request that caused the error
Error codes
[400] Bad Request
[404] Not Found
[406] Not Acceptable
[409] Duplicated
[429] Too Many Requests
Sample response
{
"error": {
"class": "BatchSizeLimitExceeded",
"message": "Batch size limit (100 transactions) was exceeded.",
"documentation_url": "https://docs.saltedge.com/data_enrichment/v5/#errors-batch_size_limit_exceeded"
},
"request": {
}
}
List
ActionNotAllowed
The client has no access to the required route or direct API access is not permitted.
BatchSizeLimitExceeded
More than 100 objects were sent in the request (100 is the limit)
CategorizationLimitReached
One client can categorize at most 1000 transactions per day (only for Pending/Test clients)
ClientDisabled
The client has been disabled. You can find out more about the disabled status on Disabled guides page
ClientNotFound
The API key used in the request does not belong to a client
InternalServerError
An internal error has occurred
JsonParseError
We have received some other request format instead of JSON, or the body could not be parsed
WrongRequestFormat
The JSON request is sent in incorrect format
ActionNotAllowed
The client has no access to the required route or direct API access is not permitted.
BatchSizeLimitExceeded
More than 100 objects were sent in the request (100 is the limit)
CategorizationLimitReached
One client can categorize at most 1000 transactions per day (only for Pending/Test clients)
ClientDisabled
The client has been disabled. You can find out more about the disabled status on Disabled guides page
ClientNotFound
The API key used in the request does not belong to a client
InternalServerError
An internal error has occurred
JsonParseError
We have received some other request format instead of JSON, or the body could not be parsed
WrongRequestFormat
The JSON request is sent in incorrect format
api
Transaction Categorization
Salt Edge API automatically categorizes all the transactions. Thus, when importing a connection, all the transactions corresponding to the connection will be assigned to one of the categories.
There are 2 types of categories: personal categories and business categories, which help to categorize transactions, made by physical persons or legal entities.
The categories are represented as strings.
They are structured as parent and child categories, which can be identified by the tree structure sent in the Listing categories request.
You can test the categorization, using the fakebank_with_file_csv_xf provider. Fill out the predefined sample.csv template. The file size limit is 5MB.
Note: Country and Account Currency defaults to GB and GBP respectively. In order to test the transaction categorization in other countries, the two codes must be configured accordingly.
How to use
By default, transactions are categorized, using the list of personal categories, via parameter categorization set on routes: connections #create, #refresh, #reconnect or connect sessions #create, #refresh, #reconnect, as you need.
We also expose an API route for your applications to provide the possibility for your users to update categories for their transactions with certain description.
List
You can get the list of all the categories that we support.
The API can return multiple categories for any operation, each having its meaning. The categories are 2 types:
- Personal categories
- Business categories
Possible Errors
URL
https://www.saltedge.com/api/v5/categories
https://www.saltedge.com/api/v5/categories
Method
GET
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/categoriescurl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X GET \
https://www.saltedge.com/api/v5/categoriesSample Response
{
"data": {
"business": {
"equipment_and_materials": [
"electronics",
"software",
"supplies_and_furniture",
"raw_materials",
"consumer_goods"
],
"financials": [
"dividends",
"donations",
"interest",
"fees",
"fines",
"loans"
],
"human_resources": [
"wages",
"bonus",
"employee_benefits",
"education_and_trainings",
"staff_outsourcing",
"travel",
"entertainment",
"meals"
],
"income": [
"investments",
"sales",
"returns",
"prepayments"
],
"insurance": [
"business_insurance",
"liability_insurance",
"health_insurance",
"equipment_insurance",
"vehicle_insurance",
"professional_insurance"
],
"real_estate": [
"office_rent",
"mortgage",
"construction_and_repair"
],
"services": [
"contractors",
"accounting_and_auditing",
"legal",
"consulting",
"storage",
"marketing_and_media",
"online_subscriptions",
"it_services",
"cleaning"
],
"taxes": [
"vat",
"federal_taxes",
"property_taxes",
"income_taxes",
"duty_taxes",
"tax_return",
"payroll_taxes"
],
"transport": [
"shipping",
"leasing",
"gas_and_fuel",
"taxi",
"service_and_parts"
],
"uncategorized": [],
"utilities": [
"internet",
"phone",
"water",
"gas",
"electricity"
]
},
"personal": {
"auto_and_transport": [
"car_rental",
"gas_and_fuel",
"parking",
"public_transportation",
"service_and_parts",
"taxi"
],
"bills_and_utilities": [
"internet",
"phone",
"television",
"utilities"
],
"business_services": [
"advertising",
"office_supplies",
"shipping"
],
"education": [
"books_and_supplies",
"student_loan",
"tuition"
],
"entertainment": [
"amusement",
"arts",
"games",
"movies_and_music",
"newspapers_and_magazines"
],
"fees_and_charges": [
"provider_fee",
"loans",
"service_fee",
"taxes"
],
"food_and_dining": [
"alcohol_and_bars",
"cafes_and_restaurants",
"groceries"
],
"gifts_and_donations": [
"charity",
"gifts"
],
"health_and_fitness": [
"doctor",
"personal_care",
"pharmacy",
"sports",
"wellness"
],
"home": [
"home_improvement",
"home_services",
"home_supplies",
"mortgage",
"rent"
],
"income": [
"bonus",
"investment_income",
"paycheck"
],
"insurance": [
"car_insurance",
"health_insurance",
"life_insurance",
"property_insurance"
],
"kids": [
"allowance",
"babysitter_and_daycare",
"baby_supplies",
"child_support",
"kids_activities",
"toys"
],
"pets": [
"pet_food_and_supplies",
"pet_grooming",
"veterinary"
],
"shopping": [
"clothing",
"electronics_and_software",
"sporting_goods"
],
"transfer": [],
"travel": [
"hotel",
"transportation",
"vacation"
],
"uncategorized": []
}
}
}
Personal
Personal categories include:
auto_and_transport
Used for transactions, related to cars and other modes of transport
car_rental
Carsharing, car rentals, bicycle rentals
gas_and_fuel
Filling stations, gas, fuels, lubricants
parking
Parking spaces; parking apps
public_transportation
Public transportation of passengers; bus lines, train, metro
service_and_parts
Automotive parts and accessories; car wash, car repairs; vulcanizations
taxi
Taxicabs; limousines; taxi apps
bills_and_utilities
Refers to the set of utility services
internet
Internet bills; services of internet providers
phone
Cell phone, landline phone bills
television
Cable, satellite and other television services
utilities
Water, electricity, natural gas, heating, garbage disposal
business_services
Implies miscellaneous services for business, as accounting, consulting, marketing, legal, design
advertising
Outdoor adverstising; digital ads; social media marketing
office_supplies
Stationery, office supplies, printing paper
shipping
Logistics and delivery; courier services
education
Applied for transactions with colleges, universities, schools, learning centers
books_and_supplies
Books, periodicals, eBook apps, e-readers
student_loan
Student loans
tuition
Tuition grants and scholarships; tuition fees
entertainment
Includes entertainment activities, as visits of aquariums, dolphinariums, zoos, museums, theaters
amusement
Amusement parks
arts
Art dealers, art galleries
games
Video games, gambling, betting, casinos, lotteries
movies_and_music
Movie streaming services, audio streaming platforms, radio, cinemas and music festivals
newspapers_and_magazines
Newspapers, magazines and their distributors
fees_and_charges
Covers fees and charges
provider_fee
Banking fees
loans
Money lending
service_fee
Photo studio services; laundry; repairs and restoration
taxes
Different types of taxes, as income taxes, property taxes
food_and_dining
Applied for transactions related to food and beverage products, dining, catering
alcohol_and_bars
Alcohol sellers, bars, pubs, nightclubs
cafes_and_restaurants
Cafes, restaurants, pizzerias, canteens, steakhouses, gelaterias, trattorias
groceries
Grocery stores, supermarkets
gifts_and_donations
Refers to gifts and donations
charity
Donations, charitable services
gifts
Greetings cards, gift and souvenir shops
health_and_fitness
Covers goods and services for the maintenance or improvement of health and well-being
doctor
Hospitals; dental clinics; medical services
personal_care
Personal hygiene and beautification
pharmacy
Drugstores products, medicaments
sports
Sportclubs, gyms, fitness centers, swimming pools
wellness
Beauty spas; hair services; nail salons; massage parlors
home
Applied for household goods, services for building or maintenance of houses
home_improvement
Furniture, interior design services, improvements to outdoor structures
home_services
Home maintenance and repair, cleaning, laundry, ironing
home_supplies
Building materials, household hardware, cookware, domestic appliances
mortgage
Real estate purchases, estate sale, mortgage loans
rent
Property rentals
income
Covers different types of earnings
bonus
Bonuses, rewards, cashback
investment_income
Capital gains, dividends, interest
paycheck
Salaries, wages
insurance
Implies deals with insurance companies
car_insurance
Insurance for cars, trucks, motorcycles, and other road vehicles
health_insurance
Health insurance medical plans
life_insurance
Life insurance
property_insurance
Fire, theft and some weather damage property insurance
kids
Includes various child care activities
allowance
Child allowance
babysitter_and_daycare
Babysitting, kids daycare services
baby_supplies
Baby products, baby food
child_support
Child support
kids_activities
Amusement parks for kids, theme parks for kids
toys
Different types of toys
pets
Refers to pet stores, animal care
pet_food_and_supplies
Products and food for pets
pet_grooming
Pet grooming services
veterinary
Pet health care including veterinary clinics, pharmacies
shopping
Covers shopping malls, e-commerce marketplaces, retail of particular goods
clothing
Clothing, shoes, jewelry, sunglasses
electronics_and_software
Electronics, software, hardware, computers
sporting_goods
Equipment that completes the sport, as gym clothing, motorcycle gear
transfer
Includes money transfers; ATM cash withdrawals
travel
Covers travelling, travel agencies, tourism, excursions
hotel
Accommodation, hotels, motels, resorts
transportation
Air transportation, yachts
vacation
Holiday companies, specific trips or journies
uncategorized
The category of the transaction could not be identified
auto_and_transport
Used for transactions, related to cars and other modes of transport
car_rental
Carsharing, car rentals, bicycle rentals
gas_and_fuel
Filling stations, gas, fuels, lubricants
parking
Parking spaces; parking apps
public_transportation
Public transportation of passengers; bus lines, train, metro
service_and_parts
Automotive parts and accessories; car wash, car repairs; vulcanizations
taxi
Taxicabs; limousines; taxi apps
bills_and_utilities
Refers to the set of utility services
internet
Internet bills; services of internet providers
phone
Cell phone, landline phone bills
television
Cable, satellite and other television services
utilities
Water, electricity, natural gas, heating, garbage disposal
business_services
Implies miscellaneous services for business, as accounting, consulting, marketing, legal, design
advertising
Outdoor adverstising; digital ads; social media marketing
office_supplies
Stationery, office supplies, printing paper
shipping
Logistics and delivery; courier services
education
Applied for transactions with colleges, universities, schools, learning centers
books_and_supplies
Books, periodicals, eBook apps, e-readers
student_loan
Student loans
tuition
Tuition grants and scholarships; tuition fees
entertainment
Includes entertainment activities, as visits of aquariums, dolphinariums, zoos, museums, theaters
amusement
Amusement parks
arts
Art dealers, art galleries
games
Video games, gambling, betting, casinos, lotteries
movies_and_music
Movie streaming services, audio streaming platforms, radio, cinemas and music festivals
newspapers_and_magazines
Newspapers, magazines and their distributors
fees_and_charges
Covers fees and charges
provider_fee
Banking fees
loans
Money lending
service_fee
Photo studio services; laundry; repairs and restoration
taxes
Different types of taxes, as income taxes, property taxes
food_and_dining
Applied for transactions related to food and beverage products, dining, catering
alcohol_and_bars
Alcohol sellers, bars, pubs, nightclubs
cafes_and_restaurants
Cafes, restaurants, pizzerias, canteens, steakhouses, gelaterias, trattorias
groceries
Grocery stores, supermarkets
gifts_and_donations
Refers to gifts and donations
charity
Donations, charitable services
gifts
Greetings cards, gift and souvenir shops
health_and_fitness
Covers goods and services for the maintenance or improvement of health and well-being
doctor
Hospitals; dental clinics; medical services
personal_care
Personal hygiene and beautification
pharmacy
Drugstores products, medicaments
sports
Sportclubs, gyms, fitness centers, swimming pools
wellness
Beauty spas; hair services; nail salons; massage parlors
home
Applied for household goods, services for building or maintenance of houses
home_improvement
Furniture, interior design services, improvements to outdoor structures
home_services
Home maintenance and repair, cleaning, laundry, ironing
home_supplies
Building materials, household hardware, cookware, domestic appliances
mortgage
Real estate purchases, estate sale, mortgage loans
rent
Property rentals
income
Covers different types of earnings
bonus
Bonuses, rewards, cashback
investment_income
Capital gains, dividends, interest
paycheck
Salaries, wages
insurance
Implies deals with insurance companies
car_insurance
Insurance for cars, trucks, motorcycles, and other road vehicles
health_insurance
Health insurance medical plans
life_insurance
Life insurance
property_insurance
Fire, theft and some weather damage property insurance
kids
Includes various child care activities
allowance
Child allowance
babysitter_and_daycare
Babysitting, kids daycare services
baby_supplies
Baby products, baby food
child_support
Child support
kids_activities
Amusement parks for kids, theme parks for kids
toys
Different types of toys
pets
Refers to pet stores, animal care
pet_food_and_supplies
Products and food for pets
pet_grooming
Pet grooming services
veterinary
Pet health care including veterinary clinics, pharmacies
shopping
Covers shopping malls, e-commerce marketplaces, retail of particular goods
clothing
Clothing, shoes, jewelry, sunglasses
electronics_and_software
Electronics, software, hardware, computers
sporting_goods
Equipment that completes the sport, as gym clothing, motorcycle gear
transfer
Includes money transfers; ATM cash withdrawals
travel
Covers travelling, travel agencies, tourism, excursions
hotel
Accommodation, hotels, motels, resorts
transportation
Air transportation, yachts
vacation
Holiday companies, specific trips or journies
uncategorized
The category of the transaction could not be identified
Business
Business categories include:
equipment_and_materials
Refers to equipment and materials, used by a company
electronics
Electronics intended for use in offices
software
Any software or set of computer programs
supplies_and_furniture
Office supplies, stationery, office furniture
raw_materials
Raw materials, as wood, textil, glass, plastic
consumer_goods
Various consumer goods
financials
Covers company’s financial operations
dividends
Sums of money paid by companies to their shareholders
donations
Gifts made to a nonprofit organization, charity, private foundation
interest
Interests paid or received
fees
Financial institutions fees
fines
Local council fines, traffic offences, other offences
loans
Money lending
human_resources
Used for transactions, linked to human resources issues
wages
Paychecks, wages
bonus
Bonuses, rewards added to wages for good performance
employee_benefits
Various types of non-wage compensation provided to employees
education_and_trainings
Training providers, educational institutions, learning centers, learning apps
staff_outsourcing
Outsourcing of specialists from different domains: manufacturing, HR, accounting, developers; project-based outsourcing
travel
Air tickets, hotels
entertainment
Team buildings, corporate events
meals
Catering, drinking water, dining
income
Covers different types of income
investments
Money investments to investment funds, saving deposits, mutual funds
sales
Sales income
returns
Sales returns, online orders returns
prepayments
Advance payments
insurance
Implies deals with insurance companies
business_insurance
Business insurance; business interruption insurance
liability_insurance
Liability insurance
health_insurance
Health insurance medical plans
equipment_insurance
Inventory insurance, furniture insurance, tools insurance
vehicle_insurance
Insurance for cars, trucks, motorcycles, and other road vehicles
professional_insurance
Professional liability insurance policies, civil liability insurance
real_estate
Covers deals with real estate, as sales or rental of property
office_rent
Rental of a property used for business purposes
mortgage
Mortgage loans
construction_and_repair
Construction; repair of facilities, reconstruction, restoration
services
Implies miscellaneous services for business
contractors
Services delivered by contractors
accounting_and_auditing
Accounting, auditing, bookkeeping services
legal
Legal support services; attorneys
consulting
Consulting services
storage
Warehousing services; goods storage
marketing_and_media
Marketing and media services; advertising
online_subscriptions
Online subscriptions, web hosting, data storage
it_services
Services in IT domain, web design, app development
cleaning
Cleaning, maintenance, sanitation services
taxes
Covers different types of taxes
vat
Value added tax
federal_taxes
Federal taxes; estate tax, gift tax
property_taxes
Property taxes; land property tax
income_taxes
Income taxes
duty_taxes
Duty taxes; taxes on imported goods
tax_return
Tax return
payroll_taxes
Social Security tax; taxes for medicare
transport
Used for transactions, related to cars and other modes of transport
shipping
Motor freight carriers; logistics; delivery; courier services
leasing
Operational or financial leasing of transport
gas_and_fuel
Filling stations, gas, fuels, lubricants
taxi
Taxicabs; limousines; taxi apps
service_and_parts
Automotive parts and accessories; car wash, car repairs; vulcanizations
uncategorized
The category of the transaction could not be identified
utilities
Refers to the set of utility services and includes subcategories:
internet
Internet bills; services of internet providers
phone
Cell phone, landline phone bills
water
Water supplies
gas
Natural Gas supplies
electricity
Electricity, energy supplies
equipment_and_materials
Refers to equipment and materials, used by a company
electronics
Electronics intended for use in offices
software
Any software or set of computer programs
supplies_and_furniture
Office supplies, stationery, office furniture
raw_materials
Raw materials, as wood, textil, glass, plastic
consumer_goods
Various consumer goods
financials
Covers company’s financial operations
dividends
Sums of money paid by companies to their shareholders
donations
Gifts made to a nonprofit organization, charity, private foundation
interest
Interests paid or received
fees
Financial institutions fees
fines
Local council fines, traffic offences, other offences
loans
Money lending
human_resources
Used for transactions, linked to human resources issues
wages
Paychecks, wages
bonus
Bonuses, rewards added to wages for good performance
employee_benefits
Various types of non-wage compensation provided to employees
education_and_trainings
Training providers, educational institutions, learning centers, learning apps
staff_outsourcing
Outsourcing of specialists from different domains: manufacturing, HR, accounting, developers; project-based outsourcing
travel
Air tickets, hotels
entertainment
Team buildings, corporate events
meals
Catering, drinking water, dining
income
Covers different types of income
investments
Money investments to investment funds, saving deposits, mutual funds
sales
Sales income
returns
Sales returns, online orders returns
prepayments
Advance payments
insurance
Implies deals with insurance companies
business_insurance
Business insurance; business interruption insurance
liability_insurance
Liability insurance
health_insurance
Health insurance medical plans
equipment_insurance
Inventory insurance, furniture insurance, tools insurance
vehicle_insurance
Insurance for cars, trucks, motorcycles, and other road vehicles
professional_insurance
Professional liability insurance policies, civil liability insurance
real_estate
Covers deals with real estate, as sales or rental of property
office_rent
Rental of a property used for business purposes
mortgage
Mortgage loans
construction_and_repair
Construction; repair of facilities, reconstruction, restoration
services
Implies miscellaneous services for business
contractors
Services delivered by contractors
accounting_and_auditing
Accounting, auditing, bookkeeping services
legal
Legal support services; attorneys
consulting
Consulting services
storage
Warehousing services; goods storage
marketing_and_media
Marketing and media services; advertising
online_subscriptions
Online subscriptions, web hosting, data storage
it_services
Services in IT domain, web design, app development
cleaning
Cleaning, maintenance, sanitation services
taxes
Covers different types of taxes
vat
Value added tax
federal_taxes
Federal taxes; estate tax, gift tax
property_taxes
Property taxes; land property tax
income_taxes
Income taxes
duty_taxes
Duty taxes; taxes on imported goods
tax_return
Tax return
payroll_taxes
Social Security tax; taxes for medicare
transport
Used for transactions, related to cars and other modes of transport
shipping
Motor freight carriers; logistics; delivery; courier services
leasing
Operational or financial leasing of transport
gas_and_fuel
Filling stations, gas, fuels, lubricants
taxi
Taxicabs; limousines; taxi apps
service_and_parts
Automotive parts and accessories; car wash, car repairs; vulcanizations
uncategorized
The category of the transaction could not be identified
utilities
Refers to the set of utility services and includes subcategories:
internet
Internet bills; services of internet providers
phone
Cell phone, landline phone bills
water
Water supplies
gas
Natural Gas supplies
electricity
Electricity, energy supplies
Learn
Your customers can change the category of some of their transactions, thus improving the categorization accuracy.
The custom category will be applicable only for the customer’s new transactions, which have similar description.
The customer can change the category to the one already existing in categories list - in this case custom category is located in transaction extra as customer_category_code.
Customers can set their own category - in this case a custom category is located in the transaction extra as customer_category_name.
Note: To update the custom category, a new request should be sent for Learn with customer_id, id (the id of the transaction) and the new category_code.
Request body
The request body is an object wrapped in the data field. The data object must contain transactions field, which is an array with transactions objects. Each transaction object must contain customer_id, id (the id of the transaction) and category_code.
customer_id
string, required
The id of the customer received from customer create. This field is optional for ‘app’ authentication.
id
required
The id of the transaction
category_code
required
The new category code or the category name of the transaction
immediate
boolean optional
Defaults to false.
If sent as false, the learning threshold of the categorizer will be applied - the categorizer will store information about the user’s custom category for the transaction with this description. In case the categorizer identifies that the category has been updated 3 times for the transaction with this description, further transactions with this description will be automatically categorized for this user under this category;
If sent as true, the learning threshold of the categorizer will be ignored and further transactions with the same description will be classified under the category chosen by the user.
id
required
The id of the transaction
category_code
required
The new category code or the category name of the transaction
immediate
boolean optional
Defaults to false.
If sent as false, the learning threshold of the categorizer will be applied - the categorizer will store information about the user’s custom category for the transaction with this description. In case the categorizer identifies that the category has been updated 3 times for the transaction with this description, further transactions with this description will be automatically categorized for this user under this category;
If sent as true, the learning threshold of the categorizer will be ignored and further transactions with the same description will be classified under the category chosen by the user.
Possible Errors
URL
https://www.saltedge.com/api/v5/categories/learn
https://www.saltedge.com/api/v5/categories/learn
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"$CUSTOMER_ID\", \
\"transactions\": [ \
{ \
\"id\": \"333333333333333333\", \
\"category_code\": \"paycheck\", \
\"immediate\": true \
}, \
{ \
\"id\": \"333333333333333334\", \
\"category_code\": \"car_rental\", \
\"immediate\": false \
} \
] \
} \
}" \
https://www.saltedge.com/api/v5/categories/learncurl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"transactions\": [ \
{ \
\"id\": \"333333333333333333\", \
\"category_code\": \"paycheck\", \
\"immediate\": true \
}, \
{ \
\"id\": \"333333333333333334\", \
\"category_code\": \"car_rental\", \
\"immediate\": false \
} \
] \
} \
}" \
https://www.saltedge.com/api/v5/categories/learnSample Response
{
"data": {
"learned": true
}
}
Transaction Enrichment
In case you test categorization in Postman or use the stand-alone categorization, we will categorize your transactions and identify the related merchant by the given parameters.
Request body
The request body is an array of objects wrapped in the data field. Each object must contain the description field. The API accepts batches of at most 100 objects.
Parameters
description
string, required
The description which you wish to categorize (max 4000 chars)
action
string, optional
Learn - will create or update a rule, remove - will remove a previous created rule.
Note: category is required when action is learn
additional
string
Additional information (recommended to use in concatenation with original description, if present)
amount
decimal, optional
The amount of the transaction. Defaults to 1.0
categorization
string, optional
The type of categorization applied. Possible values: none, personal, business. Defaults to personal
category
string, optional
The new category code for the description, used with action: learn
country_code
string, optional
The code of the country, present in Salt Edge API
currency_code
string, optional
The currency code present in Salt Edge API. Defaults to USD
identifier
string, optional
A unique identifier of the transaction object (max 255 chars).
information
text, optional
Information about the transaction
mode
string, optional
Transaction’s mode. Possible values are: normal, fee, transfer. Defaults to normal
original_category
string, optional
The original category of the transaction
original_subcategory
string, optional
The original subcategory of the transaction
payee
string, optional
To whom money is paid
payee_information
string, optional
Additional payee information
status
string, optional
Possible values are: posted, pending. Defaults to posted
tags
array of strings, optional
User defined information in the bank or e-wallet interface, assigned to a transaction record (not category)
description
string, required
The description which you wish to categorize (max 4000 chars)
action
string, optional
Learn - will create or update a rule, remove - will remove a previous created rule.
Note: category is required when action is learn
additional
string
Additional information (recommended to use in concatenation with original description, if present)
amount
decimal, optional
The amount of the transaction. Defaults to 1.0
categorization
string, optional
The type of categorization applied. Possible values: none, personal, business. Defaults to personal
category
string, optional
The new category code for the description, used with action: learn
country_code
string, optional
The code of the country, present in Salt Edge API
currency_code
string, optional
The currency code present in Salt Edge API. Defaults to USD
identifier
string, optional
A unique identifier of the transaction object (max 255 chars).
information
text, optional
Information about the transaction
mode
string, optional
Transaction’s mode. Possible values are: normal, fee, transfer. Defaults to normal
original_category
string, optional
The original category of the transaction
original_subcategory
string, optional
The original subcategory of the transaction
payee
string, optional
To whom money is paid
payee_information
string, optional
Additional payee information
status
string, optional
Possible values are: posted, pending. Defaults to posted
tags
array of strings, optional
User defined information in the bank or e-wallet interface, assigned to a transaction record (not category)
Note: Custom categories will be located in transaction’s extra, see: customer_category_code and customer_category_name
Possible Errors
URL
https://www.saltedge.com/api/v5/enrichment
https://www.saltedge.com/api/v5/enrichment
Method
POST
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": [ \
{ \
\"description\": \"Amazon\", \
\"action\": \"learn\", \
\"category\": \"Online shopping\" \
}, \
{ \
\"description\": \"Tesco\", \
\"action\": \"remove\" \
}, \
{ \
\"description\": \"iTunes\", \
\"country_code\": \"GB\", \
\"identifier\": \"d5bb8cf037aa7f069\" \
}, \
{ \
\"description\": \"Ebay\", \
\"country_code\": \"US\", \
\"amount\": 100 \
}, \
{ \
\"description\": \"\", \
\"country_code\": \"US\", \
\"amount\": 100 \
} \
] \
}" \
https://www.saltedge.com/api/v5/enrichmentcurl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": [ \
{ \
\"description\": \"Amazon\", \
\"action\": \"learn\", \
\"category\": \"Online shopping\" \
}, \
{ \
\"description\": \"Tesco\", \
\"action\": \"remove\" \
}, \
{ \
\"description\": \"iTunes\", \
\"country_code\": \"GB\", \
\"identifier\": \"d5bb8cf037aa7f069\" \
}, \
{ \
\"description\": \"Ebay\", \
\"country_code\": \"US\", \
\"amount\": 100 \
}, \
{ \
\"description\": \"\", \
\"country_code\": \"US\", \
\"amount\": 100 \
} \
] \
}" \
https://www.saltedge.com/api/v5/enrichmentSample Response
{
"data": [
{
"description": "iTunes",
"identifier": "d5bb8cf037aa7f069",
"category": "electronics_and_software",
"made_on": "2020-01-10",
"amount": 1,
"mode": "normal",
"status": "posted",
"extra": {
"categorization_confidence": 1
},
"merchant_id": "1a059c025b1d42d1fc63bef2f62a9de9f781eae7ec593334632df2e9b7f507f6",
"country_code": "GB"
},
{
"description": "Ebay",
"identifier": null,
"currency_code": "USD",
"category": "shopping",
"made_on": "2020-01-10",
"amount": 100,
"mode": "normal",
"status": "posted",
"extra": {
"categorization_confidence": 1
},
"merchant_id": "a14465ec0459a33dc4c378759625aa762b17afd86f9aa243746f9253e59292d1",
"country_code": "US"
},
{
"description": "",
"identifier": null,
"currency_code": "USD",
"category": "uncategorized",
"made_on": "2020-01-10",
"amount": 1,
"mode": "normal",
"status": "posted",
"extra": {},
"errors": [
"Description can't be blank"
]
country_code: “US”
}
]
}
Merchant Identification
A merchant represents a company, that sells goods or provides services to a customer.
Identification
Merchant identification is an option that allows to identify merchant names and other useful information about them, basing on transactions’ data.
Europe
- Austria
- Belgium
- Croatia
- Czech Republic
- Estonia
- France
- Germany
- Hungary
- Italy
- Latvia
- Lithuania
- Luxembourg
- Netherlands
- Poland
- Portugal
- Republic of Ireland
- Romania
- Russia
- Slovenia
- Spain
- United Kingdom
Asia
- Hong Kong
- India
- Indonesia
- Israel
- Malaysia
- Philippines
- Saudi Arabia
- Singapore
- Turkey
- United Arab Emirates
Australia/Oceania
- Australia
- New Zealand
North America
- Mexico
South America
- Brazil
You can test the merchant identification, using the fakebank_with_file_csv_xf provider. Fill out the predefined sample.csv template. The file size limit is 5MB.
Note: Country and Account Currency defaults to GB and GBP respectively. In order to test the merchant identification in other countries, the two codes must be configured accordingly.
How to use
1a) In case you use Salt Edge Account Information API: on routes connections #create, #refresh, #reconnect or connect sessions #create, #refresh, #reconnect, when the connection creation succeeds and only if the merchant is identified, you will receive a merchant_id in the extra field of the transaction;
1b) In case you use stand-alone categorization: send the request with your transactions to transactions enrichment route, in response there will be merchant_id for transactions where merchant is identified;
2) Send all the merchant_ids you want to fetch the additional info for, to merchants show route.
Show
To fetch the name and additional info available for identified merchants, pass the desired merchant_ids in an array to route https://www.saltedge.com/api/v5/merchants.
Note that the first priority of this feature is to identify the merchant name, that’s why arrays with name and transliterated_name are always presented.
Sometimes, the transaction’s descriptional fields, can display additional information about the merchant, such as: shop number, or address of sale point, with city, post code and street numbers. In this case, it’s possible to identify the exact place where the customer’s transaction was made. If we find the point of sale corresponding to the transaction in our database, then we can return more granular information with contact and address details, including geo-coordinates.
The API accepts batches of at most 100 objects.
Attributes
id
string
The id of the merchant
names
array of objects
Merchant names that are used to name a company, corporation, brand name, franchise name or any other entity who has participated in the customer’s transaction
Possible values are: name, transliterated_name, alternative_name, brand, operator
address
object
Merchant address may include the following location parameters: city, transliterated_city, state, street, transliterated_street, country_code, post_code, coordinates and extra data associated with the address, as building_name, shop_number and so on.
contact
array of objects
Contact information via which the merchant can be accessed, eg. via website, phone or social media
Possible values are: email, viber, phone, fax, website, facebook, twitter, google_plus, linkedin, instagram, skype, vk, flickr, youtube
id
string
The id of the merchant
names
array of objects
Merchant names that are used to name a company, corporation, brand name, franchise name or any other entity who has participated in the customer’s transaction
Possible values are: name, transliterated_name, alternative_name, brand, operator
address
object
Merchant address may include the following location parameters: city, transliterated_city, state, street, transliterated_street, country_code, post_code, coordinates and extra data associated with the address, as building_name, shop_number and so on.
contact
array of objects
Contact information via which the merchant can be accessed, eg. via website, phone or social media
Possible values are: email, viber, phone, fax, website, facebook, twitter, google_plus, linkedin, instagram, skype, vk, flickr, youtube
Possible Errors
URL
https://www.saltedge.com/api/v5/merchants
https://www.saltedge.com/api/v5/merchants
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": [ \
\"f6dabf8bb3e1cbc7cce2f4571...\", \
\"ae316a83508ecaa8897e90321...\" \
] \
}" \
https://www.saltedge.com/api/v5/merchantscurl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X POST \
-d "{ \
\"data\": [ \
\"f6dabf8bb3e1cbc7cce2f4571...\", \
\"ae316a83508ecaa8897e90321...\" \
] \
}" \
https://www.saltedge.com/api/v5/merchantsSample Response
{
"data": [
{
"id": "f6dabf8bb3e1cbc7cce2f4571...",
"names": [
{
"mode": "name",
"value": "Amazon"
},
{
"mode": "transliterated_name",
"value": "amazon"
}
],
"contact": [
{
"mode": "website",
"value": "www.amazon.com"
}
],
"address": {
"country_code": "GB"
}
},
{
"id": "ae316a83508ecaa8897e90321...",
"names": [
{
"mode": "name",
"value": "Boots"
},
{
"mode": "transliterated_name",
"value": "boots"
},
{
"mode": "operator",
"value": "Boots Uk Limited"
}
],
"contact": [
{
"mode": "phone",
"value": "+44 20 73818651"
},
{
"mode": "website",
"value": "http://www.boots.com/stores/773-london-fulham-palace-road-w6-9pa"
}
],
"address": {
"country_code": "GB",
"city": "London",
"transliterated_city": "london",
"street": "Fulham Palace Road",
"transliterated_street": "fulham palace road",
"post_code": "W6 9Pa",
"coordinates": {
"latitude": "51.48467107",
"longitude": "-0.220126411"
},
"extra": {
"building_number": "198-200",
"shop_number": "773",
"type_of_shop": "Chemist"
}
}
}
]
}
Financial Insights
Financial Insights represents a report based on all the activities of a single customer. It analyzes all the unique accounts of customer’s connections to the providers for a selected period of time.
Financial Insights report is provided as an additional service. Please get in touch with our Sales team in order to discuss your use case and receive a quote.
Attributes
id
string
The id of the general report generated based on the customer’s data
status
string
Current report’s status. Possible values are: initialized, calculating, success, failed
connection_ids
array of strings
Ids of connections included in the report
Note: We do not include the duplicated accounts in the report’s calculation. If any connection is not included in the report, that means that this connection contains only duplicated account data. Also the connection will not be included in the report, if there are no successful attempts to fetch the data for this connection.
include_account_natures
array of strings, optional
Accounts with specified account natures are included in the report. Possible values are: account, bonus, card, checking, credit, credit_card, debit_card, ewallet, insurance, investment, loan, mortgage, savings
from_date
date
The date from which the data in the report are included
to_date
date
The date to which the data in the report are included
report_types
array of strings
Types of reports. Possible values are: balance, expense, income, savings, expense_categories, income_categories, inbound_transfers, outbound_transfers.
Note: for an extended Financial Insights PDF report, the following types of reports are used: balance, expense, income, savings. For a compact PDF report, the following are mostly used: expense_categories, income_categories, inbound_transfers, outbound_transfers, as well as, some other parameters from the rest of the reports
created_at
datetime
The date when the report was created
updated_at
datetime
The date when the report was last updated
id
string
The id of the general report generated based on the customer’s data
status
string
Current report’s status. Possible values are: initialized, calculating, success, failed
connection_ids
array of strings
Ids of connections included in the report
Note: We do not include the duplicated accounts in the report’s calculation. If any connection is not included in the report, that means that this connection contains only duplicated account data. Also the connection will not be included in the report, if there are no successful attempts to fetch the data for this connection.
include_account_natures
array of strings, optional
Accounts with specified account natures are included in the report. Possible values are: account, bonus, card, checking, credit, credit_card, debit_card, ewallet, insurance, investment, loan, mortgage, savings
from_date
date
The date from which the data in the report are included
to_date
date
The date to which the data in the report are included
report_types
array of strings
Types of reports. Possible values are: balance, expense, income, savings, expense_categories, income_categories, inbound_transfers, outbound_transfers.
Note: for an extended Financial Insights PDF report, the following types of reports are used: balance, expense, income, savings. For a compact PDF report, the following are mostly used: expense_categories, income_categories, inbound_transfers, outbound_transfers, as well as, some other parameters from the rest of the reports
created_at
datetime
The date when the report was created
updated_at
datetime
The date when the report was last updated
Sample object
{
"id": "509574324735183486",
"customer_id": "499952892392769962",
"customer_identifier": "test@mail.com",
"status": "success",
"connection_ids": [
"499953130209806766"
],
"include_account_natures": [
"account",
"card",
"debit_card",
"credit_card",
"checking",
"savings",
"investment",
"bonus",
"loan",
"credit",
"insurance",
"ewallet",
"mortgage"
],
"currency_code": "GBP",
"from_date": "2021-01-01",
"to_date": "2021-04-22",
"report_types": [
"balance",
"expense",
"income",
"savings",
"income_categories",
"expense_categories",
"inbound_transfers",
"outbound_transfers"
],
"data": {
},
"created_at": "2024-04-17T08:13:55Z",
"updated_at": "2024-04-17T08:13:55Z"
}
Create
Allows you to create a report for a customer for a specific date range.
Parameters
report_types
array of strings, required
Types of reports that can be generated. Possible values are: balance, expense, income, savings, expense_categories, income_categories, inbound_transfers, outbound_transfers
Note: at least one report type should be requested
Note: for an extended Financial Insights PDF report, the following types of reports are used: balance, expense, income, savings. For a compact PDF report, the following are mostly used: expense_categories, income_categories, inbound_transfers, outbound_transfers, as well as, some other parameters from the rest of the reports
include_account_natures
array of strings, optional
Accounts with specified account natures can be included in the report. Possible values are: account, bonus, card, checking, credit, credit_card, debit_card, ewallet, insurance, investment, loan, mortgage, savings
currency_code
string, required
Main currency code to be used for the report’s generation and value conversion
from_date
string, required
The date from which the data in the report will be included
to_date
string, required
The date to which the data in the report will be included
report_types
array of strings, required
Types of reports that can be generated. Possible values are: balance, expense, income, savings, expense_categories, income_categories, inbound_transfers, outbound_transfers
Note: at least one report type should be requested
Note: for an extended Financial Insights PDF report, the following types of reports are used: balance, expense, income, savings. For a compact PDF report, the following are mostly used: expense_categories, income_categories, inbound_transfers, outbound_transfers, as well as, some other parameters from the rest of the reports
include_account_natures
array of strings, optional
Accounts with specified account natures can be included in the report. Possible values are: account, bonus, card, checking, credit, credit_card, debit_card, ewallet, insurance, investment, loan, mortgage, savings
currency_code
string, required
Main currency code to be used for the report’s generation and value conversion
from_date
string, required
The date from which the data in the report will be included
to_date
string, required
The date to which the data in the report will be included
Possible Errors
URL
https://www.saltedge.com/api/v5/reports
https://www.saltedge.com/api/v5/reports
Method
POST
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"$CUSTOMER_ID\", \
\"report_types\": [ \
\"balance\", \
\"expense\", \
\"income\", \
\"savings\", \
\"expense_categories\", \
\"income_categories\", \
\"inbound_transfers\", \
\"outbound_transfers\" \
], \
\"include_account_natures\": [ \
\"account\", \
\"bonus\", \
\"card\", \
\"checking\", \
\"credit\", \
\"credit_card\", \
\"debit_card\", \
\"ewallet\", \
\"insurance\", \
\"investment\", \
\"loan\", \
\"mortgage\", \
\"savings\" \
], \
\"currency_code\": \"GBP\", \
\"from_date\": \"2021-01-01\", \
\"to_date\": \"2021-04-22\" \
} \
}" \
https://www.saltedge.com/api/v5/reportscurl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"$CUSTOMER_ID\", \
\"report_types\": [ \
\"balance\", \
\"expense\", \
\"income\", \
\"savings\", \
\"expense_categories\", \
\"income_categories\", \
\"inbound_transfers\", \
\"outbound_transfers\" \
], \
\"include_account_natures\": [ \
\"account\", \
\"bonus\", \
\"card\", \
\"checking\", \
\"credit\", \
\"credit_card\", \
\"debit_card\", \
\"ewallet\", \
\"insurance\", \
\"investment\", \
\"loan\", \
\"mortgage\", \
\"savings\" \
], \
\"currency_code\": \"GBP\", \
\"from_date\": \"2021-01-01\", \
\"to_date\": \"2021-04-22\" \
} \
}" \
https://www.saltedge.com/api/v5/reportsSample response
{
"data": {
"id": "509574324735183486",
"customer_id": "499952892392769962",
"customer_identifier": "test@email.com",
"connection_ids": [
"499953130209806766",
"499953130209806767",
"499953130209806768"
],
"status": "initialized",
"created_at": "2024-04-17T11:13:55Z"
}
}
Show
Shows the generated report with all the details.
The Report can be downloaded in PDF format via API as well, by adding .pdf after report_id parameter.
URL example: https://www.saltedge.com/api/v5/reports/{report.id}.pdf
Parameters
Possible Errors
URL
https://www.saltedge.com/api/v5/reports/{report.id}
https://www.saltedge.com/api/v5/reports/{report.id}
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/reports/3251curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/reports/3251Sample response
{
"data": {
"id": "509574324735183486",
"customer_id": "499952892392769962",
"customer_identifier": "test@mail.com",
"status": "success",
"connection_ids": [
"499953130209806766"
],
"include_account_natures": [
"account",
"card",
"debit_card",
"credit_card",
"checking",
"savings",
"investment",
"bonus",
"loan",
"credit",
"insurance",
"ewallet",
"mortgage"
],
"currency_code": "GBP",
"from_date": "2021-01-01",
"to_date": "2021-04-22",
"report_types": [
"balance",
"expense",
"income",
"savings",
"income_categories",
"expense_categories",
"inbound_transfers",
"outbound_transfers"
],
"data": {
"result": {
"accounts": [
{
"id": "499953244512979380",
"name": "2445***156",
"nature": "card",
"connection_id": "499953130209806766",
"start_date": "2021-01-01",
"end_date": "2021-04-21",
"whole_months_count": 3,
"days_count": 112,
"monthly_average_transactions_count": {
"total": 17,
"income": 3,
"expense": 14
},
"balance": {},
"income": {},
"expense": {},
"savings": {},
"expense_categories": {},
"income_categories": {},
"inbound_transfers": {},
"outbound_transfers": {}
}
],
"accounts_summary": {
"start_date": "2021-01-01",
"end_date": "2021-04-21",
"whole_months_count": 3,
"days_count": 112,
"transactions_count": 64,
"monthly_average_transactions_count": {
"total": 17,
"income": 3,
"expense": 14
},
"balance": {},
"income": {},
"expense": {},
"savings": {},
"expense_categories": {},
"income_categories": {},
"inbound_transfers": {},
"outbound_transfers": {}
}
},
"customer_id": 499952892392769962,
"connection_ids": [
"499953130209806766"
],
"connections": [
{
"id": "499953130209806766",
"customer_id": 499952892392769962,
"provider_code": "fakebank_with_file_csv_xf",
"provider_name": "Fakebank with file CSV",
"accounts": [
{
"id": "499953244512979380",
"name": "2445***156",
"nature": "card",
"balance": 6412.0,
"original_balance": 6412.0,
"original_currency_code": "GBP",
"transactions": {
"start_date": "2021-01-01",
"end_date": "2021-04-21",
"first_id": "499953313559611829",
"last_id": "499953322376038900",
"count": 64
}
}
],
"holder_info": {
"names": [
"John Doe"
]
},
"client_name": "test app"
}
],
"currency_code": "GBP",
"exchange_rates": {
"EUR": "1.083599",
"USD": "1.2341013636"
},
"report_id": 509574324735183486,
"report_types": [
"balance",
"expense",
"income",
"savings",
"income_categories",
"expense_categories",
"inbound_transfers",
"outbound_transfers"
],
"status": "success",
"from_date": "2021-01-01",
"to_date": "2021-04-22"
},
"created_at": "2021-06-21T14:19:29Z",
"updated_at": "2021-06-21T14:19:48Z"
}
}
List
Returns all the general available reports for a customer.
Parameters
from_id
string, optional
The id of the report which the list starts with
from_id
string, optional
The id of the report which the list starts with
Possible Errors
URL
https://www.saltedge.com/api/v5/reports?customer_id={customer.id}
https://www.saltedge.com/api/v5/reports?customer_id={customer.id}
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/reports?customer_id=$CUSTOMER_IDcurl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v5/reports?customer_id=$CUSTOMER_IDSample response
{
"data": [
{
"id": "509574324735183486",
"customer_id": "499952892392769962",
"customer_identifier": "test@email.com",
"connection_ids": [
"499953130209806766",
"499953130209806767"
],
"status": "success",
"created_at": "2024-04-16T11:13:55Z"
},
{
"id": "509574324735183487",
"customer_id": "499952892392769962",
"customer_identifier": "test@email.com",
"connection_ids": [
"499953130209806768",
"499953130209806769"
],
"status": "success",
"created_at": "2024-04-16T11:13:55Z"
}
],
"meta": {
"next_id": "509574324735183488",
"next_page": "/api/v5/reports/?from_id=509574324735183488"
}
}
Remove
Removes a report.
Parameters
report_id
string, required
The id of the general report
report_id
string, required
The id of the general report
Possible Errors
URL
https://www.saltedge.com/api/v5/reports/{report.id}
https://www.saltedge.com/api/v5/reports/{report.id}
Method
DELETE
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X DELETE \
https://www.saltedge.com/api/v5/reports/13843curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X DELETE \
https://www.saltedge.com/api/v5/reports/13843Sample response
{
"data": {
"id": "509574324735183486",
"deleted": true
}
}
Report Object
result
string
Report result
connection_ids
array of strings
Ids of connections included in the report
Note: We do not include the duplicated accounts in the report’s calculation. If any connection is not included in the report, that means that this connection contains only duplicated account data. Also the connection will not be included in the report, if there are no successful attempts to fetch the data for this connection.
connections
array of objects
Information related to connections included in report
exchange_rates
object
A list of exchange rates at the time of report creation
report_id
integer
The id of the generated report
report_types
array of strings
Types of generated reports. Possible values are: balance, expense, income, savings, expense_categories, income_categories, inbound_transfers, outbound_transfers
status
string
Current report’s status. Possible values are: initialized, calculating, success, failed
from_date
date
The date from which the data in the report are included
to_date
date
The date to which the data in the report are included
result
string
Report result
connection_ids
array of strings
Ids of connections included in the report
Note: We do not include the duplicated accounts in the report’s calculation. If any connection is not included in the report, that means that this connection contains only duplicated account data. Also the connection will not be included in the report, if there are no successful attempts to fetch the data for this connection.
connections
array of objects
Information related to connections included in report
exchange_rates
object
A list of exchange rates at the time of report creation
report_id
integer
The id of the generated report
report_types
array of strings
Types of generated reports. Possible values are: balance, expense, income, savings, expense_categories, income_categories, inbound_transfers, outbound_transfers
status
string
Current report’s status. Possible values are: initialized, calculating, success, failed
from_date
date
The date from which the data in the report are included
to_date
date
The date to which the data in the report are included
Sample object
{
"result": {
"accounts": [
{
"id": "499953244512979380",
"name": "2445***156",
"nature": "card",
"connection_id": "499953130209806766",
"start_date": "2021-01-01",
"end_date": "2021-04-21",
"whole_months_count": 3,
"days_count": 112,
"monthly_average_transactions_count": {
"total": 17,
"income": 3,
"expense": 14
},
"balance": { },
"income": { },
"expense": { },
"savings": { },
"expense_categories": { },
"income_categories": { },
"inbound_transfers": { },
"outbound_transfers": { }
}
],
"accounts_summary": {
"start_date": "2021-01-01",
"end_date": "2021-04-21",
"whole_months_count": 3,
"days_count": 112,
"transactions_count": 64,
"monthly_average_transactions_count": {
"total": 17,
"income": 3,
"expense": 14
},
"balance": { },
"income": { },
"expense": { },
"savings": { },
"expense_categories": { },
"income_categories": { },
"inbound_transfers": { },
"outbound_transfers": { }
}
},
"customer_id": 499952892392769962,
"connection_ids": [
"499953130209806766"
],
"connections": [
{
"id": "499953130209806766",
"customer_id": 499952892392769962,
"provider_code": "fakebank_with_file_csv_xf",
"provider_name": "Fakebank with file CSV",
"accounts": [
{
"id": "499953244512979380",
"name": "2445***156",
"nature": "card",
"balance": 6412.0,
"original_balance": 6412.0,
"original_currency_code": "GBP",
"transactions": {
"start_date": "2021-01-01",
"end_date": "2021-04-21",
"first_id": "499953313559611829",
"last_id": "499953322376038900",
"count": 64
}
}
],
"holder_info": {
"names": [
"John Doe"
]
},
"client_name": "test app"
}
],
"currency_code": "GBP",
"exchange_rates": {
"EUR": "1.083599",
"USD": "1.2341013636"
},
"report_id": 509574324735183486,
"report_types": [
"balance",
"expense",
"income",
"savings",
"income_categories",
"expense_categories",
"inbound_transfers",
"outbound_transfers"
],
"status": "success",
"from_date": "2021-01-01",
"to_date": "2021-04-22"
}
Balance Report Object
minimum
decimal
The minimum balance registered for the report’s date range.
maximum
decimal
The maximum balance registered for the report’s date range.
average
object
Average balance
forecasted_average
object
Forecasted average balance
minimum
decimal
The minimum balance registered for the report’s date range.
maximum
decimal
The maximum balance registered for the report’s date range.
average
object
Average balance
forecasted_average
object
Forecasted average balance
Sample object
{
"start_date_amount": 1150.0,
"end_date_amount": 6412.0,
"minimum": 1000.0,
"maximum": 9341.0,
"average": {
"daily": {
"start_date": "2021-01-01",
"end_date": "2021-04-22",
"amount": 5581.81
},
"daily_per_month": [
{
"amount": 3566.25,
"is_whole_month": true,
"year": 2021,
"month": 1
},
{
"amount": 4753.78,
"is_whole_month": true,
"year": 2021,
"month": 2
},
{
"amount": 6911.96,
"is_whole_month": true,
"year": 2021,
"month": 3
},
{
"amount": 7601.45,
"is_whole_month": false,
"year": 2021,
"month": 4
}
],
"monthly": {
"amount": 5077.33,
"start_date": "2021-01-01",
"end_date": "2021-03-31"
},
"minimum_monthly": {
"amount": 3566.25,
"end_date": "2021-03-31",
"start_date": "2021-01-01"
},
"maximum_monthly": {
"amount": 6911.96,
"end_date": "2021-03-31",
"start_date": "2021-01-01"
},
"quarterly": {
"amount": null,
"end_date": null,
"start_date": null
},
"annual": {
"amount": null,
"start_date": null,
"end_date": null
}
},
"forecasted_average": {
"next_month": 8423.04,
"next_quarter": null,
"next_year": null
}
}
Income/Expense Report Object
last_year_amount
decimal
Total amount of income/expense for the last fully covered 12 months
total
decimal
Total amount of income/expense per the calculated period
total_per_month
array of objects
Total amount of income/expense per each month
average
object
Average amount of income/expense
forecasted_average
object
Forecasted average amount of income/expense
streams
object
Information on income/expense a customer receives/spends on a regular/irregular basis
last_year_amount
decimal
Total amount of income/expense for the last fully covered 12 months
total
decimal
Total amount of income/expense per the calculated period
total_per_month
array of objects
Total amount of income/expense per each month
average
object
Average amount of income/expense
forecasted_average
object
Forecasted average amount of income/expense
streams
object
Information on income/expense a customer receives/spends on a regular/irregular basis
Sample object
{
"start_date": "2021-01-02",
"end_date": "2021-04-03",
"transactions_count": 9,
"last_year_amount": null,
"total": 17100.0,
"total_per_month": [
{
"year": 2021,
"month": 1,
"is_whole_month": true,
"amount": 4100.0,
"count": 3
},
{
"year": 2021,
"month": 2,
"is_whole_month": true,
"amount": 4300.0,
"count": 3
},
{
"year": 2021,
"month": 3,
"is_whole_month": true,
"amount": 4350.0,
"count": 2
},
{
"year": 2021,
"month": 4,
"is_whole_month": false,
"amount": 4350.0,
"count": 1
}
],
"average": {
"monthly": 4250.0,
"quarterly": null,
"annual": null
},
"forecasted_average": {
"next_month": 4500.0,
"next_quarter": null,
"next_year": null
},
"streams": {
"regular_amount": 16800.0,
"irregular_amount": 300.0,
"count": {
"regular": 2,
"irregular": 1,
"maximum_overlapping": 2
},
"regular": [
{
"transactions_count": 4,
"transaction_ids": [
"499953314029373878",
"499953315832924614",
"499953317401594326",
"499953321084193257"
],
"start_date": "2021-01-02",
"end_date": "2021-04-03",
"amount": {
"total": 16500.0,
"average": 4125.0,
"median": 4125.0,
"stdev": 182.0
},
"frequency": "monthly",
"days_count": 30,
"category_code": "income",
"description": "Salary",
"merchant": {
"name": null,
"email": null,
"phone": null,
"address": null,
"website": null
}
},
{
"transactions_count": 3,
"transaction_ids": [
"499953314163591607",
"499953315832924615",
"499953317544200664"
],
"start_date": "2021-01-02",
"end_date": "2021-03-01",
"amount": {
"total": 300.0,
"average": 100.0,
"median": 100.0,
"stdev": 0.0
},
"frequency": "monthly",
"days_count": 29,
"category_code": "transfer",
"description": "transfer",
"merchant": {
"name": null,
"email": null,
"phone": null,
"address": null,
"website": null
}
}
],
"irregular": {
"transactions_count": 2,
"transaction_ids": [
"499953314876623296",
"499953316806003154"
],
"start_date": "2021-01-21",
"end_date": "2021-02-19"
}
}
}
Savings Report Object
total
decimal
Total amount of savings per the calculated period
per_month
array of objects
Information related to net savings per each month
average
object
Average savings
forecasted_average
object
Forecasted average savings
runway
decimal
Provides an estimate (number of months) on how long the current balance will be sufficient until the customer runs out of money. The customer’s income and expenses are taken into account.Note: This indicator is calculated only for cases when the customer has positive current balance and the amount of expenses exceeds the amount of income.
expense_to_savings_rate
decimal
Shows whether the customer increases or loses capital. Taking into account the customer’s income and expenses, this indicator shows the number of months during which the customer’s savings are either increased or reduced by an amount equal to 1 month of expenses.Note: This indicator is calculated only for cases when the customer has both savings/dissavings and expenses.
stress_runway
decimal
Provides an estimate (number of months) on how long the customer’s current balance will be sufficient to cover regular expenses in case income unexpectedly stops.Note: This indicator is calculated for all cases, except the one, when the customer has no expenses
income_stability
decimal
Average weighted stability of income from all the sources
Note: it is close to 1, if customer has stable income
income_regularity
decimal
Average weighted regularity of income from all the sources
Note: it is close to 1, if customer has regular income
income_to_expense_rate
decimal
Ratio of average monthly income to average monthly expense
total
decimal
Total amount of savings per the calculated period
per_month
array of objects
Information related to net savings per each month
average
object
Average savings
forecasted_average
object
Forecasted average savings
runway
decimal
Provides an estimate (number of months) on how long the current balance will be sufficient until the customer runs out of money. The customer’s income and expenses are taken into account.Note: This indicator is calculated only for cases when the customer has positive current balance and the amount of expenses exceeds the amount of income.
expense_to_savings_rate
decimal
Shows whether the customer increases or loses capital. Taking into account the customer’s income and expenses, this indicator shows the number of months during which the customer’s savings are either increased or reduced by an amount equal to 1 month of expenses.Note: This indicator is calculated only for cases when the customer has both savings/dissavings and expenses.
stress_runway
decimal
Provides an estimate (number of months) on how long the customer’s current balance will be sufficient to cover regular expenses in case income unexpectedly stops.Note: This indicator is calculated for all cases, except the one, when the customer has no expenses
income_stability
decimal
Average weighted stability of income from all the sources
Note: it is close to 1, if customer has stable income
income_regularity
decimal
Average weighted regularity of income from all the sources
Note: it is close to 1, if customer has regular income
income_to_expense_rate
decimal
Ratio of average monthly income to average monthly expense
Sample object
{
"total": 5262.0,
"per_month": [
{
"year": 2021,
"month": 1,
"is_whole_month": true,
"amount": 430.0
},
{
"year": 2021,
"month": 2,
"is_whole_month": true,
"amount": 1955.0
},
{
"year": 2021,
"month": 3,
"is_whole_month": true,
"amount": 1730.0
},
{
"year": 2021,
"month": 4,
"is_whole_month": false,
"amount": 1147.0
}
],
"average": {
"monthly": 1371.66,
"quarterly": null,
"annual": null
},
"forecasted_average": {
"next_month": 2671.66,
"next_quarter": null,
"next_year": null
},
"runway": null,
"expense_to_savings_rate": 2.098,
"stress_runway": 2.227,
"income_stability": 0.34,
"income_regularity": 0.934,
"income_to_expense_rate": 1.476
}
Expense Categories Report Object
categories
array of objects
Information on the expense categories a customer spends money on.
Note: outbound transfers are not considered.
categories
array of objects
Information on the expense categories a customer spends money on.
Note: outbound transfers are not considered.
Sample object
{
"categories": [
{
"category": "Education",
"amount": -3000.0,
"average": -1000.0,
"amounts_per_month": [
{
"month": "2021-01",
"amount": -1000.0
},
{
"month": "2021-02",
"amount": -1000.0
},
{
"month": "2021-03",
"amount": -1000.0
},
{
"month": "2021-04",
"amount": 0
}
]
},
{
"category": "Utilities",
"amount": -1980.0,
"average": -493.33,
"amounts_per_month": [
{
"month": "2021-01",
"amount": -500.0
},
{
"month": "2021-02",
"amount": -550.0
},
{
"month": "2021-03",
"amount": -430.0
},
{
"month": "2021-04",
"amount": -500.0
}
]
},
{
"category": "Shopping",
"amount": -1915.0,
"average": -155.0,
"amounts_per_month": [
{
"month": "2021-01",
"amount": -200.0
},
{
"month": "2021-02",
"amount": -165.0
},
{
"month": "2021-03",
"amount": -100.0
},
{
"month": "2021-04",
"amount": -1450.0
}
]
},
{
"category": "Home improvement",
"amount": -1206.0,
"average": -300.0,
"amounts_per_month": [
{
"month": "2021-01",
"amount": -300.0
},
{
"month": "2021-02",
"amount": -300.0
},
{
"month": "2021-03",
"amount": -300.0
},
{
"month": "2021-04",
"amount": -306.0
}
]
},
{
"category": "Service and parts",
"amount": -1100.0,
"average": -200.0,
"amounts_per_month": [
{
"month": "2021-01",
"amount": -600.0
},
{
"month": "2021-02",
"amount": 0
},
{
"month": "2021-03",
"amount": 0
},
{
"month": "2021-04",
"amount": -500.0
}
]
},
{
"category": "Other categories",
"amount": -2585.0,
"average": -730.0,
"amounts_per_month": [
{
"month": "2021-01",
"amount": -1070.0
},
{
"month": "2021-02",
"amount": -330.0
},
{
"month": "2021-03",
"amount": -790.0
},
{
"month": "2021-04",
"amount": -395.0
}
]
}
]
}
Income Categories Report Object
streams
array of objects
Information on the income a customer receives on a regular/irregular basis.
Note: inbound transfers and other categories of incoming transactions are not considered.
streams
array of objects
Information on the income a customer receives on a regular/irregular basis.
Note: inbound transfers and other categories of incoming transactions are not considered.
Sample object
{
"streams": {
"regular_amount": 16500.0,
"irregular_amount": 300.0,
"count": {
"regular": 1,
"irregular": 1
},
"regular": [
{
"transactions_count": 4,
"transaction_ids": [
"499953314029373878",
"499953315832924614",
"499953317401594326",
"499953321084193257"
],
"start_date": "2021-01-02",
"end_date": "2021-04-03",
"amount": {
"total": 16500.0,
"average": 4125.0,
"median": 4125.0,
"stdev": 182.0
},
"amounts_per_month": [
{
"year": 2021,
"month": 1,
"amount": 3900.0
},
{
"year": 2021,
"month": 2,
"amount": 4000.0
},
{
"year": 2021,
"month": 3,
"amount": 4250.0
},
{
"year": 2021,
"month": 4,
"amount": 4350.0
}
],
"frequency": "monthly",
"days_count": 30,
"category_code": "income",
"description": "Salary",
"merchant": {
"name": null,
"email": null,
"phone": null,
"address": null,
"website": null
}
}
],
"irregular": {
"transactions_count": 2,
"transaction_ids": [
"499953314876623296",
"499953316806003154"
],
"start_date": "2021-01-21",
"end_date": "2021-02-19",
"amounts_per_month": [
{
"year": 2021,
"month": 1,
"amount": 100.0
},
{
"year": 2021,
"month": 2,
"amount": 200.0
},
{
"year": 2021,
"month": 3,
"amount": 0.0
},
{
"year": 2021,
"month": 4,
"amount": 0.0
}
],
"average": 100.0
}
}
}
Inbound Transfers Report Object
streams
array of objects
Information on the transfers a customer receives on a regular/irregular basis.
Note: all the transfers incoming from one account to another are considered as inbound transfers, no matter if those accounts belong to the same customer or different.
streams
array of objects
Information on the transfers a customer receives on a regular/irregular basis.
Note: all the transfers incoming from one account to another are considered as inbound transfers, no matter if those accounts belong to the same customer or different.
Sample object
{
"streams": {
"regular_amount": 300.0,
"irregular_amount": 0,
"count": {
"regular": 1,
"irregular": 0
},
"regular": [
{
"transactions_count": 3,
"transaction_ids": [
"499953314163591607",
"499953315832924615",
"499953317544200664"
],
"start_date": "2021-01-02",
"end_date": "2021-03-01",
"amount": {
"total": 300.0,
"average": 100.0,
"median": 100.0,
"stdev": 0.0
},
"amounts_per_month": [
{
"year": 2021,
"month": 1,
"amount": 100.0
},
{
"year": 2021,
"month": 2,
"amount": 100.0
},
{
"year": 2021,
"month": 3,
"amount": 100.0
},
{
"year": 2021,
"month": 4,
"amount": 0.0
}
],
"frequency": "monthly",
"days_count": 29,
"category_code": "transfer",
"description": "transfer",
"merchant": {
"name": null,
"email": null,
"phone": null,
"address": null,
"website": null
}
}
],
"irregular": {
"transactions_count": 0,
"transaction_ids": [],
"start_date": null,
"end_date": null,
"amounts_per_month": null,
"average": null
}
}
}
Outbound Transfers Report Object
streams
array of objects
Information on the transfers a customer sends on a regular/irregular basis.
Note: all the transfers outgoing from one account to another are considered as outbound transfers, no matter if those accounts belong to the same customer or different.
streams
array of objects
Information on the transfers a customer sends on a regular/irregular basis.
Note: all the transfers outgoing from one account to another are considered as outbound transfers, no matter if those accounts belong to the same customer or different.
Sample object
{
"streams": {
"regular_amount": 0,
"irregular_amount": -52.0,
"count": {
"regular": 0,
"irregular": 1
},
"regular": [],
"irregular": {
"transactions_count": 1,
"transaction_ids": [
"499953322376038900"
],
"start_date": "2021-04-21",
"end_date": "2021-04-21",
"amounts_per_month": [
{
"year": 2021,
"month": 1,
"amount": 0.0
},
{
"year": 2021,
"month": 2,
"amount": 0.0
},
{
"year": 2021,
"month": 3,
"amount": 0.0
},
{
"year": 2021,
"month": 4,
"amount": -52.0
}
],
"average": 0.0
}
}
}