Overview

Salt Edge Partners API aims to provide access to financial information for registered partners as simple as a cURL.

  • Import financial information from PSD2 APIs (Open Banking Standard, NextGenPSD2 Berlin Group, CBI Globe Northbound, Polish API, etc.)
  • Securely import financial information from online banking interfaces of multiple countries;
  • Automatically synchronize accounts and transactions on a daily basis;
  • Automatically enrich financial transactions by categorization and merchant identification;
  • Keep a well-organized and up-to-date list of currency rates.

If you have any questions regarding what can be done with Salt Edge Partners API, feel free to contact us.

Integrations

The Salt Edge platform is easy to integrate. 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 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 - a country where providers located;
  • Provider - a bank or an online payments system;
  • Lead - a verified end-user email associated with Salt Edge Limited customer record;
  • Partner Consent - a permission given to Salt Edge Limited to share fetched data with registered partner;
  • Customer - a customer of the client who is consuming Salt Edge Partners API;
  • Connection - the central entity of the API, representing a connection between a customer’s bank and Salt Edge;
  • Consent - a permission from user to fetch data;
  • Attempt - an attempt which is created when user connects his financial institution;
  • 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;
  • Transaction - a single financial transaction made within an account;
  • Merchant - a merchant;
  • Category - one of the 79 categories assigned to a transaction.
  • Currency - string code is using for 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

This quick start guide will show the easiest path of integration with Partners API: creating a Lead, connecting consent, authenticating in bank interface, fetch financial data on success.

Get invitation

Request an invitation through contact us or our sales team.

Create an account

a. Get an invitation to visit the Sign up page, then generate a secure password to confirm partner account creation.

b. 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 Salt Edge Partners API is authenticated, so before you are able to fetch any data you 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 Public key field blank, before you go LIVE and Signing requests will become mandatory.

Each request to Partners 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 and Sandbox providers to make sure that the application can handle any scenario that might happen with a real data provider (e.g. bank or standard).

Create lead

Before we can create any connections using Salt Edge Partners API, we need to create a Lead. A Lead in Salt Edge Partners API is the verified end-user email of your application.

Result of this request will be a Customer ID and Email.

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

$ export CUSTOMER_ID=111

See lead reference and customers reference for related API endpoints.

URL

https://www.saltedge.com/api/partners/v1/leads

https://www.saltedge.com/api/partners/v1/leads

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\": { \
                \"email\": \"test@email.com\" \
              } \
            }" \
        https://www.saltedge.com/api/partners/v1/leads
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"email\": \"test@email.com\" \
              } \
            }" \
        https://www.saltedge.com/api/partners/v1/leads

Sample response

{
  "data": {
    "email": "test+123@email.com",
    "customer_id": "456"
  }
}

Create lead session

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

To initiate a connection you need to execute a request to create lead session endpoint.

You will receive in response a redirect_url. This is the URL your end-user will visit to create the connection.

See Lead sessions reference for more information and related API endpoints.

URL

https://www.saltedge.com/api/partners/v1/lead_sessions/create

https://www.saltedge.com/api/partners/v1/lead_sessions/create

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\", \
                \"consent\": { \
                  \"from_date\": \"2019-01-01\", \
                  \"period_days\": 90, \
                  \"scopes\": [ \
                    \"account_details\", \
                    \"transactions_details\" \
                  ] \
                }, \
                \"attempt\": { \
                  \"from_date\": \"2019-02-01\", \
                  \"fetch_scopes\": [ \
                    \"accounts\", \
                    \"transactions\" \
                  ] \
                } \
              } \
            }" \
        https://www.saltedge.com/api/partners/v1/lead_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\": { \
                  \"from_date\": \"2019-01-01\", \
                  \"period_days\": 90, \
                  \"scopes\": [ \
                    \"account_details\", \
                    \"transactions_details\" \
                  ] \
                }, \
                \"attempt\": { \
                  \"from_date\": \"2019-02-01\", \
                  \"fetch_scopes\": [ \
                    \"accounts\", \
                    \"transactions\" \
                  ] \
                } \
              } \
            }" \
        https://www.saltedge.com/api/partners/v1/lead_sessions/create

Sample response

{
  "data": {
    "expires_at": "2019-08-19T12:44:00Z",
    "redirect_url": "https://www.saltedge.com/dashboard/connect?invitation_token=GENERATED_TOKEN"
  }
}

Visit redirect url

Initially, all Salt Edge registered partners are in pending statue and only have access to fake and sandbox providers. Let’s connect one of them. Visit the redirect_url from the previous API response and search for “Fake Bank Simple”.

Once selected, we 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 “Connect”.

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 Salt Edge Partners API, a distinct bank connection is called a Connection. Each Salt Edge Partners API Customer can have multiple Connections. When we visited Redirect URL and connected “Fake Bank Simple” we created a Connection associated with 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 1227) to retrieve its accounts.

$ export CONNECTION_ID=1227

See connections reference for more information on Connection endpoints.

Sample Request

URL

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

https://www.saltedge.com/api/partners/v1/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/partners/v1/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/partners/v1/connections?customer_id=$CUSTOMER_ID

Sample Response

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

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 142) to retrieve all transactions for this account.

$ export ACCOUNT_ID=142

Sample Request

URL

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

https://www.saltedge.com/api/partners/v1/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/partners/v1/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/partners/v1/accounts?connection_id=$CONNECTION_ID

Sample Response

{
  "data": [
    {
      "id": "142",
      "name": "Fake account 1",
      "nature": "card",
      "balance": 2007.2,
      "currency_code": "EUR",
      "connection_id": "1227",
      "created_at": "2019-08-19T08:44:00Z",
      "updated_at": "2019-08-19T08:44:00Z",
      "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/partners/v1/transactions?connection_id={connection.id}&account_id={account.id}

https://www.saltedge.com/api/partners/v1/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/partners/v1/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/partners/v1/transactions?connection_id=$CONNECTION_ID&account_id=$ACCOUNT_ID

Sample Response

{
  "data": [
    {
      "id": "987",
      "duplicated": false,
      "mode": "normal",
      "status": "posted",
      "made_on": "2013-05-03",
      "amount": -200.0,
      "currency_code": "USD",
      "description": "test transaction",
      "category": "advertising",
      "account_id": "100",
      "created_at": "2019-08-17T11:44:00Z",
      "updated_at": "2019-08-18T11:44:00Z",
      "extra": {
        "original_amount": -3974.60,
        "original_currency_code": "CZK",
        "posting_date": "2013-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.
  • Since new Salt Edge partners are in pending mode and have access only to fake and sandbox 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 Salt Edge Partners 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

Salt Edge Partners API requires APP_ID and SECRET headers in order to authenticate as partner. If you don’t have an API key created yet, you can you 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 Salt Edge API will be authenticated using your API key.

Before going LIVE

In order to upgrade you partner accounts status to LIVE mode, the following steps should be followed:

  • Please provide Salt Edge account manager with App’s test account to verify Salt Edge Partners API integration;
  • Be sure to provide signature in accordance with the instructions;
  • Your application should be working correctly with all of the fake banks or sandboxes;
  • Your application should not create any duplicated leads (i.e. connecting the same provider with the same verified email);
  • The user should be able to revoke partner consent;
  • The Multi-factor authentication must 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 end-users read and agree to End User License Terms.

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

Callbacks

The most important parts of Salt Edge Partners 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. Applications can also poll Salt Edge Partners 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 Salt Edge Partners 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 port 80/HTTP only in test and pending modes.
Port 443/HTTPS is accepted by all modes.
Also, the callbacks do not follow redirects!

Signature

Signature

In order for the client to identify that the request is coming from Salt Edge Partners API, there is a Signature header in the request.

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 Salt Edge Partners 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":"1234","customer_id":"4321","custom_fields":{}},"meta":{"version":"5","time":"2017-01-03T13:00:28Z"}}

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

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

Success

We send a callback to your application’s success URL whenever any triggered 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 Connect, 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 fetch the full connection data, along with the accounts and transactions at each callback, as some information might change during the fetching process.

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

{
  "data": {
    "connection_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" }
  },
  "meta": {
    "version": "5",
    "time": "2019-08-19T11:44:00.531Z"
  }
}

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": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" },
    "error_class": "InvalidCredentials",
    "error_message": "Invalid credentials."
  },
  "meta": {
    "version": "5",
    "time": "2019-08-19T11:44:00.544Z"
  }
}

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

Additional callbacks

There are three additional callbacks that your app needs to implement in order to use the API-only version of Salt Edge Partners API.

Notify

Salt Edge can inform you about the progress of a connection using Notify callback.

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.

Note that for some of the connections, you might not receive all the stages.

Notify callback will not be triggered for daily attempts.

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

{
  "data": {
    "connection_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" },
    "stage": "start"
  },
  "meta": {
    "version": "5",
    "time": "2019-08-18T11:44:00Z"
  }
}

Destroy

Whenever a connection gets removed, we will send a callback to your application’s destroy URL, if such exists.

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

{
  "data": {
    "connection_id": "123",
    "customer_id": "34445"
  },
  "meta": {
    "version": "5",
    "time": "2013-05-17T14:29:35Z"
  }
}

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": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" },
    "reason": "updated"
  },
  "meta": {
    "version": "5",
    "time": "2019-08-18T11:44:00Z"
  }
}

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 support team to enable holder info for your client account.

Upon enabling the feature you will receive a holder_info field inside 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 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 fake provider.

Sample response (as provider attribute)

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

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

Merchant Identification

Merchant identification is an option that allows getting more information about transaction merchants. This option is country based and currently is available in 13 countries - United Kingdom, Italy, Czech Republic, Australia, Russia, India, Singapore, Romania, Austria, Hungary, Latvia, Germany, Netherlands 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

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

  • on Lead session create, when the connection creation succeeds and only if the merchant is identified, you will receive a merchant_id in the extra field of the transaction;
  • send all the merchant_ids you want to fetch the additional info for, to merchants.

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

User support

Salt Edge has a dedicated page for user support, where user can ask a question, make a suggestion or report a problem related to data coming from Salt Edge connections.

It is also possible for client to prefill provider name by appending provider_code into query string. In this case, the provider will be already preselected.

For example: https://www.saltedge.com/support_requests/new?provider_code=demobank

Errors

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

Error attributes

class
string

the class of the error, one of the listed below

message
string

a message describing the error

documentation_url
string

a link for error documentation

request
object

the body of the request that caused the error

class
string

the class of the error, one of the listed below

message
string

a message describing the error

documentation_url
string

a link for error documentation

request
object

the body of the request that caused the error

Error codes

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

Sample response

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

List

AccountNotFound

An account with the sent account_id could not be found

ActionNotAllowed

The client has no access to the required route

AllAccountsExcluded

You have excluded all the accounts from the 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. 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 the Restricted state. You can find out more about the 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

CredentialsNotMatch

New connection credentials do not match old ones on reconnect

CustomFieldsSizeTooBig

The custom_fields object has more than 1 KB

CustomFieldsFormatInvalid

The custom_fields field is not of type object

DateFormatInvalid

We have received an invalid Date format

DateOutOfRange

Sending a date value that does not fit in admissible range

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 not allowed by client, provider and/or consent

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

Connection cannot be refreshed right now

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 customer denied access to his data from the provider’s page

ProviderDisabled

The accessed provider is disabled

ProviderError

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

ProviderInactive

The accessed provider is inactive at the moment

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 temporary unavailable

PublicKeyNotProvided

The client did not provide the public key in his 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 invalid

ReturnURLTooLong

The return_to URL exceeds 2040 characters

RouteNotFound

The action you are trying to access does not exist

SecretNotProvided

The Secret was not provided in request headers

SignatureNotMatch

The Signature header does not match with the correct one

TooManyRequests

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

TransactionNotFound

A transaction with the sent transaction_id could not be found

ValueOutOfRange

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

WrongClientToken

We have received a wrong combination of customer_id, 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

A partner consent with such id does not exist

AccountNotFound

An account with the sent account_id could not be found

ActionNotAllowed

The client has no access to the required route

AllAccountsExcluded

You have excluded all the accounts from the 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. 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 the Restricted state. You can find out more about the 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

CredentialsNotMatch

New connection credentials do not match old ones on reconnect

CustomFieldsSizeTooBig

The custom_fields object has more than 1 KB

CustomFieldsFormatInvalid

The custom_fields field is not of type object

DateFormatInvalid

We have received an invalid Date format

DateOutOfRange

Sending a date value that does not fit in admissible range

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 not allowed by client, provider and/or consent

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

Connection cannot be refreshed right now

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 customer denied access to his data from the provider’s page

ProviderDisabled

The accessed provider is disabled

ProviderError

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

ProviderInactive

The accessed provider is inactive at the moment

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 temporary unavailable

PublicKeyNotProvided

The client did not provide the public key in his 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 invalid

ReturnURLTooLong

The return_to URL exceeds 2040 characters

RouteNotFound

The action you are trying to access does not exist

SecretNotProvided

The Secret was not provided in request headers

SignatureNotMatch

The Signature header does not match with the correct one

TooManyRequests

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

TransactionNotFound

A transaction with the sent transaction_id could not be found

ValueOutOfRange

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

WrongClientToken

We have received a wrong combination of customer_id, 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

A partner consent with such id does not exist

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

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 Salt Edge Partners 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/partners/v1/countries

https://www.saltedge.com/api/partners/v1/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/partners/v1/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/partners/v1/countries

Sample response

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

Providers

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

Attributes

id
string

provider’s id

code
string

provider’s code

name
string

provider’s name

mode
string

possible values are: oauth, web, api, file

status
string

possible values are: active, inactive, disabled

automatic_fetch
boolean

whether the provider’s 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

instructions on how to connect the bank, in English

home_url
string

the url of the main page of the provider

login_url
string

point of entrance to provider’s login web interface

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
updated_at
datetime
timezone
string

time zone data of capital/major city in a region corresponding to Provider.

max_interactive_delay
integer

delay in seconds before InteractiveAdapterTimeout will happen

optional_interactivity
boolean

provider which supports flipping of interactive and automatic_fetch flags after connect

max_fetch_interval
integer

max period in days that can be fetched form provider 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

id
string

provider’s id

code
string

provider’s code

name
string

provider’s name

mode
string

possible values are: oauth, web, api, file

status
string

possible values are: active, inactive, disabled

automatic_fetch
boolean

whether the provider’s 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

instructions on how to connect the bank, in English

home_url
string

the url of the main page of the provider

login_url
string

point of entrance to provider’s login web interface

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
updated_at
datetime
timezone
string

time zone data of capital/major city in a region corresponding to Provider.

max_interactive_delay
integer

delay in seconds before InteractiveAdapterTimeout will happen

optional_interactivity
boolean

provider which supports flipping of interactive and automatic_fetch flags after connect

max_fetch_interval
integer

max period in days that can be fetched form provider 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

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": "2019-08-09T11:44:00Z",
  "updated_at": "2019-08-14T11:44:00Z",
  "timezone": "Europe/London",
  "max_interactive_delay": 480,
  "optional_interactivity": true,
  "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"]
}

Show

Provider show allows you to inspect the single provider in order to give your users a proper interface to input their credentials. The response will have an array of required_fields and interactive_fields.

Parameters

provider_code
string

provider’s code

provider_code
string

provider’s code

Possible Errors

URL

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

https://www.saltedge.com/api/partners/v1/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/partners/v1/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/partners/v1/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,
    "max_fetch_interval": 60,
    "supported_fetch_scopes": ["accounts", "transactions"],
    "supported_account_natures": ["account", "card"],
    "supported_account_types": ["personal"],
    "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.

Parameters

from_id
string, optional

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

from_date
date, optional

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

country_code
string, optional

filtering providers by country, defaults to null

mode
string, optional

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

include_fake_providers
boolean, optional

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

from_id
string, optional

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

from_date
date, optional

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

country_code
string, optional

filtering providers by country, defaults to null

mode
string, optional

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

include_fake_providers
boolean, optional

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

Possible Errors

URL

https://www.saltedge.com/api/partners/v1/providers

https://www.saltedge.com/api/partners/v1/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/partners/v1/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/partners/v1/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": "2019-08-09T11:44:00Z",
      "updated_at": "2019-08-14T11:44:00Z",
      "timezone": "Europe/London",
      "max_interactive_delay": 480,
      "optional_interactivity": true,
      "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"]
    }
  ],
  "meta": {
    "next_id": null,
    "next_page": null
  }
}

Fake

In order to help 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.

The API supplies a number of fake providers:

  • fakebank_simple_xf - requires a username and 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 connect, 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 a transactions with same made_on, amount, currency_code but different description. On second attempt and later it marks those transaction with extra[:possible_duplicate] flag;
  • fakebank_with_rememberable_credentials_xf - remembers all the answers to secret questions and doesn’t ask them in 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 to select which 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 error with a generic message An error has occurred. Please report this error..

We also supply fake providers:

  • 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 in 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.

Leads

Leads are end-users (PSUs) that can create connections and share data with a partner.

Create

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

Allows to create a lead, thus bypassing the Sign Up stage which requires user input. The response contains the email of the created lead (“salted” with the partner_id to avoid duplication) and the associated customer_id which can be used for creating a lead session.

The lead is created with a one-time password. An email with instructions on how to set their own password and access their Salt Edge Dashboard account will be sent.

Parameters

email
string, required

email address

email
string, required

email address

Possible Errors

URL

https://www.saltedge.com/api/partners/v1/leads

https://www.saltedge.com/api/partners/v1/leads

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\": { \
                \"email\": \"test@email.com\" \
              } \
            }" \
        https://www.saltedge.com/api/partners/v1/leads
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"email\": \"test@email.com\" \
              } \
            }" \
        https://www.saltedge.com/api/partners/v1/leads

Sample response

{
  "data": {
    "email": "test+123@email.com",
    "customer_id": "456"
  }
}

Lead session

Lead session is a temporary object that links the Connect session with new connection object that will be created once the users grants his consent to Salt Edge Partners API to fetch data.

Create

Allows you to create a lead session.

Parameters

customer_id
string, optional

the ID of the customer. If passed, following the redirect_url will allow the customer to continue bypassing the Sign Up/Sign In stage.

consent
object, required

the consent object

attempt
object, optional

the attempt object

allowed_countries
array of strings, optional

the list of countries that will be accessible for the customer to choose from, defaults to EU and EEA region + XF. Full list: AT, BE, BG, CR, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HU, IE, IS, IT, LI, LT, LU, LV, ML, NL, NO, PL, PT, RO, SE, SI, SK, XF.

Example: ['CZ', 'DE']

provider_code
string, optional

the code of the desired provider, defaults to null

skip_provider_select
boolean, optional

whether the provider selection page should be skipped. In order for this to work, besides passing skip_provider_select as true, an OAuth provider’s provider_code should be passed. Defaults to: false

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

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

categorization
string, optional

the type of categorization applied. Possible values: none, personal, business. Default: personal

include_fake_providers
boolean, optional

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

consent
object, required

the consent object

attempt
object, optional

the attempt object

allowed_countries
array of strings, optional

the list of countries that will be accessible for the customer to choose from, defaults to EU and EEA region + XF. Full list: AT, BE, BG, CR, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HU, IE, IS, IT, LI, LT, LU, LV, ML, NL, NO, PL, PT, RO, SE, SI, SK, XF.

Example: ['CZ', 'DE']

provider_code
string, optional

the code of the desired provider, defaults to null

skip_provider_select
boolean, optional

whether the provider selection page should be skipped. In order for this to work, besides passing skip_provider_select as true, an OAuth provider’s provider_code should be passed. Defaults to: false

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

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

categorization
string, optional

the type of categorization applied. Possible values: none, personal, business. Default: personal

include_fake_providers
boolean, optional

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

Possible Errors

URL

https://www.saltedge.com/api/partners/v1/lead_sessions/create

https://www.saltedge.com/api/partners/v1/lead_sessions/create

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\": { \
                \"consent\": { \
                  \"from_date\": \"2019-01-01\", \
                  \"period_days\": 90, \
                  \"scopes\": [ \
                    \"account_details\", \
                    \"transactions_details\" \
                  ] \
                }, \
                \"attempt\": { \
                  \"from_date\": \"2019-02-01\", \
                  \"fetch_scopes\": [ \
                    \"accounts\", \
                    \"transactions\" \
                  ] \
                } \
              } \
            }" \
        https://www.saltedge.com/api/partners/v1/lead_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\": { \
                \"consent\": { \
                  \"from_date\": \"2019-01-01\", \
                  \"period_days\": 90, \
                  \"scopes\": [ \
                    \"account_details\", \
                    \"transactions_details\" \
                  ] \
                }, \
                \"attempt\": { \
                  \"from_date\": \"2019-02-01\", \
                  \"fetch_scopes\": [ \
                    \"accounts\", \
                    \"transactions\" \
                  ] \
                } \
              } \
            }" \
        https://www.saltedge.com/api/partners/v1/lead_sessions/create

Sample response

{
  "data": {
    "expires_at": "2019-08-19T12:44:00Z",
    "redirect_url": "https://www.saltedge.com/dashboard/sign_up?invitation_token=GENERATED_TOKEN"
  }
}

Partner consents

Partner consent is a part of combined consent, shown to the customer that allows Salt Edge to share account, transaction and holder info data with the registered partner, based on the right to data portability enforced by the EU General Data Protection Regulation (GDPR).

Attributes

id
string

the ID of the partner consent

connection_id
string

the ID of the connection

customer_id
string

the ID of the customer

status
string

possible values are: active, revoked

revoked_by
string

entity who revoked the partner consent. Possible values: partner, lead, saltedge

revoked_at
date

when the partner consent was revoked

created_at
date

when the partner consent was created

updated_at
date

when the partner consent was updated

id
string

the ID of the partner consent

connection_id
string

the ID of the connection

customer_id
string

the ID of the customer

status
string

possible values are: active, revoked

revoked_by
string

entity who revoked the partner consent. Possible values: partner, lead, saltedge

revoked_at
date

when the partner consent was revoked

created_at
date

when the partner consent was created

updated_at
date

when the partner consent was updated

List

Returns all the partner consents accessible to your application for certain customer. The partner consents are sorted in ascending order of their ID, so the latest partner 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 partner consents

customer_id
string, optional

the ID of the customer containing the partner consents.
Note: Will be ignored if connection_id is present.

from_id
string, optional

the id from which the next page of partner consents starts

from_id
string, optional

the id from which the next page of partner consents starts

Possible Errors

URL

https://www.saltedge.com/api/partners/v1/partner_consents?connection_id={connection.id}

https://www.saltedge.com/api/partners/v1/partner_consents

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/partners/v1/partner_consents?connection_id=100
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/partners/v1/partner_consents

Sample Response

{
  "data": [
    {
      "id": "41",
      "connection_id": "100",
      "customer_id": "36",
      "status": "active",
      "revoked_by": null,
      "revoked_at": null,
      "created_at": "2019-08-19T08:44:00Z",
      "updated_at": "2019-08-19T08:44:00Z"
    }
  ],
  "meta" : {
    "next_id": "144",
    "next_page": "/api/partners/v1/partner_consents?connection_id=100&from_id=144"
  }
}
{
  "data": [
    {
      "id": "41",
      "connection_id": "100",
      "customer_id": "36",
      "status": "active",
      "revoked_by": null,
      "revoked_at": null,
      "created_at": "2019-08-19T08:44:00Z",
      "updated_at": "2019-08-19T08:44:00Z"
    }
  ],
  "meta" : {
    "next_id": "144",
    "next_page": "/api/partners/v1/partner_consents?from_id=144"
  }
}

Show

Returns the partner consent object.

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.
Note: Will be ignored if connection_id is present.

id
string, required

the id of the consent

id
string, required

the id of the consent

Possible Errors

URL

https://www.saltedge.com/api/partners/v1/partner_consents/{consent.id}?connection_id={connection.id}

https://www.saltedge.com/api/partners/v1/partner_consents/{consent.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/partners/v1/partner_consents/41?connection_id=100
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/partners/v1/partner_consents/41

Sample Response

{
  "data":  {
      "id": "41",
      "connection_id": "100",
      "customer_id": "36",
      "status": "active",
      "revoked_by": null,
      "revoked_at": null,
      "created_at": "2019-08-19T08:44:00Z",
      "updated_at": "2019-08-19T08:44:00Z"
    }
}
{
  "data": {
      "id": "41",
      "connection_id": "100",
      "customer_id": "36",
      "status": "active",
      "revoked_by": null,
      "revoked_at": null,
      "created_at": "2019-08-19T08:44:00Z",
      "updated_at": "2019-08-19T08:44:00Z"
    }
}

Revoke

Partner consent revoke is an action that allows you to revoke a partner consent given by a specific customer.

Attributes

connection_id
string, optional

the ID of the connection containing the consents

customer_id
string, optional

the ID of the customer containing the consents.
Note: Will be ignored if connection_id is present.

id
string, required

the id of the partner consent

id
string, required

the id of the partner consent

Possible Errors

URL

https://www.saltedge.com/api/partners/v1/partner_consents/{consent.id}/revoke?connection_id={connection.id}

https://www.saltedge.com/api/partners/v1/partner_consents/{consent.id}/revoke

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/partners/v1/partner_consents/41/revoke?connection_id=100
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X PUT \
        https://www.saltedge.com/api/partners/v1/partner_consents/41/revoke

Sample Response

{
  "data": {
      "id": "41",
      "connection_id": "100",
      "customer_id": "36",
      "status": "revoked",
      "revoked_by": "partner",
      "revoked_at": "2019-08-19T08:44:00Z",
      "created_at": "2019-08-19T08:44:00Z",
      "updated_at": "2019-08-19T08:44:00Z"
    }
}
{
  "data": {
      "id": "41",
      "connection_id": "100",
      "customer_id": "36",
      "status": "revoked",
      "revoked_by": "partner",
      "revoked_at": "2019-08-19T08:44:00Z",
      "created_at": "2019-08-19T08:44:00Z",
      "updated_at": "2019-08-19T08:44:00Z"
    }
}

Customers

A customer represents a single end-user of the Salt Edge Partners API.

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

You need to store the id returned in the callbacks, which is necessary when listing Connections. We give you the following customer API actions so that the customer will be successfully identified within Salt Edge.

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/partners/v1/customers/{customer.id}

https://www.saltedge.com/api/partners/v1/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/partners/v1/customers/18892
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/partners/v1/customers/18892

Sample Response

{
  "data": {
    "id":         "18892",
    "identifier": "12rv1212f1efxchsdhbgv"
  }
}

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.

Possible Errors

URL

https://www.saltedge.com/api/partners/v1/customers

https://www.saltedge.com/api/partners/v1/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/partners/v1/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/partners/v1/customers

Sample Response

{
  "data": [
    {
      "id":         "123",
      "identifier": "unique_customer_identifier",
    },
    {
      "id":         "124",
      "identifier": "unique_customer_identifier_2",
    }
  ],
  "meta": {
    "next_id": "125",
    "next_page": "/api/partners/v1/customers?from_id=125"
  }
}

Connections

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

Within Salt Edge Partners API, a connection can have one of the following statuses:

  • active - the current set of credentials is valid and allows us to properly fetch the data;
  • inactive - an error appeared while fetching the connection;
  • 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 Salt Edge Partners API.

Attributes

id
string
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
updated_at
datetime
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

last_attempt
object, attempt object

last attempt of this connection

show_consent_confirmation
boolean

whether any consent was given for this login on Salt Edge side

last_consent_id
string

the ID of the last consent

id
string
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
updated_at
datetime
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

last_attempt
object, attempt object

last attempt of this connection

show_consent_confirmation
boolean

whether any consent was given for this login on Salt Edge side

last_consent_id
string

the ID of the last consent

Sample object

{
  "country_code": "XF",
  "created_at": "2019-08-18T11:44:00Z",
  "customer_id": "905",
  "daily_refresh": false,
  "id": "1227",
  "show_consent_confirmation": true,
  "last_consent_id": "102492",
  "last_attempt": {
    "api_mode": "service",
    "api_version": "5",
    "automatic_fetch": true,
    "daily_refresh": false,
    "categorization": "personal",
    "created_at": "2019-08-19T11:44:00Z",
    "customer_last_logged_at": "2019-08-19T08:44:00Z",
    "custom_fields": {},
    "device_type": "desktop",
    "remote_ip": "93.184.216.34",
    "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,
    "success_at": "2019-08-19T11:44:00Z",
    "to_date": null,
    "updated_at": "2019-08-19T11:44:00Z",
    "show_consent_confirmation": true,
    "consent_id": "102492",
    "include_natures": ["account", "card", "bonus"],
    "last_stage": {
      "created_at": "2019-08-19T11:44:00Z",
      "id": "2691802",
      "name": "finish",
      "updated_at": "2019-08-19T11:44:00Z"
    }
  },
  "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": "2019-08-19T11:44:00Z",
  "provider_id": "1234",
  "provider_code": "fakebank_simple_xf",
  "provider_name": "Fakebank Simple",
  "status": "active",
  "updated_at": "2019-08-19T11:44:00Z"
}

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 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 record starting the next page

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 record starting the next page

Possible Errors

URL

https://www.saltedge.com/api/partners/v1/connections

https://www.saltedge.com/api/partners/v1/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/partners/v1/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/partners/v1/connections?customer_id=$CUSTOMER_ID

Sample Response

{ "data":
  [
    {
      "country_code": "XF",
      "created_at": "2019-08-18T11:44:00Z",
      "customer_id": "905",
      "daily_refresh": false,
      "id": "1227",
      "show_consent_confirmation": true,
      "last_consent_id": "102492",
      "last_attempt": {
          "api_mode": "service",
          "api_version": "5",
          "automatic_fetch": true,
          "daily_refresh": false,
          "categorization": "personal",
          "created_at": "2019-08-19T11:04:00Z",
          "customer_last_logged_at": "2019-08-19T08:44:00Z",
          "custom_fields": {},
          "device_type": "desktop",
          "remote_ip": "93.184.216.34",
          "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,
          "success_at": "2019-08-19T11:04:00Z",
          "to_date": null,
          "updated_at": "2019-08-19T11:04:00Z",
          "show_consent_confirmation": true,
          "consent_id": "102492",
          "include_natures": ["account", "card", "bonus"],
          "last_stage": {
            "created_at": "2019-08-19T11:04:00Z",
            "id": "2691802",
            "name": "finish",
            "updated_at": "2019-08-19T11:04:00Z"
          }
      },
      "last_success_at": "2019-08-19T11:04:00Z",
      "provider_id": "1234",
      "provider_code": "fakebank_simple_xf",
      "provider_name": "Fakebank Simple",
      "status": "active",
      "updated_at": "2019-08-19T11:04:00Z"
    }
  ],
  "meta" : {
    "next_id": "1228",
    "next_page": "/api/partners/v1/connections?customer_id=100&from_id=1228"
  }
}

Show

Returns a single connection object.

Possible Errors

URL

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

https://www.saltedge.com/api/partners/v1/connection

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/partners/v1/connections/1227
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/partners/v1/connection

Sample Response

{
  "data": {
    "country_code": "MD",
    "created_at": "2014-10-24T20:09:02Z",
    "customer_id": "905",
    "daily_refresh": false,
    "id": "1227",
    "show_consent_confirmation": true,
    "last_consent_id": "102492",
    "last_attempt": {
      "api_mode": "service",
      "api_version": "5",
      "automatic_fetch": true,
      "daily_refresh": false,
      "categorization": "personal",
      "created_at": "2016-02-02T16:14:53Z",
      "customer_last_logged_at": "2019-08-19T08:44:00Z",
      "custom_fields": {},
      "device_type": "desktop",
      "remote_ip": "93.184.216.34",
      "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,
      "success_at": "2016-02-02T16:16:19Z",
      "to_date": null,
      "updated_at": "2016-02-02T16:16:19Z",
      "show_consent_confirmation": true,
      "consent_id": "102492",
      "include_natures": ["account", "card", "bonus"],
      "last_stage": {
        "created_at": "2016-02-02T16:16:19Z",
        "id": "2691802",
        "name": "finish",
        "updated_at": "2016-02-02T16:16:19Z"
      }
    },
    "last_success_at": "2016-02-02T16:16:19Z",
    "provider_id": "1234",
    "provider_code": "moldindconbank_wb_md",
    "provider_name": "Moldindconbank Web Banking",
    "status": "active",
    "updated_at": "2016-02-04T09:41:23Z"
  }
}
{
  "data": {
    "country_code": "MD",
    "created_at": "2014-10-24T20:09:02Z",
    "customer_id": "905",
    "daily_refresh": false,
    "id": "1227",
    "show_consent_confirmation": true,
    "last_consent_id": "102492",
    "last_attempt": {
      "api_mode": "service",
      "api_version": "5",
      "automatic_fetch": true,
      "daily_refresh": false,
      "categorization": "personal",
      "created_at": "2016-02-02T16:14:53Z",
      "customer_last_logged_at": "2019-08-19T08:44:00Z",
      "custom_fields": {},
      "device_type": "desktop",
      "remote_ip": "93.184.216.34",
      "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,
      "success_at": "2016-02-02T16:16:19Z",
      "to_date": null,
      "updated_at": "2016-02-02T16:16:19Z",
      "show_consent_confirmation": true,
      "consent_id": "102492",
      "include_natures": ["account", "card", "bonus"],
      "last_stage": {
        "created_at": "2016-02-02T16:16:19Z",
        "id": "2691802",
        "name": "finish",
        "updated_at": "2016-02-02T16:16:19Z"
      }
    },
    "last_success_at": "2016-02-02T16:16:19Z",
    "provider_id": "1234",
    "provider_code": "moldindconbank_wb_md",
    "provider_name": "Moldindconbank Web Banking",
    "status": "active",
    "updated_at": "2016-02-04T09:41:23Z"
  }
}

Consents

A consent represents the access to data and the limits of this access agreed on by a customer and is 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
string

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

revoked_at
date

the date when consent was revoked

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
string

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

revoked_at
date

the date when consent was revoked

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 certain customer or 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.
Note: Will be ignored if connection_id is present.

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/partners/v1/consents?connection_id={connection.id}

https://www.saltedge.com/api/partners/v1/consents

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/partners/v1/consents?connection_id=100
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/partners/v1/consents

Sample Response

{
  "data": [
    {
      "id": "41",
      "connection_id": "100",
      "customer_id": "36",
      "scopes": [
        "account_details",
        "transactions_details"
      ],
      "period_days": 60,
      "expires_at": "2019-10-18T08:44:00Z",
      "from_date": "2019-07-19",
      "to_date": null,
      "collected_by": "client",
      "revoked_at": null,
      "revoke_reason": null,
      "created_at": "2019-08-19T08:44:00Z",
      "updated_at": "2019-08-19T08:44:00Z"
    }
  ],
  "meta" : {
    "next_id": "144",
    "next_page": "/api/partners/v1/consents?connection_id=100&from_id=144"
  }
}
{
  "data": [
    {
      "id": "41",
      "scopes": [
        "account_details",
        "transactions_details"
      ],
      "period_days": 60,
      "expires_at": "2019-10-18T08:44:00Z",
      "from_date": "2019-07-19",
      "to_date": null,
      "collected_by": "client",
      "revoked_at": null,
      "revoke_reason": null,
      "created_at": "2019-08-19T08:44:00Z",
      "updated_at": "2019-08-19T08:44:00Z"
    }
  ],
  "meta" : {
    "next_id": "144",
    "next_page": "/api/partners/v1/consents?from_id=144"
  }
}

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/partners/v1/consents/{consent.id}?connection_id={connection.id}

https://www.saltedge.com/api/partners/v1/consents/{consent.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/partners/v1/consents/41?connection_id=100
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/partners/v1/consents/41

Sample Response

{
  "data": {
    "id": "41",
    "connection_id": "100",
    "customer_id": "36",
    "scopes": [
      "account_details",
      "transactions_details"
    ],
    "period_days": 60,
    "expires_at": "2019-10-18T08:44:00Z",
    "from_date": "2019-07-19",
    "to_date": null,
    "collected_by": "client",
    "revoked_at": null,
    "revoke_reason": null,
    "created_at": "2019-08-19T08:44:00Z",
    "updated_at": "2019-08-19T08:44:00Z"
  }
}
{
  "data": {
    "id": "41",
    "scopes": [
      "account_details",
      "transactions_details"
    ],
    "period_days": 60,
    "expires_at": "2019-10-18T08:44:00Z",
    "from_date": "2019-07-19",
    "to_date": null,
    "collected_by": "client",
    "revoked_at": null,
    "revoke_reason": null,
    "created_at": "2019-08-19T08:44:00Z",
    "updated_at": "2019-08-19T08:44:00Z"
  }
}

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']
Note: 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. Default: 3 months ago.
Note: 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 untill. Default: null (limitless).
Note: 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. Default: null (limitless) or provider’s max_consent_days.
Note: 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']
Note: 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. Default: 3 months ago.
Note: 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 untill. Default: null (limitless).
Note: 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. Default: null (limitless) or provider’s max_consent_days.
Note: The allowed value for this parameter must not be higher than the provider’s max_consent_days.

Attempts

The attempt resource 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. Default: personal

created_at
datetime

when the attempt was created

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

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 (2 months)

from_date
date

date from which the data had been fetched

id
string
interactive
boolean

whether the connection related to the attempt is interactive

locale
string

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

partial
boolean

whether the connection was partially fetched

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. Default: personal

created_at
datetime

when the attempt was created

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

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 (2 months)

from_date
date

date from which the data had been fetched

id
string
interactive
boolean

whether the connection related to the attempt is interactive

locale
string

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

partial
boolean

whether the connection was partially fetched

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

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

Sample object

{
  "api_mode": "service",
  "api_version": "5",
  "automatic_fetch": true,
  "categorization": "personal",
  "created_at": "2019-08-19T09:44:01Z",
  "customer_last_logged_at": "2019-08-19T08:44:01Z",
  "custom_fields": {},
  "daily_refresh": false,
  "device_type": "desktop",
  "remote_ip": "93.184.216.34",
  "fail_at": null,
  "fail_error_class": null,
  "fail_message": null,
  "fetch_scopes": ["accounts", "transactions"],
  "finished": true,
  "finished_recent": true,
  "from_date": null,
  "id": "337518",
  "interactive": false,
  "partial": false,
  "success_at": "2019-08-19T10:44:01Z",
  "to_date": null,
  "updated_at": "2019-08-19T10:44:01Z",
  "show_consent_confirmation": true,
  "include_natures": ["account", "card", "bonus"],
  "last_stage": {
    "created_at": "2019-08-19T10:44:01Z",
    "id": "2094640",
    "name": "finish",
    "updated_at": "2019-08-19T10:44:01Z"
  }
}

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
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
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 specific connection.

Parameters

connection_id
string

the ID of the connection whose attempts are to be fetched

URL

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

https://www.saltedge.com/api/partners/v1/attempts

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/partners/v1/attempts?connection_id=47872
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/partners/v1/attempts

Sample response

{
  "data": {
    [
      {
        "api_mode": "service",
        "api_version": "5",
        "automatic_fetch": true,
        "categorization": "personal",
        "created_at": "2019-08-19T09:44:01Z",
        "customer_last_logged_at": "2019-08-19T08:44:01Z",
        "custom_fields": {},
        "device_type": "desktop",
        "daily_refresh": false,
        "remote_ip": "93.184.216.34",
        "fail_at": null,
        "fail_error_class": null,
        "fail_message": null,
        "fetch_scopes": ["accounts", "transactions"],
        "finished": true,
        "finished_recent": true,
        "from_date": null,
        "id": "337518",
        "interactive": false,
        "locale": "en",
        "partial": false,
        "success_at": "2019-08-19T10:44:01Z",
        "to_date": null,
        "updated_at": "2019-08-19T10:44:01Z",
        "show_consent_confirmation": true,
        "include_natures": ["account", "card", "bonus"],
        "last_stage": {
          "created_at": "2019-08-19T10:44:01Z",
          "id": "2094640",
          "name": "finish",
          "updated_at": "2019-08-19T10:44:01Z"
        }
      }
    ]
  },
  "meta": {
    "next_id": "337520",
    "next_page": "/api/partners/v1/attempts?connection_id=47872&from_id=337520"
  }
}
{
  "data": {
    [
      {
        "api_mode": "app",
        "api_version": "5",
        "automatic_fetch": true,
        "categorization": "personal",
        "created_at": "2019-08-19T09:44:01Z",
        "customer_last_logged_at": "2019-08-19T08:44:01Z",
        "custom_fields": {},
        "device_type": "desktop",
        "daily_refresh": false,
        "remote_ip": "93.184.216.34",
        "fail_at": null,
        "fail_error_class": null,
        "fail_message": null,
        "fetch_scopes": ["accounts", "transactions"],
        "finished": true,
        "finished_recent": true,
        "from_date": null,
        "id": "337518",
        "interactive": false,
        "locale": "en",
        "partial": false,
        "success_at": "2019-08-19T10:44:01Z",
        "to_date": null,
        "updated_at": "2019-08-19T10:44:01Z",
        "show_consent_confirmation": true,
        "include_natures": ["account", "card", "bonus"],
        "last_stage": {
          "created_at": "2019-08-19T10:44:01Z",
          "id": "2094640",
          "name": "finish",
          "updated_at": "2019-08-19T10:44:01Z"
        }
      }
    ]
  },
  "meta": {
    "next_id": "337520",
    "next_page": "/api/partners/v1/attempts?from_id=337520"
  }
}

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/partners/v1/attempts/{attempt.id}?connection_id={connection.id}

https://www.saltedge.com/api/partners/v1/attempts/{attempt.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/partners/v1/attempts/340?connection_id=47872
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/partners/v1/attempts/340

Sample response

{
  "data": {
    "api_mode": "service",
    "api_version": "5",
    "automatic_fetch": true,
    "daily_refresh": false,
    "categorization": "personal",
    "created_at": "2019-08-19T09:44:01Z",
    "customer_last_logged_at": "2019-08-19T08:44:01Z",
    "custom_fields": {},
    "device_type": "desktop",
    "remote_ip": "93.184.216.34",
    "fail_at": null,
    "fail_error_class": null,
    "fail_message": null,
    "fetch_scopes": ["accounts", "transactions"],
    "finished": true,
    "finished_recent": true,
    "from_date": null,
    "id": "340",
    "interactive": false,
    "locale": "en",
    "partial": false,
    "success_at": "2019-08-19T10:44:01Z",
    "to_date": null,
    "updated_at": "2019-08-19T10:44:01Z",
    "show_consent_confirmation": true,
    "include_natures": ["account", "card", "bonus"],
    "stages": [
      {
        "created_at": "2019-08-19T09:44:01Z",
        "id": "17676",
        "name": "start",
        "updated_at": "2019-08-19T09:44:01Z"
      },
      {
        "created_at": "2019-08-19T09:54:01Z",
        "id": "17677",
        "name": "connect",
        "updated_at": "2019-08-19T09:54:01Z"
      },
      {
        "created_at": "2019-08-19T10:44:01Z",
        "id": "17681",
        "name": "finish",
        "updated_at": "2019-08-19T10:44:01Z"
      }
    ]
  }
}
{
  "data": {
    "api_mode": "app",
    "api_version": "5",
    "automatic_fetch": true,
    "daily_refresh": false,
    "categorization": "personal",
    "created_at": "2019-08-19T09:44:01Z",
    "customer_last_logged_at": "2019-08-19T08:44:01Z",
    "custom_fields": {},
    "device_type": "desktop",
    "remote_ip": "93.184.216.34",
    "fail_at": null,
    "fail_error_class": null,
    "fail_message": null,
    "fetch_scopes": ["accounts", "transactions"],
    "finished": true,
    "finished_recent": true,
    "from_date": null,
    "id": "340",
    "interactive": false,
    "locale": "en",
    "partial": false,
    "success_at": "2019-08-19T10:44:01Z",
    "to_date": null,
    "updated_at": "2019-08-19T10:44:01Z",
    "show_consent_confirmation": true,
    "include_natures": ["account", "card", "bonus"],
    "stages": [
      {
        "created_at": "2019-08-19T09:44:01Z",
        "id": "17676",
        "name": "start",
        "updated_at": "2019-08-19T09:44:01Z"
      },
      {
        "created_at": "2019-08-19T09:54:01Z",
        "id": "17677",
        "name": "connect",
        "updated_at": "2019-08-19T09:54:01Z"
      },
      {
        "created_at": "2019-08-19T10:44:01Z",
        "id": "17681",
        "name": "finish",
        "updated_at": "2019-08-19T10:44:01Z"
      }
    ]
  }
}

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']. Default: consent scopes.
Note: 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. Default: consent from_date.
Note: 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. Default: null (today).
Note: 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 provider error messages in the ISO 639-1 format. Possible values are: bg, cz, de, en, es, he, hu, it, nl, pl, pt-BR, ro, ru, sk, tr, uk, zh, 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

return_to
string, optional

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

fetch_scopes
array of strings, optional

fetching mode. Possible values: ['accounts'], ['holder_info'], ['accounts', 'holder_info'], ['accounts', 'transactions'], ['accounts', 'holder_info', 'transactions']. Default: consent scopes.
Note: 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. Default: consent from_date.
Note: 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. Default: null (today).
Note: 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 provider error messages in the ISO 639-1 format. Possible values are: bg, cz, de, en, es, he, hu, it, nl, pl, pt-BR, ro, ru, sk, tr, uk, zh, 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

return_to
string, optional

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

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 name(s)

emails
array

account holder email(s)

phone_numbers
array

account holder phone number(s)

addresses
array of objects

account holder address(es)

names
array

account holder name(s)

emails
array

account holder email(s)

phone_numbers
array

account holder phone number(s)

addresses
array of objects

account holder address(es)

Extra

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

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

Possible Errors

URL

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

https://www.saltedge.com/api/partners/v1/holder_info

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/partners/v1/holder_info?connection_id=100
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/partners/v1/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"
      }
    ]
  }
}

Accounts

Any connection can have one or more accounts. The accounts are bound to a currency such that all the transactions within a single account have 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
name
string

the unique name of the account

nature
string

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

balance
decimal

the account’s current balance

currency_code
string

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

extra
object, extra object

extra data associated with the account

connection_id
string

the id of the connection the account belongs to

created_at
datetime
updated_at
datetime
id
string
name
string

the unique name of the account

nature
string

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

balance
decimal

the account’s current balance

currency_code
string

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

extra
object, extra object

extra data associated with the account

connection_id
string

the id of the connection the account belongs to

created_at
datetime
updated_at
datetime

Sample Object

{
    "id": "223",
    "name": "Fake account 2",
    "nature": "account",
    "balance": 2012.7,
    "currency_code": "USD",
    "extra": {
        "cards": [
            "1234....5678",
            "*8765"
        ],
        "transactions_count": {
          "posted": 22,
          "pending": 1
        }
    },
    "connection_id": "123",
    "created_at": "2019-08-19T09:44:01Z",
    "updated_at": "2019-08-19T09:44:01Z"
}

List

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

Parameters

connection_id
string

the ID of the connection whose attempts are to be fetched

from_id
string, optional

the id from which the next page of accounts starts

customer_id
string, optional

the ID of the customer containing the accounts, required unless connection_id parameter is sent.
Note: Will be ignored if connection_id is present.

from_id
string, optional

the id from which the next page of accounts starts

customer_id
string, optional

the ID of the customer containing the accounts, required unless connection_id parameter is sent.
Note: Will be ignored if connection_id is present.

Possible Errors

URL

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

https://www.saltedge.com/api/partners/v1//accounts

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/partners/v1/accounts?connection_id=100
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/partners/v1/accounts

Sample Response

{
  "data": [
    {
      "id": "142",
      "name": "Fake account 1",
      "nature": "card",
      "balance": 2007.2,
      "currency_code": "EUR",
      "extra": {
        "client_name": "Fake name"
      },
      "connection_id": "123",
      "created_at": "2019-08-19T08:44:01Z",
      "updated_at": "2019-08-19T08:44:01Z"
    },
    {
      "id": "143",
      "name": "Fake account 2",
      "nature": "account",
      "balance": 2012.7,
      "currency_code": "USD",
      "extra": {
        "cards": [
          "1234....5678",
          "*8765"
        ],
        "transactions_count": {
          "posted": 22,
          "pending": 1
        }
      },
      "connection_id": "123",
      "created_at": "2019-08-19T09:44:01Z",
      "updated_at": "2019-08-19T09:44:01Z"
    }
  ],
  "meta" : {
    "next_id": "144",
    "next_page": "/api/partners/v1/accounts?connection_id=100&from_id=144"
  }
}
{
  "data": [
    {
      "id": "142",
      "name": "Fake account 1",
      "nature": "card",
      "balance": 2007.2,
      "currency_code": "EUR",
      "extra": {
        "client_name": "Fake name"
      },
      "created_at": "2019-08-19T08:44:01Z",
      "updated_at": "2019-08-19T08:44:01Z"
    },
    {
      "id": "143",
      "name": "Fake account 2",
      "nature": "account",
      "balance": 2012.7,
      "currency_code": "USD",
      "extra": {
        "cards": [
          "1234....5678",
          "*8765"
        ],
        "transactions_count": {
          "posted": 22,
          "pending": 1
        }
      },
      "connection_id": "123",
      "created_at": "2019-08-19T09:44:01Z",
      "updated_at": "2019-08-19T09:44:01Z"
    }
  ],
  "meta" : {
    "next_id": "144",
    "next_page": "/api/partners/v1/accounts?from_id=144"
  }
}

Nature

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

  • account
  • bonus
  • card
  • checking
  • credit
  • credit_card
  • debit_card
  • ewallet
  • insurance
  • investment
  • loan
  • mortgage
  • savings

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. Note: You may or may not have all of the fields listed below.

account_name
string

changeable name of the account

account_number
string

internal bank account number

assets
array of strings

array of crypto codes and their amounts assigned to investment account

available_amount
decimal

available amount in 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

client_name
string

account client owner

closing_balance
decimal

account balance at the end of an accounting period

credit_limit
decimal

credit limit 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 IBAN number

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

card open date

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 bank’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

is the account 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}

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)

account_name
string

changeable name of the account

account_number
string

internal bank account number

assets
array of strings

array of crypto codes and their amounts assigned to investment account

available_amount
decimal

available amount in 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

client_name
string

account client owner

closing_balance
decimal

account balance at the end of an accounting period

credit_limit
decimal

credit limit 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 IBAN number

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

card open date

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 bank’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

is the account 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}

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)

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

Salt Edge Partners API uses an algorithm for automatic categorization of transactions. Thus, when importing a connection, all the transactions corresponding to the connection will be assigned to one of the categories.

Attributes

id
string
mode
string

possible values are: normal, fee, transfer

status
string

possible values are: posted, pending

made_on
date

the date when the transaction was made

amount
decimal

transaction’s amount

currency_code
string

transaction’s currency code

description
text

transaction’s description

category
string

transaction’s category

duplicated
boolean

whether the transaction is duplicated or not

extra
object, extra object

extra data associated with the transaction

account_id
string

the id of the account the transaction belongs to

created_at
datetime
updated_at
datetime
id
string
mode
string

possible values are: normal, fee, transfer

status
string

possible values are: posted, pending

made_on
date

the date when the transaction was made

amount
decimal

transaction’s amount

currency_code
string

transaction’s currency code

description
text

transaction’s description

category
string

transaction’s category

duplicated
boolean

whether the transaction is duplicated or not

extra
object, extra object

extra data associated with the transaction

account_id
string

the id of the account the transaction belongs to

created_at
datetime
updated_at
datetime

Sample object

{
    "id": "987",
    "duplicated": false,
    "mode": "normal",
    "status": "posted",
    "made_on": "2013-05-03",
    "amount": -200.0,
    "currency_code": "USD",
    "description": "Money spent on company advertising",
    "category": "advertising",
    "extra": {
      "merchant_id": "b3e8ec2349df872072c051e0c...",
      "original_amount": -3974.60,
      "original_currency_code": "CZK",
      "posting_date": "2013-05-07",
      "time": "23:56:12"
    },
    "account_id": "100",
    "created_at": "2019-08-17T11:44:01Z",
    "updated_at": "2019-08-18T11:44:01Z"
}

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 from which the next page of transactions starts

account_id
string, optional

the id of the account

from_id
string, optional

the id from which the next page of transactions starts

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

Possible Errors

URL

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

https://www.saltedge.com/api/partners/v1/transactions?account_id={account.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/partners/v1/transactions?connection_id=100&account_id=225
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -H "Connection-secret: $CONNECTION_SECRET" \
        -X GET \
        https://www.saltedge.com/api/partners/v1/transactions?account_id=225

Sample response

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

Pending

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

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

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

Parameters

connection_id
string, required

the id of the connection

account_id
string, optional

the id of the account

from_id
string, optional

the id from which the next page of transactions starts

account_id
string, optional

the id of the account

from_id
string, optional

the id from which the next page of transactions starts

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

Possible Errors

URL

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

https://www.saltedge.com/api/partners/v1/transactions/pending?account_id={account.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/partners/v1/transactions/pending?connection_id=100&account_id=225
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/partners/v1/transactions/pending?account_id=225

Sample response

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

Duplicates

You can see the list of 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 from which the next page of transactions starts

account_id
string, optional

the id of the account

from_id
string, optional

the id from which the next page of transactions starts

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

Possible Errors

URL

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

https://www.saltedge.com/api/partners/v1/transactions/duplicates&account_id=225

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/partners/v1/transactions/duplicates?connection_id=100&account_id=225
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/partners/v1/transactions/duplicates?account_id=225

Sample response

{
  "data": [
    {
      "id": "987",
      "duplicated": true,
      "mode": "normal",
      "status": "posted",
      "made_on": "2013-05-03",
      "amount": -200.0,
      "currency_code": "USD",
      "description": "test transaction",
      "category": "advertising",
      "extra": {
        "original_amount": -3974.60,
        "original_currency_code": "CZK",
        "posting_date": "2013-05-07",
        "time": "23:56:12"
      },
      "account_id": "100",
      "created_at": "2019-08-17T11:44:01Z",
      "updated_at": "2019-08-18T11:44:01Z"
    },
    {
      "id": "988",
      "duplicated": true,
      "mode": "normal",
      "status": "posted",
      "made_on": "2013-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": "2013-05-06",
        "time": "12:16:25"
      },
      "account_id": "100",
      "created_at": "2019-08-17T11:44:01Z",
      "updated_at": "2019-08-18T11:44:01Z"
    }
  ],
  "meta" : {
    "next_id": "990",
    "next_page": "/api/v1/transactions/?connection_id=124&account_id=225&from_id=990"
  }
}
{
  "data": [
    {
      "id": "987",
      "duplicated": true,
      "mode": "normal",
      "status": "posted",
      "made_on": "2013-05-03",
      "amount": -200.0,
      "currency_code": "USD",
      "description": "test transaction",
      "category": "advertising",
      "extra": {
        "original_amount": -3974.60,
        "original_currency_code": "CZK",
        "posting_date": "2013-05-07",
        "time": "23:56:12"
      },
      "account_id": "100",
      "created_at": "2019-08-17T11:44:01Z",
      "updated_at": "2019-08-18T11:44:01Z"
    },
    {
      "id": "988",
      "duplicated": true,
      "mode": "normal",
      "status": "posted",
      "made_on": "2013-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": "2013-05-06",
        "time": "12:16:25"
      },
      "account_id": "100",
      "created_at": "2019-08-17T11:44:01Z",
      "updated_at": "2019-08-18T11:44:01Z"
    }
  ],
  "meta" : {
    "next_id": "990",
    "next_page": "/api/v1/transactions/?account_id=225&from_id=990"
  }
}

Extra

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

account_balance_snapshot
decimal

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

account_number
string

number of the account the transaction belongs to

additional
text

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 transaction

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

possible transaction ID

information
text

information about the transaction

mcc
string

the transaction’s Merchant Category Code

merchant_id
string

merchant identifier

opening_balance
decimal

account balance before transaction

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 money is 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 attempt when the transaction was imported

account_number
string

number of the account the transaction belongs to

additional
text

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 transaction

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

possible transaction ID

information
text

information about the transaction

mcc
string

the transaction’s Merchant Category Code

merchant_id
string

merchant identifier

opening_balance
decimal

account balance before transaction

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 money is 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)

Categories

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

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

List

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

Possible Errors

URL

https://www.saltedge.com/api/partners/v1/categories

https://www.saltedge.com/api/partners/v1/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/partners/v1/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/partners/v1/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": []
    }
  }
}

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/partners/v1/currencies

https://www.saltedge.com/api/partners/v1/currencies

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/partners/v1/currencies
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/partners/v1/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 account nature. 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": "223",
    "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": "123",
    "created_at": "2019-08-19T09:44:01Z",
    "updated_at": "2019-08-19T09:44:01Z"
}

List

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

Possible Errors

URL

https://www.saltedge.com/api/partners/v1/assets

https://www.saltedge.com/api/partners/v1/assets

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/partners/v1/assets
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/partners/v1/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,
    "issued_on": "2014-02-12",
    "fail": false
}

List

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

Parameters

date
optional

date for which currency rates will be retrieved

date
optional

date for which currency rates will be retrieved

Possible Errors

URL

https://www.saltedge.com/api/partners/v1/rates

https://www.saltedge.com/api/partners/v1/rates

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/partners/v1/rates?date=2014-03-21
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/partners/v1/rates?date=2014-03-21

Sample Response

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

Merchants

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

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/partners/v1/merchants.

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

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

Attributes

id
string

merchant id

names
array of objects

merchant names; there are used to name a company, corporation, brand name, franchise name or any other entity who is participated in Customer’s transaction
Possible values for mode field: name, transliterated_name, alternative_name, brand, operator

address
object

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

contact
array of objects

contact information, which makes merchant accessible via website, phone or social media
Possible values for mode field: email, viber, phone, fax, website, facebook, twitter, google_plus, linkedin, instagram, skype, vk, flickr, youtube

id
string

merchant id

names
array of objects

merchant names; there are used to name a company, corporation, brand name, franchise name or any other entity who is participated in Customer’s transaction
Possible values for mode field: name, transliterated_name, alternative_name, brand, operator

address
object

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

contact
array of objects

contact information, which makes merchant accessible via website, phone or social media
Possible values for mode field: email, viber, phone, fax, website, facebook, twitter, google_plus, linkedin, instagram, skype, vk, flickr, youtube

Possible Errors

URL

https://www.saltedge.com/api/partners/v1/merchants

https://www.saltedge.com/api/partners/v1/merchants

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\": [ \
                \"0e81d5f8be1e3e73e4e604a36...\", \
                \"b3e8ec2349df872072c051e0c...\" \
              ] \
            }" \
        https://www.saltedge.com/api/partners/v1/merchants
curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": [ \
                \"0e81d5f8be1e3e73e4e604a36...\", \
                \"b3e8ec2349df872072c051e0c...\" \
              ] \
            }" \
        https://www.saltedge.com/api/partners/v1/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"
        }
      }
    }
  ]
}