Overview

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

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

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

Integrations

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

However, if you think your application could benefit more from 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:

• Client - an application consuming Spectre API;
• Customer - a customer of the client who is consuming Spectre API;
• Provider - a bank or an online payments system;
• Login - the central entity of the API, representing a connection between a customer’s bank and Salt Edge;
• Attempt - an attempt which is created when user connects his financial institution;
• Account - one of the accounts associated with a login. 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;
• Category - one of the 79 categories assigned to a transaction.

Following the guides

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

Quick start

Here are some steps to get you started.

Create an account

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

b. Confirm your Email.

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

Create api keys

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

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

$ export APP_ID=YOUR_APP_ID
$ export SECRET=YOUR_APP_SECRET

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

Create customer

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

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 customers reference for Customer related API endpoints.

Create connect token

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

There are 2 ways to create connections in Spectre API:

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

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

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

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

Visit connect url

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

Once selected, 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 logins

In Spectre API, a distinct bank connection is called a Login. Each Spectre Customer can have multiple Logins. When we visited Salt Edge Connect and connected “Fake Bank Simple” we effectively created a Login for our Customer in the system. So to retrieve all data for this Login we first need to retrieve the Login 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 LOGIN_ID=1227

See logins reference for more information on Login endpoints.

Fetch accounts for logins

Having the Login 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

Fetch transactions for an account

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

Next steps

• Request Test status to connect real banking institutions.
• Switch to Live status to bring value to your customers globally.
• In this guide, we visited Connect manually. You might want to do that programmatically. For more information see about embedding Salt Edge Connect in your application.
• Since new Spectre API clients are in test mode and have access only to fake providers, the request signature is not required. However, you will need to implement request signing before you are going live. For more information see our signature guide.
• All responses with arrays (like accounts or transactions) are paginated by default, see how to implement it on our pagination guide.
• The recommended way of syncronizing data with Spectre 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.

Changelog

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

Authentication

• Client-id and Service-secret headers are no longer supported. In V4, each Client is able to create an unlimited amount of API keys for API use. You can manage your keys on the Keys and Secrets page.

• Each request will now have consistent auth headers: App-id + Secret for both Apps and Services (ex: logins#create).

Removed

• client#info route;
• categorize flag/field from Attempt object and from logins#create. Instead, the new categorization flag was added to the same route. Possible values: none, personal, business, default: personal.

Changed

• All IDs are returned as strings in API responses and HTTP callbacks;
• Categories objects from /api/v4/categories now include business and personal categories list;
• md5 digest from imported file hash was changed to sha256;
• sha1 digest from request signature was changed to sha256;
• sha1 digest from callback signature was changed to sha256;
• fetch_type was replaced by fetch_scopes, required on login/token create and is optional on login/token reconnect or refresh;
• Consent window is now shown by default, unless show_consent_confirmation is false. In other cases, it will be shown only when fetch_scopes has changed;
• Consents can now have an expiration date. It can be set by passing the consent duration in the consent_period_days flag.

Added

• identification_mode - provider attribute that shows whether the requests to the provider are made with your authorization headers or with SaltEdge’s;
• Support for merchant identification;
• identify_merchant - flag that shows if merchant identification is enabled for a login;
• Support for encrypted_credentials that can be sent on logins#create, logins#reconnect and logins#interactive;
• consent_period_days - flag that allows limiting the time the consent is valid;
• override_credentials and override_credentials_strategy flags that allow overriding previous credentials when reconnecting a Login via an API request or Token respectively;
• New callbacks header - Signature-key-version which holds the version of the private key used to sign the callback. You can find the public_key that corresponds to this version here;
• transactions#remove that allows transaction removal older than a specified period.

• New currencies:

  • ERN - Eritrean nakfa (232)
  • ITL - Italian lira (380)
  • ECS - Ecuadorian sucre (218)
  • DEM - German mark (276)
  • KYD - Cayman Islands dollar (136)
  • CYP - Cypriot pound (196)
  • FRF - French franc (250)
  • SIT - Slovenian tolar (705)

• number and dynamic_select natures to provider fields;

• immediate flag added to categories#learn route.

• Provider logos (see logo_url in provider attributes)

New errors

• ApiKeyNotFound - the API key with the provided App-id and Secret does not exist or is inactive;
• AppIdNotProvided - missing App-id from headers;
• FetchScopesInvalid - client sent invalid values. Ex: fetch_scopes: [accounts];
• FetchScopesNotAllowed - client sent not supported values. Ex: he has access only to holder_info (Credit bureau for ex.) but sent fetch_scopes: [accounts].

Upgrade guide

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

• Visit Keys and Secrets page of your Client Dashboard and create a new API key with “service” key type;
• Change the routes that are polled in your system from v3 to v4;
• Replace Client-id and App-secret headers in all your requests with App-id and Secret headers corresponding to the key created in step 1;
• Make sure you use the right public_key to verify the authenticity of the received callbacks.

Before going LIVE

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

• Please provide SaltEdge representative with app’s test account to verify Spectre API integration;
• Be sure to provide signature in accordance with the instructions;
• If your application is running on mobile devices, desktops, tablets, which are under user’s control, please use app authentication;
• Your application should be working correctly with all of the fake banks;
• Your application should not create any duplicated customers (i.e. connecting the same provider with the same credentials, for the same user, using different customer entities);
• The end user should be able to create, reconnect, refresh and delete logins;
• After deleting a user from your system, you should send a delete request;
• Your application should handle correctly the refresh_timeout in provider entity;
• Your application should handle correctly the LoginDuplicated error;
• Your application should show the instructions for providers;
• Your application should not allow usage of disabled providers;
• Your application should use the duplicate route for a better user experience;
• The 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 SaltEdge representative, the account will be transferred to LIVE mode.

Know Your Customer

Account holder info

This feature allows the client to fetch essential information about customers from their bank accounts to be further used with the purpose of KYC verification. Make sure to contact our 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.

Login attribute holder_info 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 login information, e.g. accounts and transactions.

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

Encrypted credentials

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

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

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

Try Spectre API 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.

Step 3

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

Salt Edge Connect

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

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

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

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

To start the fetching process, they will have to press “Connect”. Afterwards, they will be informed about their connection progress.

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

Embeding connect in your appication

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

• by inserting an iframe with a specific source URL into the connect page;
• external object, calling window.external.SaltBridge;
• external object, calling window.external.Notify;
• postMessage, calling window.addEventListener(“message”….

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

Iframe injection

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

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

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

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

saltbridge://connect/{"data":{"duplicated_login_id":"994317674","stage":"error","custom_fields":{"key":"value"}}}

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

External object

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

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

Post message

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

External notify

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

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

Connect callbacks

There are 2 callback types of Salt Edge Connect:

• Standart callback
• Duplicated login callback

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

Fetching

{
  "data": {
    "login_id": "997674448",
    "stage": "fetching",
    "secret": "Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
    "custom_fields": {
      "key": "value"
    }
  }
}

and on duplicated login:

{
  "data": {
    "duplicated_login_id": "997674448",
    "stage": "fetching",
    "custom_fields": {
      "key": "value"
    }
  }
}

Success

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

{
  "data": {
    "login_id": "997674448",
    "stage": "success",
    "secret": "Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
    "custom_fields": {
      "key": "value"
    }
  }
}

and on duplicated login:

{
  "data": {
    "duplicated_login_id": "997674448",
    "stage": "success",
    "custom_fields": {
      "key": "value"
    }
  }
}

Error

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

{
  "data": {
    "login_id": "997674448",
    "stage": "error",
    "secret": "Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
    "custom_fields": {
      "key": "value"
    }
  }
}

and on duplicated login:

{
  "data": {
    "duplicated_login_id": "997674448",
    "stage": "error",
    "custom_fields": {
      "key": "value"
    }
  }
}

API Connect

If you do not wish to connect logins using Salt Edge Connect, you can perform all the login actions using our API.

In order to connect a new login, you should use the logins create route described in the API reference. After connecting the login, your application will receive the corresponding callbacks so you can fetch your newly created login.

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

Refreshing data

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

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

Note

API Connect requires high security standards for data handling on client’s side. This integration method is only available for the certified and/or selected partners. For more information, feel free to contact us.

Callbacks

The most important parts of Spectre API (e.g. Login management) are asynchronous. Applications can poll Spectre API in order to retrieve the updated information.

Every Web application has to provide a set of valid URLs which we will use to notify about the fetching progress. Other applications can poll Spectre 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 Spectre API;
• The request method is always POST;
• The JSON object sent will always have a data field;
• The meta field will display the version of the callbacks API.

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

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

Request Identification

In order for the client to identify that the request is coming from Spectre API, there are two options:

Signature

Signature - base64 encoded SHA256 signature of the string represented in the form callback_url|post_body - 2 parameters concatenated with a vertical bar |, signed with a Spectre 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 4.0 which corresponds to the following public key:

  -----BEGIN PUBLIC KEY-----
  MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzi1XL1b0XwUYVHj7/AR6
  Hr0YN34wH/bDOIub0nwt0s/s3tD+DPxNB85xpMEZrLikPW5PAKkQ/oC3OyPYxKOb
  8TNhzGmQhEfyCkbdRwxNZqRMRwuOc+N4sdBtQKPN8+XF3RIcRZAk25JGROtb1M2o
  d/Nb9QqdQwMjdk6W+Vdq5Sj25Tj2efJc8zmBJkNXR4WtW45p4XSdjSEjuVCSZjOy
  +N8/Od8MGixC99jYbiKm3RrVDJCgDi4YYnNRI0QgxZRpJKbQX/WeZiYOrbctG3m8
  l1/Hpkv3w1QHz/YFIshCOKwUL+xg1hLMaW4IH7XFHenE+JlUKdCqhcWyi7oIDkyr
  7wIDAQAB
  -----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":{"login_id":"1234","customer_id":"4321","custom_fields":{}},"meta":{"version":"4","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")))

Mutual TLS

To verify that callback is coming from Spectre API you can use Client Certifcate Authentication.

Instructions

1. Go to Account -> Callbacks and press Mutual TLS Settings

2. Press Generate CSR.

   

3. Set Certificate attributes if needed and press Generate.

   

4. Download CSR.

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

   openssl x509 -req -days 365 -in salt_edge_callbacks.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out client.crt
   

6. Upload generated certificate via following form.

   

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

Requests cycle

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

Success

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

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 login. Afterwards, your application will be able to use the show login route and query the information about this login. You could also fetch the login’s accounts and query the accounts (if any exist at the moment we sent the callback).

Whenever we have more information about the login, 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 login data, along with the accounts and transactions at each callback, as some information might change during the fetching process.

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

{
  "data": {
    "login_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" }
  },
  "meta": {
    "version": "4",
    "time": "2019-03-21T14:57:34.450Z"
  }
}

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

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": {
    "login_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" },
    "error_class": "InvalidCredentials",
    "error_message": "Invalid credentials."
  },
  "meta": {
    "version": "4",
    "time": "2019-03-21T14:57:34.450Z"
  }
}

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

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

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

Additional callbacks

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

Notify

Since you issue a create request to create a Login, Salt Edge can inform you about the progress the new login is going through using a Notify callback.

Your app can expect the notify callback several times, depending on the type of the login, 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 logins, 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": {
    "login_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" },
    "stage": "start"
  },
  "meta": {
    "version": "4",
    "time": "2019-03-20T14:57:34Z"
  }
}

Interactive

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

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

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

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

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

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

{
  "data": {
    "login_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" },
    "stage": "interactive",
    "html": "<div id='interactive'><img src='https://docs.saltedge.com/assets/images/saltedge_captcha.png' width='10' height='10' alt='some description' title='some description'></div>",
    "session_expires_at": "2019-03-20T15:57:34Z",
    "interactive_fields_names": ["image"]
  },
  "meta": {
    "version": "4",
    "time": "2019-03-20T14:57:34Z"
  }
}

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

{
  "data": {
    "login_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" },
    "stage": "interactive",
    "html": "<p>Please select accounts from the list:</p>",
    "session_expires_at": "2018-04-18T11:27:10Z",
    "interactive_fields_names": ["accounts"],
    "interactive_fields_options": {
      "accounts": [
        {
          "name":           "account1",
          "english_name":   "My checking account",
          "localized_name": "My checking account",
          "option_value":   "service_acc_guid1",
          "selected":       true
        },
        {
          "name":           "account2",
          "english_name":   "My savings account",
          "localized_name": "My savings account",
          "option_value":   "service_acc_guid2",
          "selected":       true
        }
      ]
    }
  },
  "meta": {
    "version": "4",
    "time": "2018-04-18T10:27:10Z"
  }
}

Destroy

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

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

{
  "data": {
    "login_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" }
  },
  "meta": {
    "version": "4",
    "time": "2013-05-17T14:29:35Z"
  }
}

Service

Whenever the login had issues in the past and a change was made in login’s provider codebase, your application will receive a callback telling that a refresh is needed in order to update login’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": {
    "login_id": "123",
    "customer_id": "34445",
    "custom_fields": { "key": "value" },
    "reason": "updated"
  },
  "meta": {
    "version": "4",
    "time": "2019-03-20T14:57:34Z"
  }
}

Merchant Identification

Merchant identification is an option that allows getting more information about transaction merchants. This option is country based and currently works only for UK providers but 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:

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

Errors

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

Error attributes

error_class

string

the class of the error, one of the listed below

error_message

string

a message describing the error

request

object

the body of the request that caused the error

Errors list

AccountNotFound

An account with the sent account_id could not be found

ActionNotAllowed

The client has no access to the required route

AllAccountsExcluded

You have excluded all the accounts from the login fetching process

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 login credentials do not match old ones on reconnect

CustomFieldsSizeTooBig

The custom_fields object has more than 1 KB

CustomFieldsFormatInvalid

The custom_fields field is not of type object

DateFormatInvalid

We have received an invalid Date format

DateOutOfRange

Sending a date value that does not fit in admissible range

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

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 login

FileNotSaved

File was not saved because of an error

HolderInfoNotSupported

Fetching holder info for this provider is not supported

IdentifierInvalid

Invalid identifier sent for identifying the customer

InteractiveAdapterTimeout

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

InteractiveTimeout

It took too long to respond to the interactive question

InternalServerError

An internal error has occured

InvalidCredentials

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

InvalidEncoding

Invalid JSON encoded values

InvalidFromDate

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

InvalidInteractiveCredentials

Interactive credentials that were sent are wrong

InvalidToDate

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

JsonParseError

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

LoginAlreadyProcessing

The login is already being processed

LoginAlreadyAuthorized

The login was already authorized

LoginCannotBeRefreshed

Login cannot be refreshed right now

LoginDisabled

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

LoginDuplicated

The client tried to create a login that already exists

LoginFetchingStopped

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

LoginLimitReached

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

LoginNotFound

We could not find a login with the requested login_id

MissingExpiresAt

The Expires-at field is missing in the headers

MissingSignature

The Signature field is missing in the headers

ProviderAccessNotGranted

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

ProviderDisabled

The accessed provider is disabled

ProviderError

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

ProviderInactive

The accessed provider is inactive at the moment

ProviderNotFound

Sending a provider_code that is not present in our system

ProviderKeyFound

The chosen provider does not have provider keys

ProviderNotInteractive

The login’s provider has no interactive step

ProviderUnavailable

The provider is temporary unavailable

PublicKeyNotProvided

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

RateLimitExceeded

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

RequestExpired

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

ReturnURLInvalid

The return_to URL is invalid

ReturnURLTooLong

The return_to URL exceeds 2040 characters

RouteNotFound

The action you are trying to access deos 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 occured for connecting/reconnecting a login from one IP address in a small period of time

TransactionNotFound

A transaction with the sent transaction_id could not be found

ValueOutOfRange

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

WrongClientToken

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

WrongProviderMode

We do not support the received provider_mode

WrongRequestFormat

The JSON request is incorrectly formed

Countries

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

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

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

Listing countries

Returns a list of countries supported by Spectre API.

Parameters

include_fake_providers

boolean, optional

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

Response

name

string

name of the country

code

string

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

refresh_start_time

integer

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

Possible Errors

• ClientDisabled
• ClientNotFound

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 logins can be automatically fetched

customer_notified_on_sign_in

boolean

whether the provider will notify the customer on log in attempt

interactive

boolean

whether the provider requires interactive input

identification_mode

string

whether the request to the provider is made with your authorization headers or with SaltEdge’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

forum_url

string

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

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

Provider show

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

Parameters

provider_code

string

provider’s code

Possible Errors

• ClientDisabled
• ClientNotFound
• ProviderNotFound

Listing providers

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

Providers that require a client provider key will be included only if you have created provider keys for them.

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

include_provider_fields

boolean, optional

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

provider_key_owner

string, optional

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

Possible Errors

• ClientDisabled
• ClientNotFound
• DateOutOfRange
• ValueOutOfRange

Provider fields

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

nature

string

possible values are: text, password, select, dynamic_select, file, number. The dynamic_select is used only for providers that require a provider key

name

string

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

english_name

string

the field’s name in US English

localized_name

string

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

position

integer

field’s position in the public user interface

optional

boolean

whether the input for this field is required by the provider

field_options

object

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

Provider field options

Some providers ask their users to select a secret word or an answer to a question as a security measure. In this case, the provider will contain a field of select type. The field will contain an array of field_options objects, which describe the possible choices for the user.

name

string

the name of the field option

english_name

string

the option’s name in US English

localized_name

string

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

option_value

string

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

selected

boolean

whether the choice is selected by default

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

Fake Providers

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 Erorrs - 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 to test your Client Provider Keys with:

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

Check the provider’s instructions 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.

Customers

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

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

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

Create customer

Creates a customer, returning the customer object.

Parameters

identifier

string, required

a unique identifier of the new customer

Possible Errors

• ClientDisabled
• ClientNotFound
• DuplicatedCustomer
• JsonParseError
• WrongRequestFormat

Show customer

Returns the customer object.

Parameters

id

string, required

the id of the customer

Possible Errors

• ClientDisabled
• ClientNotFound
• CustomerNotFound

List customers

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

Possible Errors

• ClientDisabled
• ClientNotFound

Remove customer

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

Possible Errors

• ClientDisabled
• ClientNotFound
• CustomerNotFound
• JsonParseError
• WrongRequestFormat

Lock customer

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

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

Possible Errors

• ClientDisabled
• ClientNotFound
• CustomerNotFound
• JsonParseError
• WrongRequestFormat

Unlock customer

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

Possible Errors

• ClientDisabled
• ClientNotFound
• CustomerNotFound
• JsonParseError
• WrongRequestFormat

Tokens

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

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

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

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

Create

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

Parameters

customer_id

string, required

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

allowed_countries

array of strings, optional

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

provider_code

string, optional

the code of the desired provider, defaults to null

fetch_scopes

array of strings, required

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

fetched_accounts_notify

boolean, optional

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

identify_merchant

boolean, optional

whether merchant identification should be applied. Defaults to false

customer_last_logged_at

datetime, optional

the datetime when user was last active in your application

custom_fields

object, optional

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

daily_refresh

boolean, optional

whether the login should be automatically refreshed by Salt Edge

disable_provider_search

boolean, optional

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

from_date

date, optional

date from which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_scopes parameter contains transactions, otherwise InvalidFromDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow.
To increase the maximum allowed time interval, please contact our sales team. Default: 2 moths ago

to_date

date, optional

date until which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_scopes parameter contains transactions, otherwise InvalidToDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow.
To increase the maximum allowed time interval, please contact our sales team. Default: today

locale

string, optional

the language of the Salt Edge Connect page 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

return_to

string, optional

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

return_login_id

boolean, optional

whether to append login_id to return_to URL. Defaults to false

provider_modes

array of strings, optional

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

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

categorization

string, optional

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

javascript_callback_type

string, optional

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

include_fake_providers

boolean, optional

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

lost_connection_notify

boolean, optional

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

show_consent_confirmation

boolean, optional

if sent as false, upon submitting the form, the user will not be asked to give his consent to Salt Edge Inc. in order for the data requested via the fetch_scopes flag to be fetched. Default value: true.

consent_period_days

integer, optional

determines the period the consent will be valid for. Default value: null (limitless).
Note: The provider you connect with can have a max_consent_days attribute with a value lower than consent_period_days. In that case, the minimum of the two will be applied.

credentials_strategy

string, optional

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

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)

Possible Errors

• ClientDisabled
• ClientNotFound
• ClientRestricted
• CountryNotFound
• CustomerLocked
• CustomerNotFound
• DateTimeFormatInvalid
• DateTimeOutOfRange
• FetchScopesNotAllowed
• InvalidFromDate
• InvalidToDate
• JsonParseError
• LoginNotFound
• ProviderNotFound
• ReturnURLInvalid
• ReturnURLTooLong
• WrongProviderMode
• WrongRequestFormat

Reconnect

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

Parameters

login_id

string, required

the ID of the login you wish to reconnect

locale

string, optional

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

return_to

string, optional

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']

fetched_accounts_notify

boolean, optional

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

identify_merchant

boolean, optional

whether merchant identification should be applied. Defaults to false

customer_last_logged_at

datetime, optional

the datetime when user was last active in your application

custom_fields

object, optional

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

daily_refresh

boolean, optional

whether the login should be automatically refreshed by Salt Edge

from_date

date, optional

date from which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_scopes parameter contains transactions, otherwise InvalidFromDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow.
To increase the maximum allowed time interval, please contact our sales team.
Spectre API will use the most optimal value for this field if it wasn’t specified in the request.

to_date

date, optional

date until which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_scopes parameter contains transactions, otherwise InvalidToDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow.
To increase the maximum allowed time interval, please contact our sales team. Default: today

exclude_accounts

array of strings, optional

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

return_login_id

boolean, optional

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

provider_modes

array of strings, optional

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

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

javascript_callback_type

string, optional

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

categorization

string, optional

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

include_fake_providers

boolean, optional

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

lost_connection_notify

boolean, optional

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

show_consent_confirmation

boolean, optional

if sent as false, upon submitting the form, the user will not be asked to give his consent to Salt Edge Inc. in order for the data requested via the fetch_scopes flag to be fetched. Default value: true.

consent_period_days

integer, optional

determines the period the consent will be valid for. Default value: null (limitless).
Note: The provider you connect with can have a max_consent_days attribute with a value lower than consent_period_days. In that case, the minimum of the two will be applied.

credentials_strategy

string, optional

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

override_credentials_strategy

string, optional

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

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)

Possible Errors

• AllAccountsExcluded
• ClientDisabled
• ClientNotFound
• ClientRestricted
• DateTimeFormatInvalid
• DateTimeOutOfRange
• FetchScopesNotAllowed
• InvalidFromDate
• InvalidToDate
• JsonParseError
• LoginNotFound
• ReturnURLInvalid
• ReturnURLTooLong
• WrongRequestFormat

Refresh

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

Parameters

login_id

string, required

the ID of the login you wish to reconnect

locale

string, optional

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

fetch_scopes

array of strings, optional

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

fetched_accounts_notify

boolean, optional

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

identify_merchant

boolean, optional

whether merchant identification should be applied. Defaults to false

customer_last_logged_at

datetime, optional

the datetime when user was last active in your application

custom_fields

object, optional

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

daily_refresh

boolean, optional

whether the login should be automatically refreshed by Salt Edge

user_present

boolean, optional

whether the request was initiated by the end user of your application. Defaults to false

from_date

date, optional

date from which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_scopes parameter contains transactions, otherwise InvalidFromDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow.
To increase the maximum allowed time interval, please contact our sales team.
Spectre API will use the most optimal value for this field if it wasn’t specified in the request.

to_date

date, optional

date until which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_scopes parameter contains transactions, otherwise InvalidToDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow.
To increase the maximum allowed time interval, please contact our sales team. Default: today

exclude_accounts

array of strings, optional

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

return_to

string, optional

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

return_login_id

boolean, optional

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

provider_modes

array of strings, optional

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

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

javascript_callback_type

string, optional

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

categorization

string, optional

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

lost_connection_notify

boolean, optional

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

show_consent_confirmation

boolean, optional

if sent as false, upon submitting the form, the user will not be asked to give his consent to Salt Edge Inc. in order for the data requested via the fetch_scopes flag to be fetched. Default value: true.

consent_period_days

integer, optional

determines the period the consent will be valid for. Default value: null (limitless).
Note: The provider you connect with can have a max_consent_days attribute with a value lower than consent_period_days. In that case, the minimum of the two will be applied.
If the consent for a connection has expired, on refresh, you will be redirected to a Reconnect page in order for a new consent to be given.

include_fake_providers

boolean, optional

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

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)

Possible Errors

• AllAccountsExcluded
• BackgroundFetchLimitExceeded
• ClientDisabled
• ClientNotFound
• ClientRestricted
• DateTimeFormatInvalid
• DateTimeOutOfRange
• FetchScopesNotAllowed
• InvalidFromDate
• InvalidToDate
• JsonParseError
• LoginNotFound
• ReturnURLInvalid
• ReturnURLTooLong
• WrongRequestFormat

OAuth Providers

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

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

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

Create

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

Note that mobile clients receive a login_secret parameter in the return_to URL if the login was successfully connected and an error_message parameter. return_to is optional for clients only if they use a shared (owned by Salt Edge) provider key (it is set as the client’s home_url by default). If clients use their own provider keys, return_to is required and should be a valid url that was registered within the provider they are connecting to.

Parameters

country_code

string, required

the code of the country

provider_code

string, required

the code of the provider

customer_id

string, required

the ID of the customer received from customer create

return_to

string, required

the address your user will be redirected to after they grant or deny the access. If you used your own provider keys to connect to the provider, the url to which the end-user will be redirected will contain a bunch of parameters appended by the provider that you need to send to the authorize route in order to continue the fetching process

daily_refresh

boolean, optional

whether the login should be automatically refreshed by Salt Edge

fetch_scopes

array of strings, required

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

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

customer_last_logged_at

datetime, optional

the datetime when user was last active in your application

from_date

date, optional

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

to_date

date, optional

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

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

return_login_id

boolean, optional

whether to append login_id to return_to URL. Defaults to false

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 providers. This flag allows it, if sent as true the customer will have the possibility to create any fake provider available. Defaults to false

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)

Possible Errors

• ClientDisabled
• ClientNotFound
• CountryNotFound
• CustomerLocked
• CustomerNotFound
• DateTimeFormatInvalid
• DateTimeOutOfRange
• FetchScopesNotAllowed
• InvalidFromDate
• InvalidToDate
• JsonParseError
• ProviderNotFound
• ReturnURLInvalid
• ReturnURLTooLong
• WrongRequestFormat

Reconnect

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

Note that mobile clients receive a login_secret parameter in the return_to URL and a error_message parameter if the login failed to connect for some reason. return_to is optional for clients only if they use a shared (owned by Salt Edge) provider key (it is set as the client’s home_url by default). If clients use their own provider keys, return_to is required and should be a valid url that was registered within the provider they are connecting to.

Parameters

login_id

string, required

the ID of the login that is to be reconnected

return_to

string, required

the address your user will be redirected to after they grant or deny the access. If you used your own provider keys to connect to the provider, the url to which the end-user will be redirected will contain a bunch of parameters appended by the provider that you need to send to the authorize route in order to continue the fetching process

daily_refresh

boolean, optional

whether the login should be automatically refreshed by Salt Edge

fetch_scopes

array of strings, optional

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

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

customer_last_logged_at

datetime, optional

the datetime when user was last active in your application

from_date

date, optional

date from which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_scopes parameter contains transactions, otherwise InvalidFromDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow.
Spectre API will use the most optimal value for this field if it wasn’t specified in the request.

to_date

date, optional

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

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

exclude_accounts

array of strings, optional

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

return_login_id

boolean, optional

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

categorization

string, optional

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

include_fake_providers

boolean, optional

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

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)

Possible Errors

• AllAccountsExcluded
• ClientDisabled
• ClientNotFound
• DateTimeFormatInvalid
• DateTimeOutOfRange
• FetchScopesNotAllowed
• InvalidFromDate
• InvalidToDate
• JsonParseError
• LoginNotFound
• ReturnURLInvalid
• ReturnURLTooLong
• WrongRequestFormat

Refresh

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

Note that mobile clients receive a login_secret parameter in the return_to URL and a error_message parameter if the login failed to connect for some reason. return_to is optional for clients only if they use a shared (owned by Salt Edge) provider key (it is set as the client’s home_url by default). If clients use their own provider keys, return_to is required and should be a valid url that was registered within the provider they are connecting to.

Parameters

login_id

string, required

the ID of the login that is to be reconnected

return_to

string, required

the address your user will be redirected to after they grant or deny the access. If you used your own provider keys to connect to the provider, the url to which the end-user will be redirected will contain a bunch of parameters appended by the provider that you need to send to the authorize route in order to continue the fetching process

daily_refresh

boolean, optional

whether the login should be automatically refreshed by Salt Edge

user_present

boolean, optional

whether the request was initiated by the end user of your application. Defaults to false

fetch_scopes

array of strings, optional

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

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

customer_last_logged_at

datetime, optional

the datetime when user was last active in your application

from_date

date, optional

date from which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_scopes parameter contains transactions, otherwise InvalidFromDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow.
Spectre API will use the most optimal value for this field if it wasn’t specified in the request.

to_date

date, optional

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

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

exclude_accounts

array of strings, optional

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

return_login_id

boolean, optional

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

categorization

string, optional

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

include_fake_providers

boolean, optional

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

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)

Possible Errors

• AllAccountsExcluded
• BackgroundFetchLimitExceeded
• ClientDisabled
• ClientNotFound
• DateTimeFormatInvalid
• DateTimeOutOfRange
• FetchScopesNotAllowed
• InvalidFromDate
• InvalidToDate
• JsonParseError
• LoginNotFound
• ReturnURLInvalid
• ReturnURLTooLong
• WrongRequestFormat

Authorize

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

Examples: <return_to url>?access_token=bc4521d3&state=Pd8b4d0eb, <return_to url>#access_token=bc4521d3&state=Pd8b4d0eb. For both cases, the query_string that is needed to authorize the connection is access_token=bc4521d3&state=Pd8b4d0eb.

Parameters

login_id

string, required

the id of the login that is being authorized

query_string

string, required

all the parameters appended to your return_to url upon being redirected from the bank back to your application

Possible Errors

• ClientDisabled
• ClientNotFound
• JsonParseError
• LoginAlreadyAuthorized
• WrongRequestFormat

Logins

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

Within Spectre, a login 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 login. An inactive login cannot be refreshed;
• disabled - in case of non-compliance with our Terms of Service, we can contact the application’s owner and disable the login.

Attributes

id

string

provider_id

string

the ID of the Provider the login belongs to

provider_code

string

the code of the Provider the login belongs to

provider_name

string

the name of the Provider the login belongs to

daily_refresh

boolean

whether the login will be refreshed daily

customer_id

string

customer’s ID

created_at

datetime

updated_at

datetime

last_success_at

datetime

time when the login was successfully fetched

status

string

possible values are: active, inactive, disabled

country_code

string

code of the country the provider belongs to

next_refresh_possible_at

datetime

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

store_credentials

boolean

whether the credentials were stored on our side

last_attempt

object, attempt object

last attempt of this login

holder_info

object, holder object

contains the account holder information

show_consent_confirmation

boolean

whether any consent was given for this login

consent_types

array of strings

the information that was given consent for. Possible values: holder_information, account_information, transaction_information

consent_period_days

integer

the period the consent will be valid for

consent_given_at

datetime

time when the consent was given

consent_expires_at

datetime

time when the consent will expire

Holder Info

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

names

array

account holder name(s)

emails

array

account holder email(s)

phone_numbers

array

account holder phone number(s)

addresses

array of objects

account holder address(es)

Extra

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

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

Listing logins

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

Parameters

from_id

string, optional

the id of the record starting the next page

customer_id

string, optional

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

Possible Errors

• ClientDisabled
• ClientNotFound
• ValueOutOfRange

Login show

Returns a single login object.

Possible Errors

• ClientDisabled
• ClientNotFound
• LoginNotFound

Creating logins

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

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

For example, here’s a provider:

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

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

{
  "code": "hunter2"
}

Here’s another example that includes a select:

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

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

The credentials object should look like this:

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

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

Parameters

customer_id

string, required

the ID of the customer

country_code

string, required

the country code of the desired provider

provider_code

string, required

the code of the desired provider

credentials

object, required unless encrypted_credentials are present

the credentials required to access the data

encrypted_credentials

object, required unless credentials are present

the encrypted credentials required to access the data

daily_refresh

boolean, optional

whether the login should be automatically refreshed by Salt Edge

fetch_scopes

array of strings, required

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

identify_merchant

boolean, optional

whether merchant identification should be applied. Defaults to false

customer_last_logged_at

datetime, optional

the datetime when user was last active in your application

custom_fields

object, optional

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

fetched_accounts_notify

boolean, optional

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

from_date

date, optional

date from which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_scopes parameter contains transactions, otherwise InvalidFromDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow.
To increase the maximum allowed time interval, please contact our sales team. Default: 2 moths ago

to_date

date, optional

date until which you want to fetch data for your login.
Note: The usage of this parameter is only available when fetch_scopes parameter contains transactions, otherwise InvalidToDate error will be returned. The allowed values for this parameter must be within exactly 2 months ago and tomorrow.
To increase the maximum allowed time interval, please contact our sales team. Default: today

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_fake_providers

boolean, optional

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

categorization

string, optional

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

store_credentials

boolean, optional

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

file_url

string, optional

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

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)

Response

A complete Login object.

Possible Errors

• ClientDisabled
• ClientNotFound
• ClientRestricted
• CountryNotFound
• CustomerLocked
• CustomerNotFound
• DateTimeFormatInvalid
• DateTimeOutOfRange
• FetchScopesNotAllowed
• FileNotProvided
• FileNotSaved
• InvalidFromDate
• InvalidToDate
• JsonParseError
• LoginDuplicated
• LoginFetchingStopped
• LoginLimitReached
• ProviderDisabled
• ProviderInactive
• ProviderNotFound
• RateLimitExceeded
• WrongRequestFormat