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/categories
curl -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/categories

Sample 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.

The category identified by the Salt Edge Categorizer algorithms is always displayed in the transaction’s category field.

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/learn
curl -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/learn

Sample 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

mcc

string, optional

The transaction’s Merchant Category Code

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

mcc

string, optional

The transaction’s Merchant Category Code

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/enrichment
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/enrichment

Sample 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.

Merchant identification is a country based option and it is currently available for the following countries:

Europe

  • Austria
  • Czech Republic
  • Estonia
  • France
  • Germany
  • Hungary
  • Italy
  • Latvia
  • Lithuania
  • Netherlands
  • Poland
  • Portugal
  • Republic of Ireland
  • Romania
  • Russia
  • Spain
  • United Kingdom

Asia

  • Hong Kong
  • India
  • Indonesia
  • Malaysia
  • Singapore

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 next 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 next 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/merchants
curl -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/merchants

Sample 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 customer’s connections to the connected 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

customer_id

string

The id of the customer for which the report has been requested

customer_identifier

string

Unique customer identifier

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

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

currency_code

string

Main currency code used for the report’s generation and value conversion

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

data

object

Contains Report Object

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

customer_id

string

The id of the customer for which the report has been requested

customer_identifier

string

Unique customer identifier

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

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

currency_code

string

Main currency code used for the report’s generation and value conversion

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

data

object

Contains Report Object

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": "2021-10-15T10:46:19Z",
  "updated_at": "2021-10-15T10:46:19Z"
}

Create

This endpoint is available only for apps using API keys of type service. For more information please see authentication guide.

Allows you to create a report for a customer for a specific date range.

The report might take some time to finish, this can be tracked by the status attribute.

Parameters

customer_id

string, required

The id of the customer that the report will be generated for

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

customer_id

string, required

The id of the customer that the report will be generated for

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/reports
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/reports

Sample response

{
  "data": {
    "id": "509574324735183486",
    "customer_id": "499952892392769962",
    "customer_identifier": "test@email.com",
    "connection_ids": [
      "499953130209806766",
      "499953130209806767",
      "499953130209806768"
    ],
    "status": "initialized",
    "created_at": "2021-10-15T13:46:19Z"
  }
}

Show

This endpoint is available only for apps using API keys of type service. For more information please see authentication guide.

Shows the generated report with all the details.

Parameters

report_id

string, required

The id of the report generated based on the customer’s data.

report_id

string, required

The id of the report generated based on the customer’s data.

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/3251
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/3251

Sample 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

This endpoint is available only for apps using API keys of type service. For more information please see authentication guide.

Returns all the general available reports for a customer.

Parameters

customer_id

string, optional

The id of the customer for which the report(s) has been requested

from_id

string, optional

The id of the report which the list starts with

customer_id

string, optional

The id of the customer for which the report(s) has been requested

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_ID
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_ID

Sample response

{
  "data": [
    {
      "id": "509574324735183486",
      "customer_id": "499952892392769962",
      "customer_identifier": "test@email.com",
      "connection_ids": [
        "499953130209806766",
        "499953130209806767"
      ],
      "status": "success",
      "created_at": "2021-10-14T13:46:19Z"
    },
    {
      "id": "509574324735183487",
      "customer_id": "499952892392769962",
      "customer_identifier": "test@email.com",
      "connection_ids": [
        "499953130209806768",
        "499953130209806769"
      ],
      "status": "success",
      "created_at": "2021-10-14T13:46:19Z"
    }
  ],
  "meta": {
    "next_id": "509574324735183488",
    "next_page": "/api/v5/reports/?from_id=509574324735183488"
  }
}

Remove

This endpoint is available only for apps using API keys of type service. For more information please see authentication guide.

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/13843
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/13843

Sample response

{
  "data": {
    "id": "509574324735183486",
    "deleted": true
  }
}

Report Object

result

string

Show child attributes

Report result

customer_id

integer

The id of the customer

connection_ids

array of strings

Ids of Connections included in report

connections

array of objects

Show child attributes

Information related to connections included in report

currency_code

string

Main currency code used for report’s generation and value convertion

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

Show child attributes

Report result

customer_id

integer

The id of the customer

connection_ids

array of strings

Ids of Connections included in report

connections

array of objects

Show child attributes

Information related to connections included in report

currency_code

string

Main currency code used for report’s generation and value convertion

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

start_date_amount

decimal

Opening balance. The balance before the first transaction was imported

end_date_amount

decimal

Closing balance. The balance after the last transaction was imported

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

Show child attributes

Average balance

forecasted_average

object

Show child attributes

Forecasted average balance

start_date_amount

decimal

Opening balance. The balance before the first transaction was imported

end_date_amount

decimal

Closing balance. The balance after the last transaction was imported

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

Show child attributes

Average balance

forecasted_average

object

Show child attributes

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

start_date

date

The date of the first income/expense transaction

end_date

date

The date of the last income/expense transaction

transactions_count

integer

Number of income/expense transactions

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

Show child attributes

Total amount of income/expense per each month

average

object

Show child attributes

Average amount of income/expense

forecasted_average

object

Show child attributes

Forecasted average amount of income/expense

streams

object

Show child attributes

Information on income/expense a customer receives/spends on a regular/irregular basis

start_date

date

The date of the first income/expense transaction

end_date

date

The date of the last income/expense transaction

transactions_count

integer

Number of income/expense transactions

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

Show child attributes

Total amount of income/expense per each month

average

object

Show child attributes

Average amount of income/expense

forecasted_average

object

Show child attributes

Forecasted average amount of income/expense

streams

object

Show child attributes

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

Show child attributes

Information related to net savings per each month

average

object

Show child attributes

Average savings

forecasted_average

object

Show child attributes

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

Show child attributes

Information related to net savings per each month

average

object

Show child attributes

Average savings

forecasted_average

object

Show child attributes

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

Show child attributes

Information on the expense categories a customer spends money on.

Note: outbound transfers are not considered.

categories

array of objects

Show child attributes

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

Show child attributes

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

Show child attributes

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

Show child attributes

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

Show child attributes

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

Show child attributes

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

Show child attributes

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
    }
  }
}