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

Errors 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

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

Show merchants

Merchant identification is an option that allows you to get more information about transaction merchants during data aggregation.

To fetch the additional info about merchants, pass the desired merchant_ids in an array.

Attributes

id
string

merchant id

names
array of objects

merchant names
Possible values for mode field: name, transliterated_name, alternative_name, brand, operator

address
object

merchant location

contact
array of objects

merchant contact information
Possible values for mode field: email, viber, phone, fax, website, facebook, twitter, google_plus, linkedin, instagram, skype, vk, flickr, youtube

Possible Errors

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

Sample Response

{
  "data": [
    {
      "id": "0e81d5f8be1e3e73e4e604a36...",
      "names": [
        {
          "mode": "name",
          "value": "Sainsbury's to you"
        },
        {
          "mode": "transliterated_name",
          "value": "sainsburys to you"
        }
      ],
      "address": {
        "country_code": "GB",
        "city": "London",
        "transliterated_city": "london",
        "coordinates": {
          "latitude": "0.0100",
          "longitude": "0.0200"
        }
      },
      "contact": [
        {
          "mode": "email",
          "value": "sainsburys_email_1@gmail.com"
        },
        {
          "mode": "twitter",
          "value": "sainsburys.twitter1"
        },
        {
          "mode": "viber",
          "value": "+47712345678"
        }
      ]
    },
    {
      "id": "b3e8ec2349df872072c051e0c...",
      "names": [
        {
          "mode": "name",
          "value": "Debenhams"
        },
        {
          "mode": "transliterated_name",
          "value": "debenhams"
        }
      ],
      "address": {
        "country_code": "GB",
        "city": "London",
        "transliterated_city": "london",
        "coordinates": {
          "latitude":  "0.0100",
          "longitude": "0.0200"
        }
      },
      "contact": []
    }
  ]
}

Categorize 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)

currency_code
string, optional

the code of the currency, present in SaltEdge API

country_code
string, optional

the code of the country, present in SaltEdge API

amount
decimal, optional

the amount of the transaction

category
string, optional

the new category code for the description, used with action: learn

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

identifier
string, optional

a unique identifier of the transaction object (max 255 chars).

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

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

Learn category

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

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

Possible Errors

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

Sample Response

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