general
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.
Authentication
For more information about the Expires-at
and Signature
headers, see Signature page of the guides.
All of the resources queried through the API are protected by 4 different headers, on different levels of security, as shown on the diagramm below:
App ID and Secret
The App-id
and Secret
headers should be passed in with every request. Keep in mind that you can obtain these keys on your API keys page.
Here’s an example request listing all the countries that the API currently supports.
Services and Apps authentication
There 2 types of access to Salt Edge API - as a service
or as an app
. The type of access is set up by the type of the API key that you are using while accessing the API:
service
- intended to be used by backends, all the API endpoints are availableapp
- intended to be used by Applications without a backend. Some endpoints for this type of Secret are not available, because mobile applications can be easily compromised/revers engineered, hence the are security constraints in place to mitigate this
Customer secret
In order to create tokens,
logins and
oauth providers,
your app should pass the Customer-secret
header inside the request, so the API
can identify which customer the entity belongs to.
Login secret
Since an app should be able to query information only about the logins it created, requests that query or modify logins should be signed with a Login-secret
header.
URL
https://www.saltedge.com/api/v4/transactions?account_id={account.id}
https://www.saltedge.com/api/v4/transactions?account_id={account.id}
Method
GET
Authentication
Sample Request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v4transactions?account_id=100
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X GET \
https://www.saltedge.com/api/v4transactions?account_id=100
Quick start
Here are some steps to get you started.
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.
URL
https://www.saltedge.com/api/v4/customers
https://www.saltedge.com/api/v4/customers
Method
POST
Sample Request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"identifier\": \"test1\" \
} \
}" \
https://www.saltedge.com/api/v4/customers
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"identifier\": \"test1\" \
} \
}" \
https://www.saltedge.com/api/v4/customers
Sample Response
{
"data": {
"id": "111",
"identifier": "test1",
"secret": "SECRET"
}
}
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.
URL
https://www.saltedge.com/api/v4/tokens/create
https://www.saltedge.com/api/v4/tokens/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\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
} \
}" \
https://www.saltedge.com/api/v4/tokens/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\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
} \
}" \
https://www.saltedge.com/api/v4/tokens/create
Sample Response
{
"data": {
"token": "GENERATED_TOKEN",
"expires_at": "2022-04-15T14:09:10Z",
"connect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
}
}
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.
URL
https://www.saltedge.com/api/v4/logins?customer_id={customer.id}
https://www.saltedge.com/api/v4/logins?customer_id={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/v4/logins?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/v4/logins?customer_id=$CUSTOMER_ID
Sample Response
{
"data": [
{
"id": "1227",
"provider_code": "fakebank_simple_xf",
"provider_name": "Fakebank Simple",
"customer_id": "111",
...
}
]
}
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
URL
https://www.saltedge.com/api/v4/accounts?login_id={login.id}
https://www.saltedge.com/api/v4/accounts?login_id={login.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/v4/accounts?login_id=$LOGIN_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/v4/accounts?login_id=$LOGIN_ID
Sample Response
{
"data": [
{
"id": "142",
"name": "Fake account 1",
"nature": "card",
"balance": 2007.2,
"currency_code": "EUR",
"login_id": "1227",
"created_at": "2022-04-15T10:09:10Z",
"updated_at": "2022-04-15T10:09:10Z",
"extra": {
"client_name": "Fake name"
},
...
}
]
}
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.
URL
https://www.saltedge.com/api/v4/transactions?account_id={account.id}
https://www.saltedge.com/api/v4/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/v4/transactions?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/v4/transactions?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": "2022-04-13T13:09:10Z",
"updated_at": "2022-04-14T13:09:10Z",
"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.
- 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
andService-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 fromAttempt
object and from logins#create. Instead, the newcategorization
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
andpersonal
categories list; md5 digest
from imported file hash was changed tosha256
;sha1 digest
from request signature was changed tosha256
;sha1 digest
from callback signature was changed tosha256
;fetch_type
was replaced byfetch_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 whenfetch_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 Salt Edge’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
andoverride_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 thepublic_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
anddynamic_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
andSecret
does not exist or isinactive
; - 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 sentfetch_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
tov4
; - Replace
Client-id
andApp-secret
headers in all your requests withApp-id
andSecret
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 Salt Edge accounts transferred to LIVE mode the following steps should be followed:
- Please provide Salt Edge representative with app’s test account to verify 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.
- Be sure to indicate Incident Reporting Email in the dashboard settings;
After all of the verifications have been made by a Salt Edge representative, the 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.
Sample response (as provider attribute)
"holder_info": ["names", "emails"]
Sample response (as login attribute)
{
"holder_info": {
"names": ["John Doe"],
"emails": ["john.doe@example.com"]
"addresses": [
{
"city": "Cupertino",
"state": "CA",
"street": "1 Infinite Loop",
"country_code": "US",
"post_code": "95014"
}
]
}
}
Encrypted credentials
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.
Payload Structure
{
"algorithm": "AES-256-CBC",
"key": base64(public_rsa(random_key)),
"iv": base64(public_rsa(random_iv)),
"data": base64(aes_encrypt(random_key, random_iv, credentials_json)),
"version": "version_provided_by_saltedge"
}
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
If you access the Connect page from a .Net host, and you use WebBrowser.ObjectForScripting
, we will try to call the window.external.SaltBridge
function with the connection attributes serialized as json.
NOTE: In the example SaltBridge
is a method defined on the object that was specified as a object for scripting: webBrowser1.ObjectForScripting = this
which initialized the WebView
.
External Notify Example
public void SaltBridge(String serializedLogin) {
// data
}
serializedConnection
{
"data": {
"connection_id":"123",
"stage":"fetching",
"secret":"Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
"custom_fields":{
"key":"value"
},
"api_stage": "start"
}
}
Post message
If you access the connect page wrapped in an iframe, you can use Window.postMessage which performs cross-origin communication
Post Message Example
window.addEventListener("message", function(event) {
console.log(JSON.parse(event.data))
}
)
serializedLogin
{
"data": {
"login_id":"997674448",
"stage":"fetching",
"secret":"Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
"custom_fields": {
"key":"value"
}
}
}
External notify
On Windows Store app platform you can use event handler for ScriptNotify
event of WebView
. Your code should handle window.external.notify(args)
call, ScriptNotify
will fire and you’ll get the args in Value
property of NotifyEventArgs
parameter.
Remember to add https://saltedge.com
and https://*.saltedge.com
to Content URIs in Package.appxmanifest
.
External Notify Example
protected override void OnNavigatedTo(NavigationEventArgs e) {
browser.ScriptNotify += browser_ScriptNotify;
}
private void browser_ScriptNotify(object sender, NotifyEventArgs e) {
var serializedLogin = e.Value;
}
serializedLogin
{
"data": {
"login_id":"997674448",
"stage":"fetching",
"secret":"Oqws977brjJUfXbEnGqHNsIRl8PytSL60T7JIsRBCZM",
"custom_fields": {
"key":"value"
}
}
}
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"
}
}
}
Direct API
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
Direct API 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 isapplication/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
Go to
Account
-> Callbacks and press Mutual TLS SettingsPress
Generate CSR
.Set Certificate attributes if needed and press
Generate
.Download CSR.
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
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 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 lists updated login object, updates account balances, extra fields and transactions using from_id to fetch newly imported records at each callback, as some information might change during the fetching process.
For instance, when your user has created a 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": "2022-04-15T13:09:11.189Z"
}
}
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": "2022-04-15T13:09:11.206Z"
}
}
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": "2022-04-14T13:09:11Z"
}
}
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": "2022-04-14T14:09:11Z",
"interactive_fields_names": ["image"]
},
"meta": {
"version": "4",
"time": "2022-04-14T13:09:11Z"
}
}
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": false
},
{
"name": "account2",
"english_name": "My savings account",
"localized_name": "My savings account",
"option_value": "service_acc_guid2",
"selected": false
}
]
}
},
"meta": {
"version": "4",
"time": "2018-04-18T10:27:10Z"
}
}
Note: Some interactive providers request to select only one option from dynamic_select
interactive_field. In this case we mark such fields by adding multiple: false
flag to the extra key in provider’s interactive fields:
"interactive_fields": [
{
"name": "language",
"english_name": "Language",
"localized_name": "Language",
"nature": "dynamic_select",
"position": 3,
"optional": false,
"extra": {
"multiple": false
}
}
]
In such case we expect to receive only 1 selected option value as a String
.
When provider requires multiple options to be selected, we mark such fields by adding multiple: true
flag to the extra key in provider’s interactive fields:
"interactive_fields": [
{
"name": "accounts",
"english_name": "Accounts",
"localized_name": "Accounts",
"nature": "dynamic_select",
"position": 3,
"optional": false,
"extra": {
"multiple": true
}
}
]
In such case we expect to receive an Array
of strings.
Interactive Redirect
There are some OAuth providers that require 2 redirects for authorization. In these cases, for the 2nd redirect Salt Edge will send an interactive callback with redirect_url
field:
{
"data": {
"login_id": "123",
"customer_id": "34445",
"html": "",
"redirect_url": "https://bank.com/authorize"
"stage": "interactive",
"session_expires_at": "2022-04-14T14:09:11Z",
"interactive_fields_names": [],
"custom_fields": { "key": "value" }
},
"meta": {
"version": "4",
"time": "2022-04-14T13:09:11Z"
}
}
Your application should redirect the user to redirect_url
field
value of the interactive callback payload. Once the end-user will
be authorized on the provider’s side, they will be redirected to
the return_to
URL indicated in the
create login
request.
To continue the process, you need to send a request containing the
query string appended to your return_to
URL to the
interactive route.
{
"data": {
"credentials": {
"query_string": "access_token=123"
}
}
}
If there are no query parameters when the end-user is redirected to
the return_to
URL, please send an empty credentials
object.
{
"data": {
"credentials": {}
}
}
Authentication
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"credentials\": { \
} \
} \
}" \
https://www.saltedge.com/api/v4/logins/123/interactive
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Login-secret: $LOGIN_SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"credentials\": { \
} \
} \
}" \
https://www.saltedge.com/api/v4/login/interactive
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": "2022-04-14T13:09:11Z"
}
}
Merchant Identification
Merchant identification is an option that allows to identify merchant names and other useful information about them, basing on transactions’ data.
This option is country based and currently is available in 17 countries - UK, Ireland, Italy, Netherlands, Germany, Czech Republic, Austria, Hungary, Poland, Romania, Latvia, Spain, Portugal, Australia, Russia, India, Singapore and the list will continue to grow.
Also, you can test it, using the fakebank_simple_xf
provider, available for the fake XF
country.
How to use
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 amerchant_id
in theextra
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
error_class
string
The class of the error, one of the listed below
error_message
string
A message describing the error
request
object
The body of the request that caused the error
Error codes
[400] Bad Request
[404] Not Found
[406] Not Acceptable
[409] Duplicated
Sample response
{
"error_class": "LoginNotFound",
"error_message": "Login with id: '987' was not found.",
"request": {
"login_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 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
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
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
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
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
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
api
Countries
The country is represented just as a string. We’re using ISO 3166-1 alpha-2 country codes. Thus, all the country codes will have exactly two uppercase letters. There are two special cases:
- “Other”, encoded as
XO
- “Fake”, encoded as
XF
Note that the Fake country is only available for clients in Test and Pending statuses.
List
Returns a list of countries supported by Spectre 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 logins 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 logins will be automatically refreshed. Possible values: 0 to 23
Possible Errors
URL
https://www.saltedge.com/api/v4/countries
https://www.saltedge.com/api/v4/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/v4/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/v4/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 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 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 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
regulated
boolean
Whether the provider uses regulated channels
max_fetch_interval
integer
Max period in days that can be fetched form provider interface
custom_pendings
boolean
Equals to true
if the provider supports a custom pending logic. For example, when the transactions for the last 7 days are marked as pending. Usually implemented to avoid the generation of duplicated transactions due to inconsistent transaction information returned by the bank.
custom_pendings_period
integer
Populated when custom_pendings
is true
. Shows the number of days according to the custom pending period implemented in the provider.
supported_fetch_scopes
array
Array of strings with supported fetch_scopes
supported_account_types
array
Possible values are: personal
, business
identification_codes
array
List of codes identifying supported branches of a specific provider. It may include BLZ(Germany), ABI+CAB(Italy), Branch Codes(France) etc.
bic_codes
array
List of BIC codes identifying supported branches of a specific provider.
supported_iframe_embedding
boolean
Possible values are: true
, false
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 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 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
regulated
boolean
Whether the provider uses regulated channels
max_fetch_interval
integer
Max period in days that can be fetched form provider interface
custom_pendings
boolean
Equals to true
if the provider supports a custom pending logic. For example, when the transactions for the last 7 days are marked as pending. Usually implemented to avoid the generation of duplicated transactions due to inconsistent transaction information returned by the bank.
custom_pendings_period
integer
Populated when custom_pendings
is true
. Shows the number of days according to the custom pending period implemented in the provider.
supported_fetch_scopes
array
Array of strings with supported fetch_scopes
supported_account_types
array
Possible values are: personal
, business
identification_codes
array
List of codes identifying supported branches of a specific provider. It may include BLZ(Germany), ABI+CAB(Italy), Branch Codes(France) etc.
bic_codes
array
List of BIC codes identifying supported branches of a specific provider.
supported_iframe_embedding
boolean
Possible values are: true
, false
Sample object
{
"id": "123",
"code": "fakebank_simple_xf",
"name": "Fake Bank",
"mode": "web",
"status": "active",
"automatic_fetch": true,
"customer_notified_on_sign_in": false,
"interactive": false,
"identification_mode": "saltedge",
"instruction": "Please fill in all the fields.",
"home_url": "http://example.com",
"login_url": "http://example.com/login",
"forum_url": "https://www.saltedge.com/support_requests/new?provider_code=fakebank_simple_xf",
"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": "2022-04-05T13:09:11Z",
"updated_at": "2022-04-10T13:09:11Z",
"timezone": "Europe/London",
"max_interactive_delay": 480,
"optional_interactivity": true,
"regulated": false,
"max_fetch_interval": 60,
"supported_fetch_scopes": ["accounts", "transactions"],
"supported_account_extra_fields": [],
"supported_transaction_extra_fields": [],
"supported_account_natures": ["account", "card"],
"supported_account_types": ["personal"],
"identification_codes": ["123123"],
"bic_codes": ["ABCDEFGH"],
"supported_iframe_embedding": true
}
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
provider_code
string
Provider’s code
Possible Errors
URL
https://www.saltedge.com/api/v4/providers/{provider.code}
https://www.saltedge.com/api/v4/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/v4/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/v4/providers/fakebank_interactive_xf
Sample response
{
"data": {
"id": "67",
"code": "fakebank_interactive_xf",
"name": "Fake Bank with SMS",
"mode": "web",
"status": "active",
"automatic_fetch": false,
"interactive": true,
"instruction": "Valid credentials for this provider are:\nlogin - any string which starts with \"username\",\npassword - \"secret\",\nsms - \"123456\"\n",
"refresh_timeout": 5,
"customer_notified_on_sign_in": false,
"home_url": "http://example.com",
"login_url": "http://example.com/login",
"forum_url": "https://www.saltedge.com/support_requests/new?provider_code=fakebank_interactive_xf",
"logo_url": "https://d1uuj3mi6rzwpm.cloudfront.net/logos/providers/xf/fakebank_interactive_xf.svg",
"country_code": "XF",
"created_at": "2014-03-19T17:55:44Z",
"updated_at": "2019-03-07T09:57:26Z",
"timezone": "UTC",
"holder_info": [],
"max_consent_days": null,
"identification_mode": "saltedge",
"max_interactive_delay": 180,
"optional_interactivity": false,
"regulated": false,
"max_fetch_interval": 60,
"supported_fetch_scopes": ["accounts", "transactions"],
"supported_account_natures": ["account", "card"],
"supported_account_types": ["personal"],
"identification_codes": ["123123"],
"bic_codes": ["ABCDEFGH"],
"supported_iframe_embedding": true,
"supported_account_extra_fields": [
"account_name",
"account_number",
"card_type",
"cards",
"client_name",
"iban",
"sort_code",
"status",
"swift"
],
"supported_transaction_extra_fields": [
"convert",
"original_amount",
"original_currency_code",
"payee",
"posting_date",
"transfer_account_name"
],
"required_fields": [{
"name": "login",
"english_name": "Login",
"localized_name": "Login",
"nature": "text",
"position": 1,
"optional": false,
"extra": {}
},
{
"name": "password",
"english_name": "Password",
"localized_name": "Password",
"nature": "password",
"position": 2,
"optional": false,
"extra": {}
}
],
"interactive_fields": [{
"name": "sms",
"english_name": "SMS code",
"localized_name": "SMS code",
"nature": "number",
"position": 1,
"optional": false,
"extra": {}
}]
}
}
List
Returns all the providers we operate with.
If a provider becomes disabled
, it is not included in the list.
You can read more about the next_id
field, in the pagination section of the reference.
Providers that require a client provider key will be included only if you have created provider keys for them.
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
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
URL
https://www.saltedge.com/api/v4/providers
https://www.saltedge.com/api/v4/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/v4/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/v4/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",
"forum_url": "https://www.saltedge.com/support_requests/new?provider_code=fakebank_image_xf",
"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": "2022-04-05T13:09:11Z",
"updated_at": "2022-04-10T13:09:11Z",
"timezone": "Europe/London",
"max_interactive_delay": 480,
"optional_interactivity": true,
"regulated": false,
"max_fetch_interval": 60,
"supported_fetch_scopes": ["accounts", "transactions"],
"supported_account_extra_fields": [],
"supported_transaction_extra_fields": [],
"supported_account_natures": ["account", "card"],
"supported_account_types": ["personal"],
"identification_codes": ["123123"],
"bic_codes": ["ABCDEFGH"],
"supported_iframe_embedding": true
}
],
"meta": {
"next_id": null,
"next_page": null
}
}
Fields
There are several types of fields as marked by their nature
attribute:
nature
string
Possible values are: text
, password
, select
, dynamic_select
, file
, number
. 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
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
Example object
{
"nature": "text",
"name": "login",
"english_name": "Username",
"localized_name": "Utilizator",
"optional": false,
"position": 1
}
Field options
Some providers ask their users to select a secret word or an answer to a question as a security measure. In this case, the provider will contain a field of select
type. The field will contain an array of field_options
objects, which describe the possible choices for the user.
name
string
The name of the field option
english_name
string
The option’s name in US English
localized_name
string
The name of the field in the provider’s main language
option_value
string
The value of the option that needs to be passed as credentials
selected
boolean
Whether the choice is selected by default
name
string
The name of the field option
english_name
string
The option’s name in US English
localized_name
string
The name of the field in the provider’s main language
option_value
string
The value of the option that needs to be passed as credentials
selected
boolean
Whether the choice is selected by default
Note: The options for dynamic_select
are not stored in the Provider, they are generated dynamically and sent in an Interactive callback.
Example object
{
"name": "home",
"english_name": "Home",
"localized_name": "Casa",
"option_value": "home",
"selected": true
}
Fake
In order to help 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 tofakebank_interactive_xf
, but with some of the interactive fields marked asoptional
;fakebank_api_with_fields_xf
- similar tofakebank_simple_xf
, used for ensuring API providers availability;fakebank_oauth_xf
- asks for authorization;fakebank_oauth_with_pending_xf
- similar tofakebank_oauth_xf
, returns pending transactions;fakebank_oauth_with_n_transactions_xf
- similar tofakebank_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 tofakebank_oauth_with_pending_xf
, having accounts, which have different values forbalance
andavailable_balance
;fakebank_with_possible_duplicates_xf
- each attempt generates a transactions with samemade_on
,amount
,currency_code
but differentdescription
. On second attempt and later it marks those transaction withextra[: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 asfakebank_simple_xf
;No Errors with Partial Data
- returns accounts and transactions, where partial flag is set totrue
;ExecutionTimeout
- no accounts and transactions, raises theExecutionTimeout
error;FetchingTimeout
- no accounts and transactions, raises theFetchingTimeout
error;ProviderUnavailable
- no accounts and transactions, raises theProviderUnavailable
error;ProviderError
- no accounts and transactions, raises error with a generic messageAn 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 to enter a fake captcha code in addition to a username and a password (embedded).fake_interactive_decoupled_client_xf
- decoupled interactive flow (e.g. push notification), asks to wait 10 seconds in Connect widget and then click Proceed to continue in addition to a username and a 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
Creates a customer, returning the customer object.
Parameters
identifier
string, required
A unique identifier of the new customer
identifier
string, required
A unique identifier of the new customer
Possible Errors
URL
https://www.saltedge.com/api/v4/customers
https://www.saltedge.com/api/v4/customers
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"identifier\": \"12rv1212f1efxchsdhbgv\" \
} \
}" \
https://www.saltedge.com/api/v4/customers
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"identifier\": \"12rv1212f1efxchsdhbgv\" \
} \
}" \
https://www.saltedge.com/api/v4/customers
Sample Response
{
"data": {
"id": "18892",
"identifier": "12rv1212f1efxchsdhbgv"
}
}
{
"data": {
"id": "18892",
"identifier": "12rv1212f1efxchsdhbgv",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8"
}
}
Show
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/v4/customers/{customer.id}
https://www.saltedge.com/api/v4/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/v4/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/v4/customers/18892
Sample Response
{
"data": {
"id": "18892",
"identifier": "12rv1212f1efxchsdhbgv",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8"
}
}
List
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/v4/customers
https://www.saltedge.com/api/v4/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/v4/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/v4/customers
Sample Response
{
"data": [
{
"id": "123",
"identifier": "unique_customer_identifier",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8"
},
{
"id": "124",
"identifier": "unique_customer_identifier_2",
"secret": "Ct124tk12j0129i10-1j2k124kgk1lgqvUJ8CIC80-8"
}
],
"meta": {
"next_id": "125",
"next_page": "/api/v4/customers?from_id=125"
}
}
Remove
Deletes a customer, returning the customer object. This route is available only for web applications.
Possible Errors
URL
https://www.saltedge.com/api/v4/customers/{customer.id}
https://www.saltedge.com/api/v4/customers/{customer.id}
Method
DELETE
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X DELETE \
https://www.saltedge.com/api/v4/customers/124
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X DELETE \
https://www.saltedge.com/api/v4/customers/124
Sample Response
{
"data": {
"deleted": true,
"id": "11215151"
}
}
Lock
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
URL
https://www.saltedge.com/api/v4/customers/{customer.id}/lock
https://www.saltedge.com/api/v4/customers/{customer.id}/lock
Method
PUT
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
https://www.saltedge.com/api/v4/customers/124/lock
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
https://www.saltedge.com/api/v4/customers/124/lock
Sample Response
{
"data": {
"locked": true,
"id": "124"
}
}
Unlock
Unlocks a customer and its data, returning the customer object. This route is available only for web applications.
Possible Errors
URL
https://www.saltedge.com/api/v4/customers/{customer.id}/unlock
https://www.saltedge.com/api/v4/customers/{customer.id}/unlock
Method
PUT
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
https://www.saltedge.com/api/v4/customers/124/unlock
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
https://www.saltedge.com/api/v4/customers/124/unlock
Sample Response
{
"data": {
"unlocked": true,
"id": "124"
}
}
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-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). 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
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 Salt Edge 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)
include_api_stages
boolean, optional
If sent as true
it will include api_stage
in javascript callbacks. This attribute shows detailed information of the fetching process. Possible values are attempts stages. Defaults to false
return_error_class
boolean, optional
Whether to append error_class
to return_to
URL. Defaults to false
theme
string, optional
Theme of Salt Edge Connect template. If not passed or available for the current template, will use default
. Allowed values: default
, dark
.
connect_template
string, optional
Template of Salt Edge Connect. If not passed or available for the current client, will use the default template.
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-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). 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
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 Salt Edge 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)
include_api_stages
boolean, optional
If sent as true
it will include api_stage
in javascript callbacks. This attribute shows detailed information of the fetching process. Possible values are attempts stages. Defaults to false
return_error_class
boolean, optional
Whether to append error_class
to return_to
URL. Defaults to false
theme
string, optional
Theme of Salt Edge Connect template. If not passed or available for the current template, will use default
. Allowed values: default
, dark
.
connect_template
string, optional
Template of Salt Edge Connect. If not passed or available for the current client, will use the default template.
Possible Errors
URL
https://www.saltedge.com/api/v4/tokens/create
https://www.saltedge.com/api/v4/tokens/create
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"5122311\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
} \
}" \
https://www.saltedge.com/api/v4/tokens/create
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
} \
}" \
https://www.saltedge.com/api/v4/tokens/create
Sample response
{
"data": {
"token": "GENERATED_TOKEN",
"expires_at": "2022-04-15T14:09:11Z",
"connect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
}
}
Reconnect
Allows you to create a token, which will be used to access Salt Edge Connect to reconnect a login.
You will receive a connect_url
field, which allows you to enter directly to Salt Edge Connect with your newly generated token.
Parameters
login_id
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-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). 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
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 Salt Edge side
override_credentials_strategy
string, optional
Possible values: ask
, override
. If sent as ask
, the user will be required to confirm the credentials override upon submitting the form, in the scenario 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)
include_api_stages
boolean, optional
If sent as true
it will include api_stage
in javascript callbacks. This attribute shows detailed information of the fetching process. Possible values are attempts stages. Defaults to false
return_error_class
boolean, optional
Whether to append error_class
to return_to
URL. Defaults to false
theme
string, optional
Theme of Salt Edge Connect template. If not passed or available for the current template, will use default
. Allowed values: default
, dark
.
connect_template
string, optional
Template of Salt Edge Connect. If not passed or available for the current client, will use the default template.
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-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). 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
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 Salt Edge side
override_credentials_strategy
string, optional
Possible values: ask
, override
. If sent as ask
, the user will be required to confirm the credentials override upon submitting the form, in the scenario 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)
include_api_stages
boolean, optional
If sent as true
it will include api_stage
in javascript callbacks. This attribute shows detailed information of the fetching process. Possible values are attempts stages. Defaults to false
return_error_class
boolean, optional
Whether to append error_class
to return_to
URL. Defaults to false
theme
string, optional
Theme of Salt Edge Connect template. If not passed or available for the current template, will use default
. Allowed values: default
, dark
.
connect_template
string, optional
Template of Salt Edge Connect. If not passed or available for the current client, will use the default template.
Possible Errors
URL
https://www.saltedge.com/api/v4/tokens/reconnect
https://www.saltedge.com/api/v4/tokens/reconnect
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"login_id\": \"123\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
} \
}" \
https://www.saltedge.com/api/v4/tokens/reconnect
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Login-secret: $LOGIN_SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
} \
}" \
https://www.saltedge.com/api/v4/tokens/reconnect
Sample response
{
"data": {
"token": "GENERATED_TOKEN",
"expires_at": "2022-04-15T14:09:11Z",
"connect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
}
}
Refresh
Allows you to create a token, which will be used to access Salt Edge Connect to refresh a login.
You will receive a connect_url
field, which allows you to enter directly to Salt Edge Connect with your newly generated token.
In some cases, refresh
will automatically call reconnect:
- refresh is called before the value specified in
next_refresh_possible_at
; next_refresh_possible_at
is null.
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-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). 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. It is taken into account only for PSD2-compliant providers. 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
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)
include_api_stages
boolean, optional
If sent as true
it will include api_stage
in javascript callbacks. This attribute shows detailed information of the fetching process. Possible values are attempts stages. Defaults to false
return_error_class
boolean, optional
Whether to append error_class
to return_to
URL. Defaults to false
theme
string, optional
Theme of Salt Edge Connect template. If not passed or available for the current template, will use default
. Allowed values: default
, dark
.
connect_template
string, optional
Template of Salt Edge Connect. If not passed or available for the current client, will use the default template.
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-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). 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. It is taken into account only for PSD2-compliant providers. 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
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)
include_api_stages
boolean, optional
If sent as true
it will include api_stage
in javascript callbacks. This attribute shows detailed information of the fetching process. Possible values are attempts stages. Defaults to false
return_error_class
boolean, optional
Whether to append error_class
to return_to
URL. Defaults to false
theme
string, optional
Theme of Salt Edge Connect template. If not passed or available for the current template, will use default
. Allowed values: default
, dark
.
connect_template
string, optional
Template of Salt Edge Connect. If not passed or available for the current client, will use the default template.
user_present
is used only for PSD2-compliant providers
and has nothing to do with prioritizing or speeding up the fetching of connections made via screen scraping or other technology. If user_present
is set to false, a limit of 4 background fetches will be enforced as per PSD2, all request that exceeds this limit will return a BackgroundFetchLimitExceeded
Possible Errors
URL
https://www.saltedge.com/api/v4/tokens/refresh
https://www.saltedge.com/api/v4/tokens/refresh
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"login_id\": \"123\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
} \
}" \
https://www.saltedge.com/api/v4/tokens/refresh
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Login-secret: $LOGIN_SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
} \
}" \
https://www.saltedge.com/api/v4/tokens/refresh
Sample response
{
"data": {
"token": "GENERATED_TOKEN",
"expires_at": "2022-04-15T14:09:11Z",
"connect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
}
}
OAuth Providers
Spectre API also allows your app to import data from a list of OAuth-supporting providers. The OAuth workflow, in this case, is reduced to a couple of HTTP calls and redirects.
Connecting OAuth providers logins is done via the same mechanism as when connecting a usual login - using tokens for connecting, reconnecting or refreshing.
The response will contain a redirect_url
and your app has to redirect the user to that URL.
The redirect_url
points to a page where the user can provide Salt Edge access to their financial data, making it available for your app.
After the user has approved Salt Edge in the OAuth provider’s interface, they will be redirected to the return_to
page.
Create
Used to create a login for an OAuth provider.
After receiving the response, the customer will be redirected to return_to
URL.
Note that mobile clients receive a login_secret
parameter in the return_to
URL if the login was successfully connected and 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
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-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). 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
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)
country_code
string, required
The code of the country
provider_code
string, required
The code of the provider
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-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). 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
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
URL
https://www.saltedge.com/api/v4/oauth_providers/create
https://www.saltedge.com/api/v4/oauth_providers/create
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"5125125\", \
\"country_code\": \"XF\", \
\"provider_code\": \"fakebank_oauth_xf\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
], \
\"return_to\": \"http://example.com/\", \
\"return_login_id\": false \
} \
}" \
https://www.saltedge.com/api/v4/oauth_providers/create
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"country_code\": \"XF\", \
\"provider_code\": \"fakebank_oauth_xf\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
], \
\"return_to\": \"http://example.com/\", \
\"return_login_id\": false \
} \
}" \
https://www.saltedge.com/api/v4/oauth_providers/create
Sample response
{
"data": {
"login_id": "123",
"login_secret": "secret",
"attempt_id": "456",
"token": "GENERATED_TOKEN",
"expires_at": "2022-04-15T14:09:11Z",
"redirect_url": "https://www.saltedge.com/api/v4/oauth_providers/redirect?token=GENERATED_TOKEN"
}
}
Reconnect
Used to reconnect a login for an OAuth provider.
After receiving the response, the customer will be redirected to the return_to
URL.
Note that mobile clients receive a login_secret
parameter in the return_to
URL and a error_message
parameter if the login failed to connect for some reason. 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-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). 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
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)
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-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). 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
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
URL
https://www.saltedge.com/api/v4/oauth_providers/reconnect
https://www.saltedge.com/api/v4/oauth_providers/reconnect
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"login_id\": \"123\", \
\"return_to\": \"http://example.com/\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
], \
\"return_login_id\": false \
} \
}" \
https://www.saltedge.com/api/v4/oauth_providers/reconnect
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Login-secret: $LOGIN_SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"return_to\": \"http://example.com/\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
], \
\"return_login_id\": false \
} \
}" \
https://www.saltedge.com/api/v4/oauth_providers/reconnect
Sample response
{
"data": {
"login_id": "123",
"login_secret": "secret",
"attempt_id": "456",
"token": "GENERATED_TOKEN",
"expires_at": "2022-04-15T14:09:11Z",
"redirect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
}
}
Refresh
Used to refresh a login for an OAuth provider.
After receiving the response, the customer will be redirected to return_to
URL.
Note that mobile clients receive a login_secret
parameter in the return_to
URL and a error_message
parameter if the login failed to connect for some reason. 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. It is taken into account only for PSD2-compliant providers. 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-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). 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
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)
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. It is taken into account only for PSD2-compliant providers. 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-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). 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
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)
user_present
is used only for PSD2-compliant providers
and has nothing to do with prioritizing or speeding up the fetching of connections made via screen scraping or other technology. If user_present
is set to false, a limit of 4 background fetches will be enforced as per PSD2, all request that exceeds this limit will return a BackgroundFetchLimitExceeded
Possible Errors
URL
https://www.saltedge.com/api/v4/oauth_providers/refresh
https://www.saltedge.com/api/v4/oauth_providers/refresh
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"login_id\": \"123\", \
\"return_to\": \"http://mobile.application\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
], \
\"return_login_id\": false \
} \
}" \
https://www.saltedge.com/api/v4/oauth_providers/refresh
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Login-secret: $LOGIN_SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"return_to\": \"http://mobile.application\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
], \
\"return_login_id\": false \
} \
}" \
https://www.saltedge.com/api/v4/oauth_providers/refresh
Sample response
{
"data": {
"login_id": "123",
"login_secret": "secret",
"attempt_id": "456",
"token": "GENERATED_TOKEN",
"expires_at": "2022-04-15T14:09:11Z",
"redirect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
}
}
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, only reconnected;The conditions when a login will have
inactive
status:- Any attempt that fails with
Invalid credentials
error will mark the login’s status toinactive
- Any attempt that fails with
Provider Unavailable
with one of the following error messages:Account blocked. Please, contact your provider.
Provider does not have any account records available at this time.
Provider asked to update your account settings.
No active accounts were found. Please, contact your provider.
Provider is disabled.
- Any attempt that fails with
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
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
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
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
Sample object
{
"country_code": "XF",
"created_at": "2022-04-14T13:09:11Z",
"customer_id": "905",
"daily_refresh": false,
"id": "1227",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"last_attempt": {
"api_mode": "service",
"api_version": "4",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": false,
"categorization": "personal",
"created_at": "2022-04-15T13:09:11Z",
"customer_last_logged_at": "2022-04-15T10:09:11Z",
"custom_fields": {},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [],
"identify_merchant": false,
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": ["accounts", "transactions"],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "425036",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2022-04-15T13:09:11Z",
"to_date": null,
"updated_at": "2022-04-15T13:09:11Z",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"include_natures": ["account", "card", "bonus"],
"last_stage": {
"created_at": "2022-04-15T13:09:11Z",
"id": "2691802",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2022-04-15T13:09:11Z"
}
},
"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": "2022-04-15T13:09:11Z",
"next_refresh_possible_at": "2022-04-15T14:09:11Z",
"provider_id": "1234",
"provider_code": "fakebank_simple_xf",
"provider_name": "Fakebank Simple",
"status": "active",
"store_credentials": true,
"updated_at": "2022-04-15T13:09:11Z"
}
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)
names
array
Account holder name(s)
emails
array
Account holder email(s)
phone_numbers
array
Account holder phone number(s)
addresses
array of objects
Account holder address(es)
Extra
Depending on provider, additional information on account holder might be available.
ssn
- Social Security Number shortened (last 4 digits)cpf
- Cadastro de Pessoas Físicas (present in Brazil)
Sample Object
{
"names": ["John Doe"],
"emails": ["john.doe@example.com", "johndoe@gmail.com"],
"phone_numbers": ["+40981233422"],
"addresses": [
{
"city": "Cupertino",
"state": "CA",
"street": "1 Infinite Loop",
"country_code": "US",
"post_code": "95014"
}
]
}
List
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 login which the list starts with
customer_id
string, optional
The id of the customer, allows to fetch logins only for a certain customer
from_id
string, optional
The id of the login which the list starts with
customer_id
string, optional
The id of the customer, allows to fetch logins only for a certain customer
Possible Errors
URL
https://www.saltedge.com/api/v4/logins
https://www.saltedge.com/api/v4/logins
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/v4/logins
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/v4/logins
Sample Response
{ "data":
[
{
"country_code": "XF",
"created_at": "2022-04-14T13:09:11Z",
"customer_id": "905",
"daily_refresh": false,
"id": "1227",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"last_attempt": {
"api_mode": "service",
"api_version": "4",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": false,
"categorization": "personal",
"created_at": "2022-04-15T12:29:11Z",
"customer_last_logged_at": "2022-04-15T10:09:11Z",
"custom_fields": {},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [],
"identify_merchant": false,
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": ["accounts", "transactions"],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "425036",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2022-04-15T12:29:11Z",
"to_date": null,
"updated_at": "2022-04-15T12:29:11Z",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"include_natures": ["account", "card", "bonus"],
"last_stage": {
"created_at": "2022-04-15T12:29:11Z",
"id": "2691802",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2022-04-15T12:29:11Z"
}
},
"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": "2022-04-15T12:29:11Z",
"next_refresh_possible_at": "2022-04-15T14:09:11Z",
"provider_id": "1234",
"provider_code": "fakebank_simple_xf",
"provider_name": "Fakebank Simple",
"status": "active",
"store_credentials": true,
"updated_at": "2022-04-15T12:29:11Z"
}
],
"meta" : {
"next_id": "1228",
"next_page": "/api/v4/logins?from_id=1228"
}
}
URL
https://www.saltedge.com/api/v4/logins/{login.id}
https://www.saltedge.com/api/v4/login
Method
GET
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v4/logins/1227
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 "Login-secret: $LOGIN_SECRET" \
-X GET \
https://www.saltedge.com/api/v4/login
Sample Response
{
"data": {
"country_code": "MD",
"created_at": "2014-10-24T20:09:02Z",
"customer_id": "905",
"daily_refresh": false,
"id": "1227",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"last_attempt": {
"api_mode": "service",
"api_version": "4",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": false,
"categorization": "personal",
"created_at": "2016-02-02T16:14:53Z",
"customer_last_logged_at": "2022-04-15T10:09:11Z",
"custom_fields": {},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [],
"identify_merchant": false,
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": ["accounts", "transactions"],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "425036",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2016-02-02T16:16:19Z",
"to_date": null,
"updated_at": "2016-02-02T16:16:19Z",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"include_natures": ["account", "card", "bonus"],
"last_stage": {
"created_at": "2016-02-02T16:16:19Z",
"id": "2691802",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2016-02-02T16:16:19Z"
}
},
"holder_info": {
"names": ["John Doe"],
"emails": ["john.doe@example.com", "johndoe@gmail.com"],
"phone_numbers": ["+40981233422"],
"addresses": [
{
"city": "Cupertino",
"state": "CA",
"street": "1 Infinite Loop",
"country_code": "US",
"post_code": "95014"
}
]
},
"last_success_at": "2016-02-02T16:16:19Z",
"next_refresh_possible_at": "2016-02-02T17:16:19Z",
"provider_id": "1234",
"provider_code": "moldindconbank_wb_md",
"provider_name": "Moldindconbank Web Banking",
"status": "active",
"store_credentials": true,
"updated_at": "2016-02-04T09:41:23Z"
}
}
Create
When not using Salt Edge Connect, your app will have to pass the user’s values of provider’s fields within the payload.
The credentials object should be modeled after the provider’s fields.
For instance, if the provider’s required fields contain a field with the value of name
equal to username
, the credential object should contain a username
attribute with the value being the actual username.
For example, here’s a provider:
{
"data": {
"code": "bigbank_us",
"required_fields": [
{
"english_name": "Pass Code",
"localized_name": "Pass Code",
"name": "code",
"nature": "text",
"position": 1
}
]
}
}
The user should be prompted to input their Pass Code.
If they input their Pass Code (in this case, the user has input “hunter2”), your app should send the following data in the credentials
object:
{
"code": "hunter2"
}
Here’s another example that includes a select:
{
"data": {
"code": "anotherbank_us",
"required_fields": [
{
"english_name": "Password",
"localized_name": "Password",
"name": "password",
"nature": "password",
"position": 1
},
{
"nature": "select",
"name": "image",
"english_name": "Image",
"localized_name": "Imagine",
"position": 2,
"optional": false,
"field_options": [
{
"name": "1",
"english_name": "Home",
"localized_name": "Casa",
"option_value": "home",
"selected": false
},
{
"name": "2",
"english_name": "Car",
"localized_name": "Automobil",
"option_value": "car",
"selected": false
}
]
}
]
}
}
In this case, your app should prompt the user to input their Password and offer them a select with the options of “Casa” and “Automobil” (the localized_name
or english_name
values, depending on your service).
The credentials should contain the name of the 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, optional
The ID of the customer
country_code
string, required
The country code of the desired provider
provider_code
string, required
The code of the desired provider
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-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). Defaults to en
.
include_fake_providers
boolean, optional
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 Salt Edge 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)
customer_id
string, optional
The ID of the customer
country_code
string, required
The country code of the desired provider
provider_code
string, required
The code of the desired provider
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-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). Defaults to en
.
include_fake_providers
boolean, optional
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 Salt Edge 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
URL
https://www.saltedge.com/api/v4/logins
https://www.saltedge.com/api/v4/login
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"905\", \
\"country_code\": \"XF\", \
\"provider_code\": \"fakebank_simple_xf\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
], \
\"credentials\": { \
\"login\": \"username\", \
\"password\": \"secret\" \
} \
} \
}" \
https://www.saltedge.com/api/v4/logins
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"country_code\": \"XF\", \
\"provider_code\": \"fakebank_simple_xf\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
], \
\"credentials\": { \
\"login\": \"username\", \
\"password\": \"secret\" \
} \
} \
}" \
https://www.saltedge.com/api/v4/login
Sample request (with encrypted credentials)
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"905\", \
\"country_code\": \"XF\", \
\"provider_code\": \"fakebank_simple_xf\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
], \
\"encrypted_credentials\": { \
\"algorithm\": \"AES-256-CBC\", \
\"key\": \"Yir+HThidKxlpqA...\", \
\"iv\": \"JEhn/N5oK9s0U1L...\", \
\"data\": \"S8XD2kHCPsIQj+x...\", \
\"version\": \"your_key_version\" \
} \
} \
}" \
https://www.saltedge.com/api/v4/logins
Sample request (with file providers)
curl -v -include \
-H "Accept: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-F "file=@file.ofx" \
-F "data[provider_code]=ofx_xo" \
-F "data[country_code]=XO" \
-F "data[fetch_scopes][]=accounts" \
-F "data[customer_id]=995" \
https://www.saltedge.com/api/v4/logins
curl -v -include \
-H "Accept: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-F "file=@file.ofx" \
-F "data[provider_code]=ofx_xo" \
-F "data[country_code]=XO" \
-F "data[fetch_scopes][]=accounts" \
https://www.saltedge.com/api/v4/login
Sample request (with file providers, using file_url)
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"905\", \
\"country_code\": \"XO\", \
\"provider_code\": \"mint_csv_xo\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
], \
\"file_url\": \"http://spatialkeydocs.s3.amazonaws.com/FL_insurance_sample.csv\" \
} \
}" \
https://www.saltedge.com/api/v4/logins
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"country_code\": \"XO\", \
\"provider_code\": \"mint_csv_xo\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
], \
\"file_url\": \"http://spatialkeydocs.s3.amazonaws.com/FL_insurance_sample.csv\" \
} \
}" \
https://www.saltedge.com/api/v4/login
Sample response
{
"data": {
"country_code": "XF",
"created_at": "2022-04-14T13:09:11Z",
"customer_id": "905",
"daily_refresh": false,
"id": "1227",
"show_consent_confirmation": false,
"consent_types": null,
"consent_period_days": null,
"consent_given_at": null,
"consent_expires_at": null,
"last_attempt": {
"api_mode": "service",
"api_version": "4",
"automatic_fetch": true,
"user_present": true,
"daily_refresh": false,
"categorization": "personal",
"created_at": "2022-04-15T12:29:11Z",
"customer_last_logged_at": "2022-04-15T10:09:11Z",
"custom_fields": {},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [],
"identify_merchant": false,
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": ["accounts", "transactions"],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "425036",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2022-04-15T12:29:11Z",
"to_date": null,
"updated_at": "2022-04-15T12:29:11Z",
"show_consent_confirmation": false,
"consent_types": null,
"consent_period_days": null,
"consent_given_at": null,
"consent_expires_at": null,
"include_natures": ["account", "card", "bonus"],
"last_stage": {
"created_at": "2022-04-15T12:29:11Z",
"id": "2691802",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2022-04-15T12:29:11Z"
}
},
"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": "2022-04-15T12:29:11Z",
"next_refresh_possible_at": "2022-04-15T14:09:11Z",
"provider_id": "1234",
"provider_code": "fakebank_simple_xf",
"provider_name": "Fakebank Simple",
"status": "active",
"store_credentials": true,
"updated_at": "2022-04-15T12:29:11Z"
}
}
{
"data": {
"country_code": "XF",
"created_at": "2022-04-14T13:09:11Z",
"daily_refresh": false,
"id": "1227",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"show_consent_confirmation": false,
"consent_types": null,
"consent_period_days": null,
"consent_given_at": null,
"consent_expires_at": null,
"last_attempt": {
"api_mode": "services",
"api_version": "4",
"automatic_fetch": true,
"user_present": true,
"daily_refresh": false,
"categorization": "personal",
"created_at": "2022-04-15T12:29:11Z",
"customer_last_logged_at": "2022-04-15T10:09:11Z",
"custom_fields": {},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [],
"identify_merchant": false,
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": ["accounts", "transactions"],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "425036",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2022-04-15T12:29:11Z",
"to_date": null,
"updated_at": "2022-04-15T12:29:11Z",
"show_consent_confirmation": false,
"consent_types": null,
"consent_period_days": null,
"consent_given_at": null,
"consent_expires_at": null,
"include_natures": ["account", "card", "bonus"],
"last_stage": {
"created_at": "2022-04-15T12:29:11Z",
"id": "2691802",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2022-04-15T12:29:11Z"
}
},
"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": "2022-04-15T12:29:11Z",
"next_refresh_possible_at": "2022-04-15T14:09:11Z",
"provider_id": "1234",
"provider_code": "fakebank_simple_xf",
"provider_name": "Fakebank Simple",
"status": "active",
"store_credentials": true,
"updated_at": "2022-04-15T12:29:11Z"
}
}
Reconnect
In order to Reconnect a login, your app needs to send just a credentials object and the login’s id.
Parameters
credentials
object, required 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
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']
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.
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
locale
string, optional
The language of the provider error messages in the ISO 639-1 format. Possible values are: bg
, cz
, de
, en
, es-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). Defaults to en
.
exclude_accounts
array of strings, optional
Array of account IDs which will not be fetched. Defaults to empty array
include_fake_providers
boolean, optional
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 Salt Edge side. Default value: true
.
Note: The usage of this flag is not available for file
providers. In order to update the login, reconnect is required. It will not be possible to use refresh option if store_credentials
is set to false
file_url
string, optional
URL of a file. Is used when creating a login for a provider with mode file
override_credentials
boolean, optional
If sent as true
, new credentials will automatically override the old ones, in the scenario were the new credentials are different from the ones in the previous attempt. Default: 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)
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
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']
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.
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
locale
string, optional
The language of the provider error messages in the ISO 639-1 format. Possible values are: bg
, cz
, de
, en
, es-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). Defaults to en
.
exclude_accounts
array of strings, optional
Array of account IDs which will not be fetched. Defaults to empty array
include_fake_providers
boolean, optional
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 Salt Edge side. Default value: true
.
Note: The usage of this flag is not available for file
providers. In order to update the login, reconnect is required. It will not be possible to use refresh option if store_credentials
is set to false
file_url
string, optional
URL of a file. Is used when creating a login for a provider with mode file
override_credentials
boolean, optional
If sent as true
, new credentials will automatically override the old ones, in the scenario were the new credentials are different from the ones in the previous attempt. Default: 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)
Response
A complete Login object.
Possible Errors
URL
https://www.saltedge.com/api/v4/logins/{login.id}/reconnect
https://www.saltedge.com/api/v4/login/reconnect
Method
PUT
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"credentials\": { \
\"login\": \"username\", \
\"password\": \"secret\" \
}, \
\"override_credentials\": true \
} \
}" \
https://www.saltedge.com/api/v4/logins/1227/reconnect
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Login-secret: $LOGIN_SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"credentials\": { \
\"login\": \"username\", \
\"password\": \"secret\" \
}, \
\"override_credentials\": true \
} \
}" \
https://www.saltedge.com/api/v4/login/reconnect
Sample request (with encrypted credentials)
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"encrypted_credentials\": { \
\"algorithm\": \"AES-256-CBC\", \
\"key\": \"Yir+HThidKxlpqA...\", \
\"iv\": \"JEhn/N5oK9s0U1L...\", \
\"data\": \"S8XD2kHCPsIQj+x...\", \
\"version\": \"your_key_version\" \
} \
} \
}" \
https://www.saltedge.com/api/v4/logins/1227/reconnect
Sample request (with file providers)
curl -v -include \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-F "file=@file.ofx" \
https://www.saltedge.com/api/v4/logins/1227/reconnect
curl -v -include \
-H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Login-secret: $LOGIN_SECRET" \
-F "file=@file.ofx" \
https://www.saltedge.com/api/v4/login/reconnect
Sample response
{
"data": {
"country_code": "XF",
"created_at": "2022-04-14T13:09:11Z",
"customer_id": "905",
"daily_refresh": false,
"id": "1227",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"last_attempt": {
"api_mode": "service",
"api_version": "4",
"automatic_fetch": true,
"user_present": true,
"daily_refresh": true,
"categorization": "personal",
"created_at": "2022-04-15T12:29:11Z",
"customer_last_logged_at": "2022-04-15T10:09:11Z",
"custom_fields": {},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [],
"identify_merchant": false
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": ["accounts", "transactions"],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "425036",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2022-04-15T12:29:11Z",
"to_date": null,
"updated_at": "2022-04-15T12:29:11Z",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"include_natures": ["account", "card", "bonus"],
"last_stage": {
"created_at": "2022-04-15T12:29:11Z",
"id": "2691802",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2022-04-15T12:29:11Z"
}
},
"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": "2022-04-15T12:29:11Z",
"next_refresh_possible_at": "2022-04-15T14:09:11Z",
"provider_id": "1234",
"provider_code": "fakebank_simple_xf",
"provider_name": "Fakebank Simple",
"status": "active",
"store_credentials": true,
"updated_at": "2022-04-15T12:29:11Z"
}
}
Interactive
If the currently fetching login requires any interactive credentials for fetching, Salt Edge will send the Interactive callback.
Upon receiving the interactive callback, your app should ask the user for the interactive credentials and send them to the /interactive
route for the login. After that, the fetching process will continue as usual.
In case of dynamic_select
field nature, when it has extra: { multiple: true }
flag - send the option_value
of the user selected options in an Array
of strings:
{
"data": {
"credentials": {
"accounts": ["account1", "account2"]
}
}
}
In case of dynamic_select
field nature, when it has extra: { multiple: false }
flag - send the option_value
of the user selected option as a single String
:
{
"data": {
"credentials": {
"language": "english"
}
}
}
Please note that in some cases (e.g. when fetching Fake Bank with SMS logins), on interactive stage provider may not require any interactive fields (see interactive_fields_names
), thus you should send an empty object in the credentials field:
{
"data": {
"credentials": {}
}
}
Parameters
credentials
object, required unless encrypted_credentials are present
The credentials object based on the provider’s interactive fields
encrypted_credentials
object, required unless credentials are present
The encrypted credentials required to access the data, based on provider’s interactive fields
credentials
object, required unless encrypted_credentials are present
The credentials object based on the provider’s interactive fields
encrypted_credentials
object, required unless credentials are present
The encrypted credentials required to access the data, based on provider’s interactive fields
Response
A complete Login object.
Possible Errors
URL
https://www.saltedge.com/api/v4/logins/{login.id}/interactive
https://www.saltedge.com/api/v4/login/interactive
Method
PUT
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"credentials\": { \
\"sms\": \"AB123\" \
} \
} \
}" \
https://www.saltedge.com/api/v4/logins/1227/interactive
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Login-secret: $LOGIN_SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"credentials\": { \
\"sms\": \"AB123\" \
} \
} \
}" \
https://www.saltedge.com/api/v4/login/interactive
Sample request (with encrypted credentials)
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"encrypted_credentials\": { \
\"algorithm\": \"AES-256-CBC\", \
\"key\": \"Yir+HThidKxlpqA...\", \
\"iv\": \"JEhn/N5oK9s0U1L...\", \
\"data\": \"S8XD2kHCPsIQj+x...\", \
\"version\": \"your_key_version\" \
} \
} \
}" \
https://www.saltedge.com/api/v4/logins/1227/interactive
Sample response
{
"data": {
"country_code": "XF",
"created_at": "2022-04-14T13:09:11Z",
"customer_id": "905",
"daily_refresh": false,
"id": "1227",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"last_attempt": {
"api_mode": "service",
"api_version": "4",
"automatic_fetch": false,
"user_present": false,
"daily_refresh": false,
"categorization": "personal",
"created_at": "2022-04-15T12:29:11Z",
"customer_last_logged_at": "2022-04-15T10:09:11Z",
"custom_fields": {},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [],
"identify_merchant": false,
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": ["accounts", "transactions"],
"finished": false,
"finished_recent": false,
"from_date": null,
"id": "425036",
"interactive": true,
"locale": "en",
"partial": true,
"store_credentials": true,
"success_at": "2022-04-15T12:29:11Z",
"to_date": null,
"updated_at": "2022-04-15T12:29:11Z",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"include_natures": ["account", "card", "bonus"],
"last_stage": {
"created_at": "2022-04-15T12:29:11Z",
"id": "2691802",
"interactive_fields_names": ["sms"],
"interactive_html": "<input type="text" name="sms" placeholder="Sms">",
"name": "interactive",
"updated_at": "2022-04-15T12:29:11Z"
}
},
"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": "2022-04-15T12:29:11Z",
"next_refresh_possible_at": "2022-04-15T14:09:11Z",
"provider_id": "1234",
"provider_code": "fakebank_interactive_xf",
"provider_name": "Fake Bank with SMS",
"status": "active",
"updated_at": "2022-04-15T12:29:11Z"
}
}
Refresh
Lets you trigger a refetch of the data associated with a specific Login.
Note that you can refresh a login once in every 60 minutes.
If the response is successful, it will contain the next_refresh_possible_at
value and you can expect the usual callbacks of the fetching workflow.
Parameters
daily_refresh
boolean, optional
Whether the login should be automatically refreshed by Salt Edge
user_present
boolean, optional
Whether the request was initiated by the end user of your application. It is taken into account only for PSD2-compliant providers. 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']
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.
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
locale
string, optional
The language of the provider error messages in the ISO 639-1 format. Possible values are: bg
, cz
, de
, en
, es-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). Defaults to en
.
exclude_accounts
array of strings, optional
Array of account IDs which will not be fetched. Defaults to empty array
include_fake_providers
boolean, optional
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 Salt Edge 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
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)
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. It is taken into account only for PSD2-compliant providers. 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']
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.
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
locale
string, optional
The language of the provider error messages in the ISO 639-1 format. Possible values are: bg
, cz
, de
, en
, es-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). Defaults to en
.
exclude_accounts
array of strings, optional
Array of account IDs which will not be fetched. Defaults to empty array
include_fake_providers
boolean, optional
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 Salt Edge 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
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)
user_present
is used only for PSD2-compliant providers
and has nothing to do with prioritizing or speeding up the fetching of connections made via screen scraping or other technology. If user_present
is set to false, a limit of 4 background fetches will be enforced as per PSD2, all request that exceeds this limit will return a BackgroundFetchLimitExceeded
Possible Errors
- AllAccountsExcluded
- BackgroundFetchLimitExceeded
- ClientDisabled
- ClientNotFound
- ClientRestricted
- DateTimeFormatInvalid
- DateTimeOutOfRange
- FetchScopesNotAllowed
- InvalidFromDate
- InvalidToDate
- JsonParseError
- LoginCannotBeRefreshed
- LoginDisabled
- LoginFetchingStopped
- LoginNotFound
- ProviderDisabled
- ProviderInactive
- RateLimitExceeded
URL
https://www.saltedge.com/api/v4/logins/{login.id}/refresh
https://www.saltedge.com/api/v4/login/refresh
Method
PUT
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
} \
}" \
https://www.saltedge.com/api/v4/logins/1227/refresh
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Login-secret: $LOGIN_SECRET" \
-X PUT \
-d "{ \
\"data\": { \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
} \
}" \
https://www.saltedge.com/api/v4/login/refresh
Sample Response
{
"data": {
"country_code": "MD",
"created_at": "2014-10-24T20:09:02Z",
"customer_id": "905",
"daily_refresh": false,
"id": "1227",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"last_attempt": {
"api_mode": "service",
"api_version": "4",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": true,
"categorization": "personal",
"created_at": "2016-02-02T16:14:53Z",
"customer_last_logged_at": "2022-04-15T10:09:11Z",
"custom_fields": {},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [],
"identify_merchant": false,
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": ["accounts", "transactions"],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "425036",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2016-02-02T16:16:19Z",
"to_date": null,
"updated_at": "2016-02-02T16:16:19Z",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"include_natures": ["account", "card", "bonus"],
"last_stage": {
"created_at": "2016-02-02T16:16:19Z",
"id": "2691802",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2016-02-02T16:16:19Z"
}
},
"holder_info": {
"names": ["John Doe"],
"emails": ["john.doe@example.com", "johndoe@gmail.com"],
"phone_numbers": ["+40981233422"],
"addresses": [
{
"city": "Cupertino",
"state": "CA",
"street": "1 Infinite Loop",
"country_code": "US",
"post_code": "95014"
}
]
},
"last_success_at": "2016-02-02T16:16:19Z",
"next_refresh_possible_at": "2016-02-02T17:16:19Z",
"provider_id": "1234",
"provider_code": "moldindconbank_wb_md",
"provider_name": "Moldindconbank Web Banking",
"status": "active",
"store_credentials": true,
"updated_at": "2016-02-04T09:41:23Z"
}
}
Remove
Removes a login from our system. All the associated accounts and transactions to that login will be destroyed as well. Salt Edge will send a destroy callback to your web application.
Possible Errors
URL
https://www.saltedge.com/api/v4/logins/{login.id}
https://www.saltedge.com/api/v4/login
Method
DELETE
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X DELETE \
https://www.saltedge.com/api/v4/logins/1227
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 "Login-secret: $LOGIN_SECRET" \
-X DELETE \
https://www.saltedge.com/api/v4/login
Sample Response
{
"data": {
"id": "1227",
"removed": true
}
}
Inactivate
Marks a login from the system as inactive. In order to activate the login, you have to perform a successful reconnect.
Possible Errors
URL
https://www.saltedge.com/api/v4/logins/{login.id}/inactivate
https://www.saltedge.com/api/v4/login/inactivate
Method
PUT
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
https://www.saltedge.com/api/v4/logins/1227/inactivate
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 "Login-secret: $LOGIN_SECRET" \
-X PUT \
https://www.saltedge.com/api/v4/login/inactivate
Sample Response
{
"data": {
"country_code": "MD",
"created_at": "2014-10-24T20:09:02Z",
"customer_id": "905",
"daily_refresh": false,
"id": "1227",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"last_attempt": {
"api_mode": "service",
"api_version": "4",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": false,
"categorization": "personal",
"created_at": "2016-02-02T16:14:53Z",
"customer_last_logged_at": "2022-04-15T10:09:11Z",
"custom_fields": {},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [],
"identify_merchant": false,
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": ["accounts", "transactions"],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "425036",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2016-02-02T16:16:19Z",
"to_date": null,
"updated_at": "2016-02-02T16:16:19Z",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"include_natures": ["account", "card", "bonus"],
"last_stage": {
"created_at": "2016-02-02T16:16:19Z",
"id": "2691802",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2016-02-02T16:16:19Z"
}
},
"holder_info": {
"names": ["John Doe"],
"emails": ["john.doe@example.com", "johndoe@gmail.com"],
"phone_numbers": ["+40981233422"],
"addresses": [
{
"city": "Cupertino",
"state": "CA",
"street": "1 Infinite Loop",
"country_code": "US",
"post_code": "95014"
}
]
},
"last_success_at": "2016-02-02T16:16:19Z",
"next_refresh_possible_at": "2016-02-02T17:16:19Z",
"provider_id": "1234",
"provider_code": "moldindconbank_wb_md",
"provider_name": "Moldindconbank Web Banking",
"status": "inactive",
"store_credentials": true,
"updated_at": "2016-02-04T09:41:23Z"
}
}
Destroy credentials
Destroys credentials of the login.
Possible Errors
URL
https://www.saltedge.com/api/v4/logins/{login.id}/destroy_credentials
https://www.saltedge.com/api/v4/login/destroy_credentials
Method
PUT
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
https://www.saltedge.com/api/v4/logins/1227/destroy_credentials
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 "Login-secret: $LOGIN_SECRET" \
-X PUT \
https://www.saltedge.com/api/v4/login/destroy_credentials
Sample Response
{
"data": {
"country_code": "MD",
"created_at": "2014-10-24T20:09:02Z",
"customer_id": "905",
"daily_refresh": false,
"id": "1227",
"secret": "AtQX6Q8vRyMrPjUVtW7J_O1n06qYQ25bvUJ8CIC80-8",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"last_attempt": {
"api_mode": "service",
"api_version": "4",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": false,
"categorization": "personal",
"created_at": "2016-02-02T16:14:53Z",
"customer_last_logged_at": "2022-04-15T10:09:11Z",
"custom_fields": {},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [],
"identify_merchant": false,
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": ["accounts", "transactions"],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "425036",
"interactive": false,
"locale": "en",
"partial": false,
"store_credentials": true,
"success_at": "2016-02-02T16:16:19Z",
"to_date": null,
"updated_at": "2016-02-02T16:16:19Z",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"include_natures": ["account", "card", "bonus"],
"last_stage": {
"created_at": "2016-02-02T16:16:19Z",
"id": "2691802",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2016-02-02T16:16:19Z"
}
},
"holder_info": {
"names": ["John Doe"],
"emails": ["john.doe@example.com", "johndoe@gmail.com"],
"phone_numbers": ["+40981233422"],
"addresses": [
{
"city": "Cupertino",
"state": "CA",
"street": "1 Infinite Loop",
"country_code": "US",
"post_code": "95014"
}
]
},
"last_success_at": "2016-02-02T16:16:19Z",
"next_refresh_possible_at": null,
"provider_id": "1234",
"provider_code": "moldindconbank_wb_md",
"provider_name": "Moldindconbank Web Banking",
"status": "inactive",
"store_credentials": false,
"updated_at": "2016-02-04T09:41:23Z"
}
}
Attempts
The attempt resource represents a detailed description of a particular login connection attempt. They are meant to provide you with more information about the established connections for further usage in technical and statistical purposes.
Attributes
api_mode
string
The API mode of the customer that queried the API. Possible values: app
, service
api_version
string
The API version in which the attempt was created
automatic_fetch
boolean
Whether the login related to the attempt can be automatically fetched
daily_refresh
boolean
Latest assigned value for daily_refresh in login
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 login/token/oauth_provider
device_type
string
The type of the device that created the attempt. Possible values: desktop
, tablet
, mobile
remote_ip
string
The ip of the device that created the attempt
exclude_accounts
array of strings
The IDs of accounts that do not need to be refreshed
identify_merchant
boolean
Whether merchant identification was enabled
user_present
boolean
Whether the request was initiated by the end user of your application.
customer_last_logged_at
datetime
The datetime when user was last active in your application
fail_at
datetime
When the attempt failed to finish
fail_error_class
string
Class of error that triggered the fail for attempt
fail_message
string
Message that describes the error class
fetch_scopes
array of strings, required
Fetching mode, possible values: ['accounts']
, ['holder_info']
, ['accounts', 'holder_info']
, ['accounts', 'transactions']
, ['accounts', 'holder_info', 'transactions']
finished
boolean
Whether the login had finished fetching
finished_recent
boolean
Whether the login had finished data for recent range (2 months)
from_date
date
Date from which the data had been fetched
id
string
interactive
boolean
Whether the login related to the attempt is interactive
locale
string
The language of the provider error messages in the ISO 639-1 format. Possible values are: bg
, cz
, de
, en
, es-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). Defaults to en
.
partial
boolean
Whether the login was partially fetched
store_credentials
boolean
Whether the credentials were stored on our side
success_at
datetime
When the attempt succeeded and finished
to_date
date
Date until which the data has been fetched
updated_at
datetime
When last attempt update occured
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
include_natures
array of strings
The natures of the accounts that need to be fetched
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 login related to the attempt can be automatically fetched
daily_refresh
boolean
Latest assigned value for daily_refresh in login
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 login/token/oauth_provider
device_type
string
The type of the device that created the attempt. Possible values: desktop
, tablet
, mobile
remote_ip
string
The ip of the device that created the attempt
exclude_accounts
array of strings
The IDs of accounts that do not need to be refreshed
identify_merchant
boolean
Whether merchant identification was enabled
user_present
boolean
Whether the request was initiated by the end user of your application.
customer_last_logged_at
datetime
The datetime when user was last active in your application
fail_at
datetime
When the attempt failed to finish
fail_error_class
string
Class of error that triggered the fail for attempt
fail_message
string
Message that describes the error class
fetch_scopes
array of strings, required
Fetching mode, possible values: ['accounts']
, ['holder_info']
, ['accounts', 'holder_info']
, ['accounts', 'transactions']
, ['accounts', 'holder_info', 'transactions']
finished
boolean
Whether the login had finished fetching
finished_recent
boolean
Whether the login had finished data for recent range (2 months)
from_date
date
Date from which the data had been fetched
id
string
interactive
boolean
Whether the login related to the attempt is interactive
locale
string
The language of the provider error messages in the ISO 639-1 format. Possible values are: bg
, cz
, de
, en
, es-MX
, es
, fi
, fr
, he
, hr
, hu
, it
, nl
, pl
, pt-BR
, pt
, ro
, ru
, si
, sk
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). Defaults to en
.
partial
boolean
Whether the login was partially fetched
store_credentials
boolean
Whether the credentials were stored on our side
success_at
datetime
When the attempt succeeded and finished
to_date
date
Date until which the data has been fetched
updated_at
datetime
When last attempt update occured
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
include_natures
array of strings
The natures of the accounts that need to be fetched
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": "4",
"automatic_fetch": true,
"user_present": false,
"categorization": "personal",
"created_at": "2022-04-15T11:09:11Z",
"customer_last_logged_at": "2022-04-15T10:09:11Z",
"custom_fields": {},
"daily_refresh": false,
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [],
"identify_merchant": false,
"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,
"store_credentials": true,
"success_at": "2022-04-15T12:09:11Z",
"to_date": null,
"updated_at": "2022-04-15T12:09:11Z",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"include_natures": ["account", "card", "bonus"],
"last_stage": {
"created_at": "2022-04-15T12:09:11Z",
"id": "2094640",
"interactive_fields_name": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2022-04-15T12:09:11Z"
}
}
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
interactive_fields_names
array of strings
The interactive fields that are currently required by the provider of the login. Appears only for interactive logins
interactive_html
string
HTML code that shows the current interactive state of the login. Appears only for interactive logins
name
string
The name of the stage. Possible values: start
, connect
, interactive
, fetch_holder_info
, fetch_accounts
, fetch_recent
, fetch_full
, disconnect
, finish
updated_at
datetime
When the stage was last updated
created_at
datetime
When the stage was created
id
string
interactive_fields_names
array of strings
The interactive fields that are currently required by the provider of the login. Appears only for interactive logins
interactive_html
string
HTML code that shows the current interactive state of the login. Appears only for interactive logins
name
string
The name of the stage. Possible values: start
, connect
, interactive
, fetch_holder_info
, fetch_accounts
, fetch_recent
, fetch_full
, disconnect
, finish
updated_at
datetime
When the stage was last updated
List
Returns a paginated list of all attempts for a certain login.
Parameters
login_id
string
The ID of the login whose attempts are to be fetched
URL
https://www.saltedge.com/api/v4/attempts?login_id={login.id}
https://www.saltedge.com/api/v4/attempts
Method
GET
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v4/attempts?login_id=47872
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 "Login-secret: $LOGIN_SECRET" \
-X GET \
https://www.saltedge.com/api/v4/attempts
Sample response
{
"data": {
[
{
"api_mode": "service",
"api_version": "4",
"automatic_fetch": true,
"user_present": false,
"categorization": "personal",
"created_at": "2022-04-15T11:09:11Z",
"customer_last_logged_at": "2022-04-15T10:09:11Z",
"custom_fields": {},
"device_type": "desktop",
"daily_refresh": false,
"remote_ip": "93.184.216.34",
"exclude_accounts": [],
"identify_merchant": false,
"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,
"store_credentials": true,
"success_at": "2022-04-15T12:09:11Z",
"to_date": null,
"updated_at": "2022-04-15T12:09:11Z",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"include_natures": ["account", "card", "bonus"],
"last_stage": {
"created_at": "2022-04-15T12:09:11Z",
"id": "2094640",
"interactive_fields_name": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2022-04-15T12:09:11Z"
}
}
]
},
"meta": {
"next_id": "337520",
"next_page": "/api/v4/attempts?login_id=47872&from_id=337520"
}
}
{
"data": {
[
{
"api_mode": "app",
"api_version": "4",
"automatic_fetch": true,
"user_present": false,
"categorization": "personal",
"created_at": "2022-04-15T11:09:11Z",
"customer_last_logged_at": "2022-04-15T10:09:11Z",
"custom_fields": {},
"device_type": "desktop",
"daily_refresh": false,
"remote_ip": "93.184.216.34",
"exclude_accounts": [],
"identify_merchant": false,
"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,
"store_credentials": true,
"success_at": "2022-04-15T12:09:11Z",
"to_date": null,
"updated_at": "2022-04-15T12:09:11Z",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"include_natures": ["account", "card", "bonus"],
"last_stage": {
"created_at": "2022-04-15T12:09:11Z",
"id": "2094640",
"interactive_fields_name": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2022-04-15T12:09:11Z"
}
}
]
},
"meta": {
"next_id": "337520",
"next_page": "/api/v4/attempts?from_id=337520"
}
}
Show
Returns a single attempt object.
Parameters
login_id
string
The ID of the login whose attempts are to be fetched
login_id
string
The ID of the login whose attempts are to be fetched
URL
https://www.saltedge.com/api/v4/attempts/{attempt.id}?login_id={login.id}
https://www.saltedge.com/api/v4/attempts/{attempt.id}
Method
GET
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v4/attempts/340?login_id=47872
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 "Login-secret: $LOGIN_SECRET" \
-X GET \
https://www.saltedge.com/api/v4/attempts/340
Sample response
{
"data": {
"api_mode": "service",
"api_version": "4",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": false,
"categorization": "personal",
"created_at": "2022-04-15T11:09:11Z",
"customer_last_logged_at": "2022-04-15T10:09:11Z",
"custom_fields": {},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [],
"identify_merchant": false,
"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,
"store_credentials": true,
"success_at": "2022-04-15T12:09:11Z",
"to_date": null,
"updated_at": "2022-04-15T12:09:11Z",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"include_natures": ["account", "card", "bonus"],
"stages": [
{
"created_at": "2022-04-15T11:09:11Z",
"id": "17676",
"interactive_fields_names": null,
"interactive_html": null,
"name": "start",
"updated_at": "2022-04-15T11:09:11Z"
},
{
"created_at": "2022-04-15T11:19:11Z",
"id": "17677",
"interactive_fields_names": null,
"interactive_html": null,
"name": "connect",
"updated_at": "2022-04-15T11:19:11Z"
},
{
"created_at": "2022-04-15T12:09:11Z",
"id": "17681",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2022-04-15T12:09:11Z"
}
]
}
}
{
"data": {
"api_mode": "app",
"api_version": "4",
"automatic_fetch": true,
"user_present": false,
"daily_refresh": false,
"categorization": "personal",
"created_at": "2022-04-15T11:09:11Z",
"customer_last_logged_at": "2022-04-15T10:09:11Z",
"custom_fields": {},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"exclude_accounts": [],
"identify_merchant": false,
"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,
"store_credentials": true,
"success_at": "2022-04-15T12:09:11Z",
"to_date": null,
"updated_at": "2022-04-15T12:09:11Z",
"show_consent_confirmation": true,
"consent_types": ["account_information"],
"consent_period_days": 10,
"consent_given_at": "2022-04-15T13:09:11Z",
"consent_expires_at": "2022-04-25T13:09:11Z",
"include_natures": ["account", "card", "bonus"],
"stages": [
{
"created_at": "2022-04-15T11:09:11Z",
"id": "17676",
"interactive_fields_names": null,
"interactive_html": null,
"name": "start",
"updated_at": "2022-04-15T11:09:11Z"
},
{
"created_at": "2022-04-15T11:19:11Z",
"id": "17677",
"interactive_fields_names": null,
"interactive_html": null,
"name": "connect",
"updated_at": "2022-04-15T11:19:11Z"
},
{
"created_at": "2022-04-15T12:09:11Z",
"id": "17681",
"interactive_fields_names": null,
"interactive_html": null,
"name": "finish",
"updated_at": "2022-04-15T12:09:11Z"
}
]
}
}
Accounts
Any login can have one or more accounts. The accounts are bound to a currency so that all the transactions within a single account are in the same currency.
Sometimes, the provider allows the user to have several currencies grouped under the same account. For example, if a user holds a debit card that supports 3 currencies, the corresponding login will have 3 accounts, each with one of the debit card’s currencies.
Attributes
id
string
name
string
The unique name of the account.
Note: The name directly identifies the account. In case the account’s name has changed (in the bank’s WEB/API interface, through code changes, etc.) a new account will be created.
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.
Note: The currency directly identifies the account. In case the account’s currency code has changed (in the bank’s WEB/API interface, through code changes, etc.) a new account will be created.
login_id
string
The id
of the login the account belongs to
created_at
datetime
updated_at
datetime
id
string
name
string
The unique name of the account.
Note: The name directly identifies the account. In case the account’s name has changed (in the bank’s WEB/API interface, through code changes, etc.) a new account will be created.
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.
Note: The currency directly identifies the account. In case the account’s currency code has changed (in the bank’s WEB/API interface, through code changes, etc.) a new account will be created.
login_id
string
The id
of the login the account belongs to
created_at
datetime
updated_at
datetime
Sample Object
{
"id": "223",
"name": "Fake account 2",
"nature": "account",
"balance": 2012.7,
"currency_code": "USD",
"extra": {
"cards": [
"1234....5678",
"*8765"
],
"transactions_count": {
"posted": 22,
"pending": 1
}
},
"login_id": "123",
"created_at": "2022-04-15T11:09:11Z",
"updated_at": "2022-04-15T11:09:11Z"
}
List
You can see the list of accounts of a login.
The accounts are sorted in ascending order of their ID, so the newest accounts will come last.
You can read more about next_id
field, in the pagination section of the reference.
Parameters
login_id
string, optional
The ID of the login containing the accounts
from_id
string, optional
The ID of the account which the list starts with.
customer_id
string, optional
The ID of the customer containing the accounts.
Note: Will be ignored if login_id
is present.
from_id
string, optional
The ID of the account which the list starts with.
customer_id
string, optional
The ID of the customer containing the accounts.
Note: Will be ignored if login_id
is present.
Possible Errors
URL
https://www.saltedge.com/api/v4/accounts?login_id={login.id}
https://www.saltedge.com/api/v4/accounts
Method
GET
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v4/accounts?login_id=100
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 "Login-secret: $LOGIN_SECRET" \
-X GET \
https://www.saltedge.com/api/v4/accounts
Sample Response
{
"data": [
{
"id": "142",
"name": "Fake account 1",
"nature": "card",
"balance": 2007.2,
"currency_code": "EUR",
"extra": {
"client_name": "Fake name"
},
"login_id": "123",
"created_at": "2022-04-15T10:09:11Z",
"updated_at": "2022-04-15T10:09:11Z"
},
{
"id": "143",
"name": "Fake account 2",
"nature": "account",
"balance": 2012.7,
"currency_code": "USD",
"extra": {
"cards": [
"1234....5678",
"*8765"
],
"transactions_count": {
"posted": 22,
"pending": 1
}
},
"login_id": "123",
"created_at": "2022-04-15T11:09:11Z",
"updated_at": "2022-04-15T11:09:11Z"
}
],
"meta" : {
"next_id": "144",
"next_page": "/api/v4/accounts?login_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": "2022-04-15T10:09:11Z",
"updated_at": "2022-04-15T10:09:11Z"
},
{
"id": "143",
"name": "Fake account 2",
"nature": "account",
"balance": 2012.7,
"currency_code": "USD",
"extra": {
"cards": [
"1234....5678",
"*8765"
],
"transactions_count": {
"posted": 22,
"pending": 1
}
},
"login_id": "123",
"created_at": "2022-04-15T11:09:11Z",
"updated_at": "2022-04-15T11:09:11Z"
}
],
"meta" : {
"next_id": "144",
"next_page": "/api/v4/accounts?from_id=144"
}
}
Nature
An account can be of one of the several types, as described by the nature
field:
Payment account natures:
- account
- card
- checking
- credit_card
- debit_card
- ewallet
- loan
- mortgage
- savings
Non payment account natures:
- bonus
- insurance
- investment
- credit
Although these values do not affect neither the account’s behavior, nor its properties, they might provide some additional information to the end user.
Extra
The following represents the object you get in the extra
field of the account object.
Note: You may or may not have all of the fields listed below.
General accounts extra fields:
account_name
string
Changeable name of the account
account_number
string
Internal bank account number
assets
array of objects
Array of crypto codes and their amounts assigned to investment account
available_amount
decimal
Available amount in account’s currency
balance_type
string
Type of the imported balance as showed/returned by the bank
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
bban
string
Basic Bank Account Number
interest_rate
decimal
Interest rate of the account as percentage value
interest_type
string
Type of account interest used with interest_rate
floating_interest_rate
object
Minimum and maximum value of the interest rate e.g. {'min_value': 1.84, 'max_value': 1.99 }
remaining_payments
decimal
The number of remaining payments to pay off the loan
penalty_amount
decimal
The amount of the penalty
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}
payment_type
string
Account payment method
cashback_amount
decimal
Accumulated CashBack / Cash Benefit
monthly_total_payment
decimal
The amount a borrower was paid for a month
minimum_payment
decimal
The lowest amount you can pay on your credit card to avoid penalties
account_name
string
Changeable name of the account
account_number
string
Internal bank account number
assets
array of objects
Array of crypto codes and their amounts assigned to investment account
available_amount
decimal
Available amount in account’s currency
balance_type
string
Type of the imported balance as showed/returned by the bank
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
bban
string
Basic Bank Account Number
interest_rate
decimal
Interest rate of the account as percentage value
interest_type
string
Type of account interest used with interest_rate
floating_interest_rate
object
Minimum and maximum value of the interest rate e.g. {'min_value': 1.84, 'max_value': 1.99 }
remaining_payments
decimal
The number of remaining payments to pay off the loan
penalty_amount
decimal
The amount of the penalty
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}
payment_type
string
Account payment method
cashback_amount
decimal
Accumulated CashBack / Cash Benefit
monthly_total_payment
decimal
The amount a borrower was paid for a month
minimum_payment
decimal
The lowest amount you can pay on your credit card to avoid penalties
Investment accounts extra fields:
investment_amount
decimal
Total invested amount
unit_price
decimal
Price per unit (used with units)
units
decimal
Amount of units owned (used with unit_price)
indicative_unit_price
decimal
Indicative price per unit (used with units)
interest_income
decimal
Amount of interest income/profit
interest_amount
decimal
Interest amount in currency
profit_amount
decimal
Amount of profit/loss of investment account
profit_rate
decimal
Investment account rate of profit/loss as percentage value
asset_class
string
Class of investment asset
product_type
string
Investment product type
total_unit_value
decimal
Total units value of fund holding
fund_holdings
object
Fund holdings list with own values such as (investment_percentage
, balance
, bid_price
, value
, value_date
, total_quantity
, available_quantity
, actual_price
, actual_value
)
investment_amount
decimal
Total invested amount
unit_price
decimal
Price per unit (used with units)
units
decimal
Amount of units owned (used with unit_price)
indicative_unit_price
decimal
Indicative price per unit (used with units)
interest_income
decimal
Amount of interest income/profit
interest_amount
decimal
Interest amount in currency
profit_amount
decimal
Amount of profit/loss of investment account
profit_rate
decimal
Investment account rate of profit/loss as percentage value
asset_class
string
Class of investment asset
product_type
string
Investment product type
total_unit_value
decimal
Total units value of fund holding
fund_holdings
object
Fund holdings list with own values such as (investment_percentage
, balance
, bid_price
, value
, value_date
, total_quantity
, available_quantity
, actual_price
, actual_value
)
Insurance accounts extra fields:
string
Frequency of premium payments
policy_status
string
Current policy status
life_assured_name
string
Name of the person who is assured
decimal
Premium amount to be paid
decimal
Single premium amount to be paid
financial_consultant
string
Financial consultant name
total_reversionary_bonus
decimal
Reversionary bonus accumulated amount
gross_surrender
decimal
Current Gross Surrender value
guaranteed_gross_surrender
decimal
Guaranteed Gross Surrender value
reversionary_bonus_cash_value
decimal
Cash value of reversionary bonus
owned_policy_amount
decimal
Amount currently own on policy
policy_loan_limit
decimal
Maximum amount of additional Policy Loan
policy_converted_to_paid_up
decimal
New assured sum if Policy is converted to paid up
paid_up_conversion_reversionary_bonus
decimal
Reversionary bonus amount after ‘Policy to paid up’ conversion
policy_components
object
Policy components with own values such as (status
, amount_assured
, amount_premium
, start_date
, expiry_date
, premium_expiry_date
, assured_name
)
string
Frequency of premium payments
policy_status
string
Current policy status
life_assured_name
string
Name of the person who is assured
decimal
Premium amount to be paid
decimal
Single premium amount to be paid
financial_consultant
string
Financial consultant name
total_reversionary_bonus
decimal
Reversionary bonus accumulated amount
gross_surrender
decimal
Current Gross Surrender value
guaranteed_gross_surrender
decimal
Guaranteed Gross Surrender value
reversionary_bonus_cash_value
decimal
Cash value of reversionary bonus
owned_policy_amount
decimal
Amount currently own on policy
policy_loan_limit
decimal
Maximum amount of additional Policy Loan
policy_converted_to_paid_up
decimal
New assured sum if Policy is converted to paid up
paid_up_conversion_reversionary_bonus
decimal
Reversionary bonus amount after ‘Policy to paid up’ conversion
policy_components
object
Policy components with own values such as (status
, amount_assured
, amount_premium
, start_date
, expiry_date
, premium_expiry_date
, assured_name
)
Transactions
A transaction represents a movement of funds. Any transaction can represent a monetary transfer, withdrawal, income or expense interchange. Transactions are retained in a login’s accounts, and are imported from one of the providers.
Category
Spectre API uses an algorithm for automatic categorization of transactions. Thus, when importing a login, all the transactions corresponding to the login will be assigned to one of the categories. We also expose an API route for your applications to improve the categorization process based on your user’s behaviors.
Duplication
Although we import most of the data from the providers thoroughly checking the transactions for duplicates, the providers might change the format of some data, causing us to return transactions that have different data, but are duplicates to your end users. You can use the Duplicate action in order to let us know about a duplicate so that we can take immediate action.
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
string
Transaction’s description
category
string
Transaction’s category
duplicated
boolean
Whether the transaction is duplicated or not
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
string
Transaction’s description
category
string
Transaction’s category
duplicated
boolean
Whether the transaction is duplicated or not
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": "2022-04-13T13:09:11Z",
"updated_at": "2022-04-14T13:09:11Z"
}
List
You can see the list of transactions of an account.
You can read more about the next_id
field in the pagination section of the reference.
Parameters
login_id
string, optional
The id
of the login, required unless account_id
parameter is sent
account_id
string, optional
The id
of the account
from_id
string, optional
The id
of the transaction which the list starts with.
account_id
string, optional
The id
of the account
from_id
string, optional
The id
of the transaction which the list starts with.
All of the optional parameters for transactions list can be combined in any possible manner.
Possible Errors
URL
https://www.saltedge.com/api/v4/transactions?login_id={login.id}&account_id={account.id}
https://www.saltedge.com/api/v4/transactions?account_id={account.id}
Method
GET
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v4/transactions?login_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 "Login-secret: $LOGIN_SECRET" \
-X GET \
https://www.saltedge.com/api/v4/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": "2022-04-13T13:09:11Z",
"updated_at": "2022-04-14T13:09:11Z"
},
{
"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": "2022-04-13T13:09:11Z",
"updated_at": "2022-04-14T13:09:11Z"
}
],
"meta" : {
"next_id": "990",
"next_page": "/api/v4/transactions/?login_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": "2022-04-13T13:09:11Z",
"updated_at": "2022-04-14T13:09:11Z"
},
{
"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": "2022-04-13T13:09:11Z",
"updated_at": "2022-04-14T13:09:11Z"
}
],
"meta" : {
"next_id": "990",
"next_page": "/api/v4/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 login is refreshed, the existing pending transactions will be replaced by the currently pending transactions.
This means that your app should not rely on the pending transactions having an ID, since they might be replaced with similar transactions having a different ID. We also recommend your app to remove the account’s pending transactions every time you fetch the transactions.
Parameters
login_id
string, optional
The id
of the login, required unless account_id
parameter is sent
account_id
string, optional
The id
of the account
from_id
string, optional
The id
of the transaction which the list starts with
account_id
string, optional
The id
of the account
from_id
string, optional
The id
of the transaction which the list starts with
As with the list route, you can combine the parameters.
Possible Errors
URL
https://www.saltedge.com/api/v4/transactions/pending?login_id={login.id}&account_id={account.id}
https://www.saltedge.com/api/v4/transactions/pending?account_id={account.id}
Method
GET
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v4/transactions/pending?login_id=124&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 "Login-secret: $LOGIN_SECRET" \
-X GET \
https://www.saltedge.com/api/v4/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": "2022-04-13T13:09:11Z",
"updated_at": "2022-04-14T13:09:11Z"
}
],
"meta" : {
"next_id": "990",
"next_page": "/api/v4/transactions/pending?login_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": "2022-04-13T13:09:11Z",
"updated_at": "2022-04-14T13:09:11Z"
}
],
"meta" : {
"next_id": "990",
"next_page": "/api/v4/transactions/pending?account_id=225&from_id=990"
}
}
Duplicate
Mark a list of transactions as duplicated
.
Request body
The request body is an array of objects wrapped in the data
field.
Each object has a transaction_id
field which represents a transaction id
.
Possible Errors
URL
https://www.saltedge.com/api/v4/transactions/duplicate
https://www.saltedge.com/api/v4/transactions/duplicate
Method
PUT
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
-d "{ \
\"data\": [ \
{ \
\"transaction_id\": \"123\" \
}, \
{ \
\"transaction_id\": \"345\" \
} \
] \
}" \
https://www.saltedge.com/api/v4/transactions/duplicate
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Login-secret: $LOGIN_SECRET" \
-X PUT \
-d "{ \
\"data\": [ \
{ \
\"transaction_id\": \"123\" \
}, \
{ \
\"transaction_id\": \"345\" \
} \
] \
}" \
https://www.saltedge.com/api/v4/transactions/duplicate
Sample response
{
"data": {
"duplicated": true
}
}
Unduplicate
Remove duplicated flag from a list of transactions.
Request body
As with /transactions/duplicate
, the request body is an array of objects wrapped in the data
field.
Each object has a transaction_id
field which represents a transaction id
.
Possible Errors
URL
https://www.saltedge.com/api/v4/transactions/unduplicate
https://www.saltedge.com/api/v4/transactions/unduplicate
Method
PUT
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
-d "{ \
\"data\": [ \
{ \
\"transaction_id\": \"123\" \
}, \
{ \
\"transaction_id\": \"345\" \
} \
] \
}" \
https://www.saltedge.com/api/v4/transactions/unduplicate
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Login-secret: $LOGIN_SECRET" \
-X PUT \
-d "{ \
\"data\": [ \
{ \
\"transaction_id\": \"123\" \
}, \
{ \
\"transaction_id\": \"345\" \
} \
] \
}" \
https://www.saltedge.com/api/v4/transactions/unduplicate
Sample Response
{
"data": {
"unduplicated": true
}
}
Remove
Remove transactions older than a specified period.
Parameters
account_id
string, required
The id
of the account
keep_days
integer, required
The amount of days for which the transactions will be kept. Transactions older than that will be irreversibly removed. If value is 0 then all transactions will be removed.
account_id
string, required
The id
of the account
keep_days
integer, required
The amount of days for which the transactions will be kept. Transactions older than that will be irreversibly removed. If value is 0 then all transactions will be removed.
Possible Errors
URL
https://www.saltedge.com/api/v4/transactions
https://www.saltedge.com/api/v4/transactions
Method
DELETE
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X DELETE \
-d "{ \
\"data\": { \
\"account_id\": \"123\", \
\"keep_days\": 90 \
} \
}" \
https://www.saltedge.com/api/v4/transactions
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Login-secret: $LOGIN_SECRET" \
-X DELETE \
-d "{ \
\"data\": { \
\"account_id\": \"123\", \
\"keep_days\": 90 \
} \
}" \
https://www.saltedge.com/api/v4/transactions
Sample response
{
"data": {
"cleanup_started": true
}
}
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
string
Additional information (recommended to use in concatenation with original description, if present)
asset_amount
decimal
Original transaction amount in asset units
asset_code
string
Asset common used abbreviation (Ex.: BTC
- Bitcoin, XAU
- Gold etc.)
categorization_confidence
float
Value from 0 to 1, the probability that the current category is the correct one
check_number
string
Payee’s transaction check number
closing_balance
decimal
Account balance after 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
end_to_end_id
string
A unique identifier set by the merchant. Usually used for reconciliation.
information
string
Information about the transaction
merchant_id
string
Merchant identifier
opening_balance
decimal
Account balance before transaction
installment_debt_amount
decimal
Amount of installment transactions group
original_amount
decimal
Native amount of the transaction in transaction’s currency (comes with original_currency_code
)
original_category
string
The original category of the transaction
original_currency_code
string
Native currency of the transaction (comes with original_amount
)
original_subcategory
string
The original subcategory of the transaction
payee
string
To whom 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 payemnts (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
string
Additional information (recommended to use in concatenation with original description, if present)
asset_amount
decimal
Original transaction amount in asset units
asset_code
string
Asset common used abbreviation (Ex.: BTC
- Bitcoin, XAU
- Gold etc.)
categorization_confidence
float
Value from 0 to 1, the probability that the current category is the correct one
check_number
string
Payee’s transaction check number
closing_balance
decimal
Account balance after 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
end_to_end_id
string
A unique identifier set by the merchant. Usually used for reconciliation.
information
string
Information about the transaction
merchant_id
string
Merchant identifier
opening_balance
decimal
Account balance before transaction
installment_debt_amount
decimal
Amount of installment transactions group
original_amount
decimal
Native amount of the transaction in transaction’s currency (comes with original_currency_code
)
original_category
string
The original category of the transaction
original_currency_code
string
Native currency of the transaction (comes with original_amount
)
original_subcategory
string
The original subcategory of the transaction
payee
string
To whom 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 payemnts (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/v4/categories
https://www.saltedge.com/api/v4/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/v4/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/v4/categories
Sample Response
{
"data": {
"business": {
"cost_of_goods": [
"merchandise",
"raw_materials"
],
"financials": [
"dividends",
"donations",
"fees",
"fines",
"interest"
],
"human_resources": [
"bonus",
"education_and_trainings",
"social_security",
"staff_outsourcing",
"wages"
],
"income": [
"investment",
"returns",
"sales"
],
"insurance": [
"business_insurance",
"equipment_insurance",
"health_insurance",
"liability_insurance",
"professional_insurance"
],
"office": [
"equipment",
"office_rent",
"office_supplies",
"software"
],
"services": [
"accounting",
"consultancy",
"contractors",
"legal",
"marketing",
"online_subscriptions",
"storage"
],
"taxes": [
"duty_taxes",
"federal_taxes",
"income_taxes",
"property_taxes",
"tax_return",
"vat"
],
"transport": [
"gas_and_fuel",
"leasing",
"shipping",
"taxi"
],
"utilities": [
"electricity",
"gas",
"internet",
"phone",
"water"
],
"uncategorized": []
},
"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_and_rent"
],
"income": [
"bonus",
"investment_income",
"paycheck"
],
"insurance": [
"car_insurance",
"health_insurance",
"life_insurance",
"property_insurance"
],
"kids": [
"allowance",
"babysitter_and_daycare",
"baby_supplies",
"child_support",
"kids_activities",
"toys"
],
"pets": [
"pet_food_and_supplies",
"pet_grooming",
"veterinary"
],
"shopping": [
"clothing",
"electronics_and_software",
"sporting_goods"
],
"transfer": [],
"travel": [
"hotel",
"transportation",
"vacation"
],
"uncategorized": []
}
}
}
Learn
You can change the category of some transactions, thus improving the categorization accuracy.
Post body
transaction_id
required
The id of the transaction
category_code
required
The new category code of the transaction
immediate
boolean optional
If sent as true, the learning threshold of the categorizer will be ignored and further transactions with the same description will be classified under the same category
transaction_id
required
The id of the transaction
category_code
required
The new category code of the transaction
immediate
boolean optional
If sent as true, the learning threshold of the categorizer will be ignored and further transactions with the same description will be classified under the same category
Possible Errors
URL
https://www.saltedge.com/api/v4/categories/learn
https://www.saltedge.com/api/v4/categories/learn
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": [ \
{ \
\"transaction_id\": \"123\", \
\"category_code\": \"paycheck\", \
\"immediate\": true \
}, \
{ \
\"transaction_id\": \"124\", \
\"category_code\": \"car_rental\", \
\"immediate\": false \
} \
] \
}" \
https://www.saltedge.com/api/v4/categories/learn
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X POST \
-d "{ \
\"data\": [ \
{ \
\"transaction_id\": \"123\", \
\"category_code\": \"paycheck\", \
\"immediate\": true \
}, \
{ \
\"transaction_id\": \"124\", \
\"category_code\": \"car_rental\", \
\"immediate\": false \
} \
] \
}" \
https://www.saltedge.com/api/v4/categories/learn
Sample Response
{
"data": {
"learned": true
}
}
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/v4/currencies
https://www.saltedge.com/api/v4/currencies
Method
GET
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v4/currencies
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X GET \
https://www.saltedge.com/api/v4/currencies
Sample Response
{
"data":
[
{
"code": "AED",
"name": "United Arab Emirates dirham"
},
{
"code": "AFN",
"name": "Afghan afghani"
},
{
"code": "ALL",
"name": "Albanian lek"
},
{
"code": "AMD",
"name": "Armenian dram"
},
{
"code": "ANG",
"name": "Netherlands Antillean guilder"
},
{
"code": "AOA",
"name": "Angolan kwanza"
},
{
"code": "ARS",
"name": "Argentine peso"
},
{
"code": "AUD",
"name": "Australian dollar"
},
{
"code": "AWG",
"name": "Aruban florin"
},
...
]
}
Assets
Some of our providers support investment
accounts. Such
accounts may have an extra assets
key which contains an array of assets. Each asset consists of:
code
- asset common used abbreviation (Ex.:BTC
- Bitcoin,XAU
- Gold etc.)amount
- total amount of owned assets
balance
for these investment
accounts is a sum of all assets amounts converted to selected currency.
Sample Object
{
"id": "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
}
},
"login_id": "123",
"created_at": "2022-04-15T11:09:12Z",
"updated_at": "2022-04-15T11:09:12Z"
}
List
You can get the list of all the assets that we support.
Possible Errors
URL
https://www.saltedge.com/api/v4/assets
https://www.saltedge.com/api/v4/assets
Method
GET
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v4/assets
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X GET \
https://www.saltedge.com/api/v4/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/v4/rates
https://www.saltedge.com/api/v4/rates
Method
GET
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/v4/rates?date=2014-03-21
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X GET \
https://www.saltedge.com/api/v4/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/v4/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.
The API accepts batches of at most 100 objects.
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/v4/merchants
https://www.saltedge.com/api/v4/merchants
Method
POST
Authentication
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": [ \
\"f6dabf8bb3e1cbc7cce2f4571...\", \
\"ae316a83508ecaa8897e90321...\" \
] \
}" \
https://www.saltedge.com/api/v4/merchants
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X POST \
-d "{ \
\"data\": [ \
\"f6dabf8bb3e1cbc7cce2f4571...\", \
\"ae316a83508ecaa8897e90321...\" \
] \
}" \
https://www.saltedge.com/api/v4/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"
}
}
}
]
}