Data types

All of the responses returned by Spectre API are in the JSON format. The description of the data types encoded in a JSON response is below.

boolean
true or false

a boolean value

date

a date in the YYYY-MM-DD format

datetime

a date in the ISO-8601 format

float

a value corresponding to a real number using the double-precision representation

integer

a value corresponding to a integer number

object

a string representing a JSON object (please refer to the RFC 4627 for more information)

string

a UTF-8 compatible sequence of characters

Pagination

Most Spectre API routes return lists of paginated objects instead of the whole amount. The data you receive is divided into smaller chunks of data called pages.

By default, when you request a list of paginated resources, you will get a next_id in the meta object response. The value of the next_id equals to the resource_id next page will start with.

If you wish to customize the number of items you get per page, you should send the per_page attribute ranging between 100 and 1000 items in the request, which shows how many items you will receive per page. If no per_page parameter is sent, 100 items will be received by default.

In order to get all the data, you should send an additional from_id parameter with the corresponding id, or use the next_page attribute to query the next page.

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v3/logins?per_page=150

Sample Response

{
  "data": [
    {
      "country_code": "XF",
      "created_at": "2017-05-23T17:35:06Z",
      "customer_id": 905,
      "id": 156,
      "last_attempt": {
          "api_mode": "service",
          "api_version": "3",
          "automatic_fetch": true,
          "categorize": true,
          "created_at": "2017-05-24T16:55:06Z",
          "custom_fields": {},
          "device_type": "desktop",
          "remote_ip": "93.184.216.34",
          "exclude_accounts": [],
          "fail_at": null,
          "fail_error_class": null,
          "fail_message": null,
          "fetch_type": "recent",
          "finished": true,
          "finished_recent": true,
          "from_date": null,
          "id": 425036,
          "interactive": false,
          "partial": false,
          "store_credentials": true,
          "success_at": "2017-05-24T16:55:06Z",
          "to_date": null,
          "updated_at": "2017-05-24T16:55:06Z",
          "last_stage": {
            "created_at": "2017-05-24T16:55:06Z",
            "id": 2691802,
            "interactive_fields_names": null,
            "interactive_html": null,
            "name": "finish",
            "updated_at": "2017-05-24T16:55:06Z"
          }
      },
      "last_success_at": "2017-05-24T16:55:06Z",
      "next_refresh_possible_at": "2017-05-24T18:35:06Z",
      "provider_code": "fakebank_simple_xf",
      "provider_name": "Fakebank Simple",
      "status": "active",
      "updated_at": "2017-05-24T16:55:06Z"
    },
    ...
  ],
  "meta": {
    "next_id":175,
    "next_page":"/api/v3/logins?from_id=175&per_page=150"
  }
}

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": "LoginNotFound",
  "message": "Login with id: '987' was not found.",
  "request": {
    "login_id": 987
  }
}

Errors list

AccountNotFound

An account with the sent account_id could not be found

ActionNotAllowed

The client has no access to the required route

AllAccountsExcluded

You have excluded all the accounts from the login fetching process

AttemptNotFound

An attempt with such id does not exist

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

ClientIdNotProvided

The Client-id was not provided in request headers

ClientNotFound

The Client-id and Client-secret fields do not coincide

ClientPending

The client is pending approval. You can find out more about the pending status on Pending guides page

ClientRestricted

The client is in the Restricted state. You can find out more about the restricted status on Restricted guides page

ConnectionFailed

Some network errors appear while fetching data

CountryNotFound

Sending a country_code that is not present in our system

CustomerNotFound

A customer with such customer_id could not be found

CredentialsNotMatch

New login credentials do not match old ones on reconnect

CustomFieldsSizeTooBig

The custom_fields object has more than 1 KB

CustomFieldsFormatInvalid

The custom_fields field is not of type object

DateFormatInvalid

We have received an invalid Date format

DateOutOfRange

Sending a date value that does not fit in admissible range

DuplicatedCustomer

The customer you are trying to create already exists

EmailInvalid

The email is invalid

ExecutionTimeout

The whole fetching process took too long to execute

ExpiresAtInvalid

The Expires-at header is invalid, or is set to more than 1 hour from now in UTC

FetchingTimeout

One of the steps of the fetching process took too long to execute

FetchTypeNotAllowed

The value of fetch_type parameter is not allowed

FileError

There were errors while uploading and processing files

FileNotProvided

Provider with the file mode was chosen, but no file was uploaded before creating or reconnecting a login

FileNotSaved

File was not saved because of an error

HolderInfoNotSupported

Fetching holder info for this provider is not supported

IdentifierInvalid

Invalid identifier sent for identifying the customer

InteractiveAdapterTimeout

The interactive step of the fetching process took too long to execute

InteractiveTimeout

It took too long to respond to the interactive question

InternalServerError

An internal error has occured

InvalidCredentials

The customer tried to connect/reconnect a login with invalid credentials

InvalidEncoding

Invalid JSON encoded values

InvalidFromDate

Invalid from_date value, whether out of range or wrong date format

InvalidInteractiveCredentials

Interactive credentials that were sent are wrong

InvalidToDate

Invalid to_date value, whether out of range or wrong date format

JsonParseError

We have received some other request format instead of JSON, or the body could not be parsed

LoginAlreadyProcessing

The login is already being processed

LoginCannotBeRefreshed

Login cannot be refreshed right now

LoginDisabled

The customer tried to connect, reconnect or fetch a login, but it appears to be disabled

LoginDuplicated

The client tried to create a login that already exists

LoginFetchingStopped

Login fetching had stopped because of fetching timeout or login was deleted during fetch process

LoginLimitReached

The client tried to create more logins than possible for a client which is in Test or Pending status

LoginNotFound

We could not find a login with the requested login_id

MissingExpiresAt

The Expires-at field is missing in the headers

MissingSignature

The Signature field is missing in the headers

ProviderAccessNotGranted

The customer denied access to his data from the provider’s page

ProviderDisabled

The accessed provider is disabled

ProviderError

There’s an error on the provider’s side which obstructs us from obtaining the data for the login

ProviderInactive

The accessed provider is inactive at the moment

ProviderNotFound

Sending a provider_code that is not present in our system

ProviderNotInteractive

The login’s provider has no interactive step

ProviderUnavailable

The provider is temporary unavailable

PublicKeyNotProvided

The client did not provide the public key in his account information

RateLimitExceeded

Too many logins are being processed at the same time from one application

RequestExpired

The request has expired, took longer than mentioned in the Expires-at header

ReturnURLInvalid

The return_to URL is invalid

ReturnURLTooLong

The return_to URL exceeds 512 characters

RouteNotFound

The action you are trying to access deos not exist

SecretNotProvided

The App-secret or Service-secret was not provided in request headers

SignatureNotMatch

The Signature header does not match with the correct one

TooManyRequests

Too many requests have occured for connecting/reconnecting a login from one IP address in a small period of time

TransactionNotFound

A transaction with the sent transaction_id could not be found

ValueOutOfRange

Sending a value (e.g. id) which exceeds integer limit

WrongClientToken

We have received a wrong combination of customer_id, client_id and login_id

WrongProviderMode

We do not support the received provider_mode

WrongRequestFormat

The JSON request is incorrectly formed

Client

A Client is the entity that will be consuming our API.

Client attributes

settings

general client settings

email
string email of the client
success_url
string success callback URL
fail_url
string fail callback URL
notify_url
string notify callback URL
destroy_url
string destroy callback URL
interactive_url
string interactive callback URL
info

client info

status
string possible values: pending, disabled, test, live, restricted
signed_up_at
datetime time when the client signed up
activated_at
datetime time when the client became live
last_request_sent_at
datetime time when last request was sent
last_callback_received_at
datetime time when last callback was received
customers

data about all the client’s customers

total
integer the total number of customers
logins

data about all of the client’s logins

total
integer number of registered logins
active
integer number of active logins, will be shown if active logins exist
inactive
integer number of inactive logins, will be shown if inactive logins exist
disabled
integer number of disabled logins, will be shown if disabled logins exist

Sample Object

{
  "data": {
    "settings": {
      "email": "john@smith.com",
      "success_url": "https://api.saltedge.com/se_api/success",
      "fail_url": "https://api.saltedge.com/se_api/failure",
      "notify_url": "https://api.saltedge.com/se_api/notify",
      "destroy_url": "https://api.saltedge.com/se_api/destroy",
      "interactive_url": "https://api.saltedge.com/se_api/interactive"
    },
    "info": {
      "status": "test",
      "signed_up_at": "2017-05-22T17:35:06Z",
      "activated_at": "2017-05-21T17:35:06Z",
      "last_request_sent_at": "2017-05-23T17:35:06Z",
      "last_callback_received_at": "2017-05-24T12:35:06Z"
    },
    "customers": {
      "total": 78
    },
    "logins": {
      "total": 123,
      "active": 100,
      "inactive": 20,
      "disabled": 3
    }
  }
}

Client info

You can query the information about a client. Available only for web applications, no such route exists for mobile ones.

Response

The response is a client object wrapped in a data attribute.

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v3/client/info

Countries

The country is represented just as a string. We’re using ISO 3166-1 alpha-2 country codes. Thus, all the country codes will have exactly two uppercase letters. There are two special cases:

  • “Other”, encoded as XO
  • “Fake”, encoded as XF

Note that the Fake country is only available for clients in Test and Pending statuses.

Listing countries

Returns a list of countries supported by Spectre API.

Parameters

include_fake_providers
boolean, optional

whether you wish to fetch the fake countries, defaults to false

Response

name
string

name of the country

code
string

country code as dated in ISO 3166-1 alpha-2

refresh_start_time
integer

local country time when logins will be automatically refreshed. Possible values: 0 to 23

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v3/countries

Sample Response

{
  "data": [
    {
      code: "CZ",
      name: "Czech Republic",
      refresh_start_time: 2
    },
    {
      code: "IL",
      name: "Israel",
      refresh_start_time: 2
    },
    {
      code: "MD",
      name: "Moldova",
      refresh_start_time: 2
    },
    {
      code: "RO",
      name: "Romania",
      refresh_start_time: 2
    },
    {
      code: "RU",
      name: "Russia",
      refresh_start_time: 2
    },
    {
      code: "UA",
      name: "Ukraine",
      refresh_start_time: 2
    },
    {
      code: "XF",
      name: "Fake",
      refresh_start_time: 2
    },
    {
      code: "XO",
      name: "Other",
      refresh_start_time: 2
    },
    ...
  ]
}

Providers

A provider is a source of financial data. We recommend you update all of the provider’s fields at least daily.

Attributes

id
integer

provider’s id

code
string

provider’s code

name
string

provider’s name

mode
string

possible values are: oauth, web, api, file

status
string

possible values are: active, inactive, disabled

automatic_fetch
boolean

whether the provider’s logins can be automatically fetched

customer_notified_on_sign_in
boolean

whether the provider will notify the customer on log in attempt

interactive
boolean

whether the provider requires interactive input

instruction
string

instructions on how to connect the bank, in English

home_url
string

the url of the main page of the provider

login_url
string

point of entrance to provider’s login web interface

forum_url
string

the url for the Salt Edge Forum page, dedicated to the provider

country_code
string

code of the provider’s country

refresh_timeout
integer

amount of time (in minutes) after which the provider’s logins are allowed to be refreshed

holder_info
array

contains information on the account holder details that can be fetched from this provider

created_at
datetime
updated_at
datetime

Sample object

{
  "id": 123,
  "code": "fakebank_simple_xf",
  "name": "Fake Bank",
  "mode": "web",
  "status": "active",
  "automatic_fetch": true,
  "customer_notified_on_sign_in": false,
  "interactive": false,
  "instruction": "Please fill in all the fields.",
  "home_url": "http://example.com",
  "login_url": "http://example.com/login",
  "forum_url": "https://forum.saltedge.com/themes/xf/forums/fake/all",
  "country_code": "XF",
  "refresh_timeout": 60,
  "holder_info": ["names", "emails", "phone_numbers"],
  "created_at": "2017-05-14T17:35:06Z",
  "updated_at": "2017-05-19T17:35:06Z"
}

Provider show

Provider show allows you to inspect the single provider in order to give your users a proper interface to input their credentials. The response will have an array of required_fields and interactive_fields, which are explained in more detail in the create section of this reference.

Parameters

provider_code
string

provider’s code

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v3/providers/fakebank_simple_xf

Sample response

{
  "data": {
    "id": 123,
    "automatic_fetch": true,
    "customer_notified_on_sign_in": false,
    "code": "fakebank_simple_xf",
    "country_code": "XF",
    "created_at": "2014-02-07T12:56:54Z",
    "forum_url": "https://forum.banksalt.com/themes/xf/forums/fakebank_simple_xf/all",
    "home_url": "http://example.com",
    "instruction": "Fill in all the fields",
    "interactive": false,
    "login_url": "http://example.com/login",
    "mode": "web",
    "name": "Fake Bank Simple",
    "refresh_timeout": 60,
    "holder_info": ["names", "emails", "phone_numbers"],
    "required_fields": [
      {
        "english_name": "Login",
        "localized_name": "Login",
        "name": "login",
        "nature": "text",
        "optional": false,
        "position": 1
      },
      {
        "english_name": "Password",
        "localized_name": "Password",
        "name": "password",
        "nature": "password",
        "optional": false,
        "position": 2
      }
    ],
    "status": "active",
    "updated_at": "2014-06-06T13:34:35Z"
  }
}

Listing providers

Returns all the providers we operate with. If a provider becomes disabled, it is not included in the list. You can read more about the next_id field, in the pagination section of the reference.

Parameters

from_id
integer, optional

the id of the record starting the next page, defaults to null

from_date
date, optional

filtering providers created or updated starting from this date, defaults to null

country_code
string, optional

filtering providers by country, defaults to null

mode
string, optional

filtering providers by mode, possible values are: oauth, web, api, file

include_fake_providers
boolean, optional

whether you wish to fetch the fake providers, defaults to false

include_provider_fields
boolean, optional

whether you wish to include all provider fields in the provider objects, defaults to false

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v3/providers

Sample Response

{
  "data": [
    {
      "id": 123,
      "code": "fakebank_image_xf",
      "name": "Fake Bank with Image",
      "mode": "web",
      "status": "active",
      "automatic_fetch": false,
      "customer_notified_on_sign_in": true,
      "interactive": true,
      "instruction": "Please fill in all the fields.",
      "home_url": "http://example.com",
      "login_url": "http://example.com/login",
      "forum_url": "http://forum.banksalt.com/themes/xf/forums/fakebank_image_xf/all",
      "country_code": "XF",
      "refresh_timeout": 60,
      "holder_info": ["names", "emails", "phone_numbers"],
      "created_at": "2017-05-14T17:35:06Z",
      "updated_at": "2017-05-19T17:35:06Z"
    }
  ],
  "meta": {
    "next_id": null,
    "next_page": null
  }
}

Provider fields

There are several types of fields as marked by their nature attribute:

nature
string

possible values are: text, password, select, file

name
string

the field’s name that should be used as a key in the credentials object

english_name
string

the field’s name in US English

localized_name
string

the name of the field in the provider’s main language

position
integer

field’s position in the public user interface

optional
boolean

whether the input for this field is required by the provider

field_options
object

only for the select field type. Contains the options for the select

Example object

  {
    "nature":         "text",
    "name":           "login",
    "english_name":   "Username",
    "localized_name": "Utilizator",
    "optional":       false,
    "position":       1
  }

Provider field options

Some providers ask their users to select a secret word or an answer to a question as a security measure.

In this case, the provider will contain a field of select type. The field will contain an array of field_options objects, which describe the possible choices for the user.

name
string

the name of the field option

english_name
string

the option’s name in US English

localized_name
string

the name of the field in the provider’s main language

option_value
string

the value of the option that needs to be passed as credentials

selected
boolean

whether the choice is selected by default

Example object

  {
    "name":           "home",
    "english_name":   "Home",
    "localized_name": "Casa",
    "option_value":   "home",
    "selected":       true
  }

Customers

A customer represents a person who will be using your application. You need to store the id returned from the response in your application, which is necessary when creating logins. We give you the following customer API actions so that the customer will be successfully identified within Salt Edge.

Create customer

Creates a customer, returning the customer object.

Parameters

identifier
string, required

a unique identifier of the new customer

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"identifier\": \"12rv1212f1efxchsdhbgv\" \
              } \
            }" \
        https://www.saltedge.com/api/v3/customers/

Sample Response

{
  "data": {
    "id":         18892,
    "identifier": "12rv1212f1efxchsdhbgv",
    "secret":     "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8"
  }
}

Show customer

Returns the customer object.

Parameters

id
integer, required

the id of the customer

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v3/customers/18892

Sample Response

{
  "data": {
    "id":         18892,
    "identifier": "12rv1212f1efxchsdhbgv",
    "secret":     "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8"
  }
}

List customers

List all of your app’s customers. This route is available only for web applications, not mobile ones.

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v3/customers

Sample Response

{
  "data": [
    {
      "id":         123,
      "identifier": "unique_customer_identifier",
      "secret":     "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8"
    },
    {
      "id":         124,
      "identifier": "unique_customer_identifier_2",
      "secret":     "Ct124tk12j0129i10-1j2k124kgk1lgqvUJ8CIC80-8"
    }
  ],
  "meta": {
    "next_id": 125,
    "next_page": "/api/v3/customers?from_id=125"
  }
}

Remove customer

Deletes a customer, returning the customer object. Only available for web applications.

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X DELETE \
        https://www.saltedge.com/api/v3/customers/124

Sample Response

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

Tokens

We use tokens to identify clients who will use Salt Edge Connect. With a token, you will be able to let your users connect, reconnect or refresh a login. Note that the token will expire in 60 seconds if you do not access Salt Edge Connect. After the token has been used to redirect the user to Salt Edge Connect, the user will have 10 minutes to fill in the necessary data. Afterwards, the user’s session will expire.

Before acquiring a token, you should be sure that the user exists in the system, or you should create one.

If your status is Pending, you will receive a ClientPending error when connecting any login not from the fake providers.

You can read more about tokens in the Tokens guides page.

Create

Allows you to create a token, which will be used to access Salt Edge Connect for login creation. You will receive a connect_url field, which allows you to enter directly to Salt Edge Connect with your newly generated token.

Parameters

customer_id
integer, required

the ID of the customer received from customer create

allowed_countries
array of strings, optional

the list of countries that will be accessible in Salt Edge Connect, defaults to null. Example: ['US', 'DE']

provider_code
string, optional

the code of the desired provider, defaults to null

fetch_type
string, optional

fetching mode, possible values: recent, accounts, custom. Default value: recent

custom_fields
object, optional

a JSON object, which will be sent back on any of your callbacks

daily_refresh
boolean, optional

whether the login should be automatically refreshed by Salt Edge

from_date
date, optional

date from which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidFromDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow

to_date
date, optional

date until which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidToDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow

locale
string, optional

the language of the Salt Edge Connect page in the ISO 639-1 format. Possible values are: uk, bg, de, pl, en, ru, ro, it, he, es, pt-BR, defaults to en

return_to
string, optional

the URL the user will be redirected to, defaults to client’s home URL

return_login_id
boolean, optional

whether to append login_id to return_to URL. Defaults to false

provider_modes
array of strings, optional

restrict the list of the providers to only the ones that have the mode included in the array.

Possible values inside the array are: oauth, web, api, file, defaults to the array containing all possible modes

categorize
boolean, optional

the flag allows you to specify whether the transactions of this login should be categorized or not. Defaults to true

javascript_callback_type
string, optional

allows you to specify what kind of callback type you are expecting. Possible values: iframe, external_saltbridge, external_notify, post_message. Defaults to null, which means that you will not receive any callbacks.

include_fake_providers
boolean, optional

being live, the customer will not be able to create fake provider logins. This flag allows it; if sent as true the customer will have the possibility to create any available fake provider logins. Defaults to false

credentials_strategy
string, optional

the strategy of storing customers credentials. Possible values: store, do_not_store, ask. Default value: store.
Note: If the value is ask, on the Connect page customer will be able to choose whether to save or not his credentials on SaltEdge side

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"customer_id\": 5122311, \
                \"fetch_type\": \"recent\" \
              } \
            }" \
        https://www.saltedge.com/api/v3/tokens/create

Sample response

{
  "data": {
    "token": "GENERATED_TOKEN",
    "expires_at": "2017-05-24T18:35:07Z",
    "connect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
  }
}

Reconnect

Allows you to create a token, which will be used to access Salt Edge Connect to reconnect a login. You will receive a connect_url field, which allows you to enter directly to Salt Edge Connect with your newly generated token.

Parameters

login_id
integer, required

the ID of the login you wish to reconnect

locale
string, optional

the language of the Salt Edge Connect page in the ISO 639-1 format. Possible values are: uk, bg, de, pl, en, ru, ro, it, he, es, pt-BR, defaults to en

return_to
string, optional

URL the user will be redirected to, defaults to client’s home URL

fetch_type
string, optional

fetching mode, possible values: recent, accounts, custom. Default value: recent

custom_fields
object, optional

a JSON object, which will be sent back on any of your callbacks

daily_refresh
boolean, optional

whether the login should be automatically refreshed by Salt Edge

from_date
date, optional

date from which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidFromDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow

to_date
date, optional

date until which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidToDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow

exclude_accounts
array, optional

array of account IDs which will not be fetched. Defaults to empty array

return_login_id
boolean, optional

shows whether to append login_id to return_to URL. Defaults to false

provider_modes
array of strings, optional

restrict the list of the providers to only the ones that have the mode included in the array.

Possible values inside the array are: oauth, web, api, file, defaults to the array containing all possible modes

javascript_callback_type
string, optional

allows you to specify what kind of callback type are you expecting. Possible values: iframe, external_saltbridge, external_notify, post_message. Defaults to null, which means that you will not receive any callbacks.

categorize
boolean, optional

the flag allows you to specify whether the transactions of this login should be categorized or not. Defaults to true

include_fake_providers
boolean, optional

shows whether it would be possible to reconnect a fake provider or not in live mode. Defaults to false

credentials_strategy
string, optional

the strategy of storing customers credentials. Possible values: store, do_not_store, ask. Default value: store.
Note: If the value is ask, on the Connect page customer will be able to choose whether to save or not his credentials on SaltEdge side

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"login_id\": \"123\", \
                \"fetch_type\": \"recent\" \
              } \
            }" \
        https://www.saltedge.com/api/v3/tokens/reconnect

Sample response

{
  "data": {
    "token": "GENERATED_TOKEN",
    "expires_at": "2017-05-24T18:35:07Z",
    "connect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
  }
}

Refresh

Allows you to create a token, which will be used to access Salt Edge Connect to refresh a login. You will receive a connect_url field, which allows you to enter directly to Salt Edge Connect with your newly generated token.

Parameters

login_id
integer, required

the ID of the login you wish to reconnect

locale
string, optional

the language of the Salt Edge Connect page in the ISO 639-1 format. Possible values are: uk, bg, de, pl, en, ru, ro, it, he, es, pt-BR, defaults to en

fetch_type
string, optional

fetching mode, possible values: recent, accounts, custom. Default value: recent

custom_fields
object, optional

a JSON object, which will be sent back on any of your callbacks

daily_refresh
boolean, optional

whether the login should be automatically refreshed by Salt Edge

from_date
date, optional

date from which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidFromDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow

to_date
date, optional

date until which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidToDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow

exclude_accounts
array, optional

array of account IDs which will not be fetched. Defaults to empty array

return_to
string, optional

URL the user will be redirected to, defaults to client’s home URL

return_login_id
boolean, optional

shows whether to append login_id to return_to URL. Defaults to false

provider_modes
array of strings, optional

restrict the list of the providers to only the ones that have the mode included in the array.

Possible values inside the array are: oauth, web, api, file, defaults to the array containing all possible modes

javascript_callback_type
string, optional

allows you to specify what kind of callback type are you expecting. Possible values: iframe, external_saltbridge, external_notify, post_message. Defaults to null, which means that you will not receive any callbacks.

categorize
boolean, optional

the flag allows you to specify whether the transactions of this login should be categorized or not. Defaults to true

include_fake_providers
boolean, optional

shows whether it would be possible to refresh a fake provider or not in live mode. Defaults to false

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"login_id\": \"123\", \
                \"fetch_type\": \"recent\" \
              } \
            }" \
        https://www.saltedge.com/api/v3/tokens/refresh

Sample response

{
  "data": {
    "token": "GENERATED_TOKEN",
    "expires_at": "2017-05-24T18:35:07Z",
    "connect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
  }
}

OAuth Providers

Spectre API also allows your app to import data from a list of OAuth-supporting providers. The OAuth workflow, in this case, is reduced to a couple of HTTP calls and redirects.

Connecting OAuth providers logins is done via the same mechanism as when connecting a usual login - using tokens for connecting, reconnecting or refreshing. The response will contain a redirect_url and your app has to redirect the user to that URL.

The redirect_url points to a page where the user can provide Salt Edge access to their financial data, making it available for your app. After the user has approved Salt Edge in the OAuth provider’s interface, they will be redirected to the return_to page.

Create

Used to create a login for an OAuth provider. After receiving the response, the customer will be redirected to return_to URL.

Note that mobile clients receive a login_secret parameter in the return_to URL if the login was successfully connected and a error_message parameter. Also, return_to is optional for web clients.

Parameters

country_code
string, required

the code of the country

provider_code
string, required

the code of the provider

customer_id
integer, required

the ID of the customer received from customer create

return_to
string, required

the address your user will be redirected to after they grant or deny the access

daily_refresh
boolean, optional

whether the login should be automatically refreshed by Salt Edge

fetch_type
string, optional

fetching mode, possible values: recent, accounts, custom. Default value: recent

custom_fields
object, optional

a JSON object, which will be sent back on any of your callbacks

from_date
date, optional

date from which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidFromDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow

to_date
date, optional

date until which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidToDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow

locale
string, optional

the language of the provider error messages in the ISO 639-1 format. Possible values are: uk, bg, de, pl, en, ru, ro, it, he, es, pt-BR, defaults to en

return_login_id
boolean, optional

whether to append login_id to return_to URL. Defaults to false

categorize
boolean, optional

the flag allows you to specify whether the transactions of this login should be categorized or not. Defaults to true

include_fake_providers
boolean, optional

being live, the customer will not be able to create fake providers. This flag allows it, if sent as true the customer will have the possibility to create any fake provider available. Defaults to false

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"country_code\": \"XF\", \
                \"provider_code\": \"fakebank_oauth_xf\", \
                \"customer_id\": 5125125, \
                \"fetch_type\": \"recent\", \
                \"return_to\": \"http://example.com/\", \
                \"return_login_id\": false \
              } \
            }" \
        https://www.saltedge.com/api/v3/oauth_providers/create

Sample response

{
  "data": {
    "token": "GENERATED_TOKEN",
    "expires_at": "2017-05-24T18:35:07Z",
    "redirect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
  }
}

Reconnect

Used to reconnect a login for an OAuth provider. After receiving the response, the customer will be redirected to the return_to URL.

Note that mobile clients receive a login_secret parameter in the return_to URL and a error_message parameter if the login failed to connect for some reason. Also, return_to is optional for web clients.

Parameters

login_id
integer, required

the ID of the login that is to be reconnected

return_to
string, required

the address your user will be redirected to after they grant or deny access

daily_refresh
boolean, optional

whether the login should be automatically refreshed by Salt Edge

fetch_type
string, optional

fetching mode, possible values: recent, accounts, custom. Default value: recent

custom_fields
object, optional

a JSON object, which will be sent back on any of your callbacks

from_date
date, optional

date from which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidFromDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow

to_date
date, optional

date until which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidToDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow

locale
string, optional

the language of the provider error messages in the ISO 639-1 format. Possible values are: uk, bg, de, pl, en, ru, ro, it, he, es, pt-BR, defaults to en

exclude_accounts
array, optional

array of account IDs which will not be fetched. Defaults to empty array

return_login_id
boolean, optional

shows whether to append login_id to return_to URL. Defaults to false

categorize
boolean, optional

the flag allows you to specify whether the transactions of this login should be categorized or not. Defaults to true

include_fake_providers
boolean, optional

shows whether it would be possible to reconnect a fake provider or not in live mode. Defaults to false

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"login_id\": 123, \
                \"return_to\": \"http://example.com/\", \
                \"fetch_type\": \"recent\", \
                \"return_login_id\": false \
              } \
            }" \
        https://www.saltedge.com/api/v3/oauth_providers/reconnect

Sample response

{
  "data": {
    "token": "GENERATED_TOKEN",
    "expires_at": "2017-05-24T18:35:07Z",
    "redirect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
  }
}

Refresh

Used to refresh a login for an OAuth provider. After receiving the response, the customer will be redirected to return_to URL.

Note that mobile clients receive a login_secret parameter in the return_to URL and a error_message parameter if the login failed to connect for some reason. Also, return_to is optional for web clients.

Parameters

login_id
integer, required

the ID of the login that is to be reconnected

return_to
string, required

the address your user will be redirected to after they grant or deny access

daily_refresh
boolean, optional

whether the login should be automatically refreshed by Salt Edge

fetch_type
string, optional

fetching mode, possible values: recent, accounts, custom. Default value: recent

custom_fields
object, optional

a JSON object, which will be sent back on any of your callbacks

from_date
date, optional

date from which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidFromDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow

to_date
date, optional

date until which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidToDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow

locale
string, optional

the language of the provider error messages in the ISO 639-1 format. Possible values are: uk, bg, de, pl, en, ru, ro, it, he, es, pt-BR, defaults to en

exclude_accounts
array, optional

array of account IDs which will not be fetched. Defaults to empty array

return_login_id
boolean, optional

shows whether to append login_id to return_to URL. Defaults to false

categorize
boolean, optional

the flag allows you to specify whether the transactions of this login should be categorized or not. Defaults to true

include_fake_providers
boolean, optional

shows whether it would be possible to refresh a fake provider or not in live mode. Defaults to false

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"login_id\": 123, \
                \"return_to\": \"http://example.com/\", \
                \"fetch_type\": \"recent\", \
                \"return_login_id\": false \
              } \
            }" \
        https://www.saltedge.com/api/v3/oauth_providers/refresh

Sample response

{
  "data": {
    "token": "GENERATED_TOKEN",
    "expires_at": "2017-05-24T18:35:07Z",
    "redirect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
  }
}

Logins

The login resource represents a single connection of the client’s customer to a source of financial data – one of the providers.

Attributes

id
integer
provider_id
integer

the ID of the Provider the login belongs to

provider_code
string

the code of the Provider the login belongs to

provider_name
string

the name of the Provider the login belongs to

daily_refresh
boolean

whether the login will be refreshed daily

customer_id
integer

customer’s ID

created_at
datetime
updated_at
datetime
last_success_at
datetime

time when the login was successfully fetched

status
string

possible values are: active, inactive, disabled

country_code
string

code of the country the provider belongs to

next_refresh_possible_at
datetime

when the next refresh will be available. May contain null value if login has automatic_fetch set as false, or is already processing

store_credentials
boolean

whether the credentials were stored on our side

last_attempt
object, attempt object

last attempt of this login

holder_info
object, holder object

contains the account holder information

Sample object

{
  "country_code": "XF",
  "created_at": "2017-05-23T17:35:07Z",
  "customer_id": 905,
  "daily_refresh": false,
  "id": 1227,
  "last_attempt": {
      "api_mode": "service",
      "api_version": "3",
      "automatic_fetch": true,
      "daily_refresh": false,
      "categorize": true,
      "created_at": "2017-05-24T16:55:07Z",
      "custom_fields": {},
      "device_type": "desktop",
      "remote_ip": "93.184.216.34",
      "exclude_accounts": [],
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "fetch_type": "recent",
      "finished": true,
      "finished_recent": true,
      "from_date": null,
      "id": 425036,
      "interactive": false,
      "locale": "en",
      "partial": false,
      "store_credentials": true,
      "success_at": "2017-05-24T16:55:07Z",
      "to_date": null,
      "updated_at": "2017-05-24T16:55:07Z",
      "last_stage": {
        "created_at": "2017-05-24T16:55:07Z",
        "id": 2691802,
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "finish",
        "updated_at": "2017-05-24T16:55:07Z"
      }
  },
  "holder_info": {
    "names": ["John Doe"],
    "emails": ["john.doe@example.com", "johndoe@gmail.com"],
    "phone_numbers": ["+40981233422"],
    "addresses": [
      {
        "city": "Cupertino",
        "state": "CA",
        "street": "1 Infinite Loop",
        "country_code": "US",
        "post_code": "95014"
      }
    ]
  },
  "last_success_at": "2017-05-24T16:55:07Z",
  "next_refresh_possible_at": "2017-05-24T18:35:07Z",
  "provider_id": 1234,
  "provider_code": "fakebank_simple_xf",
  "provider_name": "Fakebank Simple",
  "status": "active",
  "store_credentials": true,
  "updated_at": "2017-05-24T16:55:07Z"
}

Holder Info

You can query essential information about the account holder. Make sure to request this feature to be enabled for your client account.

names
array

account holder name(s)

emails
array

account holder email(s)

phone_numbers
array

account holder phone number(s)

addresses
array of objects

account holder address(es)

Extra

Depending on provider, additional information on account holder might be available.

  • ssn - Social Security Number shortened (last 4 digits)
  • cpf - Cadastro de Pessoas Físicas (present in Brazil)

Sample Object

{
  "names": ["John Doe"],
  "emails": ["john.doe@example.com", "johndoe@gmail.com"],
  "phone_numbers": ["+40981233422"],
  "addresses": [
    {
      "city": "Cupertino",
      "state": "CA",
      "street": "1 Infinite Loop",
      "country_code": "US",
      "post_code": "95014"
    }
  ]
}

Listing logins

Returns all the logins accessible to your application. The logins are sorted in ascending order of their ID, so the newest logins will come last. We recommend you fetch the whole list of logins to check whether any of the properties have changed. You can read more about next_id field, in the pagination section of the reference.

Parameters

from_id
integer, optional

the id of the record starting the next page

customer_id
integer, optional

the id of the customer, allows to fetch logins only for a certain customer

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v3/logins

Sample Response

{ "data":
  [
    {
      "country_code": "XF",
      "created_at": "2017-05-23T17:35:07Z",
      "customer_id": 905,
      "daily_refresh": false,
      "id": 1227,
      "last_attempt": {
          "api_mode": "service",
          "api_version": "3",
          "automatic_fetch": true,
          "daily_refresh": false,
          "categorize": true,
          "created_at": "2017-05-24T16:55:07Z",
          "custom_fields": {},
          "device_type": "desktop",
          "remote_ip": "93.184.216.34",
          "exclude_accounts": [],
          "fail_at": null,
          "fail_error_class": null,
          "fail_message": null,
          "fetch_type": "recent",
          "finished": true,
          "finished_recent": true,
          "from_date": null,
          "id": 425036,
          "interactive": false,
          "locale": "en",
          "partial": false,
          "store_credentials": true,
          "success_at": "2017-05-24T16:55:07Z",
          "to_date": null,
          "updated_at": "2017-05-24T16:55:07Z",
          "last_stage": {
            "created_at": "2017-05-24T16:55:07Z",
            "id": 2691802,
            "interactive_fields_names": null,
            "interactive_html": null,
            "name": "finish",
            "updated_at": "2017-05-24T16:55:07Z"
          }
      },
      "holder_info": {
        "names": ["John Doe"],
        "emails": ["john.doe@example.com", "johndoe@gmail.com"],
        "phone_numbers": ["+40981233422"],
        "addresses": [
          {
            "city": "Cupertino",
            "state": "CA",
            "street": "1 Infinite Loop",
            "country_code": "US",
            "post_code": "95014"
          }
        ]
      },
      "last_success_at": "2017-05-24T16:55:07Z",
      "next_refresh_possible_at": "2017-05-24T18:35:07Z",
      "provider_id": 1234,
      "provider_code": "fakebank_simple_xf",
      "provider_name": "Fakebank Simple",
      "status": "active",
      "store_credentials": true,
      "updated_at": "2017-05-24T16:55:07Z"
    }
  ],
  "meta" : {
    "next_id": 1228,
    "next_page": "/api/v3/logins?from_id=1228"
  }
}

Login show

Returns a single login object.

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v3/logins/1227

Sample Response

{
  "data": {
    "country_code": "MD",
    "created_at": "2014-10-24T20:09:02Z",
    "customer_id": 905,
    "daily_refresh": false,
    "id": 1227,
    "last_attempt": {
      "api_mode": "service",
      "api_version": "3",
      "automatic_fetch": true,
      "daily_refresh": false,
      "categorize": true,
      "created_at": "2016-02-02T16:14:53Z",
      "custom_fields": {},
      "device_type": "desktop",
      "remote_ip": "93.184.216.34",
      "exclude_accounts": [],
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "fetch_type": "recent",
      "finished": true,
      "finished_recent": true,
      "from_date": null,
      "id": 425036,
      "interactive": false,
      "locale": "en",
      "partial": false,
      "store_credentials": true,
      "success_at": "2016-02-02T16:16:19Z",
      "to_date": null,
      "updated_at": "2016-02-02T16:16:19Z",
      "last_stage": {
        "created_at": "2016-02-02T16:16:19Z",
        "id": 2691802,
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "finish",
        "updated_at": "2016-02-02T16:16:19Z"
      }
    },
    "holder_info": {
      "names": ["John Doe"],
      "emails": ["john.doe@example.com", "johndoe@gmail.com"],
      "phone_numbers": ["+40981233422"],
      "addresses": [
        {
          "city": "Cupertino",
          "state": "CA",
          "street": "1 Infinite Loop",
          "country_code": "US",
          "post_code": "95014"
        }
      ]
    },
    "last_success_at": "2016-02-02T16:16:19Z",
    "next_refresh_possible_at": "2016-02-02T17:16:19Z",
    "provider_id": 1234,
    "provider_code": "moldindconbank_wb_md",
    "provider_name": "Moldindconbank Web Banking",
    "status": "active",
    "store_credentials": true,
    "updated_at": "2016-02-04T09:41:23Z"
  }
}

Creating logins

When not using Salt Edge Connect, your app will have to pass the user’s values of provider’s fields within the payload.

The credentials object should be modeled after the provider’s fields. For instance, if the provider’s required fields contain a field with the value of name equal to username, the credential object should contain a username attribute with the value being the actual username.

For example, here’s a provider:


{
  "data": {
    "code": "bigbank_us",
    "required_fields": [
      {
        "english_name": "Pass Code",
        "localized_name": "Pass Code",
        "name": "code",
        "nature": "text",
        "position": 1
      }
    ]
  }
}

The user should be prompted to input their Pass Code. If they input their Pass Code (in this case, the user has input “hunter2”), your app should send the following data in the credentials object:


{
  "code": "hunter2"
}

Here’s another example that includes a select:


{
  "data": {
    "code": "anotherbank_us",
    "required_fields": [
      {
        "english_name": "Password",
        "localized_name": "Password",
        "name": "password",
        "nature": "password",
        "position": 1
      },
      {
        "nature":         "select",
        "name":           "image",
        "english_name":   "Image",
        "localized_name": "Imagine",
        "position":       2,
        "optional":       false,
        "field_options": [
          {
            "name":           "1",
            "english_name":   "Home",
            "localized_name": "Casa",
            "option_value":   "home",
            "selected":       false
          },
          {
            "name":           "2",
            "english_name":   "Car",
            "localized_name": "Automobil",
            "option_value":   "car",
            "selected":       false
          }
        ]
      }
    ]
  }
}

In this case, your app should prompt the user to input their Password and offer them a select with the options of “Casa” and “Automobil” (the localized_name or english_name values, depending on your service). The credentials should contain the name of the select field (in this case image) as the key and the user’s selected option_value as its value. Let’s say the user has input hunter2 as their password and has chosen “Automobil” from the select.

The credentials object should look like this:


{
  "password": "hunter2",
  "image": "car"
}

Please refer to the example on the right for more info.

Parameters

customer_id
integer, required

the ID of the customer

country_code
string, required

the country code of the desired provider

provider_code
string, required

the code of the desired provider

credentials
object, required

the credentials required to access the data

daily_refresh
boolean, optional

whether the login should be automatically refreshed by Salt Edge

fetch_type
string, optional

fetching mode, possible values: recent, accounts, custom. Default value: recent

from_date
date, optional

date from which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidFromDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow

to_date
date, optional

date until which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidToDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow

locale
string, optional

the language of the provider error messages in the ISO 639-1 format. Possible values are: uk, bg, de, pl, en, ru, ro, it, he, es, pt-BR, defaults to en

include_fake_providers
boolean, optional

being live, the customer will not be able to create fake providers. This flag allows it, if sent as true the customer will have the possibility to create any fake provider available. Defaults to false

categorize
boolean, optional

the flag allows you to specify whether the transactions of this login should be categorized or not. Defaults to true

store_credentials
boolean, optional

this flag allows not to store credentials on SaltEdge side. Default value: true.
Note: The usage of this flag is not available for file providers. In order to update the login, reconnect is required. It will not be possible to use refresh option if store_credentials is set to false

file_url
string, optional

URL of a file. Is used when creating a login for a provider with file mode

Response

A complete Login object.

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"customer_id\": 905, \
                \"country_code\": \"XF\", \
                \"provider_code\": \"fakebank_simple_xf\", \
                \"fetch_type\": \"recent\", \
                \"credentials\": { \
                  \"login\": \"username\", \
                  \"password\": \"secret\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v3/logins

Sample request (with file providers)

curl -v -include \
        -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -F "file=@file.ofx" \
        -F "data[provider_code]=ofx_xo" \
        -F "data[country_code]=XO" \
        -F "data[customer_id]=995" \
        https://www.saltedge.com/api/v3/logins

Sample request (with file providers, using file_url)

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"customer_id\": 905, \
                \"country_code\": \"XO\", \
                \"provider_code\": \"mint_csv_xo\", \
                \"fetch_type\": \"recent\", \
                \"file_url\": \"http://spatialkeydocs.s3.amazonaws.com/FL_insurance_sample.csv\" \
              } \
            }" \
        https://www.saltedge.com/api/v3/logins

Sample response

{
  "data": {
    "country_code": "XF",
    "created_at": "2017-05-23T17:35:07Z",
    "customer_id": 905,
    "daily_refresh": false,
    "id": 1227,
    "last_attempt": {
        "api_mode": "service",
        "api_version": "3",
        "automatic_fetch": true,
        "daily_refresh": false,
        "categorize": true,
        "created_at": "2017-05-24T16:55:07Z",
        "custom_fields": {},
        "device_type": "desktop",
        "remote_ip": "93.184.216.34",
        "exclude_accounts": [],
        "fail_at": null,
        "fail_error_class": null,
        "fail_message": null,
        "fetch_type": "recent",
        "finished": true,
        "finished_recent": true,
        "from_date": null,
        "id": 425036,
        "interactive": false,
        "locale": "en",
        "partial": false,
        "store_credentials": true,
        "success_at": "2017-05-24T16:55:07Z",
        "to_date": null,
        "updated_at": "2017-05-24T16:55:07Z",
        "last_stage": {
          "created_at": "2017-05-24T16:55:07Z",
          "id": 2691802,
          "interactive_fields_names": null,
          "interactive_html": null,
          "name": "finish",
          "updated_at": "2017-05-24T16:55:07Z"
        }
    },
    "holder_info": {
      "names": ["John Doe"],
      "emails": ["john.doe@example.com", "johndoe@gmail.com"],
      "phone_numbers": ["+40981233422"],
      "addresses": [
        {
          "city": "Cupertino",
          "state": "CA",
          "street": "1 Infinite Loop",
          "country_code": "US",
          "post_code": "95014"
        }
      ]
    },
    "last_success_at": "2017-05-24T16:55:07Z",
    "next_refresh_possible_at": "2017-05-24T18:35:07Z",
    "provider_id": 1234,
    "provider_code": "fakebank_simple_xf",
    "provider_name": "Fakebank Simple",
    "status": "active",
    "store_credentials": true,
    "updated_at": "2017-05-24T16:55:07Z"
  }
}

Login reconnect

In order to Reconnect a login, your app needs to send just a credentials object and the login’s id.

Parameters

credentials
object, required

the the credentials required to access the data

daily_refresh
boolean, optional

whether the login should be automatically refreshed by Salt Edge

fetch_type
string, optional

fetching mode, possible values: recent, accounts, custom. Default value: recent

from_date
date, optional

date from which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidFromDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow

to_date
date, optional

date until which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidToDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow

locale
string, optional

the language of the provider error messages in the ISO 639-1 format. Possible values are: uk, bg, de, pl, en, ru, ro, it, he, es, pt-BR, defaults to en

exclude_accounts
array, optional

array of account IDs which will not be fetched. Defaults to empty array

include_fake_providers
boolean, optional

shows whether it would be possible to reconnect a fake provider or not in live mode. Defaults to false

categorize
boolean, optional

the flag allows you to specify whether the transactions of this login should be categorized or not. Defaults to true

store_credentials
boolean, optional

this flag allows not to store credentials on SaltEdge side. Default value: true.
Note: The usage of this flag is not available for file providers. In order to update the login, reconnect is required. It will not be possible to use refresh option if store_credentials is set to false

file_url
string, optional

URL of a file. Is used when creating a login for a provider with mode file

Response

A complete Login object.

Possible Errors

Sample request


curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"credentials\": { \
                  \"login\": \"username\", \
                  \"password\": \"secret\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v3/logins/1227/reconnect

Sample request (with file providers)

curl -v -include \
        -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -F "file=@file.ofx" \
        https://www.saltedge.com/api/v3/logins/1227/reconnect

Sample response

{
  "data": {
    "country_code": "XF",
    "created_at": "2017-05-23T17:35:07Z",
    "customer_id": 905,
    "daily_refresh": false,
    "id": 1227,
    "last_attempt": {
        "api_mode": "service",
        "api_version": "3",
        "automatic_fetch": true,
        "daily_refresh": true,
        "categorize": true,
        "created_at": "2017-05-24T16:55:07Z",
        "custom_fields": {},
        "device_type": "desktop",
        "remote_ip": "93.184.216.34",
        "exclude_accounts": [],
        "fail_at": null,
        "fail_error_class": null,
        "fail_message": null,
        "fetch_type": "recent",
        "finished": true,
        "finished_recent": true,
        "from_date": null,
        "id": 425036,
        "interactive": false,
        "locale": "en",
        "partial": false,
        "store_credentials": true,
        "success_at": "2017-05-24T16:55:07Z",
        "to_date": null,
        "updated_at": "2017-05-24T16:55:07Z",
        "last_stage": {
          "created_at": "2017-05-24T16:55:07Z",
          "id": 2691802,
          "interactive_fields_names": null,
          "interactive_html": null,
          "name": "finish",
          "updated_at": "2017-05-24T16:55:07Z"
        }
    },
    "holder_info": {
      "names": ["John Doe"],
      "emails": ["john.doe@example.com", "johndoe@gmail.com"],
      "phone_numbers": ["+40981233422"],
      "addresses": [
        {
          "city": "Cupertino",
          "state": "CA",
          "street": "1 Infinite Loop",
          "country_code": "US",
          "post_code": "95014"
        }
      ]
    },
    "last_success_at": "2017-05-24T16:55:07Z",
    "next_refresh_possible_at": "2017-05-24T18:35:07Z",
    "provider_id": 1234,
    "provider_code": "fakebank_simple_xf",
    "provider_name": "Fakebank Simple",
    "status": "active",
    "store_credentials": true,
    "updated_at": "2017-05-24T16:55:07Z"
  }
}

Logins interactive

If the currently fetching login requires any interactive credentials for fetching, Salt Edge will send the Interactive callback.

Upon receiving the interactive callback, your app should ask the user for the interactive credentials and send them to the /interactive route for the login. After that, the fetching process will continue as usual.

Please note that in some cases (e.g. when fetching Fake Bank with SMS logins), on interactive stage provider may not require any interactive fields (see interactive_fields_names), thus you should send an empty object in the credentials field:

{ "data": { "credentials": {} } }

Parameters

credentials
object, required

the credentials object based on the provider’s interactive fields

fetch_type
string, optional

fetching mode, possible values: recent, accounts, custom. Default value: recent

from_date
date, optional

date from which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidFromDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow

to_date
date, optional

date until which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidToDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow

Response

A complete Login object.

Possible Errors

Sample request


curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"fetch_type\": \"recent\", \
                \"credentials\": { \
                  \"sms\": \"AB123\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v3/logins/1227/interactive

Sample response

{
  "data": {
    "country_code": "XF",
    "created_at": "2017-05-23T17:35:07Z",
    "customer_id": 905,
    "daily_refresh": false,
    "id": 1227,
    "last_attempt": {
        "api_mode": "service",
        "api_version": "3",
        "automatic_fetch": false,
        "daily_refresh": false,
        "categorize": true,
        "created_at": "2017-05-24T16:55:07Z",
        "custom_fields": {},
        "device_type": "desktop",
        "remote_ip": "93.184.216.34",
        "exclude_accounts": [],
        "fail_at": null,
        "fail_error_class": null,
        "fail_message": null,
        "fetch_type": "recent",
        "finished": false,
        "finished_recent": false,
        "from_date": null,
        "id": 425036,
        "interactive": true,
        "locale": "en",
        "partial": true,
        "store_credentials": true,
        "success_at": "2017-05-24T16:55:07Z",
        "to_date": null,
        "updated_at": "2017-05-24T16:55:07Z",
        "last_stage": {
          "created_at": "2017-05-24T16:55:07Z",
          "id": 2691802,
          "interactive_fields_names": ["sms"],
          "interactive_html": "<input type="text" name="sms" placeholder="Sms">",
          "name": "interactive",
          "updated_at": "2017-05-24T16:55:07Z"
        }
    },
    "holder_info": {
      "names": ["John Doe"],
      "emails": ["john.doe@example.com", "johndoe@gmail.com"],
      "phone_numbers": ["+40981233422"],
      "addresses": [
        {
          "city": "Cupertino",
          "state": "CA",
          "street": "1 Infinite Loop",
          "country_code": "US",
          "post_code": "95014"
        }
      ]
    },
    "last_success_at": "2017-05-24T16:55:07Z",
    "next_refresh_possible_at": "2017-05-24T18:35:07Z",
    "provider_id": 1234,
    "provider_code": "fakebank_interactive_xf",
    "provider_name": "Fake Bank with SMS",
    "status": "active",
    "updated_at": "2017-05-24T16:55:07Z"
  }
}

Login refresh

Lets you trigger a refetch of the data associated with a specific Login. Note that you can refresh a login once in every 60 minutes. If the response is successful, it will contain the next_refresh_possible_at value and you can expect the usual callbacks of the fetching workflow.

Parameters

daily_refresh
boolean, optional

whether the login should be automatically refreshed by Salt Edge

fetch_type
string, optional

fetching mode, possible values: recent, accounts, custom. Default value: recent

from_date
date, optional

date from which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidFromDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow.

to_date
date, optional

date until which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_type parameter is set to custom, otherwise InvalidToDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow

locale
string, optional

the language of the provider error messages in the ISO 639-1 format. Possible values are: uk, bg, de, pl, en, ru, ro, it, he, es, pt-BR, defaults to en

exclude_accounts
array, optional

array of account IDs which will not be fetched. Defaults to empty array

include_fake_providers
boolean, optional

shows whether it would be possible to refresh a fake provider or not in live mode. Defaults to false

categorize
boolean, optional

the flag allows you to specify whether the transactions of this login should be categorized or not. Defaults to true

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"fetch_type\": \"recent\" \
              } \
            }" \
        https://www.saltedge.com/api/v3/logins/1227/refresh

Sample Response

{
  "data": {
    "country_code": "MD",
    "created_at": "2014-10-24T20:09:02Z",
    "customer_id": 905,
    "daily_refresh": false,
    "id": 1227,
    "last_attempt": {
        "api_mode": "service",
        "api_version": "3",
        "automatic_fetch": true,
        "daily_refresh": true,
        "categorize": true,
        "created_at": "2016-02-02T16:14:53Z",
        "custom_fields": {},
        "device_type": "desktop",
        "remote_ip": "93.184.216.34",
        "exclude_accounts": [],
        "fail_at": null,
        "fail_error_class": null,
        "fail_message": null,
        "fetch_type": "recent",
        "finished": true,
        "finished_recent": true,
        "from_date": null,
        "id": 425036,
        "interactive": false,
        "locale": "en",
        "partial": false,
        "store_credentials": true,
        "success_at": "2016-02-02T16:16:19Z",
        "to_date": null,
        "updated_at": "2016-02-02T16:16:19Z",
        "last_stage": {
          "created_at": "2016-02-02T16:16:19Z",
          "id": 2691802,
          "interactive_fields_names": null,
          "interactive_html": null,
          "name": "finish",
          "updated_at": "2016-02-02T16:16:19Z"
        }
    },
    "holder_info": {
      "names": ["John Doe"],
      "emails": ["john.doe@example.com", "johndoe@gmail.com"],
      "phone_numbers": ["+40981233422"],
      "addresses": [
        {
          "city": "Cupertino",
          "state": "CA",
          "street": "1 Infinite Loop",
          "country_code": "US",
          "post_code": "95014"
        }
      ]
    },
    "last_success_at": "2016-02-02T16:16:19Z",
    "next_refresh_possible_at": "2016-02-02T17:16:19Z",
    "provider_id": 1234,
    "provider_code": "moldindconbank_wb_md",
    "provider_name": "Moldindconbank Web Banking",
    "status": "active",
    "store_credentials": true,
    "updated_at": "2016-02-04T09:41:23Z"
  }
}

Login remove

Removes a login from our system. All the associated accounts and transactions to that login will be destroyed as well. Salt Edge will send a destroy callback to your web application.

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X DELETE \
        https://www.saltedge.com/api/v3/logins/20

Sample Response

{
  "data": {
    "id": 20,
    "removed": true
  }
}

Login inactivate

Marks a login from the system as inactive. In order to activate the login, you have to perform a successful reconnect.

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X PUT \
        https://www.saltedge.com/api/v3/logins/20/inactivate

Sample Response

{
  "data": {
    "country_code": "MD",
    "created_at": "2014-10-24T20:09:02Z",
    "customer_id": 905,
    "daily_refresh": false,
    "id": 1227,
    "last_attempt": {
      "api_mode": "service",
      "api_version": "3",
      "automatic_fetch": true,
      "daily_refresh": false,
      "categorize": true,
      "created_at": "2016-02-02T16:14:53Z",
      "custom_fields": {},
      "device_type": "desktop",
      "remote_ip": "93.184.216.34",
      "exclude_accounts": [],
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "fetch_type": "recent",
      "finished": true,
      "finished_recent": true,
      "from_date": null,
      "id": 425036,
      "interactive": false,
      "locale": "en",
      "partial": false,
      "store_credentials": true,
      "success_at": "2016-02-02T16:16:19Z",
      "to_date": null,
      "updated_at": "2016-02-02T16:16:19Z",
      "last_stage": {
        "created_at": "2016-02-02T16:16:19Z",
        "id": 2691802,
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "finish",
        "updated_at": "2016-02-02T16:16:19Z"
      }
    },
    "holder_info": {
      "names": ["John Doe"],
      "emails": ["john.doe@example.com", "johndoe@gmail.com"],
      "phone_numbers": ["+40981233422"],
      "addresses": [
        {
          "city": "Cupertino",
          "state": "CA",
          "street": "1 Infinite Loop",
          "country_code": "US",
          "post_code": "95014"
        }
      ]
    },
    "last_success_at": "2016-02-02T16:16:19Z",
    "next_refresh_possible_at": "2016-02-02T17:16:19Z",
    "provider_id": 1234,
    "provider_code": "moldindconbank_wb_md",
    "provider_name": "Moldindconbank Web Banking",
    "status": "inactive",
    "store_credentials": true,
    "updated_at": "2016-02-04T09:41:23Z"
  }
}

Destroy credentials

Destroys credentials of the login.

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X PUT \
        https://www.saltedge.com/api/v3/logins/20/destroy_credentials

Sample Response

{
  "data": {
    "country_code": "MD",
    "created_at": "2014-10-24T20:09:02Z",
    "customer_id": 905,
    "daily_refresh": false,
    "id": 1227,
    "last_attempt": {
      "api_mode": "service",
      "api_version": "3",
      "automatic_fetch": true,
      "daily_refresh": false,
      "categorize": true,
      "created_at": "2016-02-02T16:14:53Z",
      "custom_fields": {},
      "device_type": "desktop",
      "remote_ip": "93.184.216.34",
      "exclude_accounts": [],
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "fetch_type": "recent",
      "finished": true,
      "finished_recent": true,
      "from_date": null,
      "id": 425036,
      "interactive": false,
      "locale": "en",
      "partial": false,
      "store_credentials": true,
      "success_at": "2016-02-02T16:16:19Z",
      "to_date": null,
      "updated_at": "2016-02-02T16:16:19Z",
      "last_stage": {
        "created_at": "2016-02-02T16:16:19Z",
        "id": 2691802,
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "finish",
        "updated_at": "2016-02-02T16:16:19Z"
      }
    },
    "holder_info": {
      "names": ["John Doe"],
      "emails": ["john.doe@example.com", "johndoe@gmail.com"],
      "phone_numbers": ["+40981233422"],
      "addresses": [
        {
          "city": "Cupertino",
          "state": "CA",
          "street": "1 Infinite Loop",
          "country_code": "US",
          "post_code": "95014"
        }
      ]
    },
    "last_success_at": "2016-02-02T16:16:19Z",
    "next_refresh_possible_at": null,
    "provider_id": 1234,
    "provider_code": "moldindconbank_wb_md",
    "provider_name": "Moldindconbank Web Banking",
    "status": "inactive",
    "store_credentials": false,
    "updated_at": "2016-02-04T09:41:23Z"
  }
}

Attempts

The attempt resource represents a detailed description of a particular login connection attempt. They are meant to provide you with more information about the established connections for further usage in technical and statistical purposes.

Attributes

api_mode
string

the API mode of the customer that queried the API. Possible values: app, service

api_version
integer

the API version in which the attempt was created

automatic_fetch
boolean

whether the login related to the attempt can be automatically fetched

daily_refresh
boolean

latest assigned value for daily_refresh in login

categorize
boolean

whether the transactions belonging to the attempt’s login have been categorized

created_at
datetime

when the attempt was created

custom_fields
object

the custom fields that had been sent when creating login/token/oauth_provider

device_type
string

the type of the device that created the attempt. Possible values: desktop, tablet, mobile

remote_ip
string

the ip of the device that created the attempt

exclude_accounts
array of integers

the IDs of accounts that do not need to be refreshed

fail_at
datetime

when the attempt failed to finish

fail_error_class
string

class of error that triggered the fail for attempt

fail_message
string

message that describes the error class

fetch_type
string

type of fetch when attempt ended. Possible values: full, recent, accounts, custom

finished
boolean

whether the login had finished fetching

finished_recent
boolean

whether the login had finished data for recent range (2 months)

from_date
date

date from which the data had been fetched

id
integer
interactive
boolean

whether the login related to the attempt is interactive

locale
string

the language of the provider error messages in the ISO 639-1 format. Possible values are: uk, bg, de, pl, en, ru, ro, it, he, es, pt-BR, defaults to en

partial
boolean

whether the login was partially fetched

store_credentials
boolean

whether the credentials were stored on our side

success_at
datetime

when the attempt succeeded and finished

to_date
date

date until which the data has been fetched

updated_at
datetime

when last attempt update occured

stages
array of stage objects

information about stages through which the login has passed

Note that the values of the interactive and automatic_fetch are subject to change, since the customer can activate or deactivate the interactive requirements separately with their bank.

Sample object

{
  "api_mode": "service",
  "api_version": 3,
  "automatic_fetch": true,
  "categorize": true,
  "created_at": "2017-05-24T15:35:08Z",
  "custom_fields": {},
  "daily_refresh": false,
  "device_type": "desktop",
  "remote_ip": "93.184.216.34",
  "exclude_accounts": [],
  "fail_at": null,
  "fail_error_class": null,
  "fail_message": null,
  "fetch_type": "recent",
  "finished": true,
  "finished_recent": true,
  "from_date": null,
  "id": 337518,
  "interactive": false,
  "partial": false,
  "store_credentials": true,
  "success_at": "2017-05-24T16:35:08Z",
  "to_date": null,
  "updated_at": "2017-05-24T16:35:08Z",
  "last_stage": {
    "created_at": "2017-05-24T16:35:08Z",
    "id": 2094640,
    "interactive_fields_name": null,
    "interactive_html": null,
    "name": "finish",
    "updated_at": "2017-05-24T16:35:08Z"
  }
}

Stages

The following represents the objects you get in the stages field of the attempt object.

created_at
datetime

when the stage was created

id
integer
interactive_fields_names
array of strings

the interactive fields that are currently required by the provider of the login. Appears only for interactive logins

interactive_html
string

HTML code that shows the current interactive state of the login. Appears only for interactive logins

name
string

the name of the stage. Possible values: start, connect, interactive, fetch_holder_info, fetch_accounts, fetch_recent, fetch_full, disconnect, finish

updated_at
datetime

when the stage was last updated

Listing attempts

Returns a paginated list of all attempts for a certain login.

Parameters

login_id
integer

the ID of the login whose attempts are to be fetched

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v3/attempts?login_id=47872

Sample response

{
  "data": {
    [
      {
        "api_mode": "service",
        "api_version": 3,
        "automatic_fetch": true,
        "categorize": true,
        "created_at": "2017-05-24T15:35:08Z",
        "custom_fields": {},
        "device_type": "desktop",
        "daily_refresh": false,
        "remote_ip": "93.184.216.34",
        "exclude_accounts": [],
        "fail_at": null,
        "fail_error_class": null,
        "fail_message": null,
        "fetch_type": "recent",
        "finished": true,
        "finished_recent": true,
        "from_date": null,
        "id": 337518,
        "interactive": false,
        "locale": "en",
        "partial": false,
        "store_credentials": true,
        "success_at": "2017-05-24T16:35:08Z",
        "to_date": null,
        "updated_at": "2017-05-24T16:35:08Z",
        "last_stage": {
          "created_at": "2017-05-24T16:35:08Z",
          "id": 2094640,
          "interactive_fields_name": null,
          "interactive_html": null,
          "name": "finish",
          "updated_at": "2017-05-24T16:35:08Z"
        }
      }
    ]
  },
  "meta": {
    "next_id": 337520,
    "next_page": "/api/v3/attempts?from_id=337520&login_id=47872"
  }
}

Attempts show

Returns a single attempt object.

Parameters

login_id
integer

the ID of the login whose attempts are to be fetched

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v3/attempts/340?login_id=47872

Sample response

{
  "data": {
    "api_mode": "service",
    "api_version": 3,
    "automatic_fetch": true,
    "daily_refresh": false,
    "categorize": true,
    "created_at": "2017-05-24T15:35:08Z",
    "custom_fields": {},
    "device_type": "desktop",
    "remote_ip": "93.184.216.34",
    "exclude_accounts": [],
    "fail_at": null,
    "fail_error_class": null,
    "fail_message": null,
    "fetch_type": "recent",
    "finished": true,
    "finished_recent": true,
    "from_date": null,
    "id": 340,
    "interactive": false,
    "locale": "en",
    "partial": false,
    "store_credentials": true,
    "success_at": "2017-05-24T16:35:08Z",
    "to_date": null,
    "updated_at": "2017-05-24T16:35:08Z",
    "stages": [
      {
        "created_at": "2017-05-24T15:35:08Z",
        "id": 17676,
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "start",
        "updated_at": "2017-05-24T15:35:08Z"
      },
      {
        "created_at": "2017-05-24T15:45:08Z",
        "id": 17677,
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "connect",
        "updated_at": "2017-05-24T15:45:08Z"
      },
      {
        "created_at": "2017-05-24T16:35:08Z",
        "id": 17681,
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "finish",
        "updated_at": "2017-05-24T16:35:08Z"
      }
    ]
  }
}

Accounts

Any login can have one or more accounts, each of them having transactions. There are several types of accounts, please refer to the accounts guide for more information.

Attributes

id
integer
name
string

the unique name of the account

nature
string

the type of the account. Possible values are: account, bonus, card, checking, credit, credit_card, debit_card, ewallet, insurance, investment, loan, mortgage, savings. Note that for credit_card nature, the balance represents the sum of all negative transactions, the positive ones do not count

balance
decimal

the account’s current balance

currency_code
string

one of the possible values for currency codes. Max 3 letters

extra
object, extra object

extra data associated with the account

login_id
integer

the id of the login the account belongs to

created_at
datetime
updated_at
datetime

Sample Object

{
    "id": 223,
    "name": "Fake account 2",
    "nature": "account",
    "balance": 2012.7,
    "currency_code": "USD",
    "extra": {
        "cards": [
            "1234....5678",
            "*8765"
        ],
        "transactions_count": {
          "posted": 22,
          "pending": 1
        }
    },
    "login_id": 123,
    "created_at": "2017-05-24T15:35:08Z",
    "updated_at": "2017-05-24T15:35:08Z"
}

Listing accounts

You can see the list of accounts of a login. The accounts are sorted in ascending order of their ID, so the newest accounts will come last. You can read more about next_id field, in the pagination section of the reference.

Parameters

login_id
integer, optional

the ID of the login containing the accounts

customer_id
integer, optional

the ID of the customer containing the accounts.
Note: Will be ignored if login_id is present.

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v3/accounts

Sample Response

{
    "data": [
        {
          "id": 142,
          "name": "Fake account 1",
          "nature": "card",
          "balance": 2007.2,
          "currency_code": "EUR",
          "extra": {
            "client_name": "Fake name"
          },
          "login_id": 123,
          "created_at": "2017-05-24T14:35:08Z",
          "updated_at": "2017-05-24T14:35:08Z"
        },
        {
          "id": 143,
          "name": "Fake account 2",
          "nature": "account",
          "balance": 2012.7,
          "currency_code": "USD",
          "extra": {
            "cards": [
              "1234....5678",
              "*8765"
            ],
            "transactions_count": {
              "posted": 22,
              "pending": 1
            }
          },
          "login_id": 123,
          "created_at": "2017-05-24T15:35:08Z",
          "updated_at": "2017-05-24T15:35:08Z"
        }
    ],
    "meta" : {
      "next_id": 144,
      "next_page": "/api/v3/accounts?from_id=144"
    }
}

Extra

The following represents the object you get in the extra field of the account object. Note: You may or may not have all of the fields listed below.

account_name
string

changeable name of the account

status
string

is the account active or inactive

client_name
string

account client owner

iban
string

account IBAN number

swift
string

account SWIFT code

card_type
string

type of the card account. Possible values are: american_express, china_unionpay, diners_club, jcb, maestro, master_card, uatp and visa

account_number
string

internal bank account number

blocked_amount
decimal

the amount currently blocked in account’s currency

available_amount
decimal

available amount in account’s currency

credit_limit
decimal

credit limit in account’s currency

interest_rate
decimal

interest rate of the account as percentage value

expiry_date
date

card expiry date

open_date
date

card open date

current_time
datetime

time of provider statement generation (applicable to banks)

current_date
date

date of provider statement generation (applicable to banks)

cards
array of strings

list of masked card numbers

units
decimal

amount of units owned (used with unit_price, available for investment accounts nature only)

unit_price
decimal

price per unit (used with units, available for investment accounts nature only)

transactions_count
object

number of transactions, separated by posted and pending. e.g. {'posted': 12, 'pending': 0}

Transactions

A transaction represents a movement of funds. Any transaction can represent a monetary transfer, withdrawal, income or expense interchange. Transactions are retained in a login’s accounts, and are imported from one of the providers.

Attributes

id
integer
mode
string

possible values are: normal, fee, transfer

status
string

possible values are: posted, pending

made_on
date

the date when the transaction was made

amount
decimal

transaction’s amount

currency_code
string

transaction’s currency code

description
text

transaction’s description

category
string

transaction’s category

duplicated
boolean

whether the transaction is duplicated or not

extra
object, extra object

extra data associated with the transaction

account_id
integer

the id of the account the transaction belongs to

created_at
datetime
updated_at
datetime

Sample object

{
    "id": 987,
    "duplicated": false,
    "mode": "normal",
    "status": "posted",
    "made_on": "2013-05-03",
    "amount": -200.0,
    "currency_code": "USD",
    "description": "Money spent on company advertising",
    "category": "advertising",
    "extra": {
      "posting_date": "2013-05-07",
      "time": "23:56:12",
      "original_amount": -3974.60,
      "original_currency_code": "CZK"
    },
    "account_id": 100,
    "created_at": "2017-05-22T17:35:08Z",
    "updated_at": "2017-05-23T17:35:08Z"
}

List transactions

You can see the list of transactions of an account. You can read more about the next_id field in the pagination section of the reference.

Parameters

account_id
integer, optional

the id of the account

login_id
integer, optional

the id of the login

from_id
integer, optional

the id from which the next page of transactions starts

from_date
date, optional

the date from which the transactions should be listed

to_date
date, optional

the date to which the transactions should be listed

All of the optional parameters for transactions list can be combined in any possible manner. Also, the from_date and to_date represent a closed interval, so the dates will be included in the filter as well.

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v3/transactions

Sample response

{
  "data": [
    {
      "id": 987,
      "duplicated": false,
      "mode": "normal",
      "status": "posted",
      "made_on": "2013-05-03",
      "amount": -200.0,
      "currency_code": "USD",
      "description": "test transaction",
      "category": "advertising",
      "extra": {
        "posting_date": "2013-05-07",
        "time": "23:56:12",
        "original_amount": -3974.60,
        "original_currency_code": "CZK"
      },
      "account_id": 100,
      "created_at": "2017-05-22T17:35:08Z",
      "updated_at": "2017-05-23T17:35:08Z"
    },
    {
      "id": 988,
      "duplicated": false,
      "mode": "normal",
      "status": "posted",
      "made_on": "2013-05-03",
      "amount": 50.0,
      "currency_code": "USD",
      "description": "business expense",
      "category": "business_services",
      "extra": {
        "posting_date": "2013-05-06",
        "time": "12:16:25",
        "original_amount": 993.90,
        "original_currency_code": "CZK"
      },
      "account_id": 100,
      "created_at": "2017-05-22T17:35:08Z",
      "updated_at": "2017-05-23T17:35:08Z"
    }
  ],
  "meta" : {
    "next_id": 990,
    "next_page": "/api/v3/transactions/?login_id=124&account_id=225&from_id=990"
  }
}

Pending

You can use this route to obtain the currently pending transactions for an account. Note that although the pending transactions have the same structure as the regular transactions, they behave differently.

The provider may delete the pending transactions and modify some of its attributes. Thus, every time a login is refreshed, the existing pending transactions will be replaced by the currently pending transactions.

This means that your app should not rely on the pending transactions having an ID, since they might be replaced with similar transactions having a different ID. We also recommend your app to remove the account’s pending transactions every time you fetch the transactions.

Parameters

account_id
integer, optional

the id of the account

login_id
integer, optional

the id of the login

from_id
integer, optional

the id from which the next page of transactions starts

from_date
date, optional

the date from which the transactions should be listed

to_date
date, optional

the date to which the transactions should be listed

As with the list route, you can combine the parameters.

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v3/transactions/pending

Sample response

{
  "data": [
    {
      "id": 987,
      "duplicated": false,
      "mode": "normal",
      "status": "pending",
      "made_on": "2013-05-03",
      "amount": -200.0,
      "currency_code": "USD",
      "description": "ads expense",
      "category": "advertising",
      "extra": {
        "posting_date": "2013-05-07",
        "time": "23:56:12",
        "original_amount": -3974.60,
        "original_currency_code": "CZK"
      },
      "account_id": 100,
      "created_at": "2017-05-22T17:35:08Z",
      "updated_at": "2017-05-23T17:35:08Z"
    }
  ],
  "meta" : {
    "next_id": 990,
    "next_page": "/api/v3/transactions/pending?login_id=124&account_id=225&from_id=990"
  }
}

Duplicate

Mark a list of transactions as duplicated.

Request body

The request body is an array of objects wrapped in the data field. Each object has a transaction_id field which represents a transaction id.

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X PUT \
        -d "{ \
              \"data\": [ \
                { \
                  \"transaction_id\": 123 \
                }, \
                { \
                  \"transaction_id\": 345 \
                } \
              ] \
            }" \
        https://www.saltedge.com/api/v3/transactions/duplicate

Sample response

{
  "data": {
    "duplicated": true
  }
}

Unduplicate

Remove duplicated flag from a list of transactions.

Request body

As with /transactions/duplicate, the request body is an array of objects wrapped in the data field. Each object has a transaction_id field which represents a transaction id.

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X PUT \
        -d "{ \
              \"data\": [ \
                { \
                  \"transaction_id\": 123 \
                }, \
                { \
                  \"transaction_id\": 345 \
                } \
              ] \
            }" \
        https://www.saltedge.com/api/v3/transactions/unduplicate

Sample Response

{
  "data": {
    "unduplicated": true
  }
}

Categorize

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

identifier
string, optional

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

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X POST \
        -d "{ \
              \"data\": [ \
                { \
                  \"description\": \"Itunes\", \
                  \"currency_code\": \"USD\", \
                  \"identifier\": \"d5bb8cf037aa7f069\" \
                }, \
                { \
                  \"description\": \"\", \
                  \"currency_code\": \"EUR\" \
                } \
              ] \
            }" \
        https://www.saltedge.com/api/v3/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"
      ]
    }
  ]
}

Extra

The following represents the object you get in the extra field of the transaction object. Note: You may or may not have all of the fields listed below.

id
string

possible transaction ID

record_number
string

bank record number

information
text

information about the transaction

time
time

time when the transaction was made

posting_date
date

date when the transaction appears in statement

posting_time
string

time in HH:MM:SS format, representing time when the transaction appears in statement

account_number
string

number of the account the transaction belongs to

original_amount
decimal

native amount of the transaction in transaction’s currency (comes with original_currency_code)

original_currency_code
string

native currency of the transaction (comes with original_amount)

original_category
string

the original category of the transaction

original_subcategory
string

the original subcategory of the transaction

customer_category_code
string

the category (present in categories list) that was categorized by the rules created by the customer

customer_category_name
string

the category (not present in categories list) that was categorized by the rules created by the customer

tags
array of strings

the original tags of the transaction

mcc
string

the transaction’s Merchant Category Code

payee
string

to whom money is paid

type
string

transaction type

check_number
string

payee’s transaction check number

units
decimal

amount of units owned (used with unit_price, available for investment accounts nature only)

additional
text

additional information (recommended to use in concatenation with original description, if present)

unit_price
decimal

price per unit (used with units, available for investment accounts nature only)

account_balance_snapshot
decimal

balance of the transaction’s amount at the moment the transaction was imported

categorization_confidence
float

value from 0 to 1, the probability that the current category is the correct one

Categories

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.

This arrangement is represented as a reference. You can change it as you wish.

Listing categories

You can get the list of all the categories that we support.

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v3/categories

Sample Response

{
   "data": {
      "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": []
   }
}

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

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X POST \
        -d "{ \
              \"data\": [ \
                { \
                  \"transaction_id\": 123, \
                  \"category_code\": \"paycheck\" \
                }, \
                { \
                  \"transaction_id\": 124, \
                  \"category_code\": \"car_rental\" \
                } \
              ] \
            }" \
        https://www.saltedge.com/api/v3/categories/learn

Sample Response

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

Currencies

The currency is represented just as a string. We use ISO 4217 currency codes. Thus, all the currency codes will have exactly three uppercase letters. If certain currencies no longer exist, we will still support them for the transactions held in those currencies. Example:

  • Zambian Kwacha ZMK (old currency code)
  • Zambian Kwacha ZMW (new currency code)

both of them are supported.

Listing currencies

You can get the list of all the currencies that we support.

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v3/currencies

Sample Response

{
  "data":
    [
      {
        code: "AED",
        name: "United Arab Emirates dirham"
      },
      {
        code: "AFN",
        name: "Afghan afghani"
      },
      {
        code: "ALL",
        name: "Albanian lek"
       },
      {
        code: "AMD",
        name: "Armenian dram"
      },
      {
        code: "ANG",
        name: "Netherlands Antillean guilder"
      },
      {
        code: "AOA",
        name: "Angolan kwanza"
      },
      {
        code: "ARS",
        name: "Argentine peso"
      },
      {
        code: "AUD",
        name: "Australian dollar"
      },
      {
        code: "AWG",
        name: "Aruban florin"
      },
    ...
    ]
}

Rates

A rate is an index of any currency value in relation to the USD currency. All rates are updated daily.

Attributes

currency_code
string

the code of the currency

rate
decimal

the ratio of the currency in relation to the USD currency

fail
boolean

the field which shows if we have an up-to-date rate for the currency. If the flag is true, it means that the rate has been taken from the previous available date

issued_on
date

the date the rate has been issued on

Sample object

{
    "currency_code": "EUR",
    "rate": 1.37,
    "issued_on": "2014-02-12",
    "fail": false
}

Listing rates

You can get the list of all the currency rates that we support. You will receive the currency rates starting March 21, 2014. If any older date is requested, you will still receive the rates starting March 21, 2014.

Parameters

date
optional

date for which currency rates will be retrieved

Possible Errors

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "Client-id: CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v3/rates?date=2014-03-21

Sample Response

{
  "data": [
    {
      "currency_code": "ZMK",
      "rate": 0.0001926968,
      "fail": false
    },
    {
      "currency_code": "ZWL",
      "rate": 0.0031021699,
      "fail": false
    },
    {
      "currency_code": "ZMW",
      "rate": 0.1589825119,
      "fail": false
    },
    {
      "currency_code": "AED",
      "rate": 0.2722570106,
      "fail": false
    }
    ...
  ],
  "meta" : {
    "issued_on": "2014-03-21"
  }
}