Errors

The API can return multiple errors for any operation, each having its meaning and usage.

Error attributes

error_class: string
the class of the error, one of the listed below
error_message: string
a message describing the error
request: object
the body of the request that caused the error

error_class: string
the class of the error, one of the listed below
error_message: string
a message describing the error
request: object
the body of the request that caused the error

Error codes

[400] Bad Request
[404] Not Found
[406] Not Acceptable
[409] Duplicated

Sample response

{
  "error_class": "BatchSizeLimitExceeded",
  "error_message": "Batch size limit (100 transactions) was exceeded."
}

List

ActionNotAllowed: The client has no access to the required route
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
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 incorrectly formed

ActionNotAllowed: The client has no access to the required route
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
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 incorrectly formed

Categories

Salt Edge API uses an algorithm for automatic categorization of 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.

How to use

By default transactions are categorized, using the list of personal categories , via parameter categorization set on routes: logins #create, #refresh, #reconnect or tokens #create, #refresh, #reconnect, as you need.

We also expose an API route for your applications to improve the categorization process based on your user’s behaviors.

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:

Business Categories
Personal Categories

URL

https://www.saltedge.com/api/v4/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/v4/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/v4/categories

Sample Response

{
  "data": {
    "business": {
      "cost_of_goods": [
        "raw_materials",
        "merchandise"
      ],
      "financials": [
        "dividends",
        "donations",
        "interest",
        "fees",
        "fines"
      ],
      "human_resources": [
        "wages",
        "bonus",
        "social_security",
        "education_and_trainings",
        "staff_outsourcing"
      ],
      "income": [
        "investment",
        "sales",
        "returns"
      ],
      "insurance": [
        "business_insurance",
        "liability_insurance",
        "health_insurance",
        "equipment_insurance",
        "professional_insurance"
      ],
      "office": [
        "office_rent",
        "equipment",
        "software",
        "office_supplies"
      ],
      "services": [
        "contractors",
        "accounting",
        "legal",
        "consultancy",
        "storage",
        "marketing",
        "online_subscriptions"
      ],
      "taxes": [
        "vat",
        "federal_taxes",
        "property_taxes",
        "income_taxes",
        "duty_taxes",
        "tax_return"
      ],
      "transport": [
        "shipping",
        "leasing",
        "gas_and_fuel",
        "taxi"
      ],
      "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_and_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": []
    }
  }
}

Business

Business Categories include:

cost_of_goods: Refers to equipment and materials intended for consumption in the production process and includes subcategories:
raw_materials: Raw materials, as wood, textil, glass, plastic
merchandise: Various consumer goods

cost_of_goods: Refers to equipment and materials intended for consumption in the production process and includes subcategories:
raw_materials: Raw materials, as wood, textil, glass, plastic
merchandise: Various consumer goods

financials: Covers company’s financial operations and includes subcategories:
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

financials: Covers company’s financial operations and includes subcategories:
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

human_resources: Used for transactions, linked to human resources issues and includes subcategories:
wages: Paychecks, wages
bonus: Bonuses, rewards added to wages for good performance
social_security: 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

human_resources: Used for transactions, linked to human resources issues and includes subcategories:
wages: Paychecks, wages
bonus: Bonuses, rewards added to wages for good performance
social_security: 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

income: Covers different types of income and includes subcategories:
investment: Money investments to investment funds, saving deposits, mutual funds
sales: Sales income
returns: Sales returns, online orders returns

income: Covers different types of income and includes subcategories:
investment: Money investments to investment funds, saving deposits, mutual funds
sales: Sales income
returns: Sales returns, online orders returns

insurance: Implies deals with insurance companies and includes subcategories:
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
professional_insurance: Professional liability insurance policies, civil liability insurance

insurance: Implies deals with insurance companies and includes subcategories:
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
professional_insurance: Professional liability insurance policies, civil liability insurance

office: Implies products and services for office and includes subcategories:
office_rent: Rental of a property used for business purposes
equipment: Equipment and materials, used by a company
software: Any software or set of computer programs
office_supplies: Stationery, office supplies, printing paper

office: Implies products and services for office and includes subcategories:
office_rent: Rental of a property used for business purposes
equipment: Equipment and materials, used by a company
software: Any software or set of computer programs
office_supplies: Stationery, office supplies, printing paper

services: Implies miscellaneous services for business and includes subcategories:
contractors: Services delivered by contractors
accounting: Accounting, auditing, bookkeeping services
legal: Legal support services; attorneys
consultancy: Consulting services
storage: Warehousing services; goods storage
marketing: Marketing and media services; advertising
online_subscriptions: Online subscriptions, web hosting, data storage

services: Implies miscellaneous services for business and includes subcategories:
contractors: Services delivered by contractors
accounting: Accounting, auditing, bookkeeping services
legal: Legal support services; attorneys
consultancy: Consulting services
storage: Warehousing services; goods storage
marketing: Marketing and media services; advertising
online_subscriptions: Online subscriptions, web hosting, data storage

taxes: Covers different types of taxes and includes subcategories:
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

taxes: Covers different types of taxes and includes subcategories:
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

transport: Used for transactions, related to cars and other modes of transport and includes subcategories:
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

transport: Used for transactions, related to cars and other modes of transport and includes subcategories:
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

uncategorized: Uncategorized

uncategorized: Uncategorized

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, enegry supplies

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, enegry supplies

Personal

Personal Categories include:

auto_and_transport: Used for transactions, related to cars and other modes of transport and includes subcategories:
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

auto_and_transport: Used for transactions, related to cars and other modes of transport and includes subcategories:
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 and includes subcategories:
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

bills_and_utilities: Refers to the set of utility services and includes subcategories:
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 and includes subcategories:
advertising: Outdoor adverstisig; digital ads; social media marketing
office_supplies: Stationery, office supplies, printing paper
shipping: Logistics and delivery; courier services

business_services: Implies miscellaneous services for business, as accounting, consulting, marketing, legal, design and includes subcategories:
advertising: Outdoor adverstisig; 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 and includes subcategories:
books_and_supplies: Books, periodicals, eBook apps, e-readers
student_loan: Student loans
tuition: Tuition grants and scholarships; tuition fees

education: Applied for transactions with colleges, universities, schools, learning centers and includes subcategories:
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 and includes subcategories:
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

entertainment: Includes entertainment activities, as visits of aquariums, dolphinariums, zoos, museums, theaters and includes subcategories:
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 and includes subcategories:
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

fees_and_charges: Covers fees and charges and includes subcategories:
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 and includes subcategories:
alcohol_and_bars: Alcohol sellers, bars, pubs, nightclubs
cafes_and_restaurants: Cafes, restaurants, pizzerias, canteens, steakhouses, gelaterias, trattorias
groceries: Grocery stores, supermarkets

food_and_dining: Applied for transactions related to food and beverage products, dining, catering and includes subcategories:
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 and includes subcategories:
charity: Donations, charitable services
gifts: Greetings cards, gift and souvenir shops

gifts_and_donations: Refers to gifts and donations and includes subcategories:
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 and includes subcategories:
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

health_and_fitness: Covers goods and services for the maintenance or improvement of health and well-being and includes subcategories:
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 and includes subcategories:
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_and_rent: Real estate purchases and rentals, estate sale, mortgage loans

home: Applied for household goods, services for building or maintenance of houses and includes subcategories:
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_and_rent: Real estate purchases and rentals, estate sale, mortgage loans

income: Covers different types of earnings and includes subcategories:
bonus: Bonuses, rewards, cashback
investment_income: Capital gains, dividends, interest
paycheck: Salaries, wages

income: Covers different types of earnings and includes subcategories:
bonus: Bonuses, rewards, cashback
investment_income: Capital gains, dividends, interest
paycheck: Salaries, wages

insurance: Implies deals with insurance companies and includes subcategories:
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

insurance: Implies deals with insurance companies and includes subcategories:
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 and includes subcategories:
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

kids: Includes various child care activities and includes subcategories:
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 and includes subcategories:
pet_food_and_supplies: Products and food for pets
pet_grooming: Pet grooming services
veterinary: Pet health care including veterinary clinics, pharmacies

pets: Refers to pet stores, animal care and includes subcategories:
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 and includes subcategories:
clothing: Clothing, shoes, jewelry, sunglasses
electronics_and_software: Electronics, software, hardware, computers
sporting_goods: Equipment that completes the sport, as gym clothing, motorcycle gear

shopping: Covers shopping malls, e-commerce marketplaces, retail of particular goods and includes subcategories:
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

transfer: Includes money transfers; ATM cash withdrawals

travel: Covers travelling, travel agencies, tourism, excursions and includes subcategories:
hotel: Accommodation, hotels, motels, resorts
transportation: Air transportation, yachts
vacation: Holiday companies, specific trips or journies

travel: Covers travelling, travel agencies, tourism, excursions and includes subcategories:
hotel: Accommodation, hotels, motels, resorts
transportation: Air transportation, yachts
vacation: Holiday companies, specific trips or journies

uncategorized: Uncategorized

uncategorized: Uncategorized

Learn

You can change the category of some transactions, thus improving the categorization accuracy.

Custom category will be applicable only for customer’s new transactions, which have similar description. It will be located in transaction extra as customer_category_code or customer_category_name.

Post body

transaction_id: required
the id of the transaction
category_code: required
the new category code of the transaction
immediate: boolean optional
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 same category

transaction_id: required
the id of the transaction
category_code: required
the new category code of the transaction
immediate: boolean optional
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 same category

Possible Errors

ClientDisabled
ClientNotFound
JsonParseError
WrongRequestFormat

URL

https://www.saltedge.com/api/v4/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\": [ \
                { \
                  \"transaction_id\": \"123\", \
                  \"category_code\": \"paycheck\", \
                  \"immediate\": true \
                }, \
                { \
                  \"transaction_id\": \"124\", \
                  \"category_code\": \"car_rental\", \
                  \"immediate\": false \
                } \
              ] \
            }" \
        https://www.saltedge.com/api/v4/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\": [ \
                { \
                  \"transaction_id\": \"123\", \
                  \"category_code\": \"paycheck\", \
                  \"immediate\": true \
                }, \
                { \
                  \"transaction_id\": \"124\", \
                  \"category_code\": \"car_rental\", \
                  \"immediate\": false \
                } \
              ] \
            }" \
        https://www.saltedge.com/api/v4/categories/learn

Sample Response

{
  "data": {
    "learned": true
  }
}

Enrich transactions

Categorizes your transactions by the given parameters.

Request body

The request body is an array of objects wrapped in the data field. Each object has a description, currency_code and identifier fields. 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: text
additional information (recommended to use in concatenation with original description, if present)
amount: decimal, optional
the amount of the transaction
categorization: string, optional
the type of categorization applied. Possible values: none, personal, business. Default: 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 code of the currency, present in Salt Edge API
identifier: string, optional
a unique identifier of the transaction object (max 255 chars).
identify_merchant: boolean, optional
whether merchant identification was enabled
information: text, optional
information about the transaction
mcc: string, optional
the transaction’s Merchant Category Code
mode: string, optional
possible values are: normal, fee, transfer
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
status: string, optional
possible values are: posted, pending
tags: array of strings, optional
the original tags of the transaction

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: text
additional information (recommended to use in concatenation with original description, if present)
amount: decimal, optional
the amount of the transaction
categorization: string, optional
the type of categorization applied. Possible values: none, personal, business. Default: 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 code of the currency, present in Salt Edge API
identifier: string, optional
a unique identifier of the transaction object (max 255 chars).
identify_merchant: boolean, optional
whether merchant identification was enabled
information: text, optional
information about the transaction
mcc: string, optional
the transaction’s Merchant Category Code
mode: string, optional
possible values are: normal, fee, transfer
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
status: string, optional
possible values are: posted, pending
tags: array of strings, optional
the original tags of the transaction

Note: Custom categories will be located in transaction’s extra, see: customer_category_code and customer_category_name

Possible Errors

ActionNotAllowed
BatchSizeLimitExceeded
CategorizationLimitReached
ClientDisabled
ClientNotFound
WrongRequestFormat

URL

https://www.saltedge.com/api/v4/transactions/categorize

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\", \
                  \"currency_code\": \"USD\", \
                  \"identifier\": \"d5bb8cf037aa7f069\" \
                }, \
                { \
                  \"description\": \"Ebay\", \
                  \"country_code\": \"US\", \
                  \"amount\": 100 \
                } \
              ] \
            }" \
        https://www.saltedge.com/api/v4/transactions/categorize

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\", \
                  \"currency_code\": \"USD\", \
                  \"identifier\": \"d5bb8cf037aa7f069\" \
                }, \
                { \
                  \"description\": \"Ebay\", \
                  \"country_code\": \"US\", \
                  \"amount\": 100 \
                } \
              ] \
            }" \
        https://www.saltedge.com/api/v4/transactions/categorize

Sample Response

{
  "data": [
    {
      "description": "Itunes",
      "identifier": "d5bb8cf037aa7f069",
      "currency_code": "USD",
      "category": "electronics_and_software",
      "made_on": "2016-08-16",
      "amount": 1,
      "mode": "normal",
      "status": "posted",
      "extra": {}
    },
    {
      "description": "",
      "identifier": null,
      "currency_code": "EUR",
      "category": "uncategorized",
      "made_on": "2016-08-16",
      "amount": 1,
      "mode": "normal",
      "status": "posted",
      "extra": {},
      "errors": [
          "Description can't be blank"
      ]
    }
  ]
}

Merchants

Merchant represents a company, that sells goods or provides services to the Customer.

Identification

Merchant identification is an option that allows to identify merchant names and other useful information about them, basing on transactions’ data.

This option is country based and currently is available in 13 countries - UK, Italy, Czech Republic, Australia, Russia, India, Singapore, Romania, Austria, Hungary, Latvia, Germany, Netherlands and the list will continue to grow.

How to use

To start using this option, all you need to do is:

pass identify_merchant: true on logins #create, #refresh, #reconnect or tokens #create, #refresh, #reconnect. When the login creation succeeds and only if the merchant is identified, you will receive a merchant_id in the extra field of the transaction;
send all the merchant_ids you want to fetch the additional info for, to merchants.

Also, you can test it, using the fakebank_simple_xf provider, available for the fake XF country.

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/v4/merchants.

Please note, that the first priority of this feature is to identify merchant name, that’s why arrays with name and transliterated_name are always presented.

Sometimes, in transaction’s descriptional fields, can be presented additional information about merchant, 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 done. If we found point of sale, corresponding to transaction, in our database, we can return more granular information with contact and address details, including geo-coordinates.

Attributes

id: string
merchant id
names: array of objects
merchant names; there are used to name a company, corporation, brand name, franchise name or any other entity who is participated in Customer’s transaction
Possible values for mode field: 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, which makes merchant accessible via website, phone or social media
Possible values for mode field: email, viber, phone, fax, website, facebook, twitter, google_plus, linkedin, instagram, skype, vk, flickr, youtube

id: string
merchant id
names: array of objects
merchant names; there are used to name a company, corporation, brand name, franchise name or any other entity who is participated in Customer’s transaction
Possible values for mode field: 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, which makes merchant accessible via website, phone or social media
Possible values for mode field: email, viber, phone, fax, website, facebook, twitter, google_plus, linkedin, instagram, skype, vk, flickr, youtube

Possible Errors

ClientDisabled
ClientNotFound
JsonParseError
WrongRequestFormat

URL

https://www.saltedge.com/api/v4/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\": [ \
                \"0e81d5f8be1e3e73e4e604a36...\", \
                \"b3e8ec2349df872072c051e0c...\" \
              ] \
            }" \
        https://www.saltedge.com/api/v4/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\": [ \
                \"0e81d5f8be1e3e73e4e604a36...\", \
                \"b3e8ec2349df872072c051e0c...\" \
              ] \
            }" \
        https://www.saltedge.com/api/v4/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"
        }
      }
    }
  ]
}

General

API Reference

Errors

Error attributes

Error codes

Sample response

List

Categories

How to use

Business

Personal

Learn

Post body

Possible Errors

URL

Method

Authentication

Sample request

Sample Response

Enrich transactions

Request body

Parameters

Possible Errors

URL

Method

Sample request

Sample Response

Merchants

Identification

How to use

Show

Attributes

Possible Errors

URL

Method

Authentication

Sample request

Sample Response