general

Overview

Account Information API aims to make requesting financial information from various providers as simple as a cURL. The API allows you to perform several important procedures, such as:

  • Securely import bank data from multiple countries;
  • Import data from online payment systems (PayPal, Yandex Money, etc.);
  • Automatically synchronize accounts and transactions on a daily basis;
  • Automatically categorize financial transactions;
  • Keep a well-organized and up-to-date list of currency rates.

If you have any questions regarding the integration and use of Account Information API, feel free to contact us.

Integrations

The Salt Edge platform is incredibly easy to integrate with. We’ve built the Salt Edge Connect interface so your application could start importing your users’ financial data in a matter of minutes.

However, if you think your application could benefit more from the native look and feel, you can always contact us, and we can discuss what would be the best solution for your app.

Formats

We use JSON for all the requests and responses, including the errors.

Glossary

Most of the API revolves around several important concepts:

  • Country - the country where a provider is located;
  • Provider - a bank or an online payments system;
  • Required Field - a mandatory field for authentication to a specific provider;
  • Interactive Field - an interactive field for authentication to a specific provider;
  • Client - an application consuming the Account Information API;
  • Customer - an end-user of the client who is consuming the Account Information API;
  • Connection - the central entity of the API, representing a connection between a customer’s bank and Salt Edge;
  • Attempt - an attempt which is created when an end-user connects his financial institution;
  • Consent - the permission from an end-user to fetch data;
  • Holder Info - information about the account holder;
  • Account - one of the accounts associated with a connection. It can be a credit card account, a savings account, one of the online accounts, etc;
  • Merchant - a company that sells goods or provides services to the customer;
  • Transaction - a single financial movement made within an account;
  • Category - one of the personal or business categories that can be assigned to a transaction.
  • Currency - string code that is used for an account.

Following the guides

You can start with Authentication and follow the links in the sidebar. If you have any questions, contact us anytime using our contact form.

Quick start

Here are some steps to get you started.

Create an account

a. Input all the necessary data and create an account on the Sign Up page.

b. Confirm your Email.

c. Add your technical team members who will work on the next integration steps on the Team page and choose the specific roles for them.

Create api keys

Any request to Account information API is authenticated, so before we are able to fetch any data, we need to create API keys. To do that, visit https://www.saltedge.com/keys_and_secrets and create a Service API key. You can leave the “Public key” field blank.

Each request to API is authenticated with an App-id, and a Secret. Let’s store them as environment variables so that all the later requests are authenticated.

$ export APP_ID=YOUR_APP_ID
$ export SECRET=YOUR_APP_SECRET

We can provide examples in various programming languages and SDKs for Android and iOS. Start testing different connection types by using fake data providers to make sure that the application can handle any scenario that might happen with a real data provider (e.g. bank).

Create customer

Before we can create any connections using Account Information API, we need to create a Customer. A Customer in Account Information API is the end-user of your application.

We need to save the Customer id (in this case “222222222222222222”) because we will use it later to create connections.

$ export CUSTOMER_ID=222222222222222222

See customers reference for Customer related API endpoints.

URL

https://www.saltedge.com/api/v5/customers

https://www.saltedge.com/api/v5/customers

Method

POST

Sample Request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"identifier\": \"test1\" \
              } \
            }" \
        https://www.saltedge.com/api/v5/customers
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"identifier\": \"test1\" \
              } \
            }" \
        https://www.saltedge.com/api/v5/customers

Sample Response

{
  "data": {
    "id":         "222222222222222222",
    "identifier": "test1",
    "secret":     "SECRET"
  }
}

Create connect session

Once we have the Customer id (in this case id “222222222222222222”), we can create a connection.

There are 2 ways to create connections in Account Information API:

  • implementing the UI for creating connections from scratch
  • use Salt Edge Connect, which already implemented the interface in a fast and secure way

This is a quick start guide so we will use the second approach. To initiate a connection in Salt Edge Connect, we need to execute a request to create connect session endpoint.

We will receive in response a connect_url. This is the url we will visit to create the connection.

See connect sessions reference for more information and API endpoints related to Salt Edge Connect.

Sample Request

URL

https://www.saltedge.com/api/v5/connect_sessions/create

https://www.saltedge.com/api/v5/connect_sessions/create

Method

POST

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"customer_id\": \"$CUSTOMER_ID\", \
                \"consent\": { \
                  \"scopes\": [ \
                    \"account_details\", \
                    \"transactions_details\" \
                  ], \
                  \"from_date\": \"2019-01-01\" \
                }, \
                \"attempt\": { \
                  \"return_to\": \"http://example.com/\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v5/connect_sessions/create
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"customer_id\": \"$CUSTOMER_ID\", \
                \"consent\": { \
                  \"scopes\": [ \
                    \"account_details\", \
                    \"transactions_details\" \
                  ], \
                  \"from_date\": \"2019-01-01\" \
                }, \
                \"attempt\": { \
                  \"return_to\": \"http://example.com/\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v5/connect_sessions/create

Sample Response

{
  "data": {
    "expires_at": "2020-08-05T08:28:27Z",
    "connect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
  }
}

Visit connect url

Initially, all Account Information API registered clients only have access to fake providers. Let’s connect one of them. Visit the connect_url from the previous API response and search for “Fake Bank Simple”.

Once selected, you will be presented with a form for user credential input, from this provider. Input “username” and “secret” as per the on-screen instructions and press “Proceed”.

After that, we will have to wait for the connection process to finish, and then we can proceed to retrieve all its data via the API.

Fetch connections

In Account Information API, a distinct bank connection is called Connection. Each Account Information API Customer can have multiple Connections. When we visited Salt Edge Connect and connected “Fake Bank Simple”, we effectively created a Connection for our Customer in the system. So to retrieve all data for this Connection, we first need to retrieve the Connection itself.

The response contains an array of entries, each representing a connection to a financial institution.

In our case we will have only one entry. We need to save the id (in our case “111111111111111111”) to retrieve its accounts.

$ export CONNECTION_ID=111111111111111111

See connections reference for more information on Connection endpoints.

Only clients who use service keys can request a list of connections. For more information, please see the authentication guide.

Sample Request

URL

https://www.saltedge.com/api/v5/connections?customer_id={customer.id}

https://www.saltedge.com/api/v5/connections?customer_id={customer.id}

Method

GET

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/connections?customer_id=$CUSTOMER_ID
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/connections?customer_id=$CUSTOMER_ID

Sample Response

{
  "data": [
    {
      "id": "111111111111111111",
      "provider_code": "fakebank_simple_xf",
      "provider_name": "Fakebank Simple",
      "customer_id": "222222222222222222",
      ...
    }
  ]
}

Fetch accounts for connections

Having the Connection id, we can retrieve all its accounts.

The response contains an array of entries, each representing an account from a financial institution.

We need to save the id (in our case “333333333333333333”) to retrieve all transactions for this account.

$ export ACCOUNT_ID=333333333333333333

Sample Request

URL

https://www.saltedge.com/api/v5/accounts?connection_id={connection.id}

https://www.saltedge.com/api/v5/accounts?connection_id={connection.id}

Method

GET

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/accounts?connection_id=$CONNECTION_ID
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/accounts?connection_id=$CONNECTION_ID

Sample Response

{
  "data": [
    {
      "id": "333333333333333333",
      "name": "Fake account 1",
      "nature": "card",
      "balance": 2007.2,
      "currency_code": "EUR",
      "connection_id": "111111111111111111",
      "created_at": "2020-08-05T04:28:27Z",
      "updated_at": "2020-08-05T04:28:27Z",
      "extra": {
        "client_name": "Fake name"
      },
      ...
    }
  ]
}

Fetch transactions for an account

Having the Connection id and the Account id, we can retrieve its transactions.

The response contains an array of entries, each representing a transaction from a financial institution.

See transactions reference for more information on Transaction endpoints.

Sample Request

URL

https://www.saltedge.com/api/v5/transactions?connection_id={connection.id}&account_id={account.id}

https://www.saltedge.com/api/v5/transactions?connection_id={connection.id}&account_id={account.id}

Method

GET

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/transactions?connection_id=$CONNECTION_ID&account_id=$ACCOUNT_ID
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/transactions?connection_id=$CONNECTION_ID&account_id=$ACCOUNT_ID

Sample Response

{
  "data": [
    {
      "id": "444444444444444444",
      "duplicated": false,
      "mode": "normal",
      "status": "posted",
      "made_on": "2020-05-03",
      "amount": -200.0,
      "currency_code": "USD",
      "description": "test transaction",
      "category": "advertising",
      "account_id": "100",
      "created_at": "2020-08-03T07:28:27Z",
      "updated_at": "2020-08-04T07:28:27Z",
      "extra": {
        "original_amount": -3974.60,
        "original_currency_code": "CZK",
        "posting_date": "2020-05-07",
        "time": "23:56:12"
      },
      ...
    }
  ]
}

Next steps

  • Request Test status to connect real banking institutions.
  • Switch to Live status to bring value to your customers globally.
  • In this guide, we visited Connect manually. You might want to do that programmatically. For more information see about embedding Salt Edge Connect in your application.
  • Since new Account Information API clients are in test mode and have access only to fake providers, the request signature is not required. However, you will need to implement request signing before you are going live. For more information see our signature guide.
  • All responses with arrays (like accounts or transactions) are paginated by default, see how to implement it on our pagination guide.
  • The recommended way of synchronizing data with Account Information API is via callbacks. That way you won’t have to poll the servers to see whether there is new data available. See our callbacks guide for more information.

Try in Postman

Step 1

Install Postman. You can get it on https://www.getpostman.com/apps.

Step 2

Import the postman collection, click the button below to do that.

Run in Postman

Step 3

Account Information API requires APP_ID and SECRET headers in order to authenticate its clients. If you don’t have an API key created yet, you can use our quick start guide to help you create one. Once you have the API key created, you can add its secrets to postman.

Click on the eye on the top right corner and press on “Add” next to “Environments”.

Define variables APP_ID and SECRET with values from the key that you generated on https://www.saltedge.com/clients/profile/secrets, then add the environment.

Once added, you can select it in the top right corner, and all the requests to Account Information API will be authenticated using your API key.

Changelog

This page differs depending on which API version you are browsing at the moment.

Changed

  • routes /logins was changed to /connections
  • routes /tokens was changed to /connect_sessions
  • route /transactions/categorize was changed to /enrichment
  • field return_login_id was changed to return_connection_id for routes /connect_sessions, /oauth_providers
  • field login_id was changed to connection_id for routes /connect_sessions, /oauth_providers
  • route /transactions returns only non-duplicated transactions
  • on create, reconnect, refresh for routes /connections, /connect_sessions, /oauth_providers request format was changed, objects were added :consent, attempt
  • fetch_scopes and consent scopes are now being validated by both client’s allowed_fetch_scopes and provider’s supported_fetch_scopes
  • request format was changed for route /categories/learn
  • request format was changed for route /transactions/duplicate
  • request format was changed for route /transactions/unduplicate

Removed

  • route /connections/inactivate - should use PUT /connections/id to update status
  • route /connections/destroy_credentials - should use PUT /connections/id to update store_credentials
  • route /oauth/refresh - should use /connections/refresh or /connection/refresh instead
  • object holder_info for route /connections - should use route GET /holder_info
  • field token for route /connect_sessions
  • field forum_url for route /providers
  • category mortgage_and_rent was removed and separated into 2 new categories: mortgage, rent

Added

New errors

  • new error response format with documentation_url
{
  "error": {
    "class": "ConnectionNotFound",
    "message": "Connection with id: '111111111111111111' was not found.",
    "documentation_url": "https://docs.saltedge.com/account_information/v5/#errors-connection_not_found"
  },
  "request": {
    "connection_id": "111111111111111111"
  }
}

Upgrade guide

This guide explains the changes you will have to keep in mind when upgrading from v4 to v5 of Account Information API. Follow these steps:

Before going LIVE

In order to have the Salt Edge accounts transferred to LIVE mode the following steps should be followed:

  • Please provide Salt Edge representative with app’s test account to verify Account Information API integration;
  • Be sure to provide signature in accordance with the instructions;
  • If your application is running on mobile devices, desktops, tablets, which are under user’s control, please use app authentication;
  • Your application should be working correctly with all of the fake banks;
  • Your application should not create any duplicated customers (i.e. connecting the same provider with the same credentials, for the same user, using different customer entities);
  • The end-user should be able to create, reconnect, refresh and remove connections;
  • After deleting a user from your system, you should send a remove request;
  • Your application should handle correctly the refresh_timeout in provider entity;
  • Your application should handle correctly the ConnectionDuplicated error;
  • Your application should show the instructions for providers;
  • Your application should not allow usage of disabled providers;
  • Your application should use the duplicate route for a better user experience;
  • The Two-factor authentication has to be enabled for your account and all your Client users;
  • In order to avoid legal issues with end-users and data providers, the client should ensure that the end-users read and agree to End User License Terms.
  • Be sure to indicate Incident Reporting Email in the dashboard settings;

After all of the verifications have been made by a Salt Edge representative, the client account will be transferred to LIVE mode.

Know Your Customer

Account holder info

This feature allows the client to fetch essential information about customers from their bank accounts to be further used with the purpose of KYC verification. Make sure to contact our Sales team to enable holder_info scope for your client account.

Upon enabling the feature you will receive a holder_info field inside the provider object. This field will provide information on the account holder details that can be fetched from the queried provider.

Holder info route returns the information fetched from the customer’s account with the particular provider.

Depending on the provider, the following attributes might be returned in the holder_info:

  • names - returns the name(s) on the customer’s account with the provider, e.g. ["John Doe"];
  • emails - returns email(s) registered within customer’s account with the provider, e.g. ["john.doe@example.com", "johndoe@gmail.com"];
  • phone_numbers - returns the phone number(s) registered in the customer’s account with the provider, e.g. ["+16135550175", "+40981233422"];
  • addresses - returns the address(es) on the customer’s account with the provider, e.g.

For some providers extra fields, e.g. Social Security Number or Cadastro de Pessoas Físicas, can also be returned.

Holder info can be fetched independently or along with other connection information, e.g. accounts and transactions.

In order to test the holder_info attribute, you can connect the fakebank_simple_xf provider.

Sample response (as provider attribute)

"holder_info": ["names", "emails"]

Sample response (as separate route)

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

Encrypted credentials

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

Any endpoint that accept or require a “credentials” object (like Creating connections), can also accept encrypted_credentials instead of credentials.

where credentials_json is the original credentials object encoded as a JSON string.

This feature is enabled separately for each client and is subject to additional fees. For more information please contact us.

Payload Structure

{
  "algorithm": "AES-256-CBC",
  "key": base64(public_rsa(random_key)),
  "iv": base64(public_rsa(random_iv)),
  "data": base64(aes_encrypt(random_key, random_iv, credentials_json)),
  "version": "version_provided_by_saltedge"
}

Salt Edge Connect

You can easily test Connect from your Dashboard page by pressing the New Connection button.

After your application has received a connect_session for connecting or reconnecting a connection, you can redirect your user to the Salt Edge Connect URL. There, they will see a screen that lets them pick a country and a provider.

Your user will also be asked to input their credentials and if needed, any of the interactive credentials.

For example, a user picked Italy as country and American Express as provider. This is what he/she will see:

To start the fetching process, the user will have to press “Proceed”. Afterwards, he will be informed about their connection’s progress.

After the fetching is done, the user will be redirected back to your application.

After the connect stage is changed to Updating Accounts(fetch_accounts), the user interaction will not be required, and the connect page can be hidden.

Using connect in an iframe

Once you receive a connect_url from Connect Sessions, you can embed it in an iframe. However, there are several things you need to take into account when doing that:

  • to subscribe to callbacks, and close the iframe when the connection process finishes;
  • connecting providers that authenticate via redirect may not work. That’s because most of the providers have HTTP headers (X-Frame-Options, Content-Security-Policy) that restrict the authentication page from being included in an iframe.

There are several ways in which you can mitigate the last point:

  • Always open providers with redirect authentication in a new page. These providers have the mode flag set to oauth.
  • If the previous scenario is not an option, you can use supported_iframe_embedding flag to distinguish providers that restrict iframe usage.

Client side callbacks

When you request for a connect session, you can pass an optional argument javascript_callback_type. This argument enables one of the following notification methods:

Salt Edge Connect will send any of these callbacks only in case when javascript_callback_type was specified in the connect session request.

Iframe injection

When not using the SDKs, your app is responsible for capturing the URLs, if you wish to be notified about the connect process.

The inserted URL has a custom scheme and host. The scheme of the URL is saltbridge and the host is connect. Here’s an example of such a URL:

saltbridge://connect/{"data":{"connection_id":"997674448","stage":"fetching","secret":"Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM", "custom_fields":{"key":"value"}, "api_stage":"start"}}

The URL will be URLEncoded (percent-encoded), the URL above is not URLEncoded to preserve it’s readability.

Once your app has captured the inserted URL, it has to serialize the JSON-encoded URL path following the scheme and the host. Here’s another example, this time of a duplicated connection callback:

saltbridge://connect/{"data":{"duplicated_connection_id":"994317674","stage":"error","custom_fields":{"key":"value"}, "api_stage":"finish"}}

Once your app has decoded the URL path, it can start performing several actions like accounts listing or error handling.

External object

If you access the Connect page from a .Net host, and you use WebBrowser.ObjectForScripting, we will try to call the window.external.SaltBridge function with the connection attributes serialized as JSON.

NOTE: In the example, SaltBridge is a method defined on the object that was specified as an object for scripting: webBrowser1.ObjectForScripting = this which initialized the WebView.

External Notify Example

public void SaltBridge(String serializedLogin) {
  // data
}

serializedConnection

{
  "data": {
    "connection_id":"111111111111111111",
    "stage":"fetching",
    "secret":"Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
    "custom_fields":{
      "key":"value"
    },
    "api_stage": "start"
  }
}

Post message

If you access the connect page wrapped in an iframe, you can use Window.postMessage which performs cross-origin communication.

Post Message Example

window.addEventListener("message", function(event) {
    console.log(JSON.parse(event.data))
  }
)

serializedConnection

{
  "data": {
    "connection_id":"111111111111111111",
    "stage":"fetching",
    "secret":"Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
    "custom_fields": {
      "key":"value"
    },
    "api_stage": "start"
  }
}

External notify

On Windows Store app platform you can use event handler for ScriptNotify event of WebView. Your code should handle window.external.notify(args) call, ScriptNotify will fire, and you’ll get the args in Value property of NotifyEventArgs parameter.

Remember to add https://saltedge.com and https://*.saltedge.com to Content URIs in Package.appxmanifest.

External Notify Example

protected override void OnNavigatedTo(NavigationEventArgs e) {
  browser.ScriptNotify += browser_ScriptNotify;
}

private void browser_ScriptNotify(object sender, NotifyEventArgs e) {
  var serializedConnection = e.Value;
}

serializedConnection

{
  "data": {
    "connection_id":"111111111111111111",
    "stage":"fetching",
    "secret":"Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
    "custom_fields": {
      "key":"value"
    },
    "api_stage": "start"
  }
}

Connect callbacks

There are 2 callback types of Salt Edge Connect:

  • Standard callback
  • Duplicated connection callback.

Possible stage values for each callback type are fetching, success and error.

Parameter api_stage shows detailed information of the fetching process. Possible values are attempts stages.

Fetching

{
  "data": {
    "connection_id": "111111111111111111",
    "stage": "fetching",
    "secret": "Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
    "custom_fields": {
      "key": "value"
    },
    "api_stage": "start"
  }
}

and on duplicated connection:

{
  "data": {
    "duplicated_connection_id": "111111111111111112",
    "stage": "fetching",
    "custom_fields": {
      "key": "value"
    },
    "api_stage": "start"
  }
}

Success

For instance, when your user has created a connection using Salt Edge Connect, we will send the following success callback:

{
  "data": {
    "connection_id": "111111111111111111",
    "stage": "success",
    "secret": "Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
    "custom_fields": {
      "key": "value"
    },
    "api_stage": "finish"
  }
}

and on duplicated connection:

{
  "data": {
    "duplicated_connection_id": "111111111111111112",
    "stage": "success",
    "custom_fields": {
      "key": "value"
    },
    "api_stage": "finish"
  }
}

Error

Sometimes we fail to fetch the information from the provider’s page. It might happen because the interactive data was not sent by the user, the credentials are wrong, or we could not perform one of the steps of the fetching process. In this case, you will receive an error callback, containing a JSON similar to the following:

{
  "data": {
    "connection_id": "111111111111111111",
    "stage": "error",
    "secret": "Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
    "custom_fields": {
      "key": "value"
    },
    "api_stage": "finish"
  }
}

and on duplicated connection:

{
  "data": {
    "duplicated_connection_id": "111111111111111112",
    "stage": "error",
    "custom_fields": {
      "key": "value"
    },
    "api_stage": "finish"
  }
}

API Connect

If you do not wish to create connections using Salt Edge Connect, you can perform all the connection actions using our API.

In order to create a new connection, you should use the connections create route. After creating the connection, your application will receive the corresponding callbacks so you can fetch your newly created connection.

If the connection you wish to connect is an interactive one, you will receive an interactive callback specified in your app’s profile, which means that you have to use the interactive route and follow the instructions specified in the API reference.

API Connect requires high-security standards for data handling on the client’s side. Having access to the API Connect routes gives you direct access to the end customer’s sensitive information, which is why we need to make sure that it is handled properly and securely. Therefore, this integration method is only available for the certified and/or selected partners.

In case your Client Account settings allow only Salt Edge Connect usage, though you try to send requests to API Connect endpoints, then you will encounter the ActionNotAllowedErrorerror. For more information and assistance on the mentioned error you have received, please contact our Sales representatives via contact us.

Updating data

If a connection had an error while connecting, and it had an InvalidCredentials error during the fetching process, you should reconnect it and send the correct credentials in your request body.

When the connection is connected correctly, and you received all the accounts and transactions details, you can refresh the connection, and keep its data up-to-date.

Callbacks

The most important parts of Account Information API (e.g. Connection management) are asynchronous.

Every Web application has to provide a set of valid URLs which we will use to notify about the fetching progress. Other applications can poll Account Information API in order to retrieve the updated information.

There are several common points about the request we send to the callback URLs provided by the client:

  • The Content-Type header is application/json;
  • There is a Signature header that identifies the request was signed by Account Information API;
  • The request method is always POST;
  • The JSON object sent will always have a data field;
  • The meta field will display the version of the callbacks API.

You can set the callback URLs for your application by accessing your callbacks page.

Due to security reasons, the callbacks can be sent to ports 80/HTTP (in test and pending modes) and 443/HTTPS (in test, pending and live modes) only!
Also, the callbacks do not follow redirects.

Request Identification

In order for the client to identify that the request is coming from Account Information API, there are two options, Signature and Mutual TLS:

Signature

Signature - base64 encoded SHA256 signature of the string represented in the form callback_url|post_body - 2 parameters concatenated with a vertical bar |, signed with a Account Information API’s private key.

You can find the version of the signature key used to sign the callback in the Signature-key-version header. The current version is 5.0 which corresponds to the following public key:

  -----BEGIN PUBLIC KEY-----
  MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvL/Xxdmj7/cpZgvDMvxr
  nTTU/vkHGM/qkJ0Q+rmfYLru0Z/rSWthPDEK3orY5BTa0sAe2wUV5Fes677X6+Ib
  roCF8nODW5hSVTrqWcrQ55I7InpFkpTxyMkiFN8XPS7qmYXl/xofbYq0olcwE/aw
  9lfHlZD7iwOpVJqTsYiXzSMRu92ZdECV895kYS/ggymSEtoMSW3405dQ6OfnK53x
  7AJPdkAp0Wa2Lk4BNBMd24uu2tasO1bTYBsHpxonwbA+o8BXffdTEloloJgW7pV+
  TWvxB/Uxil4yhZZJaFmvTCefxWFovyzLdjn2aSAEI7D1y4IYOdByMOPYQ6Mn7J9A
  9wIDAQAB
  -----END PUBLIC KEY-----

An example of the string that is to be used to generate the signature looks as follows:

https://www.client.com/api/callbacks/success|{"data":{"connection_id":"111111111111111111","customer_id":"222222222222222222","custom_fields":{}},"meta":{"version":"5","time":"2020-07-07T13:00:28Z"}}

The pseudocode that we use to generate the signature looks like this:

base64(sha256_signature(private_key, "callback_url|post_body"))

Mutual TLS

To verify that callback is coming from Account Information API, you can use Client Certificate Authentication.

  1. Go to Account -> Settings -> Callbacks. There you will see on the right Mutual TLS.

  2. Click on Generate CSR.

  3. Set Certificate attributes if needed and press Generate.

  4. Download CSR.

  5. Use CA to generate client certificate from Downloaded CSR.

    openssl x509 -req -days 365 -in salt_edge_callbacks.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out client.crt
    
  6. Upload generated certificate via the following form.

To see how it could be implemented on the server side check this example.

Requests cycle

To avoid unnecessary requests, performance issues and fetching all data, use the following diagram:

Success

We send a callback to your application’s success URL whenever any operation has caused a change in the data we store for a particular connection.

For instance, after you’ve redirected your user to the Connect page and they have selected their provider, filled in the credentials, and pressed “Proceed”, we’ll send you a success callback. This callback will contain the customer identifier and the id of the newly created connection. Afterwards, your application will be able to use the show connection route and query the information about this connection. You could also fetch the connection’s accounts and query the accounts (if any exist at the moment we sent the callback).

Whenever we have more information about the connection, we will send another success callback.

A success callback marks a change in the data, and you can generally expect from one to three success callbacks with the same payload within several minutes. We recommend that your application lists updated connection object, updates account balances, extra fields, and transactions using from_id to fetch newly imported records at each callback, as some information might change during the fetching process.

For instance, when your user has created a connection using Salt Edge Connect, we will send the following success callback:

{
  "data": {
    "connection_id": "111111111111111111",
    "customer_id": "222222222222222222",
    "custom_fields": { "key": "value" }
  },
  "meta": {
    "version": "5",
    "time": "2020-08-05T07:28:27.671Z"
  }
}

You can now use the show connection route and obtain the provider, country and some other attributes of the new connection.

Failure

Sometimes we fail to fetch the information from the provider’s page. It might happen because the interactive data was not sent by the user, the credentials are wrong or we could not perform one of the steps of the fetching process. In this case, you will receive a fail callback, containing a JSON similar to the following:

{
  "data": {
    "connection_id": "111111111111111111",
    "customer_id": "222222222222222222",
    "custom_fields": { "key": "value" },
    "error_class": "InvalidCredentials",
    "error_message": "Invalid credentials."
  },
  "meta": {
    "version": "5",
    "time": "2020-08-05T07:28:27.686Z"
  }
}

After you get this callback, you need to request the connection to check for its updates. Please note that even if there’s an error, we still store the connection.

If you would like to delete the erroneous connection, you can use the remove connection route. In case of an InvalidCredentials error, we recommend you to use a Reconnect.

In order to avoid connection duplication errors on new connection creation, when you read the connection after a fail callback, we recommend you remove the connection in case of last_fail_error_class is equal to InvalidCredentials, and the connection has zero linked accounts.

Additional callbacks

There are additional callbacks that your app needs to implement in order to use the API-only version of Account Information API.

Notify

Salt Edge can inform you about the progress the connection is going through using a Notify callback. Notify callback (if the appropriate Notify URL is set in your Client account), will be sent for create, reconnect and refresh attempts.

Your app can expect the notify callback several times, depending on the type of the connection, but you can use this information to inform your user about what’s happening with their connection.

The possible stages sent in a notify callback are as follows:

  • start - the fetching process has just begun;
  • connect - connecting to the data source;
  • interactive - waiting for the interactive credentials;
  • fetch_holder_info - fetching the information about account holder;
  • fetch_accounts - fetching the accounts;
  • fetch_recent - fetching the data for a recent period (several months);
  • fetch_full - fetching the data for a longer period;
  • disconnect - disconnecting from the data source;
  • finish - wrapping up the fetching process.

Here’s an example callback sent to the /notify route of your app:

{
  "data": {
    "connection_id": "111111111111111111",
    "customer_id": "222222222222222222",
    "custom_fields": { "key": "value" },
    "stage": "start"
  },
  "meta": {
    "version": "5",
    "time": "2020-08-04T07:28:27Z"
  }
}
You might not receive all the stages for some connections. Notify callbacks will not be triggered for daily attempts.

Interactive

Some of the providers require an additional step before signing in, asking users to input an SMS, Token, solve a CAPTCHA, etc.

Whenever we encounter that the connection requires an interactive step, we will send the interactive callback to the interactive route set in your app’s profile. Your app should prompt the user for the interactive credentials and send them to the interactive route.

We also send a snippet of HTML so that it would be easier for your app to display the CAPTCHA or image to the user. If the provider requires filling a CAPTCHA, the img tag in the HTML will contain the image URL.

During this process, the connection’s stage will be set to interactive.

The interactive callback should contain the values of the interactive_credentials field from the corresponding provider.

Here’s an example callback sent to your app’s /interactive route:

{
  "data": {
    "connection_id": "111111111111111111",
    "customer_id": "222222222222222222",
    "custom_fields": { "key": "value" },
    "stage": "interactive",
    "html": "<div id='interactive'><img src='https://docs.saltedge.com/assets/images/saltedge_captcha.png' width='10' height='10' alt='some description' title='some description'></div>",
    "session_expires_at": "2020-08-04T08:28:27Z",
    "interactive_fields_names": ["image"]
  },
  "meta": {
    "version": "5",
    "time": "2020-08-04T07:28:27Z"
  }
}

In case of a dynamic_select field (sent only for Providers in AISP flow), the callback will also include interactive_fields_options, which you need to present to the user:

{
  "data": {
    "connection_id": "111111111111111111",
    "customer_id": "222222222222222222",
    "custom_fields": { "key": "value" },
    "stage": "interactive",
    "html": "<p>Please select accounts from the list:</p>",
    "session_expires_at": "2020-07-06T11:27:10Z",
    "interactive_fields_names": ["accounts"],
    "interactive_fields_options": {
      "accounts": [
        {
          "name":           "account1",
          "english_name":   "My checking account",
          "localized_name": "My checking account",
          "option_value":   "service_acc_guid1",
          "selected":       false
        },
        {
          "name":           "account2",
          "english_name":   "My savings account",
          "localized_name": "My savings account",
          "option_value":   "service_acc_guid2",
          "selected":       false
        }
      ]
    }
  },
  "meta": {
    "version": "5",
    "time": "2020-08-04T07:28:27Z"
  }
}

Note: Some interactive providers request to select only one option from dynamic_select interactive field. In this case we mark such fields by adding multiple: false flag to the extra key in provider’s interactive fields:

"interactive_fields": [
  {
    "name": "language",
    "english_name": "Language",
    "localized_name": "Language",
    "nature": "dynamic_select",
    "position": 3,
    "optional": false,
    "extra": {
        "multiple": false
    }
  }
]

In such a case we expect to receive only 1 selected option value as a String.

When the provider requires multiple options to be selected, we mark such fields by adding multiple: true flag to the extra key in provider’s interactive fields:

"interactive_fields": [
  {
    "name": "accounts",
    "english_name": "Accounts",
    "localized_name": "Accounts",
    "nature": "dynamic_select",
    "position": 3,
    "optional": false,
    "extra": {
        "multiple": true
    }
  }
]

In such a case we expect to receive an Array of strings.

Interactive Redirect

There are some OAuth providers that require 2 redirects for authorization. In these cases, for the 2nd redirect Salt Edge will send an interactive callback with redirect_url field:

{
  "data": {
    "connection_id":            "111111111111111111",
    "customer_id":              "222222222222222222",
    "html":                     "",
    "redirect_url":             "https://bank.com/authorize"
    "stage":                    "interactive",
    "session_expires_at":       "2020-08-04T08:28:27Z",
    "interactive_fields_names": [],
    "custom_fields":            { "key": "value" }
  },
  "meta": {
    "version": "5",
    "time":    "2020-08-04T07:28:27Z"
  }
}

Your application should redirect the user to redirect_url field value of the interactive callback payload. Once the end-user will be authorized on the provider’s side, they will be redirected to the return_to URL indicated in the create connection request.

To continue the process, you need to send a request containing the query string appended to your return_to URL to the interactive route.

{
  "data": {
    "credentials": {
      "query_string": "access_token=111111111111111111"
    }
  }
}

If there are no query parameters when the end-user is redirected to the return_to URL, please send an empty credentials object.

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

Authentication

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"credentials\": { \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v5/connections/111111111111111111/interactive
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"credentials\": { \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v5/connection/interactive

Destroy

Whenever a connection gets removed, we will send a callback to your application’s destroy URL, if such is set in your Client account.

Here’s an example callback sent to your app’s /destroy route:

{
  "data": {
    "connection_id": "111111111111111111",
    "customer_id": "222222222222222222"
  },
  "meta": {
    "version": "5",
    "time": "2020-08-04T07:28:27Z"
  }
}

Service

Whenever the connection had issues in the past and a change was made in connection’s provider codebase, your application will receive a callback telling that a refresh is needed in order to update connection’s data.

The possible reasons sent in a /service callback are as follows:

  • fixed - a fix was made;
  • updated - an update was made;

Here’s an example callback sent to the /service route of your app:

{
  "data": {
    "connection_id": "111111111111111111",
    "customer_id": "222222222222222222",
    "custom_fields": { "key": "value" },
    "reason": "updated"
  },
  "meta": {
    "version": "5",
    "time": "2020-08-04T07:28:27Z"
  }
}

Errors

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

Error attributes

class

string

The class of the error, one of the listed below

message

string

A message describing the error

documentation_url

string

A link for error documentation

request

object

The body of the request that caused the error

class

string

The class of the error, one of the listed below

message

string

A message describing the error

documentation_url

string

A link for error documentation

request

object

The body of the request that caused the error

Error codes

[400] Bad Request
[404] Not Found
[406] Not Acceptable
[409] Duplicated
[429] Too Many Requests

Sample response

{
  "error": {
    "class": "ConnectionNotFound",
    "message": "Connection with id: '111111111111111111' was not found.",
    "documentation_url": "https://docs.saltedge.com/account_information/v5/#errors-connection_not_found"
  },
  "request": {
    "connection_id": "111111111111111111"
  }
}

List

AccountNotFound

An account with the sent account_id could not be found

ActionNotAllowed

The client has no access to the required route or direct API access is not permitted. Please contact us

AllAccountsExcluded

You have excluded all the accounts from the connection fetching process

ApiKeyNotFound

The API key with the provided App-id and Secret does not exist or is inactive

AppIdNotProvided

The App-id was not provided in request headers

AttemptNotFound

An attempt with such id does not exist

BackgroundFetchLimitExceeded

Background fetch limit (4 times in a 24 hour period) was exceeded (without user’s presence). This restriction applies only to PSD2 providers.

BatchSizeLimitExceeded

More than 100 objects were sent in the request (100 is the limit)

CategorizationLimitReached

One client can categorize at most 1000 transactions per day

ClientDisabled

The client has been disabled. You can find out more about the disabled status on Disabled guides page

ClientNotFound

The API key used in the request does not belong to a client

ClientPending

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

ClientRestricted

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

ConnectionFailed

Some network errors appear while fetching data

ConnectionLost

Internet connection was lost in the process

CountryNotFound

Sending a country_code that is not present in our system

CustomerNotFound

A customer with such customer_id could not be found

CustomerLocked

Customer is locked. May be unlocked

CredentialsNotMatch

New connection credentials do not match the old ones on reconnect. Please contact us in case you encountered this error.

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

DateTimeFormatInvalid

We have received an invalid DateTime format

DateTimeOutOfRange

Sending a datetime 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

FetchScopesNotAllowed

The value of fetch_scopes parameter is limited by client, provider and/or consent. In case you encounter this error, please contact us

FetchScopesInvalid

The value of fetch_scopes parameter is invalid

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 connection

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 occurred

InvalidCredentials

The customer tried to connect/reconnect a connection 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

ConnectionAlreadyProcessing

The connection is already being processed

ConnectionAlreadyAuthorized

The connection was already authorized

ConnectionCannotBeRefreshed

The next refresh attempt will be allowed according to next_refresh_possible attribute or connection’s status is inactive

ConnectionDisabled

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

ConnectionDuplicated

The client tried to create a connection that already exists

ConnectionFetchingStopped

Connection fetching had stopped because of fetching timeout or connection was deleted during fetch process

ConnectionLimitReached

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

ConnectionNotFound

We could not find a connection with the requested connection_id

MissingExpiresAt

The Expires-at field is missing in the headers

MissingSignature

The Signature field is missing in the headers

ProviderAccessNotGranted

The access to the provider during redirect flow did not complete successfully

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 connection

ProviderInactive

New connections cannot be created while the current ones cannot be refreshed or reconnected

ProviderNotFound

Sending a provider_code that is not present in our system

ProviderKeyFound

The chosen provider does not have provider keys

ProviderNotInteractive

The connection’s provider has no interactive step

ProviderUnavailable

The provider is temporarily unavailable

PublicKeyNotProvided

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

RateLimitExceeded

Too many connections 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 missing from attempts-object or you need to specify your application’s home_url in your Client dashboard

ReturnURLTooLong

The return_to URL exceeds 2040 characters

ReportNotFound

The requested Financial Insights id was not found

RouteNotFound

The action and/or the endpoint you are trying to access does not exist

SecretNotProvided

The Secret was not provided in request headers

SignatureNotMatch

The Signature header does not match the correct one

TooManyRequests

Too many requests have occurred for connecting/reconnecting a connection from one IP address in a short 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, app_id and connection_id

WrongProviderMode

We do not support the received provider_mode

WrongRequestFormat

The JSON request is incorrectly formed

The passed from_date - to_date interval is out of consent from_date - to_date range

The value of consent scopes parameter is invalid

The value of consent scopes parameter is not allowed by client or/and by provider

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

Invalid consent period_days value or not allowed by provider

The consent has already been revoked

Refresh is not possible because the consent has been revoked

Refresh is not possible because the consent has expired

A consent with such id does not exist

WrongReportType

We have received a wrong report type

AccountNotFound

An account with the sent account_id could not be found

ActionNotAllowed

The client has no access to the required route or direct API access is not permitted. Please contact us

AllAccountsExcluded

You have excluded all the accounts from the connection fetching process

ApiKeyNotFound

The API key with the provided App-id and Secret does not exist or is inactive

AppIdNotProvided

The App-id was not provided in request headers

AttemptNotFound

An attempt with such id does not exist

BackgroundFetchLimitExceeded

Background fetch limit (4 times in a 24 hour period) was exceeded (without user’s presence). This restriction applies only to PSD2 providers.

BatchSizeLimitExceeded

More than 100 objects were sent in the request (100 is the limit)

CategorizationLimitReached

One client can categorize at most 1000 transactions per day

ClientDisabled

The client has been disabled. You can find out more about the disabled status on Disabled guides page

ClientNotFound

The API key used in the request does not belong to a client

ClientPending

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

ClientRestricted

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

ConnectionFailed

Some network errors appear while fetching data

ConnectionLost

Internet connection was lost in the process

CountryNotFound

Sending a country_code that is not present in our system

CustomerNotFound

A customer with such customer_id could not be found

CustomerLocked

Customer is locked. May be unlocked

CredentialsNotMatch

New connection credentials do not match the old ones on reconnect. Please contact us in case you encountered this error.

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

DateTimeFormatInvalid

We have received an invalid DateTime format

DateTimeOutOfRange

Sending a datetime 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

FetchScopesNotAllowed

The value of fetch_scopes parameter is limited by client, provider and/or consent. In case you encounter this error, please contact us

FetchScopesInvalid

The value of fetch_scopes parameter is invalid

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 connection

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 occurred

InvalidCredentials

The customer tried to connect/reconnect a connection 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

ConnectionAlreadyProcessing

The connection is already being processed

ConnectionAlreadyAuthorized

The connection was already authorized

ConnectionCannotBeRefreshed

The next refresh attempt will be allowed according to next_refresh_possible attribute or connection’s status is inactive

ConnectionDisabled

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

ConnectionDuplicated

The client tried to create a connection that already exists

ConnectionFetchingStopped

Connection fetching had stopped because of fetching timeout or connection was deleted during fetch process

ConnectionLimitReached

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

ConnectionNotFound

We could not find a connection with the requested connection_id

MissingExpiresAt

The Expires-at field is missing in the headers

MissingSignature

The Signature field is missing in the headers

ProviderAccessNotGranted

The access to the provider during redirect flow did not complete successfully

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 connection

ProviderInactive

New connections cannot be created while the current ones cannot be refreshed or reconnected

ProviderNotFound

Sending a provider_code that is not present in our system

ProviderKeyFound

The chosen provider does not have provider keys

ProviderNotInteractive

The connection’s provider has no interactive step

ProviderUnavailable

The provider is temporarily unavailable

PublicKeyNotProvided

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

RateLimitExceeded

Too many connections 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 missing from attempts-object or you need to specify your application’s home_url in your Client dashboard

ReturnURLTooLong

The return_to URL exceeds 2040 characters

ReportNotFound

The requested Financial Insights id was not found

RouteNotFound

The action and/or the endpoint you are trying to access does not exist

SecretNotProvided

The Secret was not provided in request headers

SignatureNotMatch

The Signature header does not match the correct one

TooManyRequests

Too many requests have occurred for connecting/reconnecting a connection from one IP address in a short 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, app_id and connection_id

WrongProviderMode

We do not support the received provider_mode

WrongRequestFormat

The JSON request is incorrectly formed

The passed from_date - to_date interval is out of consent from_date - to_date range

The value of consent scopes parameter is invalid

The value of consent scopes parameter is not allowed by client or/and by provider

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

Invalid consent period_days value or not allowed by provider

The consent has already been revoked

Refresh is not possible because the consent has been revoked

Refresh is not possible because the consent has expired

A consent with such id does not exist

WrongReportType

We have received a wrong report type

If a ‘500’ error is received, please report this error to our Customer Care team.

api

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.

List

Returns a list of countries supported by Account Information API.

Parameters

include_fake_providers

boolean, optional

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

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 connections will be automatically refreshed. Possible values: 0 to 23

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 connections will be automatically refreshed. Possible values: 0 to 23

Possible Errors

URL

https://www.saltedge.com/api/v5/countries

https://www.saltedge.com/api/v5/countries

Method

GET

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/countries
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/countries

Sample response

{
  "data": [
    {
      "code": "CZ",
      "name": "Czech Republic",
      "refresh_start_time": 1
    },
    {
      "code": "IL",
      "name": "Israel",
      "refresh_start_time": 7
    },
    {
      "code": "MD",
      "name": "Moldova",
      "refresh_start_time": 0
    },
    {
      "code": "RO",
      "name": "Romania",
      "refresh_start_time": 0
    },
    {
      "code": "ES",
      "name": "Spain",
      "refresh_start_time": 1
    },
    {
      "code": "GB",
      "name": "United Kingdom",
      "refresh_start_time": 23
    },
    {
      "code": "XF",
      "name": "Fake",
      "refresh_start_time": 8
    },
    {
      "code": "XO",
      "name": "Other",
      "refresh_start_time": 4
    },
    ...
  ]
}

Providers

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

Attributes

id

string

The id of the provider

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

identification_mode

string

Whether the request to the provider is made with your authorization headers or with Salt Edge’s. Possible values are: client, saltedge

instruction

string

Guidance on how to connect the bank

home_url

string

The URL of the main page of the provider

login_url

string

Point of entrance to provider’s login web interface

logo_url

string

The URL for the provider logo, may have a placeholder for providers with missing logos

country_code

string

Code of the provider’s country

refresh_timeout

integer

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

holder_info

array

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

max_consent_days

integer

Maximum allowed consent duration. If it is null, then there are no limits

created_at

datetime

Time and date when the provider was integrated

updated_at

datetime

The last time when any of the provider’s attributes were changed

timezone

string

Time zone data of capital/major city in a region corresponding to the provider

max_interactive_delay

integer

Delay in seconds before InteractiveAdapterTimeout error will be raised

optional_interactivity

boolean

Provider which supports flipping of the interactive and automatic_fetch flags after connect

regulated

boolean

Whether the provider is integrated via a regulated channel under PSD2

max_fetch_interval

integer

Maximum period of days that a provider can return from its interface

supported_fetch_scopes

array

Array of strings with supported fetch_scopes

supported_account_extra_fields

array

Array of possible account extra fields to be fetched

supported_transaction_extra_fields

array

Array of possible transaction extra fields to be fetched

supported_account_natures

array

Array of possible account natures to be fetched

supported_account_types

array

Possible values are: personal, business

identification_codes

array

List of codes identifying supported branches of a specific provider. It may include BLZ(Germany), ABI+CAB(Italy), Branch Codes(France) etc.

supported_iframe_embedding

boolean

Possible values are: true, false

id

string

The id of the provider

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

identification_mode

string

Whether the request to the provider is made with your authorization headers or with Salt Edge’s. Possible values are: client, saltedge

instruction

string

Guidance on how to connect the bank

home_url

string

The URL of the main page of the provider

login_url

string

Point of entrance to provider’s login web interface

logo_url

string

The URL for the provider logo, may have a placeholder for providers with missing logos

country_code

string

Code of the provider’s country

refresh_timeout

integer

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

holder_info

array

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

max_consent_days

integer

Maximum allowed consent duration. If it is null, then there are no limits

created_at

datetime

Time and date when the provider was integrated

updated_at

datetime

The last time when any of the provider’s attributes were changed

timezone

string

Time zone data of capital/major city in a region corresponding to the provider

max_interactive_delay

integer

Delay in seconds before InteractiveAdapterTimeout error will be raised

optional_interactivity

boolean

Provider which supports flipping of the interactive and automatic_fetch flags after connect

regulated

boolean

Whether the provider is integrated via a regulated channel under PSD2

max_fetch_interval

integer

Maximum period of days that a provider can return from its interface

supported_fetch_scopes

array

Array of strings with supported fetch_scopes

supported_account_extra_fields

array

Array of possible account extra fields to be fetched

supported_transaction_extra_fields

array

Array of possible transaction extra fields to be fetched

supported_account_natures

array

Array of possible account natures to be fetched

supported_account_types

array

Possible values are: personal, business

identification_codes

array

List of codes identifying supported branches of a specific provider. It may include BLZ(Germany), ABI+CAB(Italy), Branch Codes(France) etc.

supported_iframe_embedding

boolean

Possible values are: true, false

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,
  "identification_mode": "saltedge",
  "instruction": "Please fill in all the fields.",
  "home_url": "http://example.com",
  "login_url": "http://example.com/login",
  "logo_url": "https://cdn.com/logos/providers/xf/fake.svg",
  "country_code": "XF",
  "refresh_timeout": 60,
  "holder_info": ["names", "emails", "phone_numbers"],
  "max_consent_days": 10,
  "created_at": "2020-07-26T07:28:27Z",
  "updated_at": "2020-07-31T07:28:27Z",
  "timezone": "Europe/London",
  "max_interactive_delay": 480,
  "optional_interactivity": true,
  "regulated": false,
  "max_fetch_interval": 60,
  "supported_fetch_scopes": ["accounts", "transactions"],
  "supported_account_extra_fields": [],
  "supported_transaction_extra_fields": [],
  "supported_account_natures": ["account", "card"],
  "supported_account_types": ["personal"],
  "identification_codes": ["123123"],
  "supported_iframe_embedding": true
}

Show

Allows you to inspect a 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

provider_code

string

Provider’s code

Possible Errors

URL

https://www.saltedge.com/api/v5/providers/{provider.code}

https://www.saltedge.com/api/v5/providers/{provider.code}

Method

GET

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/providers/fakebank_interactive_xf
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/providers/fakebank_interactive_xf

Sample response

{
  "data": {
    "id": "67",
    "code": "fakebank_interactive_xf",
    "name": "Fake Bank with SMS",
    "mode": "web",
    "status": "active",
    "automatic_fetch": false,
    "interactive": true,
    "instruction": "Valid credentials for this provider are:\nlogin - any string which starts with \"username\",\npassword - \"secret\",\nsms - \"123456\"\n",
    "refresh_timeout": 5,
    "customer_notified_on_sign_in": false,
    "home_url": "http://example.com",
    "login_url": "http://example.com/login",
    "forum_url": "https://www.saltedge.com/support_requests/new?provider_code=fakebank_interactive_xf",
    "logo_url": "https://d1uuj3mi6rzwpm.cloudfront.net/logos/providers/xf/fakebank_interactive_xf.svg",
    "country_code": "XF",
    "created_at": "2014-03-19T17:55:44Z",
    "updated_at": "2019-03-07T09:57:26Z",
    "timezone": "UTC",
    "holder_info": [],
    "max_consent_days": null,
    "identification_mode": "saltedge",
    "max_interactive_delay": 180,
    "optional_interactivity": false,
    "regulated": false,
    "max_fetch_interval": 60,
    "supported_fetch_scopes": ["accounts", "transactions"],
    "supported_account_natures": ["account", "card"],
    "supported_account_types": ["personal"],
    "identification_codes": ["123123"],
    "supported_iframe_embedding": true,
    "supported_account_extra_fields": [
      "account_name",
      "account_number",
      "card_type",
      "cards",
      "client_name",
      "iban",
      "sort_code",
      "status",
      "swift"
    ],
    "supported_transaction_extra_fields": [
      "convert",
      "original_amount",
      "original_currency_code",
      "payee",
      "posting_date",
      "transfer_account_name"
    ],
    "required_fields": [{
        "name": "login",
        "english_name": "Login",
        "localized_name": "Login",
        "nature": "text",
        "position": 1,
        "optional": false,
        "extra": {}
      },
      {
        "name": "password",
        "english_name": "Password",
        "localized_name": "Password",
        "nature": "password",
        "position": 2,
        "optional": false,
        "extra": {}
      }
    ],
    "interactive_fields": [{
      "name": "sms",
      "english_name": "SMS code",
      "localized_name": "SMS code",
      "nature": "number",
      "position": 1,
      "optional": false,
      "extra": {}
    }]
  }
}

List

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.

Providers that require a client provider key will be included only if you have created provider keys for them and added to your client account.

Parameters

from_id

string, optional

The id of the provider which the list starts with, 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

provider_key_owner

string, optional

Filtering providers by key owner, possible values are: client, saltedge. When value is set as client, only providers with client-set keys will be returned. Please see Client Provider Keys

from_id

string, optional

The id of the provider which the list starts with, 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

provider_key_owner

string, optional

Filtering providers by key owner, possible values are: client, saltedge. When value is set as client, only providers with client-set keys will be returned. Please see Client Provider Keys

Possible Errors

URL

https://www.saltedge.com/api/v5/providers

https://www.saltedge.com/api/v5/providers

Method

GET

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/providers
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/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,
      "identification_mode": "saltedge",
      "instruction": "Please fill in all the fields.",
      "home_url": "http://example.com",
      "login_url": "http://example.com/login",
      "logo_url": "https://cdn.com/logos/providers/xf/fake.svg",
      "country_code": "XF",
      "refresh_timeout": 60,
      "holder_info": ["names", "emails", "phone_numbers"],
      "max_consent_days": 10,
      "created_at": "2020-07-26T07:28:27Z",
      "updated_at": "2020-07-31T07:28:27Z",
      "timezone": "Europe/London",
      "max_interactive_delay": 480,
      "optional_interactivity": true,
      "regulated": false,
      "max_fetch_interval": 60,
      "supported_fetch_scopes": ["accounts", "transactions"],
      "supported_account_extra_fields": [],
      "supported_transaction_extra_fields": [],
      "supported_account_natures": ["account", "card"],
      "supported_account_types": ["personal"],
      "identification_codes": ["123123"],
      "supported_iframe_embedding": true
    }
  ],
  "meta": {
    "next_id": null,
    "next_page": null
  }
}

Fields

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

nature

string

Possible values are: text, password, select, dynamic_select, file, number

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

The 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

nature

string

Possible values are: text, password, select, dynamic_select, file, number

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

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

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

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

The options for dynamic_select are not stored in the Provider, they are generated dynamically and sent in an Interactive callback.

Example object

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

Fake

In order to help you with testing, we provide a fake country (having the country code XF) and a set of fake providers. If your application is in the Test or Pending status, the Connect page will let you select the fake country and its providers.

Account Information API supplies a number of fake providers:

  • fakebank_simple_xf - requires a username and a password;
  • fakebank_select_xf - has a dropdown list with some options for the user to choose from;
  • fakebank_image_xf - the user needs to solve a CAPTCHA for authentication;
  • fakebank_interactive_xf - asks for a fake SMS code;
  • fakebank_two_step_interactive_xf - asks for interactive data twice during the fetching process;
  • fakebank_semi_interactive_xf - occasionally requires an SMS code;
  • fakebank_with_optional_fields_xf - similar to fakebank_interactive_xf, but with some of the interactive fields marked as optional;
  • fakebank_api_with_fields_xf - similar to fakebank_simple_xf, used for ensuring api providers availability;
  • fakebank_oauth_xf - asks for authorization;
  • fakebank_oauth_with_pending_xf - similar to fakebank_oauth_xf, returns pending transactions;
  • fakebank_oauth_with_n_transactions_xf - similar to fakebank_oauth_xf, returns more than 1000 transactions;
  • fakebank_with_updates_xf - generates up to 4 transactions on every create, refresh, reconnect with random amounts and modes;
  • fake_demobank_xf - generates multiple accounts with different currencies, and different account natures;
  • fakebank_with_token_xf - requires a username and a fake token;
  • fakebank_with_error_xf - allows you to test the appearing errors when connecting a new provider;
  • fakebank_oauth_with_pending_and_available_balance_xf - similar to fakebank_oauth_with_pending_xf, having accounts, which have different values for balance and available_balance;
  • fakebank_with_possible_duplicates_xf - each attempt generates transactions with the same made_on, amount, currency_code but different description. On the second attempt and later it marks those transaction with extra[:possible_duplicate] flag set to true;
  • fakebank_with_rememberable_credentials_xf - remembers all the answers to secret questions and doesn’t ask them during the interactive stage if they were introduced correctly on previous attempts.
  • fakebank_with_file_csv_xf - extracts transactions from a csv file. You can download the sample here.

The Fake Bank with Error allows selecting the error you would like to test. The choices are as follows:

  • No Errors - works the same as fakebank_simple_xf;
  • No Errors with Partial Data - returns accounts and transactions, where partial flag is set to true;
  • ExecutionTimeout - no accounts and transactions, raises the ExecutionTimeout error;
  • FetchingTimeout - no accounts and transactions, raises the FetchingTimeout error;
  • ProviderUnavailable - no accounts and transactions, raises the ProviderUnavailable error;
  • ProviderError - no accounts and transactions, raises an error with a generic message An error has occurred. Please report this error.

We also supply fake providers to test your Client Provider Keys with:

  • fake_client_xf - requires a username and password (embedded);
  • fake_oauth_client_xf - asks for authorization (OAuth redirect);
  • fake_interactive_client_xf - asks for a fake SMS code in addition to username and password (embedded).

Check the provider’s instructions on the Connect page for the appropriate credentials. You can use these providers in order to test the codes, the format of the transactions, errors, etc.

Customers

A Customer represents a single end-user of the Account Information API. The customer uses the API to create Connections, i.e. bank connections, that are further used to aggregate the customer’s financial data.

Here’s a diagram that illustrates the Customer and its associated concepts:

  • Customer - a single end-user.

  • Connection - a single connection to a provider. A single customer can have multiple connections to multiple banks.

  • Account - an account returned by the provider. Corresponds to a customer’s bank account.

  • Transaction - a single movement made within an account. Can be a transfer transaction.

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

Create

Creates a customer, returning the customer object.

Parameters

identifier

string, required

A unique id of the new customer

identifier

string, required

A unique id of the new customer

Possible Errors

URL

https://www.saltedge.com/api/v5/customers

https://www.saltedge.com/api/v5/customers

Method

POST

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"identifier\": \"12rv1212f1efxchsdhbgv\" \
              } \
            }" \
        https://www.saltedge.com/api/v5/customers
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"identifier\": \"12rv1212f1efxchsdhbgv\" \
              } \
            }" \
        https://www.saltedge.com/api/v5/customers

Sample Response

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

Show

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

Returns the customer object.

Parameters

id

string, required

The id of the customer

id

string, required

The id of the customer

Possible Errors

URL

https://www.saltedge.com/api/v5/customers/{customer.id}

https://www.saltedge.com/api/v5/customers/{customer.id}

Method

GET

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/customers/222222222222222222
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/customers/222222222222222222

Sample Response

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

List

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

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

Parameters

identifier

string, optional

A unique id of a customer

identifier

string, optional

A unique id of a customer

Possible Errors

URL

https://www.saltedge.com/api/v5/customers

https://www.saltedge.com/api/v5/customers

Method

GET

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/customers
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/customers

Sample Response

{
  "data": [
    {
      "id":         "222222222222222222",
      "identifier": "unique_customer_identifier",
      "secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80"
    },
    {
      "id":         "222222222222222223",
      "identifier": "unique_customer_identifier_2",
      "secret": "UYhs6Q8vRyMrPjUVtW7J_O1n0hndQ25bvUJ8CIJT3"
    }
  ],
  "meta": {
    "next_id": "222222222222222224",
    "next_page": "/api/v5/customers?from_id=222222222222222224"
  }
}

Remove

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

Deletes a customer, returning the customer object. Revokes all consents for this customer. This route is available only for web applications.

Possible Errors

URL

https://www.saltedge.com/api/v5/customers/{customer.id}

https://www.saltedge.com/api/v5/customers/{customer.id}

Method

DELETE

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X DELETE \
        https://www.saltedge.com/api/v5/customers/222222222222222222
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X DELETE \
        https://www.saltedge.com/api/v5/customers/222222222222222222

Sample Response

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

Lock

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

Locks a customer and its data, returning the customer object.

All customer related data including connections, accounts, transactions, attempts will not be available for reading, updating or deleting even by Salt Edge. This route is available only for web applications.

Possible Errors

URL

https://www.saltedge.com/api/v5/customers/{customer.id}/lock

https://www.saltedge.com/api/v5/customers/{customer.id}/lock

Method

PUT

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X PUT \
        https://www.saltedge.com/api/v5/customers/222222222222222222/lock
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X PUT \
        https://www.saltedge.com/api/v5/customers/222222222222222222/lock

Sample Response

{
  "data": {
    "locked": true,
    "id":     "222222222222222222"
  }
}

Unlock

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

Unlocks a customer and its data, returning the customer object. This route is available only for web applications.

Possible Errors

URL

https://www.saltedge.com/api/v5/customers/{customer.id}/unlock

https://www.saltedge.com/api/v5/customers/{customer.id}/unlock

Method

PUT

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X PUT \
        https://www.saltedge.com/api/v5/customers/222222222222222222/unlock
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X PUT \
        https://www.saltedge.com/api/v5/customers/222222222222222222/unlock

Sample Response

{
  "data": {
    "unlocked": true,
    "id":     "222222222222222222"
  }
}

Connect sessions

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

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

If your client account’s status is Pending, you will receive a ClientPending error when connecting any connection not from the fake providers.

Create

Allows you to create a connect session, which will be used to access Salt Edge Connect for connection creation. You will receive a connect_url field so that you will be able to enter directly to Salt Edge Connect with your newly generated connect session.

The consent confirmation, in this case, can be handled either on the client’s side (the ‘access terms’ on which the customer has agreed should be sent) or on Salt Edge side (‘access terms’ on which the customer should agree in the Salt Edge Connect interface should be sent).

Please see the sequence diagram for details on how Connect integration works.

Parameters

customer_id

string, required

The id of the customer received from customer create. This field is optional for ‘app’ authentication

consent

object, required

attempt

object, optional

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

daily_refresh

boolean, optional

Whether the connection should be automatically refreshed by Salt Edge. Defaults to false

disable_provider_search

boolean, optional

Whether the provider search will be disabled, works only if provider_code parameter is sent. Defaults to false

return_connection_id

boolean, optional

Whether to append connection_id to return_to URL. Defaults to false

provider_modes

array of strings, optional

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

categorization

string, optional

The type of categorization applied. Possible values: none, personal, business. Defaults to personal

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

If sent as true, the customers of live clients will be able to connect fake providers. Defaults to false

lost_connection_notify

boolean, optional

Being sent as true, enables you to receive a javascript callback whenever the internet connection is lost during the fetching process. The type of the callback depends on the javascript_callback_type you specified. Defaults to false. It has the following payload: {data: {error_class: 'ConnectionLost', error_message: 'Internet connection was lost'}}.

show_consent_confirmation

boolean, optional

If consent confirmation is handled on the client’s side, this parameter should be sent as false so, upon submitting the form, the user will not be asked to give his consent to Salt Edge Inc. Defaults totrue

credentials_strategy

string, optional

The strategy of storing customer’s credentials. Possible values: store, do_not_store, ask. Defaults tostore
Note: If the value is ask, on the Connect page customer will be able to choose whether to save or not his credentials on Salt Edge side

return_error_class

boolean, optional

Whether to append error_class to return_to URL. Defaults to false

theme

string, optional

Theme of Salt Edge Connect template. If not passed or available for the current template, will use default. Allowed values: default, dark.

connect_template

string, optional

Defaults to Salt Edge Connect template unless a different template is passed and available for the current client

consent

object, required

attempt

object, optional

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

daily_refresh

boolean, optional

Whether the connection should be automatically refreshed by Salt Edge. Defaults to false

disable_provider_search

boolean, optional

Whether the provider search will be disabled, works only if provider_code parameter is sent. Defaults to false

return_connection_id

boolean, optional

Whether to append connection_id to return_to URL. Defaults to false

provider_modes

array of strings, optional

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

categorization

string, optional

The type of categorization applied. Possible values: none, personal, business. Defaults to personal

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

If sent as true, the customers of live clients will be able to connect fake providers. Defaults to false

lost_connection_notify

boolean, optional

Being sent as true, enables you to receive a javascript callback whenever the internet connection is lost during the fetching process. The type of the callback depends on the javascript_callback_type you specified. Defaults to false. It has the following payload: {data: {error_class: 'ConnectionLost', error_message: 'Internet connection was lost'}}.

show_consent_confirmation

boolean, optional

If consent confirmation is handled on the client’s side, this parameter should be sent as false so, upon submitting the form, the user will not be asked to give his consent to Salt Edge Inc. Defaults totrue

credentials_strategy

string, optional

The strategy of storing customer’s credentials. Possible values: store, do_not_store, ask. Defaults tostore
Note: If the value is ask, on the Connect page customer will be able to choose whether to save or not his credentials on Salt Edge side

return_error_class

boolean, optional

Whether to append error_class to return_to URL. Defaults to false

theme

string, optional

Theme of Salt Edge Connect template. If not passed or available for the current template, will use default. Allowed values: default, dark.

connect_template

string, optional

Defaults to Salt Edge Connect template unless a different template is passed and available for the current client

Possible Errors

URL

https://www.saltedge.com/api/v5/connect_sessions/create

https://www.saltedge.com/api/v5/connect_sessions/create

Method

POST

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"customer_id\": \"222222222222222222\", \
                \"consent\": { \
                  \"from_date\": \"2020-05-08\", \
                  \"period_days\": 90, \
                  \"scopes\": [ \
                    \"account_details\", \
                    \"transactions_details\" \
                  ] \
                }, \
                \"attempt\": { \
                  \"from_date\": \"2020-07-07\", \
                  \"fetch_scopes\": [ \
                    \"accounts\", \
                    \"transactions\" \
                  ] \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v5/connect_sessions/create
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"consent\": { \
                  \"from_date\": \"2020-05-08\", \
                  \"period_days\": 90, \
                  \"scopes\": [ \
                    \"account_details\", \
                    \"transactions_details\" \
                  ] \
                }, \
                \"attempt\": { \
                  \"from_date\": \"2020-07-07\", \
                  \"fetch_scopes\": [ \
                    \"accounts\", \
                    \"transactions\" \
                  ] \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v5/connect_sessions/create

Sample response

{
  "data": {
    "expires_at": "2020-08-05T08:28:28Z",
    "connect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
  }
}

Reconnect

Allows you to create a connect session, which will be used to access Salt Edge Connect to reconnect a connection. You will receive a connect_url field so that you will be able to enter directly to Salt Edge Connect with your newly generated connect session.

Reconnect requires new consent to be given. The consent confirmation, in this case, can be handled either on the client’s side (the ‘access terms’ on which the customer has agreed should be sent) or on Salt Edge side (‘access terms’ on which the customer should agree in the Salt Edge Connect interface should be sent).

Parameters

connection_id

string, required

The id of the connection you wish to reconnect

consent

object, required

attempt

object, optional

daily_refresh

boolean, optional

Whether the connection should be automatically refreshed by Salt Edge. Defaults to false

return_connection_id

boolean, optional

Shows whether to append connection_id to return_to URL. Defaults to false

provider_modes

array of strings, optional

Restricts 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 you are expecting. Possible values: iframe, external_saltbridge, external_notify, post_message. Defaults to null, which means that you will not receive any callbacks.

categorization

string, optional

The type of categorization applied. Possible values: none, personal, business. Defaults to personal

include_fake_providers

boolean, optional

If sent as true, the customers of live clients will be able to connect fake providers. Defaults to false

lost_connection_notify

boolean, optional

Being sent as true, enables the client to receive a javascript callback whenever the internet connection is lost during the fetching process. The type of the callback depends on the javascript_callback_type the client specified. Defaults to false. It has the following payload: {data: {error_class: 'ConnectionLost', error_message: 'Internet connection was lost'}}.

show_consent_confirmation

boolean, optional

If consent confirmation is handled on the client’s side, this parameter should be sent as false so, upon submitting the form, the user will not be asked to give his consent to Salt Edge Inc. Default value: true.

credentials_strategy

string, optional

The strategy of storing customer’s 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 Salt Edge side

override_credentials_strategy

string, optional

Possible values: ask, override. If sent as ask, the user will be required to confirm the credentials override upon submitting the form, in the scenario where the new credentials are different from the ones in the previous attempt. If sent as override, the new credentials will automatically override the old ones. Default: null

return_error_class

boolean, optional

Whether to append error_class to return_to URL. Defaults to false

theme

string, optional

Theme of Salt Edge Connect template. If not passed or available for the current template, will use default. Allowed values: default, dark.

connect_template

string, optional

Defaults to Salt Edge Connect template unless a different template is passed and available for the current client

consent

object, required

attempt

object, optional

daily_refresh

boolean, optional

Whether the connection should be automatically refreshed by Salt Edge. Defaults to false

return_connection_id

boolean, optional

Shows whether to append connection_id to return_to URL. Defaults to false

provider_modes

array of strings, optional

Restricts 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 you are expecting. Possible values: iframe, external_saltbridge, external_notify, post_message. Defaults to null, which means that you will not receive any callbacks.

categorization

string, optional

The type of categorization applied. Possible values: none, personal, business. Defaults to personal

include_fake_providers

boolean, optional

If sent as true, the customers of live clients will be able to connect fake providers. Defaults to false

lost_connection_notify

boolean, optional

Being sent as true, enables the client to receive a javascript callback whenever the internet connection is lost during the fetching process. The type of the callback depends on the javascript_callback_type the client specified. Defaults to false. It has the following payload: {data: {error_class: 'ConnectionLost', error_message: 'Internet connection was lost'}}.

show_consent_confirmation

boolean, optional

If consent confirmation is handled on the client’s side, this parameter should be sent as false so, upon submitting the form, the user will not be asked to give his consent to Salt Edge Inc. Default value: true.

credentials_strategy

string, optional

The strategy of storing customer’s 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 Salt Edge side

override_credentials_strategy

string, optional

Possible values: ask, override. If sent as ask, the user will be required to confirm the credentials override upon submitting the form, in the scenario where the new credentials are different from the ones in the previous attempt. If sent as override, the new credentials will automatically override the old ones. Default: null

return_error_class

boolean, optional

Whether to append error_class to return_to URL. Defaults to false

theme

string, optional

Theme of Salt Edge Connect template. If not passed or available for the current template, will use default. Allowed values: default, dark.

connect_template

string, optional

Defaults to Salt Edge Connect template unless a different template is passed and available for the current client

Possible Errors

URL

https://www.saltedge.com/api/v5/connect_sessions/reconnect

https://www.saltedge.com/api/v5/connect_sessions/reconnect

Method

POST

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"connection_id\": \"111111111111111111\", \
                \"consent\": { \
                  \"period_days\": 90, \
                  \"scopes\": [ \
                    \"account_details\" \
                  ] \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v5/connect_sessions/reconnect
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"consent\": { \
                  \"period_days\": 90, \
                  \"scopes\": [ \
                    \"account_details\" \
                  ] \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v5/connect_sessions/reconnect

Sample response

{
  "data": {
    "expires_at": "2020-08-05T08:28:28Z",
    "connect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
  }
}

Refresh

Allows you to create a connect session, which will be used to access Salt Edge Connect to refresh a connection. You will receive a connect_url field so that you will be able to enter directly to Salt Edge Connect with your newly generated connect session.

Refresh does not require a new consent, it is based on the limitations of the current active consent. If the latest consent has been revoked, only a reconnect is possible.

Parameters

connection_id

string, required

The id of the connection you wish to reconnect

attempt

object, optional

daily_refresh

boolean, optional

Whether the connection should be automatically refreshed by Salt Edge. Defaults to false

return_connection_id

boolean, optional

Shows whether to append connection_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 you are expecting. Possible values: iframe, external_saltbridge, external_notify, post_message. Defaults to null, which means that you will not receive any callbacks.

categorization

string, optional

The type of categorization applied. Possible values: none, personal, business. Defaults to personal

lost_connection_notify

boolean, optional

Being sent as true, enables you to receive a javascript callback whenever the internet connection is lost during the fetching process. The type of the callback depends on the javascript_callback_type you specified. Defaults to false. It has the following payload: {data: {error_class: 'ConnectionLost', error_message: 'Internet connection was lost'}}.

include_fake_providers

boolean, optional

If sent as true, the customers of live clients will be able to connect fake providers. Defaults to false

return_error_class

boolean, optional

Whether to append error_class to return_to URL. Defaults to false

theme

string, optional

Theme of Salt Edge Connect template. If not passed or available for the current template, will use default. Allowed values: default, dark.

connect_template

string, optional

Defaults to Salt Edge Connect template unless a different template is passed and available for the current client

attempt

object, optional

daily_refresh

boolean, optional

Whether the connection should be automatically refreshed by Salt Edge. Defaults to false

return_connection_id

boolean, optional

Shows whether to append connection_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 you are expecting. Possible values: iframe, external_saltbridge, external_notify, post_message. Defaults to null, which means that you will not receive any callbacks.

categorization

string, optional

The type of categorization applied. Possible values: none, personal, business. Defaults to personal

lost_connection_notify

boolean, optional

Being sent as true, enables you to receive a javascript callback whenever the internet connection is lost during the fetching process. The type of the callback depends on the javascript_callback_type you specified. Defaults to false. It has the following payload: {data: {error_class: 'ConnectionLost', error_message: 'Internet connection was lost'}}.

include_fake_providers

boolean, optional

If sent as true, the customers of live clients will be able to connect fake providers. Defaults to false

return_error_class

boolean, optional

Whether to append error_class to return_to URL. Defaults to false

theme

string, optional

Theme of Salt Edge Connect template. If not passed or available for the current template, will use default. Allowed values: default, dark.

connect_template

string, optional

Defaults to Salt Edge Connect template unless a different template is passed and available for the current client

Possible Errors

URL

https://www.saltedge.com/api/v5/connect_sessions/refresh

https://www.saltedge.com/api/v5/connect_sessions/refresh

Method

POST

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"connection_id\": \"111111111111111111\", \
                \"attempt\": { \
                  \"fetch_scopes\": [ \
                    \"accounts\", \
                    \"transactions\" \
                  ] \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v5/connect_sessions/refresh
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"attempt\": { \
                  \"fetch_scopes\": [ \
                    \"accounts\", \
                    \"transactions\" \
                  ] \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v5/connect_sessions/refresh

Sample response

{
  "data": {
    "expires_at": "2020-08-05T08:28:28Z",
    "connect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
  }
}

OAuth Providers

Account Information API also allows your app to import data from OAuth providers we support. The OAuth workflow, in this case, is reduced to a couple of HTTP calls and redirects.

Connecting OAuth providers is done via the same mechanism as when connecting a usual connection - using connect sessions for creating, 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 end-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 connection for an OAuth provider. After receiving the response, the customer will be redirected to return_to URL.

Mobile clients receive a connection_secret parameter in the return_to URL if the connection was successfully connected and an error_message parameter if the connection failed to connect for some reason.

Please note that return_to is optional for clients only if they use a shared (owned by Salt Edge) provider key (it is set as the client’s home_url by default). If a client use their own provider keys, return_to is required and should be a valid URL that was registered within the provider they are connecting to. Please see the sequence diagram on the flow described above.

Parameters

customer_id

string, required

The id of the customer received from customer create. This field is optional for ‘app’ authentication

country_code

string, required

The code of the country

provider_code

string, required

The code of the provider

consent

object, required

attempt

object, optional

daily_refresh

boolean, optional

Whether the connection should be automatically refreshed by Salt Edge. Defaults to false

return_connection_id

boolean, optional

Whether to append connection_id to return_to URL. Defaults to false

categorization

string, optional

The type of categorization applied. Possible values: none, personal, business. Defaults to personal

include_fake_providers

boolean, optional

If sent as true, the customers of live clients will be able to connect fake providers. Defaults to false

country_code

string, required

The code of the country

provider_code

string, required

The code of the provider

consent

object, required

attempt

object, optional

daily_refresh

boolean, optional

Whether the connection should be automatically refreshed by Salt Edge. Defaults to false

return_connection_id

boolean, optional

Whether to append connection_id to return_to URL. Defaults to false

categorization

string, optional

The type of categorization applied. Possible values: none, personal, business. Defaults to personal

include_fake_providers

boolean, optional

If sent as true, the customers of live clients will be able to connect fake providers. Defaults to false

Possible Errors

URL

https://www.saltedge.com/api/v5/oauth_providers/create

https://www.saltedge.com/api/v5/oauth_providers/create

Method

POST

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"customer_id\": \"222222222222222222\", \
                \"country_code\": \"XF\", \
                \"provider_code\": \"fakebank_oauth_xf\", \
                \"consent\": { \
                  \"scopes\": [ \
                    \"account_details\", \
                    \"transactions_details\" \
                  ], \
                  \"from_date\": \"2020-06-07\" \
                }, \
                \"attempt\": { \
                  \"return_to\": \"https://example.com/\", \
                  \"from_date\": \"2020-07-08\", \
                  \"fetch_scopes\": [ \
                    \"accounts\", \
                    \"transactions\" \
                  ] \
                }, \
                \"return_connection_id\": false \
              } \
            }" \
        https://www.saltedge.com/api/v5/oauth_providers/create
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"country_code\": \"XF\", \
                \"provider_code\": \"fakebank_oauth_xf\", \
                \"consent\": { \
                  \"scopes\": [ \
                    \"account_details\", \
                    \"transactions_details\" \
                  ], \
                  \"from_date\": \"2020-06-07\" \
                }, \
                \"attempt\": { \
                  \"return_to\": \"https://example.com/\", \
                  \"from_date\": \"2020-07-08\", \
                  \"fetch_scopes\": [ \
                    \"accounts\", \
                    \"transactions\" \
                  ] \
                }, \
                \"return_connection_id\": false \
              } \
            }" \
        https://www.saltedge.com/api/v5/oauth_providers/create

Sample response

{
  "data": {
    "connection_id": "111111111111111111",
    "connection_secret": "secret",
    "attempt_id": "777777777777777777",
    "token": "GENERATED_TOKEN",
    "expires_at": "2020-08-05T08:28:28Z",
    "redirect_url": "https://www.saltedge.com/api/v5/oauth_providers/redirect?token=GENERATED_TOKEN"
  }
}

Reconnect

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

Mobile clients receive a connection_secret parameter in the return_to URL if the connection was successfully connected and an error_message parameter if the connection failed to connect for some reason.

Please note that return_to is optional for clients only if they use a shared (owned by Salt Edge) provider key (it is set as the client’s home_url by default). If a client use their own provider keys, return_to is required and should be a valid URL that was registered within the provider they are connecting to.

Parameters

connection_id

string, required

The id of the connection that is to be reconnected

consent

object, required

attempt

object, optional

daily_refresh

boolean, optional

Whether the connection should be automatically refreshed by Salt Edge. Defaults to false

return_connection_id

boolean, optional

Shows whether to append connection_id to return_to URL. Defaults to false

categorization

string, optional

The type of categorization applied. Possible values: none, personal, business. Defaults topersonal

include_fake_providers

boolean, optional

If sent as true, the customers of live clients will be able to connect fake providers. Defaults to false

consent

object, required

attempt

object, optional

daily_refresh

boolean, optional

Whether the connection should be automatically refreshed by Salt Edge. Defaults to false

return_connection_id

boolean, optional

Shows whether to append connection_id to return_to URL. Defaults to false

categorization

string, optional

The type of categorization applied. Possible values: none, personal, business. Defaults topersonal

include_fake_providers

boolean, optional

If sent as true, the customers of live clients will be able to connect fake providers. Defaults to false

Possible Errors

URL

https://www.saltedge.com/api/v5/oauth_providers/reconnect

https://www.saltedge.com/api/v5/oauth_providers/reconnect

Method

POST

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"connection_id\": \"111111111111111111\", \
                \"consent\": { \
                  \"scopes\": [ \
                    \"account_details\", \
                    \"transactions_details\" \
                  ], \
                  \"from_date\": \"2020-06-07\" \
                }, \
                \"attempt\": { \
                  \"return_to\": \"https://example.com/\" \
                }, \
                \"return_connection_id\": false \
              } \
            }" \
        https://www.saltedge.com/api/v5/oauth_providers/reconnect
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"consent\": { \
                  \"scopes\": [ \
                    \"account_details\", \
                    \"transactions_details\" \
                  ], \
                  \"from_date\": \"2020-06-07\" \
                }, \
                \"attempt\": { \
                  \"return_to\": \"https://example.com/\" \
                }, \
                \"return_connection_id\": false \
              } \
            }" \
        https://www.saltedge.com/api/v5/oauth_providers/reconnect

Sample response

{
  "data": {
    "connection_id": "111111111111111111",
    "connection_secret": "secret",
    "attempt_id": "777777777777777777",
    "token": "GENERATED_TOKEN",
    "expires_at": "2020-08-05T08:28:28Z",
    "redirect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
  }
}

Authorize

Used to authorize a connection for an OAuth provider when using client owned provider keys. In this flow, once the end-user will be authorized on the provider’s side, they will be redirected to the return_to URL indicated in the previous request, with a bunch of parameters appended to it by the provider that are needed for authorizing the connection.

Examples:

  • <return_to url>?access_token=bc4521d3&state=Pd8b4d0eb
  • <return_to url>#access_token=bc4521d3&state=Pd8b4d0eb

For both cases, the query_string that is needed to authorize the connection is access_token=bc4521d3&state=Pd8b4d0eb.

Please see the sequence diagram on the flow described above.

Parameters

connection_id

string, required

The id of the connection that is being authorized

query_string

string, required

All the parameters appended to your return_to URL upon being redirected from the bank back to your application

query_string

string, required

All the parameters appended to your return_to URL upon being redirected from the bank back to your application

Possible Errors

URL

https://www.saltedge.com/api/v5/oauth_providers/authorize

https://www.saltedge.com/api/v5/oauth_providers/authorize

Method

PUT

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"connection_id\": \"111111111111111111\", \
                \"query_string\": \"access_token=bc4521d3&state=Pd8b4d0eb\" \
              } \
            }" \
        https://www.saltedge.com/api/v5/oauth_providers/authorize
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"query_string\": \"access_token=bc4521d3&state=Pd8b4d0eb\" \
              } \
            }" \
        https://www.saltedge.com/api/v5/oauth_providers/authorize

Sample response

{
  "data": {
    "country_code": "XF",
    "created_at": "2020-08-04T07:28:28Z",
    "customer_id": "222222222222222222",
    "daily_refresh": false,
    "id": "111111111111111111",
    "show_consent_confirmation": false,
    "last_consent_id": "555555555555555555",
    "last_attempt": {
      "api_mode": "service",
      "api_version": "5",
      "automatic_fetch": true,
      "user_present": true,
      "daily_refresh": false,
      "categorization": "personal",
      "created_at": "2020-08-05T06:48:28Z",
      "customer_last_logged_at": "2020-08-05T04:28:28Z",
      "custom_fields": {},
      "device_type": "desktop",
      "remote_ip": "93.184.216.34",
      "exclude_accounts": [],
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "fetch_scopes": ["accounts", "transactions"],
      "finished": true,
      "finished_recent": true,
      "from_date": null,
      "id": "777777777777777777",
      "interactive": true,
      "locale": "en",
      "partial": false,
      "store_credentials": true,
      "success_at": "2020-08-05T06:48:28Z",
      "to_date": null,
      "updated_at": "2020-08-05T06:48:28Z",
      "show_consent_confirmation": false,
      "consent_id": "555555555555555555",
      "include_natures": ["account", "card", "bonus"],
      "last_stage": {
        "created_at": "2020-08-05T06:48:28Z",
        "id": "888888888888888888",
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "finish",
        "updated_at": "2020-08-05T06:48:28Z"
      }
    },
    "last_success_at": "2020-08-05T06:48:28Z",
    "next_refresh_possible_at": "2020-08-05T08:28:28Z",
    "provider_id": "1234",
    "provider_code": "fakebank_oauth_xf",
    "provider_name": "Fakebank Oauth",
    "status": "inactive",
    "store_credentials": true,
    "updated_at": "2020-08-05T06:48:28Z"
  }
}

Connections

A connection represents a set of credentials required to access the accounts and transactions through a specific provider.

Within Account Information API, a connection can have one of the following statuses:

  • active - the current set of credentials is valid and allows us to fetch the data properly;
  • inactive - an error appeared while fetching the connection. An inactive connection cannot be refreshed, thus only reconnected;

    A connection will have inactive status in the following cases:

    • Any attempt that fails with Invalid credentials error will mark the connection’s status as inactive
    • Any attempt that fails with Provider Unavailable with one of the following error messages:
      • Account blocked. Please, contact your provider.
      • Provider does not have any account records available at this time.
      • Provider asked to update your account settings.
      • No active accounts were found. Please, contact your provider.
      • Provider is disabled.
  • disabled - in case of non-compliance with our Terms of Service, we can contact the application’s owner and disable the connection.

A Connection represents a permanent connection of a specific customer to a bank. A single end-user represents a single customer in Account Information API. When creating a connection, you should check whether the customer already exists to avoid creating new customers with the same connection. Also, we don’t recommend creating multiple connections for the same customer with the same online banking access credentials.

Attributes

id

string

The id of the connection

secret

string

The secret key associated with a specific connection. It allows to read the information related to a connection using API keys of type app.

provider_id

string

The id of the provider the connection belongs to

provider_code

string

The code of the provider the connection belongs to

provider_name

string

The name of the provider the connection belongs to

daily_refresh

boolean

Whether the connection will be refreshed daily

customer_id

string

Customer’s id

created_at

datetime

Time and date when the connection was added

updated_at

datetime

The last time when the connection’s balance was changed, new accounts were imported or new transactions added/removed

last_success_at

datetime

Time when the connection 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 connection 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 connection

show_consent_confirmation

boolean

Whether any consent was given for this connection on Salt Edge side

last_consent_id

string

The id of the last consent

id

string

The id of the connection

secret

string

The secret key associated with a specific connection. It allows to read the information related to a connection using API keys of type app.

provider_id

string

The id of the provider the connection belongs to

provider_code

string

The code of the provider the connection belongs to

provider_name

string

The name of the provider the connection belongs to

daily_refresh

boolean

Whether the connection will be refreshed daily

customer_id

string

Customer’s id

created_at

datetime

Time and date when the connection was added

updated_at

datetime

The last time when the connection’s balance was changed, new accounts were imported or new transactions added/removed

last_success_at

datetime

Time when the connection 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 connection 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 connection

show_consent_confirmation

boolean

Whether any consent was given for this connection on Salt Edge side

last_consent_id

string

The id of the last consent

Sample object

{
  "country_code": "XF",
  "created_at": "2020-08-04T07:28:28Z",
  "customer_id": "222222222222222222",
  "daily_refresh": false,
  "id": "111111111111111111",
  "secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
  "show_consent_confirmation": false,
  "last_consent_id": "555555555555555555",
  "last_attempt": {
    "api_mode": "service",
    "api_version": "5",
    "automatic_fetch": true,
    "user_present": false,
    "daily_refresh": false,
    "categorization": "personal",
    "created_at": "2020-08-05T07:28:28Z",
    "customer_last_logged_at": "2020-08-05T04:28:28Z",
    "custom_fields": {},
    "device_type": "desktop",
    "remote_ip": "93.184.216.34",
    "exclude_accounts": [],
    "fail_at": null,
    "fail_error_class": null,
    "fail_message": null,
    "fetch_scopes": ["accounts", "transactions"],
    "finished": true,
    "finished_recent": true,
    "from_date": null,
    "id": "777777777777777777",
    "interactive": false,
    "locale": "en",
    "partial": false,
    "store_credentials": true,
    "success_at": "2020-08-05T07:28:28Z",
    "to_date": null,
    "updated_at": "2020-08-05T07:28:28Z",
    "show_consent_confirmation": false,
    "consent_id": "555555555555555555",
    "include_natures": ["account", "card", "bonus"],
    "last_stage": {
      "created_at": "2020-08-05T07:28:28Z",
      "id": "888888888888888888",
      "interactive_fields_names": null,
      "interactive_html": null,
      "name": "finish",
      "updated_at": "2020-08-05T07:28:28Z"
    }
  },
  "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": "2020-08-05T07:28:28Z",
  "next_refresh_possible_at": "2020-08-05T08:28:28Z",
  "provider_id": "1234",
  "provider_code": "fakebank_simple_xf",
  "provider_name": "Fakebank Simple",
  "status": "active",
  "store_credentials": true,
  "updated_at": "2020-08-05T07:28:28Z"
}

List

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

Returns all the connections accessible to your application for a certain customer. The connections are sorted in ascending order of their id, so the newest connections will come last. We recommend you fetch the whole list of connections 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

customer_id

string, required

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

from_id

string, optional

The id of the connection which the list starts with

customer_id

string, required

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

from_id

string, optional

The id of the connection which the list starts with

Possible Errors

URL

https://www.saltedge.com/api/v5/connections

https://www.saltedge.com/api/v5/connections

Method

GET

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/connections?customer_id=$CUSTOMER_ID
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/connections?customer_id=$CUSTOMER_ID

Sample Response

{ "data":
  [
    {
      "country_code": "XF",
      "created_at": "2020-08-04T07:28:28Z",
      "customer_id": "222222222222222222",
      "daily_refresh": false,
      "id": "111111111111111111",
      "secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
      "show_consent_confirmation": false,
      "last_consent_id": "555555555555555555",
      "last_attempt": {
          "api_mode": "service",
          "api_version": "5",
          "automatic_fetch": true,
          "user_present": false,
          "daily_refresh": false,
          "categorization": "personal",
          "created_at": "2020-08-05T06:48:28Z",
          "customer_last_logged_at": "2020-08-05T04:28:28Z",
          "custom_fields": {},
          "device_type": "desktop",
          "remote_ip": "93.184.216.34",
          "exclude_accounts": [],
          "fail_at": null,
          "fail_error_class": null,
          "fail_message": null,
          "fetch_scopes": ["accounts", "transactions"],
          "finished": true,
          "finished_recent": true,
          "from_date": null,
          "id": "777777777777777777",
          "interactive": false,
          "locale": "en",
          "partial": false,
          "store_credentials": true,
          "success_at": "2020-08-05T06:48:28Z",
          "to_date": null,
          "updated_at": "2020-08-05T06:48:28Z",
          "show_consent_confirmation": false,
          "consent_id": "555555555555555555",
          "include_natures": ["account", "card", "bonus"],
          "last_stage": {
            "created_at": "2020-08-05T06:48:28Z",
            "id": "888888888888888888",
            "interactive_fields_names": null,
            "interactive_html": null,
            "name": "finish",
            "updated_at": "2020-08-05T06:48:28Z"
          }
      },
      "last_success_at": "2020-08-05T06:48:28Z",
      "next_refresh_possible_at": "2020-08-05T08:28:28Z",
      "provider_id": "1234",
      "provider_code": "fakebank_simple_xf",
      "provider_name": "Fakebank Simple",
      "status": "active",
      "store_credentials": true,
      "updated_at": "2020-08-05T06:48:28Z"
    }
  ],
  "meta" : {
    "next_id": "111111111111111112",
    "next_page": "/api/v5/connections?customer_id=222222222222222222&from_id=111111111111111112"
  }
}

Show

Returns a single connection object.

Possible Errors

URL

https://www.saltedge.com/api/v5/connections/{connection.id}

https://www.saltedge.com/api/v5/connection

Method

GET

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/connections/111111111111111111
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/connection

Sample Response

{
  "data": {
    "country_code": "MD",
    "created_at": "2020-05-07T20:09:02Z",
    "customer_id": "222222222222222222",
    "daily_refresh": false,
    "id": "111111111111111111",
    "secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
    "show_consent_confirmation": false,
    "last_consent_id": "555555555555555555",
    "last_attempt": {
      "api_mode": "service",
      "api_version": "5",
      "automatic_fetch": true,
      "user_present": false,
      "daily_refresh": false,
      "categorization": "personal",
      "created_at": "2020-05-07T16:14:53Z",
      "customer_last_logged_at": "2020-08-05T04:28:28Z",
      "custom_fields": {},
      "device_type": "desktop",
      "remote_ip": "93.184.216.34",
      "exclude_accounts": [],
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "fetch_scopes": ["accounts", "transactions"],
      "finished": true,
      "finished_recent": true,
      "from_date": null,
      "id": "777777777777777777",
      "interactive": false,
      "locale": "en",
      "partial": false,
      "store_credentials": true,
      "success_at": "2020-06-02T16:16:19Z",
      "to_date": null,
      "updated_at": "2020-06-02T16:16:19Z",
      "show_consent_confirmation": false,
      "consent_id": "555555555555555555",
      "include_natures": ["account", "card", "bonus"],
      "last_stage": {
        "created_at": "2020-06-02T16:16:19Z",
        "id": "888888888888888888",
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "finish",
        "updated_at": "2020-06-02T16:16:19Z"
      }
    },
    "last_success_at": "2020-06-02T16:16:19Z",
    "next_refresh_possible_at": "2020-06-02T17:16:19Z",
    "provider_id": "1234",
    "provider_code": "moldindconbank_wb_md",
    "provider_name": "Moldindconbank Web Banking",
    "status": "active",
    "store_credentials": true,
    "updated_at": "2020-06-02T09:41:23Z"
  }
}
{
  "data": {
    "country_code": "MD",
    "created_at": "2020-05-07T20:09:02Z",
    "customer_id": "222222222222222222",
    "daily_refresh": false,
    "id": "111111111111111111",
    "secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
    "show_consent_confirmation": false,
    "last_consent_id": "555555555555555555",
    "last_attempt": {
      "api_mode": "service",
      "api_version": "5",
      "automatic_fetch": true,
      "user_present": false,
      "daily_refresh": false,
      "categorization": "personal",
      "created_at": "2020-05-07T16:14:53Z",
      "customer_last_logged_at": "2020-08-05T04:28:28Z",
      "custom_fields": {},
      "device_type": "desktop",
      "remote_ip": "93.184.216.34",
      "exclude_accounts": [],
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "fetch_scopes": ["accounts", "transactions"],
      "finished": true,
      "finished_recent": true,
      "from_date": null,
      "id": "777777777777777777",
      "interactive": false,
      "locale": "en",
      "partial": false,
      "store_credentials": true,
      "success_at": "2020-06-02T16:16:19Z",
      "to_date": null,
      "updated_at": "2020-06-02T16:16:19Z",
      "show_consent_confirmation": false,
      "consent_id": "555555555555555555",
      "include_natures": ["account", "card", "bonus"],
      "last_stage": {
        "created_at": "2020-06-02T16:16:19Z",
        "id": "888888888888888888",
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "finish",
        "updated_at": "2020-06-02T16:16:19Z"
      }
    },
    "last_success_at": "2020-06-02T16:16:19Z",
    "next_refresh_possible_at": "2020-06-02T17:16:19Z",
    "provider_id": "1234",
    "provider_code": "moldindconbank_wb_md",
    "provider_name": "Moldindconbank Web Banking",
    "status": "active",
    "store_credentials": true,
    "updated_at": "2020-06-02T09:41:23Z"
  }
}

Create

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

Additionally, you can pass encrypted_credentials instead of credentials. See encrypted credentials page for more information.

Using this route requires a consent object to be passed. This means that the consent confirmation should be handled on the client’s side, and the ‘access terms’ the customer agreed on should be passed.

Please see the sequence diagram on the flow described above.

Parameters

customer_id

string, 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

consent

object, required

attempt

object, optional

credentials

object, required unless encrypted_credentials are present

The credentials required to access the data

encrypted_credentials

object, required unless credentials are present

The encrypted credentials required to access the data

daily_refresh

boolean, optional

Whether the connection should be automatically refreshed by Salt Edge. Defaults to false

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

categorization

string, optional

The type of categorization applied. Possible values: none, personal, business. Defaults to personal

file_url

string, optional

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

customer_id

string, optional

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

consent

object, required

attempt

object, optional

credentials

object, required unless encrypted_credentials are present

The credentials required to access the data

encrypted_credentials

object, required unless credentials are present

The encrypted credentials required to access the data

daily_refresh

boolean, optional

Whether the connection should be automatically refreshed by Salt Edge. Defaults to false

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

categorization

string, optional

The type of categorization applied. Possible values: none, personal, business. Defaults to personal

file_url

string, optional

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

Response

A complete Connection object.

Possible Errors

URL

https://www.saltedge.com/api/v5/connections

https://www.saltedge.com/api/v5/connection

Method

POST

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"customer_id\": \"222222222222222222\", \
                \"country_code\": \"XF\", \
                \"provider_code\": \"fakebank_simple_xf\", \
                \"consent\": { \
                  \"from_date\": \"2020-06-07\", \
                  \"scopes\": [ \
                    \"account_details\", \
                    \"transactions_details\" \
                  ] \
                }, \
                \"attempt\": { \
                  \"from_date\": \"2020-07-07\", \
                  \"fetch_scopes\": [ \
                    \"accounts\", \
                    \"transactions\" \
                  ], \
                  \"custom_fields\": { \
                    \"test\": true \
                  } \
                }, \
                \"credentials\": { \
                  \"login\": \"username\", \
                  \"password\": \"secret\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v5/connections
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"country_code\": \"XF\", \
                \"provider_code\": \"fakebank_simple_xf\", \
                \"consent\": { \
                  \"from_date\": \"2020-06-07\", \
                  \"scopes\": [ \
                    \"account_details\", \
                    \"transactions_details\" \
                  ] \
                }, \
                \"attempt\": { \
                  \"from_date\": \"2020-07-07\", \
                  \"fetch_scopes\": [ \
                    \"accounts\", \
                    \"transactions\" \
                  ], \
                  \"custom_fields\": { \
                    \"test\": true \
                  } \
                }, \
                \"credentials\": { \
                  \"login\": \"username\", \
                  \"password\": \"secret\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v5/connection

Sample request (with encrypted credentials)

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"customer_id\": \"222222222222222222\", \
                \"country_code\": \"XF\", \
                \"provider_code\": \"fakebank_simple_xf\", \
                \"consent\": { \
                  \"from_date\": \"2020-06-07\", \
                  \"scopes\": [ \
                    \"account_details\", \
                    \"transactions_details\" \
                  ] \
                }, \
                \"encrypted_credentials\": { \
                  \"algorithm\": \"AES-256-CBC\", \
                  \"key\": \"Yir+HThidKxlpqA...\", \
                  \"iv\": \"JEhn/N5oK9s0U1L...\", \
                  \"data\": \"S8XD2kHCPsIQj+x...\", \
                  \"version\": \"your_key_version\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v5/connections

Sample request (with file providers)

curl -v -include \
        -H "Accept: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -F "file=@file.ofx" \
        -F "data[provider_code]=ofx_xo" \
        -F "data[country_code]=XO" \
        -F "data[consent][scopes][]=account_details" \
        -F "data[customer_id]=222222222222222222" \
        https://www.saltedge.com/api/v5/connections
curl -v -include \
        -H "Accept: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -F "file=@file.ofx" \
        -F "data[provider_code]=ofx_xo" \
        -F "data[country_code]=XO" \
        -F "data[consent][scopes][]=account_details" \
        https://www.saltedge.com/api/v5/connection

Sample request (with file providers, using file_url)

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"customer_id\": \"222222222222222222\", \
                \"country_code\": \"XO\", \
                \"provider_code\": \"mint_csv_xo\", \
                \"attempt\": { \
                  \"fetch_scopes\": [ \
                    \"accounts\", \
                    \"transactions\" \
                  ] \
                }, \
                \"consent\": { \
                  \"from_date\": \"2020-06-07\", \
                  \"scopes\": [ \
                    \"account_details\", \
                    \"transactions_details\" \
                  ] \
                }, \
                \"file_url\": \"http://spatialkeydocs.s3.amazonaws.com/FL_insurance_sample.csv\" \
              } \
            }" \
        https://www.saltedge.com/api/v5/connections
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"country_code\": \"XO\", \
                \"provider_code\": \"mint_csv_xo\", \
                \"attempt\": { \
                  \"fetch_scopes\": [ \
                    \"accounts\", \
                    \"transactions\" \
                  ] \
                }, \
                \"consent\": { \
                  \"from_date\": \"2020-06-07\", \
                  \"scopes\": [ \
                    \"account_details\", \
                    \"transactions_details\" \
                  ] \
                }, \
                \"file_url\": \"http://spatialkeydocs.s3.amazonaws.com/FL_insurance_sample.csv\" \
              } \
            }" \
        https://www.saltedge.com/api/v5/connection

Sample response

{
  "data": {
    "country_code": "XF",
    "created_at": "2020-08-04T07:28:28Z",
    "customer_id": "222222222222222222",
    "daily_refresh": false,
    "id": "111111111111111111",
    "secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
    "show_consent_confirmation": false,
    "last_consent_id": "555555555555555555",
    "last_attempt": {
      "api_mode": "service",
      "api_version": "5",
      "automatic_fetch": true,
      "user_present": true,
      "daily_refresh": false,
      "categorization": "personal",
      "created_at": "2020-08-05T06:48:28Z",
      "customer_last_logged_at": "2020-08-05T04:28:28Z",
      "custom_fields": {},
      "device_type": "desktop",
      "remote_ip": "93.184.216.34",
      "exclude_accounts": [],
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "fetch_scopes": ["accounts", "transactions"],
      "finished": true,
      "finished_recent": true,
      "from_date": "2020-06-07",
      "id": "777777777777777777",
      "interactive": false,
      "locale": "en",
      "partial": false,
      "store_credentials": true,
      "success_at": "2020-08-05T06:48:28Z",
      "to_date": "2020-08-05",
      "updated_at": "2020-08-05T06:48:28Z",
      "show_consent_confirmation": false,
      "consent_id": "555555555555555555",
      "include_natures": ["account", "card", "bonus"],
      "last_stage": {
        "created_at": "2020-08-05T06:48:28Z",
        "id": "888888888888888888",
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "finish",
        "updated_at": "2020-08-05T06:48:28Z"
      }
    },
    "last_success_at": "2020-08-05T06:48:28Z",
    "next_refresh_possible_at": "2020-08-05T08:28:28Z",
    "provider_id": "1234",
    "provider_code": "fakebank_simple_xf",
    "provider_name": "Fakebank Simple",
    "status": "active",
    "store_credentials": true,
    "updated_at": "2020-08-05T06:48:28Z"
  }
}
{
  "data": {
    "country_code": "XF",
    "created_at": "2020-08-04T07:28:28Z",
    "customer_id": "222222222222222222",
    "daily_refresh": false,
    "id": "111111111111111111",
    "secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
    "show_consent_confirmation": false,
    "last_consent_id": "555555555555555555",
    "last_attempt": {
      "api_mode": "service",
      "api_version": "5",
      "automatic_fetch": true,
      "user_present": true,
      "daily_refresh": false,
      "categorization": "personal",
      "created_at": "2020-08-05T06:48:28Z",
      "customer_last_logged_at": "2020-08-05T04:28:28Z",
      "custom_fields": {},
      "device_type": "desktop",
      "remote_ip": "93.184.216.34",
      "exclude_accounts": [],
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "fetch_scopes": ["accounts", "transactions"],
      "finished": true,
      "finished_recent": true,
      "from_date": "2020-06-07",
      "id": "777777777777777777",
      "interactive": false,
      "locale": "en",
      "partial": false,
      "store_credentials": true,
      "success_at": "2020-08-05T06:48:28Z",
      "to_date": "2020-08-05",
      "updated_at": "2020-08-05T06:48:28Z",
      "show_consent_confirmation": false,
      "consent_id": "555555555555555555",
      "include_natures": ["account", "card", "bonus"],
      "last_stage": {
        "created_at": "2020-08-05T06:48:28Z",
        "id": "888888888888888888",
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "finish",
        "updated_at": "2020-08-05T06:48:28Z"
      }
    },
    "last_success_at": "2020-08-05T06:48:28Z",
    "next_refresh_possible_at": "2020-08-05T08:28:28Z",
    "provider_id": "1234",
    "provider_code": "fakebank_simple_xf",
    "provider_name": "Fakebank Simple",
    "status": "active",
    "store_credentials": true,
    "updated_at": "2020-08-05T06:48:28Z"
  }
}

Reconnect

In order to reconnect a connection, your app needs to send the credentials object, connection’s id, consent object and/or attempt object. This means that the consent confirmation should be handled on the client’s side, and the ‘access terms’ the customer agreed on should be passed.

Parameters

credentials

object, required unless encrypted_credentials are present

The credentials required to access the data

encrypted_credentials

object, required unless credentials are present

The encrypted credentials required to access the data

consent

object, required

attempt

object, optional

daily_refresh

boolean, optional

Whether the connection should be automatically refreshed by Salt Edge. Defaults to false

include_fake_providers

boolean, optional

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

categorization

string, optional

The type of categorization applied. Possible values: none, personal, business. Defaults to personal

file_url

string, optional

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

override_credentials

boolean, optional

If sent as true, new credentials will automatically override the old ones, in the scenario were the new credentials are different from the ones in the previous attempt. Defaults to false

credentials

object, required unless encrypted_credentials are present

The credentials required to access the data

encrypted_credentials

object, required unless credentials are present

The encrypted credentials required to access the data

consent

object, required

attempt

object, optional

daily_refresh

boolean, optional

Whether the connection should be automatically refreshed by Salt Edge. Defaults to false

include_fake_providers

boolean, optional

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

categorization

string, optional

The type of categorization applied. Possible values: none, personal, business. Defaults to personal

file_url

string, optional

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

override_credentials

boolean, optional

If sent as true, new credentials will automatically override the old ones, in the scenario were the new credentials are different from the ones in the previous attempt. Defaults to false

Response

A complete Connection object.

Possible Errors

URL

https://www.saltedge.com/api/v5/connections/{connection.id}/reconnect

https://www.saltedge.com/api/v5/connection/reconnect

Method

PUT

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"credentials\": { \
                  \"login\": \"username\", \
                  \"password\": \"secret\" \
                }, \
                \"consent\": { \
                  \"scopes\": [ \
                    \"account_details\" \
                  ] \
                }, \
                \"override_credentials\": true \
              } \
            }" \
        https://www.saltedge.com/api/v5/connections/111111111111111111/reconnect
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"credentials\": { \
                  \"login\": \"username\", \
                  \"password\": \"secret\" \
                }, \
                \"consent\": { \
                  \"scopes\": [ \
                    \"account_details\" \
                  ] \
                }, \
                \"override_credentials\": true \
              } \
            }" \
        https://www.saltedge.com/api/v5/connection/reconnect

Sample request (with encrypted credentials)

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"consent\": { \
                  \"scopes\": [ \
                    \"account_details\" \
                  ] \
                }, \
                \"encrypted_credentials\": { \
                  \"algorithm\": \"AES-256-CBC\", \
                  \"key\": \"Yir+HThidKxlpqA...\", \
                  \"iv\": \"JEhn/N5oK9s0U1L...\", \
                  \"data\": \"S8XD2kHCPsIQj+x...\", \
                  \"version\": \"your_key_version\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v5/connections/111111111111111111/reconnect

Sample request (with file providers)

curl -v -include \
        -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -F "file=@file.ofx" \
        https://www.saltedge.com/api/v5/connections/111111111111111111/reconnect
curl -v -include \
        -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -F "file=@file.ofx" \
        https://www.saltedge.com/api/v5/connections/111111111111111111/reconnect

Sample response

{
  "data": {
    "country_code": "XF",
    "created_at": "2020-08-04T07:28:28Z",
    "customer_id": "222222222222222222",
    "daily_refresh": false,
    "id": "111111111111111111",
    "secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
    "show_consent_confirmation": false,
    "last_consent_id": "555555555555555555",
    "last_attempt": {
      "api_mode": "service",
      "api_version": "5",
      "automatic_fetch": true,
      "user_present": true,
      "daily_refresh": true,
      "categorization": "personal",
      "created_at": "2020-08-05T06:48:28Z",
      "customer_last_logged_at": "2020-08-05T04:28:28Z",
      "custom_fields": {},
      "device_type": "desktop",
      "remote_ip": "93.184.216.34",
      "exclude_accounts": [],
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "fetch_scopes": ["accounts"],
      "finished": true,
      "finished_recent": true,
      "from_date": null,
      "id": "777777777777777777",
      "interactive": false,
      "locale": "en",
      "partial": false,
      "store_credentials": true,
      "success_at": "2020-08-05T06:48:28Z",
      "to_date": null,
      "updated_at": "2020-08-05T06:48:28Z",
      "show_consent_confirmation": false,
      "consent_id": "555555555555555555",
      "include_natures": ["account", "card", "bonus"],
      "last_stage": {
        "created_at": "2020-08-05T06:48:28Z",
        "id": "888888888888888888",
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "finish",
        "updated_at": "2020-08-05T06:48:28Z"
      }
    },
    "last_success_at": "2020-08-05T06:48:28Z",
    "next_refresh_possible_at": "2020-08-05T08:28:28Z",
    "provider_id": "1234",
    "provider_code": "fakebank_simple_xf",
    "provider_name": "Fakebank Simple",
    "status": "active",
    "store_credentials": true,
    "updated_at": "2020-08-05T06:48:28Z"
  }
}
{
  "data": {
    "country_code": "XF",
    "created_at": "2020-08-04T07:28:28Z",
    "customer_id": "222222222222222222",
    "daily_refresh": false,
    "id": "111111111111111111",
    "secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
    "show_consent_confirmation": false,
    "last_consent_id": "555555555555555555",
    "last_attempt": {
      "api_mode": "service",
      "api_version": "5",
      "automatic_fetch": true,
      "user_present": true,
      "daily_refresh": true,
      "categorization": "personal",
      "created_at": "2020-08-05T06:48:28Z",
      "customer_last_logged_at": "2020-08-05T04:28:28Z",
      "custom_fields": {},
      "device_type": "desktop",
      "remote_ip": "93.184.216.34",
      "exclude_accounts": [],
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "fetch_scopes": ["accounts"],
      "finished": true,
      "finished_recent": true,
      "from_date": null,
      "id": "777777777777777777",
      "interactive": false,
      "locale": "en",
      "partial": false,
      "store_credentials": true,
      "success_at": "2020-08-05T06:48:28Z",
      "to_date": null,
      "updated_at": "2020-08-05T06:48:28Z",
      "show_consent_confirmation": false,
      "consent_id": "555555555555555555",
      "include_natures": ["account", "card", "bonus"],
      "last_stage": {
        "created_at": "2020-08-05T06:48:28Z",
        "id": "888888888888888888",
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "finish",
        "updated_at": "2020-08-05T06:48:28Z"
      }
    },
    "last_success_at": "2020-08-05T06:48:28Z",
    "next_refresh_possible_at": "2020-08-05T08:28:28Z",
    "provider_id": "1234",
    "provider_code": "fakebank_simple_xf",
    "provider_name": "Fakebank Simple",
    "status": "active",
    "store_credentials": true,
    "updated_at": "2020-08-05T06:48:28Z"
  }
}

Interactive

If the currently fetching connection requires any interactive credentials for fetching, Salt Edge will send the Interactive callback. Make sure to specify the Interactive URL in your client account by accessing callbacks page.

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

In case of dynamic_select field nature, when it has extra: { multiple: true } flag - you should send the option_value of the user selected options in an Array of strings:

  {
    "data": {
      "credentials": {
        "accounts": ["account1", "account2"]
      }
    }
  }

In case of dynamic_select field nature, when it has extra: { multiple: false } flag - you should send the option_value of the user selected option as a single String value:

  {
    "data": {
      "credentials": {
        "language": "english"
      }
    }
  }

Please note that in some cases (e.g. when fetching Fake Bank with SMS connections), during the interactive stage a 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 unless encrypted_credentials are present

The credentials object based on the provider’s interactive fields

encrypted_credentials

object, required unless credentials are present

The encrypted credentials required to access the data, based on provider’s interactive fields

credentials

object, required unless encrypted_credentials are present

The credentials object based on the provider’s interactive fields

encrypted_credentials

object, required unless credentials are present

The encrypted credentials required to access the data, based on provider’s interactive fields

Response

A complete Connection object.

Possible Errors

URL

https://www.saltedge.com/api/v5/connections/{connection.id}/interactive

https://www.saltedge.com/api/v5/connection/interactive

Method

PUT

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"credentials\": { \
                  \"sms\": \"AB123\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v5/connections/111111111111111111/interactive
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"credentials\": { \
                  \"sms\": \"AB123\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v5/connection/interactive

Sample request (with encrypted credentials)

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"encrypted_credentials\": { \
                  \"algorithm\": \"AES-256-CBC\", \
                  \"key\": \"Yir+HThidKxlpqA...\", \
                  \"iv\": \"JEhn/N5oK9s0U1L...\", \
                  \"data\": \"S8XD2kHCPsIQj+x...\", \
                  \"version\": \"your_key_version\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v5/connections/111111111111111111/interactive

Sample response

{
  "data": {
    "country_code": "XF",
    "created_at": "2020-08-04T07:28:28Z",
    "customer_id": "222222222222222222",
    "daily_refresh": false,
    "id": "111111111111111111",
    "secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
    "show_consent_confirmation": false,
    "last_consent_id": "555555555555555555",
    "last_attempt": {
      "api_mode": "service",
      "api_version": "5",
      "automatic_fetch": false,
      "user_present": false,
      "daily_refresh": false,
      "categorization": "personal",
      "created_at": "2020-08-05T06:48:28Z",
      "customer_last_logged_at": "2020-08-05T04:28:28Z",
      "custom_fields": {},
      "device_type": "desktop",
      "remote_ip": "93.184.216.34",
      "exclude_accounts": [],
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "fetch_scopes": ["accounts", "transactions"],
      "finished": false,
      "finished_recent": false,
      "from_date": null,
      "id": "777777777777777777",
      "interactive": true,
      "locale": "en",
      "partial": true,
      "store_credentials": true,
      "success_at": "2020-08-05T06:48:28Z",
      "to_date": null,
      "updated_at": "2020-08-05T06:48:28Z",
      "show_consent_confirmation": false,
      "consent_id": "555555555555555555",
      "include_natures": ["account", "card", "bonus"],
      "last_stage": {
        "created_at": "2020-08-05T06:48:28Z",
        "id": "888888888888888888",
        "interactive_fields_names": ["sms"],
        "interactive_html": "<input type="text" name="sms" placeholder="Sms">",
        "name": "interactive",
        "updated_at": "2020-08-05T06:48:28Z"
      }
    },
    "last_success_at": "2020-08-05T06:48:28Z",
    "next_refresh_possible_at": "2020-08-05T08:28:28Z",
    "provider_id": "1234",
    "provider_code": "fakebank_interactive_xf",
    "provider_name": "Fake Bank with SMS",
    "status": "active",
    "updated_at": "2020-08-05T06:48:28Z"
  }
}
{
  "data": {
    "country_code": "XF",
    "created_at": "2020-08-04T07:28:28Z",
    "customer_id": "222222222222222222",
    "daily_refresh": false,
    "id": "111111111111111111",
    "secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
    "show_consent_confirmation": false,
    "last_consent_id": "555555555555555555",
    "last_attempt": {
      "api_mode": "service",
      "api_version": "5",
      "automatic_fetch": false,
      "user_present": false,
      "daily_refresh": false,
      "categorization": "personal",
      "created_at": "2020-08-05T06:48:28Z",
      "customer_last_logged_at": "2020-08-05T04:28:28Z",
      "custom_fields": {},
      "device_type": "desktop",
      "remote_ip": "93.184.216.34",
      "exclude_accounts": [],
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "fetch_scopes": ["accounts", "transactions"],
      "finished": false,
      "finished_recent": false,
      "from_date": null,
      "id": "777777777777777777",
      "interactive": true,
      "locale": "en",
      "partial": true,
      "store_credentials": true,
      "success_at": "2020-08-05T06:48:28Z",
      "to_date": null,
      "updated_at": "2020-08-05T06:48:28Z",
      "show_consent_confirmation": false,
      "consent_id": "555555555555555555",
      "include_natures": ["account", "card", "bonus"],
      "last_stage": {
        "created_at": "2020-08-05T06:48:28Z",
        "id": "888888888888888888",
        "interactive_fields_names": ["sms"],
        "interactive_html": "<input type="text" name="sms" placeholder="Sms">",
        "name": "interactive",
        "updated_at": "2020-08-05T06:48:28Z"
      }
    },
    "last_success_at": "2020-08-05T06:48:28Z",
    "next_refresh_possible_at": "2020-08-05T08:28:28Z",
    "provider_id": "1234",
    "provider_code": "fakebank_interactive_xf",
    "provider_name": "Fake Bank with SMS",
    "status": "active",
    "updated_at": "2020-08-05T06:48:28Z"
  }
}

Refresh

Allows you to trigger a refetch of the data associated with a specific connection. Note that you can refresh a connection only if it has an active consent. 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

attempt

object, optional

daily_refresh

boolean, optional

Whether the connection should be automatically refreshed by Salt Edge. Defaults to false

include_fake_providers

boolean, optional

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

categorization

string, optional

The type of categorization applied. Possible values: none, personal, business. Defaults to personal

attempt

object, optional

daily_refresh

boolean, optional

Whether the connection should be automatically refreshed by Salt Edge. Defaults to false

include_fake_providers

boolean, optional

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

categorization

string, optional

The type of categorization applied. Possible values: none, personal, business. Defaults to personal

Possible Errors

URL

https://www.saltedge.com/api/v5/connections/{connection.id}/refresh

https://www.saltedge.com/api/v5/connection/refresh

Method

PUT

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"attempt\": { \
                  \"fetch_scopes\": [ \
                    \"accounts\", \
                    \"transactions\" \
                  ] \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v5/connections/111111111111111111/refresh
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"attempt\": { \
                  \"fetch_scopes\": [ \
                    \"accounts\", \
                    \"transactions\" \
                  ] \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v5/connection/refresh

Sample Response

{
  "data": {
    "country_code": "MD",
    "created_at": "2020-07-06T20:09:02Z",
    "customer_id": "222222222222222222",
    "daily_refresh": false,
    "id": "111111111111111111",
    "secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
    "show_consent_confirmation": false,
    "last_consent_id": "555555555555555555",
    "last_attempt": {
      "api_mode": "service",
      "api_version": "5",
      "automatic_fetch": true,
      "user_present": false,
      "daily_refresh": true,
      "categorization": "personal",
      "created_at": "2020-07-06T16:14:53Z",
      "customer_last_logged_at": "2020-08-05T04:28:28Z",
      "custom_fields": {},
      "device_type": "desktop",
      "remote_ip": "93.184.216.34",
      "exclude_accounts": [],
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "fetch_scopes": ["accounts", "transactions"],
      "finished": true,
      "finished_recent": true,
      "from_date": null,
      "id": "777777777777777777",
      "interactive": false,
      "locale": "en",
      "partial": false,
      "store_credentials": true,
      "success_at": "2020-07-06T16:16:19Z",
      "to_date": null,
      "updated_at": "2020-07-06T16:16:19Z",
      "show_consent_confirmation": false,
      "consent_id": "555555555555555555",
      "include_natures": ["account", "card", "bonus"],
      "last_stage": {
        "created_at": "2020-07-06T16:16:19Z",
        "id": "888888888888888888",
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "finish",
        "updated_at": "2016-02-02T16:16:19Z"
      }
    },
    "last_success_at": "2020-07-06T16:16:19Z",
    "next_refresh_possible_at": "2020-07-06T17:16:19Z",
    "provider_id": "1234",
    "provider_code": "moldindconbank_wb_md",
    "provider_name": "Moldindconbank Web Banking",
    "status": "active",
    "store_credentials": true,
    "updated_at": "2020-07-06T09:41:23Z"
  }
}
{
  "data": {
    "country_code": "MD",
    "created_at": "2020-07-06T20:09:02Z",
    "customer_id": "222222222222222222",
    "daily_refresh": false,
    "id": "111111111111111111",
    "secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
    "show_consent_confirmation": false,
    "last_consent_id": "555555555555555555",
    "last_attempt": {
      "api_mode": "service",
      "api_version": "5",
      "automatic_fetch": true,
      "user_present": false,
      "daily_refresh": true,
      "categorization": "personal",
      "created_at": "2020-07-06T16:14:53Z",
      "customer_last_logged_at": "2020-08-05T04:28:28Z",
      "custom_fields": {},
      "device_type": "desktop",
      "remote_ip": "93.184.216.34",
      "exclude_accounts": [],
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "fetch_scopes": ["accounts", "transactions"],
      "finished": true,
      "finished_recent": true,
      "from_date": null,
      "id": "777777777777777777",
      "interactive": false,
      "locale": "en",
      "partial": false,
      "store_credentials": true,
      "success_at": "2020-07-06T16:16:19Z",
      "to_date": null,
      "updated_at": "2020-07-06T16:16:19Z",
      "show_consent_confirmation": false,
      "consent_id": "555555555555555555",
      "include_natures": ["account", "card", "bonus"],
      "last_stage": {
        "created_at": "2020-07-06T16:16:19Z",
        "id": "888888888888888888",
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "finish",
        "updated_at": "2016-02-02T16:16:19Z"
      }
    },
    "last_success_at": "2020-07-06T16:16:19Z",
    "next_refresh_possible_at": "2020-07-06T17:16:19Z",
    "provider_id": "1234",
    "provider_code": "moldindconbank_wb_md",
    "provider_name": "Moldindconbank Web Banking",
    "status": "active",
    "store_credentials": true,
    "updated_at": "2020-07-06T09:41:23Z"
  }
}

Update

Update status, store_credentials or daily_refresh of a connection.

Parameters

status

string, optional

Possible value is inactive

daily_refresh

boolean, optional

Whether the connection should be automatically refreshed by Salt Edge. Defaults to false

store_credentials

boolean, optional

Allows to not store credentials on Salt Edge side. Defaults to true.
Note: The usage of this flag is not available for file providers. In order to update the connection, reconnect is required. It will not be possible to use refresh option if store_credentials is set to false

status

string, optional

Possible value is inactive

daily_refresh

boolean, optional

Whether the connection should be automatically refreshed by Salt Edge. Defaults to false

store_credentials

boolean, optional

Allows to not store credentials on Salt Edge side. Defaults to true.
Note: The usage of this flag is not available for file providers. In order to update the connection, reconnect is required. It will not be possible to use refresh option if store_credentials is set to false

Not all the connections can be automatically updated by Salt Edge, even if daily_refresh flag is set to true. In case a particular provider requires user interaction during update (like SMS, OTP, etc), Salt Edge will not attempt to update it.

Possible Errors

URL

https://www.saltedge.com/api/v5/connections/{connection.id}

https://www.saltedge.com/api/v5/connection

Method

PUT

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"status\": \"inactive\", \
                \"store_credentials\": false, \
                \"daily_refresh\": true \
              } \
            }" \
        https://www.saltedge.com/api/v5/connections/111111111111111111
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"status\": \"inactive\", \
                \"store_credentials\": false, \
                \"daily_refresh\": true \
              } \
            }" \
        https://www.saltedge.com/api/v5/connection

Sample Response

{
  "data": {
    "country_code": "MD",
    "created_at": "2020-07-06T20:09:02Z",
    "customer_id": "222222222222222222",
    "daily_refresh": false,
    "id": "111111111111111111",
    "secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
    "show_consent_confirmation": false,
    "last_consent_id": "555555555555555555",
    "last_attempt": {
      "api_mode": "service",
      "api_version": "5",
      "automatic_fetch": true,
      "user_present": false,
      "daily_refresh": false,
      "categorization": "personal",
      "created_at": "2020-07-06T16:14:53Z",
      "customer_last_logged_at": "2020-08-05T04:28:28Z",
      "custom_fields": {},
      "device_type": "desktop",
      "remote_ip": "93.184.216.34",
      "exclude_accounts": [],
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "fetch_scopes": ["accounts", "transactions"],
      "finished": true,
      "finished_recent": true,
      "from_date": null,
      "id": "425036",
      "interactive": false,
      "locale": "en",
      "partial": false,
      "store_credentials": true,
      "success_at": "2020-07-06T16:16:19Z",
      "to_date": null,
      "updated_at": "2020-07-06T16:16:19Z",
      "show_consent_confirmation": false,
      "consent_id": "555555555555555555",
      "include_natures": ["account", "card", "bonus"],
      "last_stage": {
        "created_at": "2020-07-06T16:16:19Z",
        "id": "888888888888888888",
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "finish",
        "updated_at": "2020-07-06T16:16:19Z"
      }
    },
    "last_success_at": "2020-07-06T16: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": "2020-07-06T09:41:23Z"
  }
}
{
  "data": {
    "country_code": "MD",
    "created_at": "2020-07-06T20:09:02Z",
    "customer_id": "222222222222222222",
    "daily_refresh": false,
    "id": "111111111111111111",
    "secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
    "show_consent_confirmation": false,
    "last_consent_id": "555555555555555555",
    "last_attempt": {
      "api_mode": "service",
      "api_version": "5",
      "automatic_fetch": true,
      "user_present": false,
      "daily_refresh": false,
      "categorization": "personal",
      "created_at": "2020-07-06T16:14:53Z",
      "customer_last_logged_at": "2020-08-05T04:28:28Z",
      "custom_fields": {},
      "device_type": "desktop",
      "remote_ip": "93.184.216.34",
      "exclude_accounts": [],
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "fetch_scopes": ["accounts", "transactions"],
      "finished": true,
      "finished_recent": true,
      "from_date": null,
      "id": "425036",
      "interactive": false,
      "locale": "en",
      "partial": false,
      "store_credentials": true,
      "success_at": "2020-07-06T16:16:19Z",
      "to_date": null,
      "updated_at": "2020-07-06T16:16:19Z",
      "show_consent_confirmation": false,
      "consent_id": "555555555555555555",
      "include_natures": ["account", "card", "bonus"],
      "last_stage": {
        "created_at": "2020-07-06T16:16:19Z",
        "id": "888888888888888888",
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "finish",
        "updated_at": "2020-07-06T16:16:19Z"
      }
    },
    "last_success_at": "2020-07-06T16: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": "2020-07-06T09:41:23Z"
  }
}

Remove

Removes a connection from our system and revokes the consent. All the associated accounts and transactions to that connection will be destroyed as well. Salt Edge will send a destroy callback to your web application. Make sure to specify the Destroy URL in your client account by accessing callbacks page.

Possible Errors

URL

https://www.saltedge.com/api/v5/connections/{connection.id}

https://www.saltedge.com/api/v5/connection

Method

DELETE

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X DELETE \
        https://www.saltedge.com/api/v5/connections/111111111111111111
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X DELETE \
        https://www.saltedge.com/api/v5/connection

Sample Response

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

Consents

A consent represents the end-user’s permission to access its data. The limits of this access are granted by the customer and are required to access the accounts, transactions and holder information through a specific provider.

The limits of a consent are represented by:

  • data that is allowed to be accessed;
  • period of time the data can be accessed for;
  • interval of time to which the accessed data belongs to.

Attributes

id

string

The id of the consent

connection_id

string

The id of the connection

customer_id

string

The id of the customer

scopes

array of strings, required

Data that is allowed to be fetched. Possible values: ['account_details'], ['holder_information'], ['account_details', 'holder_information'], ['account_details', 'transactions_details'], ['account_details', 'holder_information', 'transactions_details']

period_days

integer

The period the consent will be valid for

expires_at

date

The date when the consent will expire

from_date

date

The date from which the data has been allowed to be fetched

to_date

date

The date until which the data has been allowed to be fetched

collected_by

string

Entity who collected the consent. Possible values: client, saltedge

revoked_at

date

The date when consent was revoked

revoke_reason

string

Revoke reason. Possible values: expired, client, provider, saltedge

created_at

date

When the consent was created

updated_at

date

When the consent was updated

id

string

The id of the consent

connection_id

string

The id of the connection

customer_id

string

The id of the customer

scopes

array of strings, required

Data that is allowed to be fetched. Possible values: ['account_details'], ['holder_information'], ['account_details', 'holder_information'], ['account_details', 'transactions_details'], ['account_details', 'holder_information', 'transactions_details']

period_days

integer

The period the consent will be valid for

expires_at

date

The date when the consent will expire

from_date

date

The date from which the data has been allowed to be fetched

to_date

date

The date until which the data has been allowed to be fetched

collected_by

string

Entity who collected the consent. Possible values: client, saltedge

revoked_at

date

The date when consent was revoked

revoke_reason

string

Revoke reason. Possible values: expired, client, provider, saltedge

created_at

date

When the consent was created

updated_at

date

When the consent was updated

List

Returns all the consents accessible to your application for a certain customer or a connection. The consents are sorted in ascending order of their id, so the latest consents will come last. You can read more about next_id field, in the pagination section of the reference.

Parameters

connection_id

string, optional

The id of the connection containing the consents

customer_id

string, optional

The id of the customer containing the consents, required unless connection_id parameter is sent.

from_id

string, optional

The id from which the next page of consents starts

from_id

string, optional

The id from which the next page of consents starts

Possible Errors

URL

https://www.saltedge.com/api/v5/consents?connection_id={connection.id}

https://www.saltedge.com/api/v5/consents

Method

GET

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/consents?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/consents

Sample Response

{
  "data": [
    {
      "id": "555555555555555555",
      "connection_id": "111111111111111111",
      "customer_id": "222222222222222222",
      "scopes": [
        "account_details",
        "transactions_details"
      ],
      "period_days": 60,
      "expires_at": "2020-10-04T04:28:28Z",
      "from_date": "2020-07-05",
      "to_date": null,
      "collected_by": "client",
      "revoked_at": null,
      "revoke_reason": null,
      "created_at": "2020-08-05T04:28:28Z",
      "updated_at": "2020-08-05T04:28:28Z"
    }
  ],
  "meta" : {
    "next_id": "555555555555555556",
    "next_page": "/api/v5/consents?connection_id=111111111111111111&from_id=555555555555555556"
  }
}
{
  "data": [
    {
      "id": "555555555555555555",
      "scopes": [
        "account_details",
        "transactions_details"
      ],
      "period_days": 60,
      "expires_at": "2020-10-04T04:28:28Z",
      "from_date": "2020-07-05",
      "to_date": null,
      "collected_by": "client",
      "revoked_at": null,
      "revoke_reason": null,
      "created_at": "2020-08-05T04:28:28Z",
      "updated_at": "2020-08-05T04:28:28Z"
    }
  ],
  "meta" : {
    "next_id": "555555555555555556",
    "next_page": "/api/v5/consents?from_id=555555555555555556"
  }
}

Show

Returns the consent object.

Parameters

connection_id

string, optional

The id of the connection containing the consent, required unless customer_id parameter is sent

customer_id

string, optional

The id of the customer containing the consent, required unless connection_id parameter is sent.

id

string, required

The id of the consent

id

string, required

The id of the consent

Possible Errors

URL

https://www.saltedge.com/api/v5/consents/{consent.id}?connection_id={connection.id}

https://www.saltedge.com/api/v5/consents/{consent.id}

Method

GET

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/consents/555555555555555555?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/consents/555555555555555555

Sample Response

{
  "data": {
    "id": "555555555555555555",
    "connection_id": "111111111111111111",
    "customer_id": "222222222222222222",
    "scopes": [
      "account_details",
      "transactions_details"
    ],
    "period_days": 60,
    "expires_at": "2020-10-04T04:28:28Z",
    "from_date": "2020-07-05",
    "to_date": null,
    "collected_by": "client",
    "revoked_at": null,
    "revoke_reason": null,
    "created_at": "2020-08-05T04:28:28Z",
    "updated_at": "2020-08-05T04:28:28Z"
  }
}
{
  "data": {
    "id": "555555555555555555",
    "scopes": [
      "account_details",
      "transactions_details"
    ],
    "period_days": 60,
    "expires_at": "2020-10-04T04:28:28Z",
    "from_date": "2020-07-05",
    "to_date": null,
    "collected_by": "client",
    "revoked_at": null,
    "revoke_reason": null,
    "created_at": "2020-08-05T04:28:28Z",
    "updated_at": "2020-08-05T04:28:28Z"
  }
}

Revoke

Allows you to revoke a consent for a connection or a customer.

Attributes

connection_id

string, optional

The id of the connection containing the consent, required unless customer_id parameter is sent

customer_id

string, optional

The id of the customer containing the consent, required unless connection_id parameter is sent.

id

string, required

The id of the consent

id

string, required

The id of the consent

Possible Errors

URL

https://www.saltedge.com/api/v5/consents/{consent.id}/revoke?connection_id={connection.id}

https://www.saltedge.com/api/v5/consents/{consent.id}/revoke

Method

PUT

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X PUT \
        https://www.saltedge.com/api/v5/consents/555555555555555555/revoke?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X PUT \
        https://www.saltedge.com/api/v5/consents/555555555555555555/revoke

Sample Response

{
  "data": {
    "id": "555555555555555555",
    "connection_id": "111111111111111111",
    "customer_id": "222222222222222222",
    "scopes": [
      "account_details",
      "transactions_details"
    ],
    "period_days": 60,
    "expires_at": "2020-10-04T04:28:28Z",
    "from_date": "2020-07-05",
    "to_date": null,
    "collected_by": "client",
    "revoked_at": "2020-08-05T07:28:28Z",
    "revoke_reason": "client",
    "created_at": "2020-08-05T04:28:28Z",
    "updated_at": "2020-08-05T04:28:28Z"
  }
}
{
  "data": {
    "id": "555555555555555555",
    "scopes": [
      "account_details",
      "transactions_details"
    ],
    "period_days": 60,
    "expires_at": "2020-10-04T04:28:28Z",
    "from_date": "2020-07-05",
    "to_date": null,
    "collected_by": "client",
    "revoked_at": "2020-08-05T07:28:28Z",
    "revoke_reason": "client",
    "created_at": "2020-08-05T04:28:28Z",
    "updated_at": "2020-08-05T04:28:28Z"
  }
}

Parameters object

The following represents the consent parameters object that is passed in requests.

scopes

array of strings, required

Data to be allowed for fetching. Possible values: ['account_details'], ['holder_information'], ['account_details', 'holder_information'], ['account_details', 'transactions_details'], ['account_details', 'holder_information', 'transactions_details']. The allowed values for this parameter must fall within the client’s allowed_fetch_scopes and/or provider’s supported_fetch_scopes restrictions. To change the client’s allowed scopes, please contact our Sales team.

from_date

date, optional

Date to be allowed for fetching the data from. Defaults to 90 days ago. This parameter is used when scopes parameter contains transactions_details. The allowed values for this parameter must be within exactly 365 days ago.

to_date

date, optional

Date to be allowed for fetching the data until. Defaults to null (limitless). The allowed values for this parameter must be equal or more than from_date.

period_days

integer, optional

Determines the period the consent will be valid for. Defaults to null (limitless) or provider’s max_consent_days. The allowed value for this parameter must not be higher than the provider’s max_consent_days.

scopes

array of strings, required

Data to be allowed for fetching. Possible values: ['account_details'], ['holder_information'], ['account_details', 'holder_information'], ['account_details', 'transactions_details'], ['account_details', 'holder_information', 'transactions_details']. The allowed values for this parameter must fall within the client’s allowed_fetch_scopes and/or provider’s supported_fetch_scopes restrictions. To change the client’s allowed scopes, please contact our Sales team.

from_date

date, optional

Date to be allowed for fetching the data from. Defaults to 90 days ago. This parameter is used when scopes parameter contains transactions_details. The allowed values for this parameter must be within exactly 365 days ago.

to_date

date, optional

Date to be allowed for fetching the data until. Defaults to null (limitless). The allowed values for this parameter must be equal or more than from_date.

period_days

integer, optional

Determines the period the consent will be valid for. Defaults to null (limitless) or provider’s max_consent_days. The allowed value for this parameter must not be higher than the provider’s max_consent_days.

Attempts

Represents a detailed description of a particular 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

string

The API version in which the attempt was created

automatic_fetch

boolean

Whether the connection related to the attempt can be automatically fetched

daily_refresh

boolean

Latest assigned value for daily_refresh in connection

categorization

string, optional

The type of categorization applied. Possible values: none, personal, business. Defaults to personal

created_at

datetime

When the attempt was made

custom_fields

object

The custom fields that had been sent when creating connection/connect_session/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 strings

The ids of accounts that do not need to be refreshed

user_present

boolean

Whether the request was initiated by the end-user of your application

customer_last_logged_at

datetime

The datetime when user was last active in your application

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_scopes

array of strings, required

Fetching mode, possible values: ['accounts'], ['holder_info'], ['accounts', 'holder_info'], ['accounts', 'transactions'], ['accounts', 'holder_info', 'transactions']

finished

boolean

Whether the connection had finished fetching

finished_recent

boolean

Whether the connection had finished data for recent range

from_date

date

Date from which the data had been fetched

id

string

Id of the attempt

interactive

boolean

Whether the connection related to the attempt is interactive

locale

string

The language of the Connect widget or/and provider error message in the ISO 639-1 format. Possible values are: bg, cz, de, en, es, es-MX, fr, he, hu, it, nl, pl, pt, pt-BR, ro, ru, sk, tr, uk, zh-HongKong. Defaults to en

partial

boolean

Whether the connection 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 occurred

show_consent_confirmation

boolean

Whether any consent was given for this connection

include_natures

array of strings

The natures of the accounts that need to be fetched

stages

array of stage objects

Information about stages through which the connection has passed

api_mode

string

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

api_version

string

The API version in which the attempt was created

automatic_fetch

boolean

Whether the connection related to the attempt can be automatically fetched

daily_refresh

boolean

Latest assigned value for daily_refresh in connection

categorization

string, optional

The type of categorization applied. Possible values: none, personal, business. Defaults to personal

created_at

datetime

When the attempt was made

custom_fields

object

The custom fields that had been sent when creating connection/connect_session/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 strings

The ids of accounts that do not need to be refreshed

user_present

boolean

Whether the request was initiated by the end-user of your application

customer_last_logged_at

datetime

The datetime when user was last active in your application

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_scopes

array of strings, required

Fetching mode, possible values: ['accounts'], ['holder_info'], ['accounts', 'holder_info'], ['accounts', 'transactions'], ['accounts', 'holder_info', 'transactions']

finished

boolean

Whether the connection had finished fetching

finished_recent

boolean

Whether the connection had finished data for recent range

from_date

date

Date from which the data had been fetched

id

string

Id of the attempt

interactive

boolean

Whether the connection related to the attempt is interactive

locale

string

The language of the Connect widget or/and provider error message in the ISO 639-1 format. Possible values are: bg, cz, de, en, es, es-MX, fr, he, hu, it, nl, pl, pt, pt-BR, ro, ru, sk, tr, uk, zh-HongKong. Defaults to en

partial

boolean

Whether the connection 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 occurred

show_consent_confirmation

boolean

Whether any consent was given for this connection

include_natures

array of strings

The natures of the accounts that need to be fetched

stages

array of stage objects

Information about stages through which the connection has passed

The values of the interactive and automatic_fetch attributes are subject to change, since the customer can activate or deactivate the interactive requirements separately with their bank or the bank may change its authorization flow (for example, requiring SCA).

Sample object

{
  "api_mode": "service",
  "api_version": "5",
  "automatic_fetch": true,
  "user_present": false,
  "categorization": "personal",
  "created_at": "2020-08-05T05:28:28Z",
  "customer_last_logged_at": "2020-08-05T04:28:28Z",
  "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_scopes": ["accounts", "transactions"],
  "finished": true,
  "finished_recent": true,
  "from_date": null,
  "id": "777777777777777777",
  "interactive": false,
  "partial": false,
  "store_credentials": true,
  "success_at": "2020-08-05T06:28:28Z",
  "to_date": null,
  "updated_at": "2020-08-05T06:28:28Z",
  "show_consent_confirmation": true,
  "include_natures": ["account", "card", "bonus"],
  "last_stage": {
    "created_at": "2020-08-05T06:28:28Z",
    "id": "888888888888888888",
    "interactive_fields_name": null,
    "interactive_html": null,
    "name": "finish",
    "updated_at": "2020-08-05T06:28:28Z"
  }
}

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

string

The id of the stage

interactive_fields_names

array of strings

The interactive fields that are currently required by the provider. Appears only for the interactive connections

interactive_html

string

HTML code that shows the current interactive state of the connection. Appears only for the interactive connections

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

created_at

datetime

When the stage was created

id

string

The id of the stage

interactive_fields_names

array of strings

The interactive fields that are currently required by the provider. Appears only for the interactive connections

interactive_html

string

HTML code that shows the current interactive state of the connection. Appears only for the interactive connections

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

List

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

Parameters

connection_id

string

The id of the connection whose attempts are to be fetched

URL

https://www.saltedge.com/api/v5/attempts?connection_id={connection.id}

https://www.saltedge.com/api/v5/attempts

Method

GET

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/attempts?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/attempts

Sample response

{
  "data": {
    [
      {
        "api_mode": "service",
        "api_version": "5",
        "automatic_fetch": true,
        "user_present": false,
        "categorization": "personal",
        "created_at": "2020-08-05T05:28:28Z",
        "customer_last_logged_at": "2020-08-05T04:28:28Z",
        "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_scopes": ["accounts", "transactions"],
        "finished": true,
        "finished_recent": true,
        "from_date": null,
        "id": "777777777777777777",
        "interactive": false,
        "locale": "en",
        "partial": false,
        "store_credentials": true,
        "success_at": "2020-08-05T06:28:28Z",
        "to_date": null,
        "updated_at": "2020-08-05T06:28:28Z",
        "show_consent_confirmation": true,
        "include_natures": ["account", "card", "bonus"],
        "last_stage": {
          "created_at": "2020-08-05T06:28:28Z",
          "id": "888888888888888888",
          "interactive_fields_name": null,
          "interactive_html": null,
          "name": "finish",
          "updated_at": "2020-08-05T06:28:28Z"
        }
      }
    ]
  },
  "meta": {
    "next_id": "777777777777777778",
    "next_page": "/api/v5/attempts?connection_id=111111111111111111&from_id=777777777777777778"
  }
}
{
  "data": {
    [
      {
        "api_mode": "app",
        "api_version": "5",
        "automatic_fetch": true,
        "user_present": false,
        "categorization": "personal",
        "created_at": "2020-08-05T05:28:28Z",
        "customer_last_logged_at": "2020-08-05T04:28:28Z",
        "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_scopes": ["accounts", "transactions"],
        "finished": true,
        "finished_recent": true,
        "from_date": null,
        "id": "777777777777777777",
        "interactive": false,
        "locale": "en",
        "partial": false,
        "store_credentials": true,
        "success_at": "2020-08-05T06:28:28Z",
        "to_date": null,
        "updated_at": "2020-08-05T06:28:28Z",
        "show_consent_confirmation": true,
        "include_natures": ["account", "card", "bonus"],
        "last_stage": {
          "created_at": "2020-08-05T06:28:28Z",
          "id": "888888888888888888",
          "interactive_fields_name": null,
          "interactive_html": null,
          "name": "finish",
          "updated_at": "2020-08-05T06:28:28Z"
        }
      }
    ]
  },
  "meta": {
    "next_id": "777777777777777778",
    "next_page": "/api/v5/attempts?from_id=777777777777777778"
  }
}

Show

Returns a single attempt object.

Parameters

connection_id

string

The id of the connection whose attempts are to be fetched

URL

https://www.saltedge.com/api/v5/attempts/{attempt.id}?connection_id={connection.id}

https://www.saltedge.com/api/v5/attempts/{attempt.id}

Method

GET

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/attempts/777777777777777777?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/attempts/777777777777777777

Sample response

{
  "data": {
    "api_mode": "service",
    "api_version": "5",
    "automatic_fetch": true,
    "user_present": false,
    "daily_refresh": false,
    "categorization": "personal",
    "created_at": "2020-08-05T05:28:28Z",
    "customer_last_logged_at": "2020-08-05T04:28:28Z",
    "custom_fields": {},
    "device_type": "desktop",
    "remote_ip": "93.184.216.34",
    "exclude_accounts": [],
    "fail_at": null,
    "fail_error_class": null,
    "fail_message": null,
    "fetch_scopes": ["accounts", "transactions"],
    "finished": true,
    "finished_recent": true,
    "from_date": null,
    "id": "777777777777777777",
    "interactive": false,
    "locale": "en",
    "partial": false,
    "store_credentials": true,
    "success_at": "2020-08-05T06:28:28Z",
    "to_date": null,
    "updated_at": "2020-08-05T06:28:28Z",
    "show_consent_confirmation": true,
    "include_natures": ["account", "card", "bonus"],
    "stages": [
      {
        "created_at": "2020-08-05T05:28:28Z",
        "id": "888888888888888881",
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "start",
        "updated_at": "2020-08-05T05:28:28Z"
      },
      {
        "created_at": "2020-08-05T05:38:28Z",
        "id": "888888888888888882",
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "connect",
        "updated_at": "2020-08-05T05:38:28Z"
      },
      {
        "created_at": "2020-08-05T06:28:28Z",
        "id": "888888888888888883",
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "finish",
        "updated_at": "2020-08-05T06:28:28Z"
      }
    ]
  }
}
{
  "data": {
    "api_mode": "app",
    "api_version": "5",
    "automatic_fetch": true,
    "user_present": false,
    "daily_refresh": false,
    "categorization": "personal",
    "created_at": "2020-08-05T05:28:28Z",
    "customer_last_logged_at": "2020-08-05T04:28:28Z",
    "custom_fields": {},
    "device_type": "desktop",
    "remote_ip": "93.184.216.34",
    "exclude_accounts": [],
    "fail_at": null,
    "fail_error_class": null,
    "fail_message": null,
    "fetch_scopes": ["accounts", "transactions"],
    "finished": true,
    "finished_recent": true,
    "from_date": null,
    "id": "777777777777777777",
    "interactive": false,
    "locale": "en",
    "partial": false,
    "store_credentials": true,
    "success_at": "2020-08-05T06:28:28Z",
    "to_date": null,
    "updated_at": "2020-08-05T06:28:28Z",
    "show_consent_confirmation": true,
    "include_natures": ["account", "card", "bonus"],
    "stages": [
      {
        "created_at": "2020-08-05T05:28:28Z",
        "id": "888888888888888881",
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "start",
        "updated_at": "2020-08-05T05:28:28Z"
      },
      {
        "created_at": "2020-08-05T05:38:28Z",
        "id": "888888888888888882",
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "connect",
        "updated_at": "2020-08-05T05:38:28Z"
      },
      {
        "created_at": "2020-08-05T06:28:28Z",
        "id": "888888888888888883",
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "finish",
        "updated_at": "2020-08-05T06:28:28Z"
      }
    ]
  }
}

Parameters object

The following represents the attempt parameters object that is passed in requests.

fetch_scopes

array of strings, optional

Fetching mode. Possible values: ['accounts'], ['holder_info'], ['accounts', 'holder_info'], ['accounts', 'transactions'], ['accounts', 'holder_info', 'transactions']. Defaults to consent scopes. The allowed values for this parameter must comply to the consent scopes restriction.

from_date

date, optional

Date from which you want to fetch data for your connection. Defaults to consent from_date. The allowed values for this parameter must be within exactly 365 days ago and it should comply to the fetching period restrictions in the consent.

to_date

date, optional

Date until which you want to fetch data for your connection. Defaults to null (today). The allowed values for this parameter must be equal or more than from_date and less or equal than tomorrow. Also it should comply to the fetching period restrictions in the consent.

fetched_accounts_notify

boolean, optional

Whether Salt Edge should send a success callback after fetching accounts. Defaults to false

custom_fields

object, optional

A JSON object, which will be sent back on any of your callbacks. Defaults to empty object

locale

string, optional

The language of the Connect widget or/and provider error message in the ISO 639-1 format. Possible values are: bg, cz, de, en, es, es-MX, fr, he, hu, it, nl, pl, pt, pt-BR, ro, ru, sk, tr, uk, zh-HongKong. Defaults to en

include_natures

array of strings, optional

The natures of the accounts that need to be fetched. Check accounts attributes for possible values. Default value: null (all accounts will be fetched)

customer_last_logged_at

datetime, optional

The datetime when user was last active in your application

exclude_accounts

array of strings, optional

Array of account ids which will not be fetched. Applied to reconnect and refresh atempts. Defaults to empty array

store_credentials

boolean

Whether the credentials should be stored on Salt Edge side

user_present

boolean, optional

Whether the request was initiated by the end-user of your application. It is taken into account only for PSD2-compliant providers and used for reconnect and refresh.

return_to

string, optional

The URL the user will be redirected to, defaults to client’s home URL. If the provider has api mode and interactive true then this field is mandatory.

fetch_scopes

array of strings, optional

Fetching mode. Possible values: ['accounts'], ['holder_info'], ['accounts', 'holder_info'], ['accounts', 'transactions'], ['accounts', 'holder_info', 'transactions']. Defaults to consent scopes. The allowed values for this parameter must comply to the consent scopes restriction.

from_date

date, optional

Date from which you want to fetch data for your connection. Defaults to consent from_date. The allowed values for this parameter must be within exactly 365 days ago and it should comply to the fetching period restrictions in the consent.

to_date

date, optional

Date until which you want to fetch data for your connection. Defaults to null (today). The allowed values for this parameter must be equal or more than from_date and less or equal than tomorrow. Also it should comply to the fetching period restrictions in the consent.

fetched_accounts_notify

boolean, optional

Whether Salt Edge should send a success callback after fetching accounts. Defaults to false

custom_fields

object, optional

A JSON object, which will be sent back on any of your callbacks. Defaults to empty object

locale

string, optional

The language of the Connect widget or/and provider error message in the ISO 639-1 format. Possible values are: bg, cz, de, en, es, es-MX, fr, he, hu, it, nl, pl, pt, pt-BR, ro, ru, sk, tr, uk, zh-HongKong. Defaults to en

include_natures

array of strings, optional

The natures of the accounts that need to be fetched. Check accounts attributes for possible values. Default value: null (all accounts will be fetched)

customer_last_logged_at

datetime, optional

The datetime when user was last active in your application

exclude_accounts

array of strings, optional

Array of account ids which will not be fetched. Applied to reconnect and refresh atempts. Defaults to empty array

store_credentials

boolean

Whether the credentials should be stored on Salt Edge side

user_present

boolean, optional

Whether the request was initiated by the end-user of your application. It is taken into account only for PSD2-compliant providers and used for reconnect and refresh.

return_to

string, optional

The URL the user will be redirected to, defaults to client’s home URL. If the provider has api mode and interactive true then this field is mandatory.

user_present is used only for PSD2-compliant providers and has nothing to do with prioritizing or speeding up the fetching of connections made via screen-scraping or other technology. If user_present is set to false, a limit of 4 background fetches will be enforced as per PSD2, all requests that exceed this limit will return a BackgroundFetchLimitExceeded. Note that for create/reconnect default value is set to true, for refresh default value is set to false.

Accounts

Any connection can have one or more accounts. The accounts are bound to a currency so that all the transactions within a single account are in the same currency.

Sometimes, the provider allows the user to have several currencies grouped under the same account. For example, if a user holds a debit card that supports 3 currencies, the corresponding connection will have 3 accounts, each with one of the debit card’s currencies.

Attributes

id

string

The id of the account

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: 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. Maximum 3 letters

extra

object, extra object

Extra data associated with the account

connection_id

string

The id of the connection the account belongs to

created_at

datetime

Time and date when the account was imported

updated_at

datetime

The last time when the account’s balance was changed or new transactions were imported

id

string

The id of the account

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: 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. Maximum 3 letters

extra

object, extra object

Extra data associated with the account

connection_id

string

The id of the connection the account belongs to

created_at

datetime

Time and date when the account was imported

updated_at

datetime

The last time when the account’s balance was changed or new transactions were imported

Sample Object

{
    "id": "333333333333333333",
    "name": "Fake account 2",
    "nature": "account",
    "balance": 2012.7,
    "currency_code": "USD",
    "extra": {
        "cards": [
            "1234....5678",
            "*8765"
        ],
        "transactions_count": {
          "posted": 22,
          "pending": 1
        }
    },
    "connection_id": "111111111111111111",
    "created_at": "2020-08-05T05:28:28Z",
    "updated_at": "2020-08-05T05:28:28Z"
}

List

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

Parameters

connection_id

string

The id of the connection whose attempts are to be fetched

from_id

string, optional

The id of the account which the list starts with

customer_id

string, optional

The id of the customer containing the accounts, required unless connection_id parameter is sent. It will be ignored if connection_id is present

from_id

string, optional

The id of the account which the list starts with

customer_id

string, optional

The id of the customer containing the accounts, required unless connection_id parameter is sent. It will be ignored if connection_id is present

Possible Errors

URL

https://www.saltedge.com/api/v5/accounts?connection_id={connection.id}

https://www.saltedge.com/api/v5//accounts

Method

GET

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/accounts?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/accounts

Sample Response

{
  "data": [
    {
      "id": "333333333333333333",
      "name": "Fake account 1",
      "nature": "card",
      "balance": 2007.2,
      "currency_code": "EUR",
      "extra": {
        "client_name": "Fake name"
      },
      "connection_id": "111111111111111111",
      "created_at": "2020-08-05T04:28:28Z",
      "updated_at": "2020-08-05T04:28:28Z"
    },
    {
      "id": "333333333333333334",
      "name": "Fake account 2",
      "nature": "account",
      "balance": 2012.7,
      "currency_code": "USD",
      "extra": {
        "cards": [
          "1234....5678",
          "*8765"
        ],
        "transactions_count": {
          "posted": 22,
          "pending": 1
        }
      },
      "connection_id": "111111111111111111",
      "created_at": "2020-08-05T05:28:28Z",
      "updated_at": "2020-08-05T05:28:28Z"
    }
  ],
  "meta" : {
    "next_id": "333333333333333335",
    "next_page": "/api/v5/accounts?connection_id=111111111111111111&from_id=333333333333333335"
  }
}
{
  "data": [
    {
      "id": "333333333333333333",
      "name": "Fake account 1",
      "nature": "card",
      "balance": 2007.2,
      "currency_code": "EUR",
      "extra": {
        "client_name": "Fake name"
      },
      "created_at": "2020-08-05T04:28:28Z",
      "updated_at": "2020-08-05T04:28:28Z"
    },
    {
      "id": "333333333333333334",
      "name": "Fake account 2",
      "nature": "account",
      "balance": 2012.7,
      "currency_code": "USD",
      "extra": {
        "cards": [
          "1234....5678",
          "*8765"
        ],
        "transactions_count": {
          "posted": 22,
          "pending": 1
        }
      },
      "connection_id": "111111111111111111",
      "created_at": "2020-08-05T05:28:28Z",
      "updated_at": "2020-08-05T05:28:28Z"
    }
  ],
  "meta" : {
    "next_id": "333333333333333335",
    "next_page": "/api/v5/accounts?from_id=333333333333333335"
  }
}

Nature

An account can be of one of the several types, as described by the nature field:

Payment account natures:

  • account
  • card
  • checking
  • credit_card
  • debit_card
  • ewallet
  • loan
  • mortgage
  • savings

Non-payment account natures:

  • bonus
  • insurance
  • investment
  • credit

Although these values do not affect neither the account’s behavior, nor its properties, they might provide some additional information to the end-user.

Extra

The following represents the object you get in the extra field of the account object.

You may or may not have all of the fields listed below.

General accounts extra fields:

account_name

string

Changeable name of the account

account_number

string

Internal bank account number

assets

array of objects

Array of crypto codes and their amounts assigned to investment account

available_amount

decimal

Available amount in the account’s currency

blocked_amount

decimal

The amount currently blocked in account’s currency

card_type

string

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

cards

array of strings

List of masked card numbers linked to the account

client_name

string

Account client owner

closing_balance

decimal

Account balance at the end of an accounting period

credit_limit

decimal

Maximum amount of money that is allowed to be spent in account’s currency

current_date

date

Date of provider statement generation (applicable to banks)

current_time

datetime

Time of provider statement generation (applicable to banks)

expiry_date

date

Card expiry date

iban

string

Account’s IBAN

interest_rate

decimal

Interest rate of the account as percentage value

next_payment_amount

decimal

Next payment amount for loans or credits

next_payment_date

date

Next payment date for loans or credits

open_date

date

The date when any type of account/card was opened

opening_balance

decimal

Account balance that is brought forward from the end of one accounting period to the beginning of a new accounting period

partial

boolean

Account transactions were not imported or imported partially because of some internal error on the provider’s side

sort_code

string

Routing number(US)/BSB code(Australia)/sort code(UK)

statement_cut_date

date

Date when current statement becomes previous one

status

string

Shows whether the account is active or inactive

swift

string

Account SWIFT code

total_payment_amount

decimal

Total payment amount for loans or credits

transactions_count

object

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

payment_type

string

Account payment method

cashback_amount

decimal

Accumulated CashBack / Cash Benefit

monthly_total_payment

decimal

The amount a borrower was paid for a month

minimum_payment

decimal

The lowest amount you can pay on your credit card to avoid penalties

account_name

string

Changeable name of the account

account_number

string

Internal bank account number

assets

array of objects

Array of crypto codes and their amounts assigned to investment account

available_amount

decimal

Available amount in the account’s currency

blocked_amount

decimal

The amount currently blocked in account’s currency

card_type

string

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

cards

array of strings

List of masked card numbers linked to the account

client_name

string

Account client owner

closing_balance

decimal

Account balance at the end of an accounting period

credit_limit

decimal

Maximum amount of money that is allowed to be spent in account’s currency

current_date

date

Date of provider statement generation (applicable to banks)

current_time

datetime

Time of provider statement generation (applicable to banks)

expiry_date

date

Card expiry date

iban

string

Account’s IBAN

interest_rate

decimal

Interest rate of the account as percentage value

next_payment_amount

decimal

Next payment amount for loans or credits

next_payment_date

date

Next payment date for loans or credits

open_date

date

The date when any type of account/card was opened

opening_balance

decimal

Account balance that is brought forward from the end of one accounting period to the beginning of a new accounting period

partial

boolean

Account transactions were not imported or imported partially because of some internal error on the provider’s side

sort_code

string

Routing number(US)/BSB code(Australia)/sort code(UK)

statement_cut_date

date

Date when current statement becomes previous one

status

string

Shows whether the account is active or inactive

swift

string

Account SWIFT code

total_payment_amount

decimal

Total payment amount for loans or credits

transactions_count

object

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

payment_type

string

Account payment method

cashback_amount

decimal

Accumulated CashBack / Cash Benefit

monthly_total_payment

decimal

The amount a borrower was paid for a month

minimum_payment

decimal

The lowest amount you can pay on your credit card to avoid penalties

Investment accounts extra fields:

investment_amount

decimal

Total invested amount

unit_price

decimal

Price per unit (used with units)

units

decimal

Amount of units owned (used with unit_price)

indicative_unit_price

decimal

Indicative price per unit (used with units)

interest_income

decimal

Amount of interest income/profit

interest_amount

decimal

Interest amount in currency

profit_amount

decimal

Amount of profit/loss of investment account

profit_rate

decimal

Investment account rate of profit/loss as percentage value

asset_class

string

Class of investment asset

product_type

string

Investment product type

total_unit_value

decimal

Total units value of fund holding

fund_holdings

object

Fund holdings list with own values such as (investment_percentage, balance, bid_price, value, value_date, total_quantity, available_quantity, actual_price, actual_value)

investment_amount

decimal

Total invested amount

unit_price

decimal

Price per unit (used with units)

units

decimal

Amount of units owned (used with unit_price)

indicative_unit_price

decimal

Indicative price per unit (used with units)

interest_income

decimal

Amount of interest income/profit

interest_amount

decimal

Interest amount in currency

profit_amount

decimal

Amount of profit/loss of investment account

profit_rate

decimal

Investment account rate of profit/loss as percentage value

asset_class

string

Class of investment asset

product_type

string

Investment product type

total_unit_value

decimal

Total units value of fund holding

fund_holdings

object

Fund holdings list with own values such as (investment_percentage, balance, bid_price, value, value_date, total_quantity, available_quantity, actual_price, actual_value)

Insurance accounts extra fields:

premium_frequency

string

Frequency of premium payments

policy_status

string

Current policy status

life_assured_name

string

Name of the person who is assured

premium_amount

decimal

Premium amount to be paid

single_premium_amount

decimal

Single premium amount to be paid

financial_consultant

string

Financial consultant name

total_reversionary_bonus

decimal

Reversionary bonus accumulated amount

gross_surrender

decimal

Current Gross Surrender value

guaranteed_gross_surrender

decimal

Guaranteed Gross Surrender value

reversionary_bonus_cash_value

decimal

Cash value of reversionary bonus

owned_policy_amount

decimal

Amount currently own on policy

policy_loan_limit

decimal

Maximum amount of additional Policy Loan

policy_converted_to_paid_up

decimal

New assured sum if Policy is converted to paid up

paid_up_conversion_reversionary_bonus

decimal

Reversionary bonus amount after Policy to paid up conversion

policy_components

object

Policy components with own values such as (status, amount_assured, amount_premium, start_date, expiry_date, premium_expiry_date, assured_name)

premium_frequency

string

Frequency of premium payments

policy_status

string

Current policy status

life_assured_name

string

Name of the person who is assured

premium_amount

decimal

Premium amount to be paid

single_premium_amount

decimal

Single premium amount to be paid

financial_consultant

string

Financial consultant name

total_reversionary_bonus

decimal

Reversionary bonus accumulated amount

gross_surrender

decimal

Current Gross Surrender value

guaranteed_gross_surrender

decimal

Guaranteed Gross Surrender value

reversionary_bonus_cash_value

decimal

Cash value of reversionary bonus

owned_policy_amount

decimal

Amount currently own on policy

policy_loan_limit

decimal

Maximum amount of additional Policy Loan

policy_converted_to_paid_up

decimal

New assured sum if Policy is converted to paid up

paid_up_conversion_reversionary_bonus

decimal

Reversionary bonus amount after Policy to paid up conversion

policy_components

object

Policy components with own values such as (status, amount_assured, amount_premium, start_date, expiry_date, premium_expiry_date, assured_name)

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 connection’s accounts, and are imported from one of the providers.

Category

Account Information API uses an algorithm for the automatic categorization of transactions. Thus, when importing a connection, all the transactions corresponding to the connection will be assigned to one of the categories. We also expose an API route for your applications to improve the categorization process based on your end-users’ behavior.

Duplication

Although we import most of the data from the providers thoroughly checking the transactions for duplicates, the providers might change the format of some data, causing us to return transactions that have different data, but are duplicates to your end-users. You can use the duplicate action in order to let us know about a duplicate so that we can take immediate actions.

Attributes

id

string

Id of the transaction

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

string

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

string

The id of the account the transaction belongs to

created_at

datetime

Time and date when the transaction was imported

updated_at

datetime

The last time when the transaction’s attributes (duplicated flag set, category learned applied) were changed by the client

id

string

Id of the transaction

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

string

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

string

The id of the account the transaction belongs to

created_at

datetime

Time and date when the transaction was imported

updated_at

datetime

The last time when the transaction’s attributes (duplicated flag set, category learned applied) were changed by the client

Sample object

{
    "id": "444444444444444444",
    "duplicated": false,
    "mode": "normal",
    "status": "posted",
    "made_on": "2020-05-03",
    "amount": -200.0,
    "currency_code": "USD",
    "description": "Money spent on company advertising",
    "category": "advertising",
    "extra": {
      "merchant_id": "b3e8ec2349df872072c051e0c...",
      "original_amount": -3974.60,
      "original_currency_code": "CZK",
      "posting_date": "2020-05-07",
      "time": "23:56:12"
    },
    "account_id": "333333333333333333",
    "created_at": "2020-08-03T07:28:28Z",
    "updated_at": "2020-08-04T07:28:28Z"
}

List

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

Parameters

connection_id

string, required

The id of the connection

account_id

string, optional

The id of the account

from_id

string, optional

The id of the transaction which the list starts with

account_id

string, optional

The id of the account

from_id

string, optional

The id of the transaction which the list starts with

All of the optional parameters of the transaction list can be combined in any possible manner.

Possible Errors

URL

https://www.saltedge.com/api/v5/transactions?connection_id={connection.id}&account_id={account.id}

https://www.saltedge.com/api/v5/transactions?account_id={account.id}

Method

GET

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/transactions?connection_id=111111111111111111&account_id=333333333333333333
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/transactions?account_id=333333333333333333

Sample response

{
  "data": [
    {
      "id": "444444444444444444",
      "duplicated": false,
      "mode": "normal",
      "status": "posted",
      "made_on": "2020-05-03",
      "amount": -200.0,
      "currency_code": "USD",
      "description": "test transaction",
      "category": "advertising",
      "extra": {
        "original_amount": -3974.60,
        "original_currency_code": "CZK",
        "posting_date": "2020-05-07",
        "time": "23:56:12"
      },
      "account_id": "333333333333333333",
      "created_at": "2020-08-03T07:28:28Z",
      "updated_at": "2020-08-04T07:28:28Z"
    },
    {
      "id": "444444444444444445",
      "duplicated": false,
      "mode": "normal",
      "status": "posted",
      "made_on": "2020-05-03",
      "amount": 50.0,
      "currency_code": "USD",
      "description": "business expense",
      "category": "business_services",
      "extra": {
        "original_amount": 993.90,
        "original_currency_code": "CZK",
        "posting_date": "2020-05-06",
        "time": "12:16:25"
      },
      "account_id": "333333333333333333",
      "created_at": "2020-08-03T07:28:28Z",
      "updated_at": "2020-08-04T07:28:28Z"
    }
  ],
  "meta" : {
    "next_id": "444444444444444446",
    "next_page": "/api/v5/transactions/?connection_id=111111111111111111&account_id=333333333333333333&from_id=444444444444444446"
  }
}
  "data": [
    {
      "id": "444444444444444444",
      "duplicated": false,
      "mode": "normal",
      "status": "posted",
      "made_on": "2020-05-03",
      "amount": -200.0,
      "currency_code": "USD",
      "description": "test transaction",
      "category": "advertising",
      "extra": {
        "original_amount": -3974.60,
        "original_currency_code": "CZK",
        "posting_date": "2020-05-07",
        "time": "23:56:12"
      },
      "account_id": "333333333333333333",
      "created_at": "2020-08-03T07:28:28Z",
      "updated_at": "2020-08-04T07:28:28Z"
    },
    {
      "id": "444444444444444445",
      "duplicated": false,
      "mode": "normal",
      "status": "posted",
      "made_on": "2020-05-03",
      "amount": 50.0,
      "currency_code": "USD",
      "description": "business expense",
      "category": "business_services",
      "extra": {
        "original_amount": 993.90,
        "original_currency_code": "CZK",
        "posting_date": "2020-05-06",
        "time": "12:16:25"
      },
      "account_id": "333333333333333333",
      "created_at": "2020-08-03T07:28:28Z",
      "updated_at": "2020-08-04T07:28:28Z"
    }
  ],
  "meta" : {
    "next_id": "444444444444444446",
    "next_page": "/api/v5/transactions/?account_id=333333333333333333&from_id=444444444444444446"
  }
}

List duplicates

You can see the list of the duplicated transactions of an account.

Parameters

connection_id

string, required

The id of the connection

account_id

string, optional

The id of the account

from_id

string, optional

The id of the transaction which the list starts with

account_id

string, optional

The id of the account

from_id

string, optional

The id of the transaction which the list starts with

All of the optional parameters of the transaction list can be combined in any possible manner.

Possible Errors

URL

https://www.saltedge.com/api/v5/transactions/duplicates?connection_id={connection.id}&account_id={account.id}

https://www.saltedge.com/api/v5/transactions/duplicates&account_id=333333333333333333

Method

GET

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/transactions/duplicates?connection_id=111111111111111111&account_id=333333333333333333
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/transactions/duplicates?account_id=333333333333333333

Sample response

{
  "data": [
    {
      "id": "444444444444444444",
      "duplicated": true,
      "mode": "normal",
      "status": "posted",
      "made_on": "2020-05-03",
      "amount": -200.0,
      "currency_code": "USD",
      "description": "test transaction",
      "category": "advertising",
      "extra": {
        "original_amount": -3974.60,
        "original_currency_code": "CZK",
        "posting_date": "2020-05-07",
        "time": "23:56:12"
      },
      "account_id": "333333333333333333",
      "created_at": "2020-08-03T07:28:28Z",
      "updated_at": "2020-08-04T07:28:28Z"
    },
    {
      "id": "444444444444444445",
      "duplicated": true,
      "mode": "normal",
      "status": "posted",
      "made_on": "2020-05-03",
      "amount": 50.0,
      "currency_code": "USD",
      "description": "business expense",
      "category": "business_services",
      "extra": {
        "original_amount": 993.90,
        "original_currency_code": "CZK",
        "posting_date": "2020-05-06",
        "time": "12:16:25"
      },
      "account_id": "333333333333333333",
      "created_at": "2020-08-03T07:28:28Z",
      "updated_at": "2020-08-04T07:28:28Z"
    }
  ],
  "meta" : {
    "next_id": "444444444444444446",
    "next_page": "/api/v5/transactions/?connection_id=111111111111111111&account_id=333333333333333333&from_id=444444444444444446"
  }
}
{
  "data": [
    {
      "id": "444444444444444444",
      "duplicated": true,
      "mode": "normal",
      "status": "posted",
      "made_on": "2020-05-03",
      "amount": -200.0,
      "currency_code": "USD",
      "description": "test transaction",
      "category": "advertising",
      "extra": {
        "original_amount": -3974.60,
        "original_currency_code": "CZK",
        "posting_date": "2020-05-07",
        "time": "23:56:12"
      },
      "account_id": "333333333333333333",
      "created_at": "2020-08-03T07:28:28Z",
      "updated_at": "2020-08-04T07:28:28Z"
    },
    {
      "id": "444444444444444445",
      "duplicated": true,
      "mode": "normal",
      "status": "posted",
      "made_on": "2020-05-03",
      "amount": 50.0,
      "currency_code": "USD",
      "description": "business expense",
      "category": "business_services",
      "extra": {
        "original_amount": 993.90,
        "original_currency_code": "CZK",
        "posting_date": "2020-05-06",
        "time": "12:16:25"
      },
      "account_id": "333333333333333333",
      "created_at": "2020-08-03T07:28:28Z",
      "updated_at": "2020-08-04T07:28:28Z"
    }
  ],
  "meta" : {
    "next_id": "444444444444444446",
    "next_page": "/api/v5/transactions/?account_id=333333333333333333&from_id=444444444444444446"
  }
}

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 connection is refreshed or reconnected, the existing pending transactions will be removed. Later on, a pending transaction may be either added again as pending (though with a different id), or added as posted, or never appear again (for example, in case it was not confirmed on the bank’s end).

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

connection_id

string, required

The id of the connection

account_id

string, optional

The id of the account

from_id

string, optional

The id of the transaction which the list starts with

account_id

string, optional

The id of the account

from_id

string, optional

The id of the transaction which the list starts with

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

Possible Errors

URL

https://www.saltedge.com/api/v5/transactions/pending?connection_id={connection.id}&account_id={account.id}

https://www.saltedge.com/api/v5/transactions/pending?account_id={account.id}

Method

GET

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/transactions/pending?connection_id=111111111111111111&account_id=333333333333333333
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/transactions/pending?account_id=333333333333333333

Sample response

{
  "data": [
    {
      "id": "444444444444444444",
      "duplicated": false,
      "mode": "normal",
      "status": "pending",
      "made_on": "2020-05-03",
      "amount": -200.0,
      "currency_code": "USD",
      "description": "ads expense",
      "category": "advertising",
      "extra": {
        "original_amount": -3974.60,
        "original_currency_code": "CZK",
        "posting_date": "2020-05-07",
        "time": "23:56:12"
      },
      "account_id": "333333333333333333",
      "created_at": "2020-08-03T07:28:28Z",
      "updated_at": "2020-08-04T07:28:28Z"
    }
  ],
  "meta" : {
    "next_id": "444444444444444445",
    "next_page": "/api/v5/transactions/pending?connection_id=111111111111111111&account_id=333333333333333333&from_id=444444444444444445"
  }
}
{
  "data": [
    {
      "id": "444444444444444444",
      "duplicated": false,
      "mode": "normal",
      "status": "pending",
      "made_on": "2020-05-03",
      "amount": -200.0,
      "currency_code": "USD",
      "description": "ads expense",
      "category": "advertising",
      "extra": {
        "original_amount": -3974.60,
        "original_currency_code": "CZK",
        "posting_date": "2020-05-07",
        "time": "23:56:12"
      },
      "account_id": "333333333333333333",
      "created_at": "2020-08-03T07:28:28Z",
      "updated_at": "2020-08-04T07:28:28Z"
    }
  ],
  "meta" : {
    "next_id": "444444444444444445",
    "next_page": "/api/v5/transactions/pending?account_id=333333333333333333&from_id=444444444444444445"
  }
}

Duplicate

Mark a list of transactions as duplicated.

Parameters

customer_id

string, required

The id of the customer

transaction_ids

array of string, required

The array of transactions ids

transaction_ids

array of string, required

The array of transactions ids

Possible Errors

URL

https://www.saltedge.com/api/v5/transactions/duplicate

https://www.saltedge.com/api/v5/transactions/duplicate

Method

PUT

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"customer_id\": \"$CUSTOMER_ID\", \
                \"transaction_ids\": [ \
                  \"444444444444444444\", \
                  \"444444444444444445\" \
                ] \
              } \
            }" \
        https://www.saltedge.com/api/v5/transactions/duplicate
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"transaction_ids\": [ \
                  \"444444444444444444\", \
                  \"444444444444444445\" \
                ] \
              } \
            }" \
        https://www.saltedge.com/api/v5/transactions/duplicate

Sample response

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

Unduplicate

Remove the duplicated flag from a list of transactions.

Parameters

customer_id

string, required

The id of the customer

transaction_ids

array of string, required

The array of transactions ids

transaction_ids

array of string, required

The array of transactions ids

Possible Errors

URL

https://www.saltedge.com/api/v5/transactions/unduplicate

https://www.saltedge.com/api/v5/transactions/unduplicate

Method

PUT

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"customer_id\": \"$CUSTOMER_ID\", \
                \"transaction_ids\": [ \
                  \"444444444444444444\", \
                  \"444444444444444445\" \
                ] \
              } \
            }" \
        https://www.saltedge.com/api/v5/transactions/unduplicate
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X PUT \
        -d "{ \
              \"data\": { \
                \"transaction_ids\": [ \
                  \"444444444444444444\", \
                  \"444444444444444445\" \
                ] \
              } \
            }" \
        https://www.saltedge.com/api/v5/transactions/unduplicate

Sample Response

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

Remove

Remove transactions older than a specified period.

Parameters

customer_id

string, required

The id of the customer

account_id

string, required

The id of the account

keep_days

integer, required

The amount of days for which the transactions will be kept. Transactions older than that will be irreversibly removed. If value is 0, then all transactions will be removed.

account_id

string, required

The id of the account

keep_days

integer, required

The amount of days for which the transactions will be kept. Transactions older than that will be irreversibly removed. If value is 0, then all transactions will be removed.

Possible Errors

URL

https://www.saltedge.com/api/v5/transactions

https://www.saltedge.com/api/v5/transactions

Method

DELETE

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X DELETE \
        -d "{ \
              \"data\": { \
                \"customer_id\": \"$CUSTOMER_ID\", \
                \"account_id\": \"333333333333333333\", \
                \"keep_days\": 90 \
              } \
            }" \
        https://www.saltedge.com/api/v5/transactions
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X DELETE \
        -d "{ \
              \"data\": { \
                \"account_id\": \"333333333333333333\", \
                \"keep_days\": 90 \
              } \
            }" \
        https://www.saltedge.com/api/v5/transactions

Sample response

{
  "data": {
    "cleanup_started": true
  }
}

Extra

The following represents the object you get in the extra field of the transaction object.

You may or may not have all of the fields listed below.

account_balance_snapshot

decimal

Balance of the account at the moment of the attempt when the transaction was imported

account_number

string

Number of the account the transaction belongs to

additional

string

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

asset_amount

decimal

Original transaction amount in asset units

asset_code

string

Asset common used abbreviation (Ex.: BTC - Bitcoin, XAU - Gold etc.)

categorization_confidence

float

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

check_number

string

Payee’s transaction check number

closing_balance

decimal

Account balance after the transaction was imported

constant_code

string

Payment reference for cashless domestic payments (transfers)

convert

boolean

Whether the transaction amount was converted using exchange rates or not

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

id

string

Transaction’s identifier on the bank’s end (do not confuse it with Salt Edge transaction id)

information

string

Information about the transaction

mcc

string

The transaction’s Merchant Category Code

merchant_id

string

Merchant’s identifier

opening_balance

decimal

Account balance before the transaction was imported

installment_debt_amount

decimal

Amount of installment transactions group

original_amount

decimal

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

original_category

string

The original category of the transaction

original_currency_code

string

Native currency of the transaction (comes with original_amount)

original_subcategory

string

The original subcategory of the transaction

payee

string

To whom the money was paid

payee_information

string

Additional payee information

payer

string

Who paid the money

payer_information

string

Additional payer information

possible_duplicate

boolean

Is set to true if current transaction duplicates amount, made_on and currency_code of any transaction parsed in previous attempt

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

record_number

string

Bank record number

specific_code

string

Additional identification information for cashless domestic payments (transfers)

tags

array of strings

The original tags of the transaction

time

time

Time when the transaction was made

transfer_account_name

string

Name of the linked account

type

string

Transaction type

unit_price

decimal

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

units

decimal

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

variable_code

string

Identifies the tax subject to the tax office, used for domestic payments (transfers)

account_balance_snapshot

decimal

Balance of the account at the moment of the attempt when the transaction was imported

account_number

string

Number of the account the transaction belongs to

additional

string

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

asset_amount

decimal

Original transaction amount in asset units

asset_code

string

Asset common used abbreviation (Ex.: BTC - Bitcoin, XAU - Gold etc.)

categorization_confidence

float

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

check_number

string

Payee’s transaction check number

closing_balance

decimal

Account balance after the transaction was imported

constant_code

string

Payment reference for cashless domestic payments (transfers)

convert

boolean

Whether the transaction amount was converted using exchange rates or not

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

id

string

Transaction’s identifier on the bank’s end (do not confuse it with Salt Edge transaction id)

information

string

Information about the transaction

mcc

string

The transaction’s Merchant Category Code

merchant_id

string

Merchant’s identifier

opening_balance

decimal

Account balance before the transaction was imported

installment_debt_amount

decimal

Amount of installment transactions group

original_amount

decimal

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

original_category

string

The original category of the transaction

original_currency_code

string

Native currency of the transaction (comes with original_amount)

original_subcategory

string

The original subcategory of the transaction

payee

string

To whom the money was paid

payee_information

string

Additional payee information

payer

string

Who paid the money

payer_information

string

Additional payer information

possible_duplicate

boolean

Is set to true if current transaction duplicates amount, made_on and currency_code of any transaction parsed in previous attempt

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

record_number

string

Bank record number

specific_code

string

Additional identification information for cashless domestic payments (transfers)

tags

array of strings

The original tags of the transaction

time

time

Time when the transaction was made

transfer_account_name

string

Name of the linked account

type

string

Transaction type

unit_price

decimal

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

units

decimal

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

variable_code

string

Identifies the tax subject to the tax office, used for domestic payments (transfers)

Show Holder Info

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

Attributes

connection_id

string

The id of the connection whose holder info are to be fetched

names

array

Account holder’s name(s)

emails

array

Account holder’s email(s)

phone_numbers

array

Account holder’s phone number(s)

addresses

array of objects

Account holder’s address(es)

names

array

Account holder’s name(s)

emails

array

Account holder’s email(s)

phone_numbers

array

Account holder’s phone number(s)

addresses

array of objects

Account holder’s 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)

Possible Errors

URL

https://www.saltedge.com/api/v5/holder_info?connection_id={connection.id}

https://www.saltedge.com/api/v5/holder_info

Method

GET

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/holder_info?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/holder_info

Sample Response

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

Transaction Categorization

Salt Edge API automatically categorizes all the transactions. Thus, when importing a connection, all the transactions corresponding to the connection will be assigned to one of the categories.

There are 2 types of categories: personal categories and business categories, which help to categorize transactions, made by physical persons or legal entities.

The categories are represented as strings. They are structured as parent and child categories, which can be identified by the tree structure sent in the Listing categories request.

How to use

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

We also expose an API route for your applications to provide the possibility for your users to update categories for their transactions with certain description.

List

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

The API can return multiple categories for any operation, each having its meaning. The categories are 2 types:

Possible Errors

URL

https://www.saltedge.com/api/v5/categories

https://www.saltedge.com/api/v5/categories

Method

GET

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/categories
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/categories

Sample Response

{
  "data": {
    "business": {
      "equipment_and_materials": [
        "electronics",
        "software",
        "supplies_and_furniture",
        "raw_materials",
        "consumer_goods"
      ],
      "financials": [
        "dividends",
        "donations",
        "interest",
        "fees",
        "fines",
        "loans"
      ],
      "human_resources": [
        "wages",
        "bonus",
        "employee_benefits",
        "education_and_trainings",
        "staff_outsourcing",
        "travel",
        "entertainment",
        "meals"
      ],
      "income": [
        "investments",
        "sales",
        "returns",
        "prepayments"
      ],
      "insurance": [
        "business_insurance",
        "liability_insurance",
        "health_insurance",
        "equipment_insurance",
        "vehicle_insurance",
        "professional_insurance"
      ],
      "real_estate": [
        "office_rent",
        "mortgage",
        "construction_and_repair"
      ],
      "services": [
        "contractors",
        "accounting_and_auditing",
        "legal",
        "consulting",
        "storage",
        "marketing_and_media",
        "online_subscriptions",
        "it_services",
        "cleaning"
      ],
      "taxes": [
        "vat",
        "federal_taxes",
        "property_taxes",
        "income_taxes",
        "duty_taxes",
        "tax_return",
        "payroll_taxes"
      ],
      "transport": [
        "shipping",
        "leasing",
        "gas_and_fuel",
        "taxi",
        "service_and_parts"
      ],
      "uncategorized": [],
      "utilities": [
        "internet",
        "phone",
        "water",
        "gas",
        "electricity"
      ]
    },
    "personal": {
      "auto_and_transport": [
        "car_rental",
        "gas_and_fuel",
        "parking",
        "public_transportation",
        "service_and_parts",
        "taxi"
      ],
      "bills_and_utilities": [
        "internet",
        "phone",
        "television",
        "utilities"
      ],
      "business_services": [
        "advertising",
        "office_supplies",
        "shipping"
      ],
      "education": [
        "books_and_supplies",
        "student_loan",
        "tuition"
      ],
      "entertainment": [
        "amusement",
        "arts",
        "games",
        "movies_and_music",
        "newspapers_and_magazines"
      ],
      "fees_and_charges": [
        "provider_fee",
        "loans",
        "service_fee",
        "taxes"
      ],
      "food_and_dining": [
        "alcohol_and_bars",
        "cafes_and_restaurants",
        "groceries"
      ],
      "gifts_and_donations": [
        "charity",
        "gifts"
      ],
      "health_and_fitness": [
        "doctor",
        "personal_care",
        "pharmacy",
        "sports",
        "wellness"
      ],
      "home": [
        "home_improvement",
        "home_services",
        "home_supplies",
        "mortgage",
        "rent"
      ],
      "income": [
        "bonus",
        "investment_income",
        "paycheck"
      ],
      "insurance": [
        "car_insurance",
        "health_insurance",
        "life_insurance",
        "property_insurance"
      ],
      "kids": [
        "allowance",
        "babysitter_and_daycare",
        "baby_supplies",
        "child_support",
        "kids_activities",
        "toys"
      ],
      "pets": [
        "pet_food_and_supplies",
        "pet_grooming",
        "veterinary"
      ],
      "shopping": [
        "clothing",
        "electronics_and_software",
        "sporting_goods"
      ],
      "transfer": [],
      "travel": [
        "hotel",
        "transportation",
        "vacation"
      ],
      "uncategorized": []
    }
  }
}

Learn

Your customers can change the category of some of their transactions, thus improving the categorization accuracy.

The custom category will be applicable only for the customer’s new transactions, which have similar description.

The customer can change the category to the one already existing in categories list - in this case custom category is located in transaction extra as customer_category_code.

The customer can set his own category - in this case a custom category is located in the transaction extra as customer_category_name.

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

Request body

The request body is an object wrapped in the data field. The data object must contain transactions field, which is an array with transactions objects. Each transaction object must contain customer_id, id (the id of the transaction) and category_code.

Post body

customer_id

string, required

The id of the customer received from customer create. This field is optional for ‘app’ authentication.

id

required

The id of the transaction

category_code

required

The new category code of the transaction

immediate

boolean optional

Defaults to false.

If sent as false, the learning threshold of the categorizer will be applied - the categorizer will store information about the user’s custom category for the transaction with this description. In case the categorizer identifies that the category has been updated 3 times for the transaction with this description, further transactions with this description will be automatically categorized for this user under this category.

If sent as true, the learning threshold of the categorizer will be ignored and further transactions with the same description will be classified under the category chosen by the user.

id

required

The id of the transaction

category_code

required

The new category code of the transaction

immediate

boolean optional

Defaults to false.

If sent as false, the learning threshold of the categorizer will be applied - the categorizer will store information about the user’s custom category for the transaction with this description. In case the categorizer identifies that the category has been updated 3 times for the transaction with this description, further transactions with this description will be automatically categorized for this user under this category.

If sent as true, the learning threshold of the categorizer will be ignored and further transactions with the same description will be classified under the category chosen by the user.

Possible Errors

URL

https://www.saltedge.com/api/v5/categories/learn

https://www.saltedge.com/api/v5/categories/learn

Method

POST

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"customer_id\": \"$CUSTOMER_ID\", \
                \"transactions\": [ \
                  { \
                    \"id\": \"444444444444444444\", \
                    \"category_code\": \"paycheck\", \
                    \"immediate\": true \
                  }, \
                  { \
                    \"id\": \"444444444444444445\", \
                    \"category_code\": \"car_rental\", \
                    \"immediate\": false \
                  } \
                ] \
              } \
            }" \
        https://www.saltedge.com/api/v5/categories/learn
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"transactions\": [ \
                  { \
                    \"id\": \"444444444444444444\", \
                    \"category_code\": \"paycheck\", \
                    \"immediate\": true \
                  }, \
                  { \
                    \"id\": \"444444444444444445\", \
                    \"category_code\": \"car_rental\", \
                    \"immediate\": false \
                  } \
                ] \
              } \
            }" \
        https://www.saltedge.com/api/v5/categories/learn

Sample Response

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

Merchant Identification

A merchant represents a company that sells goods or provides services to a customer.

Identification

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

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

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

How to use

Show

To fetch the name and additional info, available for identified merchants, pass the desired merchant_ids in an array to route https://www.saltedge.com/api/v5/merchants.

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

Sometimes, in transaction’s descriptional fields, can be presented additional information about the merchant, such as: shop number, or address of sale point, with city, post code and street numbers. In this case, it’s possible to identify the exact place where the customer’s transaction was made. If we find a point of sale, corresponding to the transaction from our database, we can return more granular information with contact and address details, including geo-coordinates.

The API accepts batches of at most 100 objects.

Attributes

id

string

The id of the merchant

names

array of objects

Merchant names that are used to name a company, corporation, brand name, franchise name or any other entity who is participating in the customer’s transaction
Possible values are: name, transliterated_name, alternative_name, brand, operator

address

object

Merchant address may include the next location parameters: city, transliterated_city, state, street, transliterated_street, country_code, post_code, coordinates and extra data associated with the address, such as building_name, shop_number and so on

contact

array of objects

Contact information via which the merchant can be accessed, eg. via website, phone or social media
Possible values are: email, viber, phone, fax, website, facebook, twitter, google_plus, linkedin, instagram, skype, vk, flickr, youtube

id

string

The id of the merchant

names

array of objects

Merchant names that are used to name a company, corporation, brand name, franchise name or any other entity who is participating in the customer’s transaction
Possible values are: name, transliterated_name, alternative_name, brand, operator

address

object

Merchant address may include the next location parameters: city, transliterated_city, state, street, transliterated_street, country_code, post_code, coordinates and extra data associated with the address, such as building_name, shop_number and so on

contact

array of objects

Contact information via which the merchant can be accessed, eg. via website, phone or social media
Possible values are: email, viber, phone, fax, website, facebook, twitter, google_plus, linkedin, instagram, skype, vk, flickr, youtube

Possible Errors

URL

https://www.saltedge.com/api/v5/merchants

https://www.saltedge.com/api/v5/merchants

Method

POST

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": [ \
                \"f6dabf8bb3e1cbc7cce2f4571...\", \
                \"ae316a83508ecaa8897e90321...\" \
              ] \
            }" \
        https://www.saltedge.com/api/v5/merchants
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -X POST \
        -d "{ \
              \"data\": [ \
                \"f6dabf8bb3e1cbc7cce2f4571...\", \
                \"ae316a83508ecaa8897e90321...\" \
              ] \
            }" \
        https://www.saltedge.com/api/v5/merchants

Sample Response

{
  "data": [
    {
      "id": "f6dabf8bb3e1cbc7cce2f4571...",
      "names": [
        {
          "mode": "name",
          "value": "Amazon"
        },
        {
          "mode": "transliterated_name",
          "value": "amazon"
        }
      ],
      "contact": [
        {
          "mode": "website",
          "value": "www.amazon.com"
        }
      ],
      "address": {
        "country_code": "GB"
      }
    },
    {
      "id": "ae316a83508ecaa8897e90321...",
      "names": [
        {
          "mode": "name",
          "value": "Boots"
        },
        {
          "mode": "transliterated_name",
          "value": "boots"
        },
        {
          "mode": "operator",
          "value": "Boots Uk Limited"
        }
      ],
      "contact": [
        {
          "mode": "phone",
          "value": "+44 20 73818651"
        },
        {
          "mode": "website",
          "value": "http://www.boots.com/stores/773-london-fulham-palace-road-w6-9pa"
        }
      ],
      "address": {
        "country_code": "GB",
        "city": "London",
        "transliterated_city": "london",
        "street": "Fulham Palace Road",
        "transliterated_street": "fulham palace road",
        "post_code": "W6 9Pa",
        "coordinates": {
          "latitude": "51.48467107",
          "longitude": "-0.220126411"
        },
        "extra": {
          "building_number": "198-200",
          "shop_number": "773",
          "type_of_shop": "Chemist"
        }
      }
    }
  ]
}

Financial Insights

Financial Insights represents a report based on all the activities of a single customer. It analyzes all the customer’s connections to the connected providers for a selected period of time.

Attributes

id

string

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

customer_id

string

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

customer_identifier

string

Unique customer identifier

status

string

Current report’s status. Possible values are: initialized, calculating, success, failed

connection_ids

array of strings

Ids of connections included in the report

currency_code

string

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

from_date

date

The date from which the data in the report are included

to_date

date

The date to which the data in the report are included

report_types

array of strings

Types of reports. Possible values are: balance, expense, income, savings

data

object

Contains Report Object

created_at

datetime

The date when the report was created

updated_at

datetime

The date when the report was last updated

id

string

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

customer_id

string

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

customer_identifier

string

Unique customer identifier

status

string

Current report’s status. Possible values are: initialized, calculating, success, failed

connection_ids

array of strings

Ids of connections included in the report

currency_code

string

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

from_date

date

The date from which the data in the report are included

to_date

date

The date to which the data in the report are included

report_types

array of strings

Types of reports. Possible values are: balance, expense, income, savings

data

object

Contains Report Object

created_at

datetime

The date when the report was created

updated_at

datetime

The date when the report was last updated

Sample object

{
  "id": "999999999999999999",
  "customer_id": "222222222222222222",
  "customer_identifier": "test@mail.com",
  "status": "success",
  "connection_ids": [
      "111111111111111111"
  ],
  "currency_code": "USD",
  "from_date": "2020-05-05",
  "to_date": "2020-08-04",
  "report_types": [
      "balance",
      "expense",
      "income",
      "savings"
  ],
  "data": {
      ...
  },
  "created_at": "2020-08-05T04:28:28Z",
  "updated_at": "2020-08-05T04:28:28Z"
}

Create

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

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

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

Parameters

customer_id

string, required

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

report_types

array of strings, required

Types of reports that can be generated, possible values balance, expense, income, savings
Note: at least one report type should be requested

currency_code

string, required

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

from_date

date, required

The date from which the data in the report will be included

to_date

date, required

The date to which the data in the report will be included

customer_id

string, required

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

report_types

array of strings, required

Types of reports that can be generated, possible values balance, expense, income, savings
Note: at least one report type should be requested

currency_code

string, required

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

from_date

date, required

The date from which the data in the report will be included

to_date

date, required

The date to which the data in the report will be included

Possible Errors

URL

https://www.saltedge.com/api/v5/reports

https://www.saltedge.com/api/v5/reports

Method

POST

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"customer_id\": \"$CUSTOMER_ID\", \
                \"report_types\": [ \
                  \"balance\", \
                  \"expense\", \
                  \"income\", \
                  \"savings\" \
                ], \
                \"currency_code\": \"USD\", \
                \"from_date\": \"2020-05-01\", \
                \"to_date\": \"2020-07-01\" \
              } \
            }" \
        https://www.saltedge.com/api/v5/reports
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"report_types\": [ \
                  \"balance\", \
                  \"expense\", \
                  \"income\", \
                  \"savings\" \
                ], \
                \"currency_code\": \"USD\", \
                \"from_date\": \"2020-05-01\", \
                \"to_date\": \"2020-07-01\" \
              } \
            }" \
        https://www.saltedge.com/api/v5/reports

Sample response

{
  "data": {
    "id": "999999999999999999",
    "customer_id": "222222222222222222",
    "customer_identifier": "test@email.com",
    "connection_ids": [
      "111111111111111111",
      "111111111111111112",
      "111111111111111113"
    ],
    "status": "initialized",
    "created_at": "2020-08-05T07:28:28Z"
  }
}

Show

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

Shows the generated report with all the details.

Parameters

report_id

string, required

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

report_id

string, required

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

Possible Errors

URL

https://www.saltedge.com/api/v5/reports/{report.id}

https://www.saltedge.com/api/v5/reports/{report.id}

Method

POST

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/reports/999999999999999999
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/reports/999999999999999999

Sample response

{
  "data": {
      "id": "999999999999999999",
      "customer_id": "222222222222222222",
      "customer_identifier": "test@mail.com",
      "status": "success",
      "connection_ids": [
          "111111111111111111"
      ],
      "currency_code": "USD",
      "from_date": "2020-05-05",
      "to_date": "2020-08-04",
      "report_types": [
          "balance",
          "expense",
          "income",
          "savings"
      ],
      "data": {
          "result": {
            "accounts": [
              {
                "id": "333333333333333333",
                "start_date": "2020-05-05",
                "end_date": "2020-08-04",
                "whole_months_count": 3,
                "days_count": 90,
                "monthly_average_transactions_count": {
                  "total": 10,
                  "income": 2,
                  "expense": 8
                },
                "balance": {
                  ...
                },
                "income": {
                  ...
                },
                "expense": {
                  ...
                },
                "savings": {
                  ...
                }
              }
            ],
            "accounts_summary": {
              "start_date": "2020-05-05",
              "transactions_count": 90,
              "whole_months_count": 3,
              "days_count": 107,
              "monthly_average_transactions_count": {
                "total": 10,
                "income": 2,
                "expense": 8
            },
            "balance": {
              ...
            },
            "income": {
              ...
            },
            "expense": {
              ...
            },
            "savings": {
              ...
            }
          },
          "status": "success",
          "to_date": "2020-08-04",
          "from_date": "2020-05-05",
          "report_id": 999999999999999999,
          "connections": [
              {
                  "id": "111111111111111111",
                  "accounts": [
                      {
                          "id": "333333333333333333",
                          "name": "Oauth account 1",
                          "nature": "card",
                          "balance": "2171.9658356",
                          "transactions": {
                              "start_date": "2020-07-05",
                              "end_date": "2020-08-04",
                              "first_id": "444444444444444441",
                              "last_id": "444444444444444489",
                              "count": 38
                          },
                          "original_balance": 2004.4,
                          "original_currency_code": "EUR"
                      }
                  ],
                  "client_name": "Client",
                  "customer_id": 222222222222222222,
                  "holder_info": null,
                  "provider_code": "fakebank_oauth_xf",
                  "provider_name": "Fake Bank OAuth"
              }
          ],
          "customer_id": 222222222222222222,
          "report_types": [
              "balance",
              "expense",
              "income",
              "savings"
          ],
          "currency_code": "USD",
          "connection_ids": [
              "111111111111111111"
          ],
          "exchange_rates": {
              "BTC": "7082.3464052288",
              "EUR": "1.083599",
              "GBP": "1.2341013636"
          }
      },
      "created_at": "2020-08-05T04:28:28Z",
      "updated_at": "2020-08-05T04:28:28Z"
  }
}

List

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

Returns all the general available reports for a customer.

Parameters

customer_id

string, optional

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

from_id

string, optional

The id of the report which the list starts with

customer_id

string, optional

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

from_id

string, optional

The id of the report which the list starts with

Possible Errors

URL

https://www.saltedge.com/api/v5/reports?customer_id={customer.id}

https://www.saltedge.com/api/v5/reports?customer_id={customer.id}

Method

POST

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/reports?customer_id=$CUSTOMER_ID
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/reports?customer_id=$CUSTOMER_ID

Sample response

{
  "data": [
        {
            "id": "999999999999999990",
            "customer_id": "222222222222222222",
            "customer_identifier": "test@email.com",
            "connection_ids": [
                "111111111111111111",
                "111111111111111112"
            ],
            "status": "success",
            "created_at": "2020-08-04T07:28:28Z",
        },
        {
            "id": "999999999999999991",
            "customer_id": "222222222222222222",
            "customer_identifier": "test@email.com",
            "connection_ids": [
                "111111111111111113",
                "111111111111111114"
            ],
            "status": "success",
            "created_at": "2020-08-04T07:28:28Z",
        }
    ],
    "meta": {
        "next_id": "999999999999999992",
        "next_page": "/api/v5/reports/?from_id=999999999999999992"
    }
  }
}

Remove

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

Removes a report.

Parameters

report_id

string, required

The id of the general report

report_id

string, required

The id of the general report

Possible Errors

URL

https://www.saltedge.com/api/v5/reports/{report.id}

https://www.saltedge.com/api/v5/reports/{report.id}

Method

DELETE

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X DELETE \
        https://www.saltedge.com/api/v5/reports/999999999999999999
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X DELETE \
        https://www.saltedge.com/api/v5/reports/999999999999999999

Sample response

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

Report Object

result

string

Show child attributes

Report result

customer_id

integer

The id of the customer

connection_ids

array of strings

Ids of Connections included in report

connections

array of objects

Show child attributes

Information related to connections included in report

currency_code

string

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

exchange_rates

object

A list of exchange rates at the time of report creation

report_id

integer

The id of the generated report

report_types

array of strings

Types of generated reports. Possible values are: balance, expense, income, savings

status

string

Current report’s status. Possible values are: initialized, calculating, success, failed

from_date

date

The date from which the data in the report are included

to_date

date

The date to which the data in the report are included

result

string

Show child attributes

Report result

customer_id

integer

The id of the customer

connection_ids

array of strings

Ids of Connections included in report

connections

array of objects

Show child attributes

Information related to connections included in report

currency_code

string

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

exchange_rates

object

A list of exchange rates at the time of report creation

report_id

integer

The id of the generated report

report_types

array of strings

Types of generated reports. Possible values are: balance, expense, income, savings

status

string

Current report’s status. Possible values are: initialized, calculating, success, failed

from_date

date

The date from which the data in the report are included

to_date

date

The date to which the data in the report are included

Sample object

{
  "result": {
    "accounts": [
      {
        "id": "333333333333333333",
        "name": "Oauth account 1",
        "nature": "card",
        "connection_id": "111111111111111111"
        "start_date": 2020-05-05,
        "end_date": 2020-08-04,
        "whole_months_count": 3,
        "days_count": 90,
        "monthly_average_transactions_count": {
          "total": 10,
          "income": 2,
          "expense": 8
        },
        "balance": { ... },
        "income": { ... },
        "expense": { ... },
        "savings": { ... }
      }
    ],
    "accounts_summary": {
      "start_date": 2020-05-05,
      "end_date": 2020-08-04,
      "transactions_count": 90,
      "whole_months_count": 3,
      "days_count": 107,
      "monthly_average_transactions_count": {
        "total": 10,
        "income": 2,
        "expense": 8
      },
      "balance": { ...  },
      "income": { ... },
      "expense": { ... },
      "savings": { ... }
    }
  },
  "customer_id": 222222222222222222,
  "connection_ids": [
      "111111111111111111"
  ],
  "connections": [
    {
      "id": "111111111111111111",
      "accounts": [
        {
          "id": "333333333333333333",
          "name": "Oauth account 1",
          "nature": "card",
          "balance": "2171.9658356",
          "transactions": {
            "start_date": 2020-05-05,
            "end_date": 2020-08-04,
            "first_id": "444444444444444441",
            "last_id": "444444444444444489",
            "count": 38
          },
          "original_balance": 2004.4,
          "original_currency_code": "EUR"
        }
      ],
      "client_name": "Client",
      "customer_id": 222222222222222222,
      "holder_info": null,
      "provider_code": "fakebank_oauth_xf",
      "provider_name": "Fake Bank OAuth"
    }
  ],
  "currency_code": "USD",
  "exchange_rates": {
    "BTC": "7082.3464052288",
    "EUR": "1.083599",
    "GBP": "1.2341013636"
  },
  "report_id": 999999999999999999,
  "report_types": [
      "balance",
      "expense",
      "income",
      "savings"
  ],
  "status": "success",
  "from_date": "2020-05-05",
  "to_date": "2020-08-04"
}

Balance Report Object

start_date_amount

decimal

Opening balance. The balance before the first transaction was imported

end_date_amount

decimal

Closing balance. The balance after the last transaction was imported

minimum

decimal

The minimum balance registered for the report’s date range

maximum

decimal

The maximum balance registered for the report’s date range

average

object

Show child attributes

Average balance

forecasted_average

object

Show child attributes

Forecasted average balance

start_date_amount

decimal

Opening balance. The balance before the first transaction was imported

end_date_amount

decimal

Closing balance. The balance after the last transaction was imported

minimum

decimal

The minimum balance registered for the report’s date range

maximum

decimal

The maximum balance registered for the report’s date range

average

object

Show child attributes

Average balance

forecasted_average

object

Show child attributes

Forecasted average balance

Sample object

{
  "start_date_amount": 1000.0,
  "end_date_amount": 6485.0,
  "minimum": 1340.0,
  "maximum": 8945.0,
  "average": {
    "daily": {
      "amount": 4573.3,
      "start_date" : "2020-01-01",
      "end_date": "2020-05-10"
    },
    "monthly": {
      "amount": 4573.3,
      "start_date" : "2020-01-01",
      "end_date": "2020-04-30"
    },
    "quarterly": {
      "amount": 4481.5,
      "start_date" : "2020-01-01",
      "end_date": "2020-03-31"
    },
    "annual": {
      "amount": null,
      "start_date": null,
      "end_date": null
    },
    "minimum_monthly": {
      "amount": 3330.0,
      "start_date" : "2020-01-01",
      "end_date": "2020-04-30"
    },
    "maximum_monthly": {
      "amount": 6085.0
      "start_date" : "2020-01-01",
      "end_date": "2020-04-30"
    },
  },
  "forecasted_average": {
    "next_month": 7517.54,
    "next_quarter": null,
    "next_year": null
  }
}

Income/Expense Report Object

start_date

date

The date of the first income/expense transaction

end_date

date

The date of the last income/expense transaction

transactions_count

integer

Number of income/expense transactions

last_year_amount

decimal

Total amount of income/expense for the last fully covered 12 months

total

decimal

Total amount of income/expense per the calculated period

total_per_month

array of objects

Show child attributes

Total amount of income/expense per each month

average

object

Show child attributes

Average amount of income/expense

forecasted_average

object

Show child attributes

Forecasted average amount of income/expense

streams

object

Show child attributes

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

start_date

date

The date of the first income/expense transaction

end_date

date

The date of the last income/expense transaction

transactions_count

integer

Number of income/expense transactions

last_year_amount

decimal

Total amount of income/expense for the last fully covered 12 months

total

decimal

Total amount of income/expense per the calculated period

total_per_month

array of objects

Show child attributes

Total amount of income/expense per each month

average

object

Show child attributes

Average amount of income/expense

forecasted_average

object

Show child attributes

Forecasted average amount of income/expense

streams

object

Show child attributes

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

Sample object

{
  "start_date": "2020-01-01",
  "end_date": "2020-04-03",
  "transactions_count": 7,
  "last_year_amount": null,
  "total": 16962.5,
  "total_per_month": [
    {
      "year": 2020,
      "month": 3,
      "is_whole_month": true,
      "amount": 4100.0
    },
    {
      "year": 2020,
      "month": 4,
      "is_whole_month": false,
      "amount": 4100.0
    }
  ],
  "average": {
    "monthly": 4275.0,
    "quarterly": null,
    "annual": null
  },
  "forecasted_average": {
    "next_month": 4636.0,
    "next_quarter": null,
    "next_year": null
  },
  "streams": {
    "regular_amount": 16950.0,
    "irregular_amount": 12.5,
    "count": {
      "regular": 2,
      "irregular": 1,
      "maximum_overlapping": 2
    },
    "regular":[
      {
        "transactions_count": 3,
        "transaction_ids": ["11", "31", "51"],
        "start_date": "2020-01-01",
        "end_date": "2020-04-03",
        "amount": {
          "total": 16450.0,
          "average": 4112.5,
          "median": 4100.0,
          "stdev": 103.08
        },
        "frequency": "monthly",
        "days_count": 31,
        "category_code": "paycheck",
        "description": "IT SOLUTIONS INC PAYROLL",
        "merchant": {
           "name": "Solutions Inc",
           "email": null,
           "phone": null,
           "address": "GB",
           "website": null
        }
      }
    ],
    "irregular": {
      "transactions_count": 2,
      "transaction_ids": ["2", "7"],
      "start_date": "2020-01-01",
      "end_date": "2020-04-03"
    }
  }
}

Savings Report Object

per_month

array of objects

Show child attributes

Information related to net savings per each month

average

object

Show child attributes

Average savings

forecasted_average

object

Show child attributes

Forecasted average savings

runway

decimal

Provides an estimate (number of months) on how long the customer’s current balance will be sufficient until they run out of money. The customer’s income and expenses are taken into account.
Note: This indicator is calculated only for cases when the customer has positive current balance and the amount of their expenses exceeds the amount of their income

expense_to_savings_rate

decimal

Shows whether the customer increases or loses his capital. Taking into account the customer’s income and expenses, this indicator shows the number of months during which the customer’s savings are either increased or reduced by an amount equal to 1 month of expenses.
Note: This indicator is calculated only for cases when the customer has both savings/dissavings and expenses

stress_runway

decimal

Provides an estimate (number of months) on how long the customer’s current balance will be sufficient to cover their regular expenses in case they unexpectedly stops receiving income.
Note: This indicator is calculated for all cases, except the one, when the customer has no expenses

income_stability

decimal

Average weighted stability of income from all the sources
Note: it is close to 1, if customer has stable income

income_regularity

decimal

Average weighted regularity of income from all the sources
Note: it is close to 1, if customer has regular income

income_to_expense_rate

decimal

Ratio of average monthly income to average monthly expense

per_month

array of objects

Show child attributes

Information related to net savings per each month

average

object

Show child attributes

Average savings

forecasted_average

object

Show child attributes

Forecasted average savings

runway

decimal

Provides an estimate (number of months) on how long the customer’s current balance will be sufficient until they run out of money. The customer’s income and expenses are taken into account.
Note: This indicator is calculated only for cases when the customer has positive current balance and the amount of their expenses exceeds the amount of their income

expense_to_savings_rate

decimal

Shows whether the customer increases or loses his capital. Taking into account the customer’s income and expenses, this indicator shows the number of months during which the customer’s savings are either increased or reduced by an amount equal to 1 month of expenses.
Note: This indicator is calculated only for cases when the customer has both savings/dissavings and expenses

stress_runway

decimal

Provides an estimate (number of months) on how long the customer’s current balance will be sufficient to cover their regular expenses in case they unexpectedly stops receiving income.
Note: This indicator is calculated for all cases, except the one, when the customer has no expenses

income_stability

decimal

Average weighted stability of income from all the sources
Note: it is close to 1, if customer has stable income

income_regularity

decimal

Average weighted regularity of income from all the sources
Note: it is close to 1, if customer has regular income

income_to_expense_rate

decimal

Ratio of average monthly income to average monthly expense

Sample object

{
  "per_month": [
    {
      "year": 2020,
      "month": 1,
      "is_whole_month": true,
      "amount": 340.0
    },
    {
      "year": 2020,
      "month": 2,
      "is_whole_month": true,
      "amount": 1915.0
    }
  ],
  "average": {
    "monthly": 1281.66,
    "quarterly": null,
    "annual": null
  },
  "forecasted_average": {
    "next_month": 2014.29,
    "next_quarter": null,
    "next_year": null
  },
  "runway": null,
  "expense_to_savings_rate": 3.553,
  "stress_runway": 3.508,
  "income_stability": 0.960,
  "income_regularity": 0.925,
  "income_to_expense_rate": 1.281
}

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.

List

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

Possible Errors

URL

https://www.saltedge.com/api/v5/currencies

https://www.saltedge.com/api/v5/currencies

Method

GET

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/currencies
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/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"
      },
    ...
    ]
}

Assets

Some of our providers support investment accounts. Such accounts may have an extra assets key which contains an array of assets. Each asset consists of:

  • code - asset common used abbreviation (Ex.: BTC - Bitcoin, XAU - Gold etc.)
  • amount - total amount of owned assets

Balance for these investment accounts is a sum of all assets amounts converted to selected currency.

Sample Object

{
    "id": "333333333333333333",
    "name": "bittrex trading",
    "nature": "investment",
    "balance": 4084.7,
    "currency_code": "USD",
    "extra": {
        "assets": [
          { "code": "BTC",  "amount": 0.25555165 },
          { "code": "ETH",  "amount": 12.456 },
          { "code": "USDT", "amount": 3054.57935489 },
          { "code": "XLM",  "amount": 0.0 }
        ],
        "transactions_count": {
          "posted": 22,
          "pending": 1
        }
    },
    "connection_id": "111111111111111111",
    "created_at": "2020-08-05T05:28:28Z",
    "updated_at": "2020-08-05T05:28:28Z"
}

List

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

Possible Errors

URL

https://www.saltedge.com/api/v5/assets

https://www.saltedge.com/api/v5/assets

Method

GET

Authentication

Sample request

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/assets
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Customer-secret: $CUSTOMER_SECRET" \
        -X GET \
        https://www.saltedge.com/api/v5/assets

Sample Response

{
  "data": [
    {
        "code": "BSD",
        "name": "BitSend"
    },
    {
        "code": "BSTY",
        "name": "GlobalBoost- Y"
    },
    {
        "code": "BTA",
        "name": "Bata"
    },
    {
        "code": "BTC",
        "name": "Bitcoin"
    },
    {
        "code": "BTCD",
        "name": "BitcoinDark"
    },
    {
        "code": "BTS",
        "name": "BitShares"
    }
    ...
  ]
}

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

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,
    "i