general
Overview
Salt Edge Partners API aims to provide access to financial information for any company that does not need to get a PSD2 Account Information Service Provider license, as simple as a cURL.
- Import financial information from UK and EU banks via PSD2 APIs (Open Banking Standard, NextGenPSD2 Berlin Group, CBI Globe, Polish API, etc.)
- Securely import financial information from online banking interfaces of multiple countries;
- Automatically synchronize accounts and transactions on a daily basis;
- Automatically enrich financial transactions by categorization and merchant identification;
- Keep a well-organized and up-to-date list of currency rates.
If you have any questions regarding what can be done with Salt Edge Partners API, feel free to contact us.
If you have any questions regarding your company’s eligibility for using the Partners API, please contact our Sales team.
Integrations
The Salt Edge platform is easy to integrate. However, if you think that your application could benefit more from the native look and feel, you can always contact us, and we can discuss what would be the best solution for your app.
Formats
We use JSON for all the requests and responses, including the errors.
Glossary
Most of the API revolves around several important concepts:
- Country - the country where providers are located;
- Provider - a bank or an online payments system;
- Lead - a verified end-user email associated with Salt Edge Limited customer record;
- Partner Consent - a permission given to Salt Edge Limited to share fetched data with registered partner;
- Customer - a customer of the client who is consuming Salt Edge Partners API;
- Connection - the central entity of the API, representing a connection between a customer’s bank and Salt Edge;
- Consent - the permission from an end-user to fetch data;
- Attempt - an attempt which is created when an end-user connects a financial institution;
- Holder Info - information about the account holder;
- Account - one of the accounts associated with a connection. It can be a credit card account, a savings account, one of the online accounts, etc;
- Transaction - a single financial movement made within an account;
- Merchant - a company that sells goods or provides services to the customer;
- Category - one of the personal or business categories that can be assigned to a transaction;
- Currency - string code that is used for an account.
Following the guides
You can start with Authentication and follow the links in the sidebar. If you have any questions, contact us anytime using our contact form.
Quick start
This quick start guide will show the easiest path of integrating with Partners API: creating a lead, granting consent, authenticating in the bank interface, fetching financial data on success.
Get invitation
Request an invitation through contact us or our sales team.
Create api keys
Any request to Salt Edge Partners API is authenticated, so before you are able to fetch any data you need to create Service API keys. To do that, visit https://www.saltedge.com/clients/api_keys and create a Service API key. You can leave Public key field blank as when you will go LIVE, signing the requests will become mandatory.
Salt Edge Partners API is supporting only Service API keys use. All communication should be done from a centralized Web Service to grant control over the data flows, security and privacy.
Each request to Partners API is authenticated with an App-id, and a Secret. Let’s store them as environment variables so that all the later requests are authenticated.
$ export APP_ID=YOUR_APP_ID
$ export SECRET=YOUR_APP_SECRET
We can provide examples in various programming languages. Start testing different connection types by using Fake and Sandbox providers to make sure that the application can handle any scenario that might happen with a real data provider (e.g. bank or standard).
Create lead
Before we can create any connections using Salt Edge Partners API, we need to create a Lead. A Lead in Salt Edge Partners API is the verified end-user email of your application.
The result of this request will be a Customer id
and Email.
We need to save the Customer id
(in this case “222222222222222222”), because we will use it later to create connections.
$ export CUSTOMER_ID=222222222222222222
See lead reference and customers reference for related API endpoints.
URL
https://www.saltedge.com/api/partners/v1/leads
https://www.saltedge.com/api/partners/v1/leads
Method
POST
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"email\": \"test@email.com\" \
} \
}" \
https://www.saltedge.com/api/partners/v1/leads
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"email\": \"test@email.com\" \
} \
}" \
https://www.saltedge.com/api/partners/v1/leads
Sample response
{
"data": {
"email": "test+123@email.com",
"customer_id": "222222222222222222"
}
}
Create lead session
Once we have the Customer id
(in this case id “222222222222222222”), we can create a connection.
To initiate a connection you need to execute a request to create lead session endpoint.
You will receive in response a redirect_url
. This is the URL your end-user will visit
to create the connection.
See Lead sessions reference for more information and related API endpoints.
URL
https://www.saltedge.com/api/partners/v1/lead_sessions/create
https://www.saltedge.com/api/partners/v1/lead_sessions/create
Method
POST
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"$CUSTOMER_ID\", \
\"consent\": { \
\"from_date\": \"2020-01-01\", \
\"period_days\": 90, \
\"scopes\": [ \
\"account_details\", \
\"transactions_details\" \
] \
}, \
\"attempt\": { \
\"from_date\": \"2020-02-01\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
} \
} \
}" \
https://www.saltedge.com/api/partners/v1/lead_sessions/create
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"$CUSTOMER_ID\", \
\"consent\": { \
\"from_date\": \"2020-01-01\", \
\"period_days\": 90, \
\"scopes\": [ \
\"account_details\", \
\"transactions_details\" \
] \
}, \
\"attempt\": { \
\"from_date\": \"2020-02-01\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
] \
} \
} \
}" \
https://www.saltedge.com/api/partners/v1/lead_sessions/create
Sample response
{
"data": {
"expires_at": "2024-10-08T15:41:01Z",
"redirect_url": "https://www.saltedge.com/dashboard/connect?invitation_token=GENERATED_TOKEN"
}
}
Visit Connect Widget URL
Initially, all Salt Edge registered partners are in pending status and only have access to fake and sandbox providers.
Let’s connect one of them. Visit the redirect_url
from the previous API response and
search for “Fake Bank Simple”.
Iframe embedding is not allowed in a webview. The Salt Edge Connect (widget) should be opened in a new browser window or in a pop-up window.
Once selected, we will be presented with a form for end-user credential input, from this provider. Input “username” and “secret” as per the on-screen instructions and press “Connect”.
Afterward, we will have to wait for the connection process to finish so that we can proceed with retrieving all its data via the API.
Fetch connections
In Salt Edge Partners API, a distinct bank connection is called a Connection. Each Salt Edge Partners API Customer can have multiple Connections. When we visited Redirect URL and connected “Fake Bank Simple”, we created a Connection associated with our Customer in the system. To retrieve all data for this Connection, we first need to retrieve the Connection itself.
The response contains an array of entries, each representing a connection to a financial institution.
In our case, we will have only one entry.
We need to save the id
(in our case 111111111111111111) to retrieve its accounts.
$ export CONNECTION_ID=111111111111111111
See connections reference for more information on Connection endpoints.
Sample Request
URL
https://www.saltedge.com/api/partners/v1/connections?customer_id={customer.id}
https://www.saltedge.com/api/partners/v1/connections?customer_id={customer.id}
Method
GET
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/connections?customer_id=$CUSTOMER_ID
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/connections?customer_id=$CUSTOMER_ID
Sample Response
{
"data": [
{
"id": "111111111111111111",
"provider_code": "fakebank_simple_xf",
"provider_name": "Fakebank Simple",
"customer_id": "222222222222222222",
...
}
]
}
Fetch accounts for connections
Having the Connection id
, we can retrieve all its accounts.
The response contains an array of entries, each representing an account from a financial institution.
We need to save the id
(in our case 333333333333333333) to retrieve all transactions for this account.
$ export ACCOUNT_ID=333333333333333333
Sample Request
URL
https://www.saltedge.com/api/partners/v1/accounts?connection_id={connection.id}
https://www.saltedge.com/api/partners/v1/accounts?connection_id={connection.id}
Method
GET
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/accounts?connection_id=$CONNECTION_ID
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/accounts?connection_id=$CONNECTION_ID
Sample Response
{
"data": [
{
"id": "333333333333333333",
"name": "Fake account 1",
"nature": "card",
"balance": 2007.2,
"currency_code": "EUR",
"connection_id": "111111111111111111",
"created_at": "2024-10-08T11:41:01Z",
"updated_at": "2024-10-08T11:41:01Z",
"extra": {
"client_name": "Fake name"
},
...
}
]
}
Fetch transactions for an account
Having the Connection id
and the Account id
, we can retrieve transactions for the account.
The response contains an array of entries, each representing a transaction from a financial institution.
See transactions reference for more information on Transaction endpoints.
Sample Request
URL
https://www.saltedge.com/api/partners/v1/transactions?connection_id={connection.id}&account_id={account.id}
https://www.saltedge.com/api/partners/v1/transactions?connection_id={connection.id}&account_id={account.id}
Method
GET
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/transactions?connection_id=$CONNECTION_ID&account_id=$ACCOUNT_ID
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/transactions?connection_id=$CONNECTION_ID&account_id=$ACCOUNT_ID
Sample Response
{
"data": [
{
"id": "444444444444444444",
"duplicated": false,
"mode": "normal",
"status": "posted",
"made_on": "2020-05-03",
"amount": -200.0,
"currency_code": "USD",
"description": "test transaction",
"category": "advertising",
"account_id": "100",
"created_at": "2024-10-06T14:41:01Z",
"updated_at": "2024-10-07T14:41:01Z",
"extra": {
"original_amount": -3974.60,
"original_currency_code": "CZK",
"posting_date": "2020-05-07",
"time": "23:56:12"
},
...
}
]
}
Next steps
- Request Test status to connect real banking institutions.
- Switch to Live status to bring value to your customers globally.
- Since new Salt Edge partners are in pending mode and have access only to fake and sandbox providers, the request signature is not required. However, you will need to implement request signing before you are going live. For more information see our signature guide.
- All responses with arrays (like accounts or transactions) are paginated by default. See how to implement it on our pagination guide.
- The recommended way of synchronizing data with Salt Edge Partners API is via callbacks. That way you won’t have to poll the servers to see whether there is new data available. See our callbacks guide for more information.
- Iframe embedding is not allowed in a webview. The Salt Edge Connect (widget) should be opened in a new browser window or in a pop-up window.
- Salt Edge Connect (widget) supports only the 2 last versions of modern browsers.
Try in Postman
Step 1
Install Postman. You can get it on https://www.getpostman.com/apps.
Step 2
Import the postman collection, click the button below to do that.
Step 3
Salt Edge Partners API requires APP_ID and SECRET headers in order to authenticate as partner. If you don’t have an API key created yet, you can you use our quick start guide to help you create one. Once you have the API key created, you can add its secrets to postman.
Click on the eye on the top right corner and press on “Add” next to “Environments”.
Define variables APP_ID and SECRET with values from the key that you generated on https://www.saltedge.com/clients/profile/secrets, then add the environment.
Once added, you can select it in the top right corner, and all the requests to Salt Edge API will be authenticated using your API key.
Before going LIVE
In order to upgrade your Partner account status to LIVE mode, the following steps should be followed:
- Provide your Account Manager at Salt Edge with a test account in your app to verify Partners API integration. If you have multiple apps (Android, iOS, web), a test account should be provided for each platform. In case the applications share the same backend, it’s enough to share an account for one platform.
- Be sure to provide the signature in accordance with the instructions.
- Your application should handle correctly a few fake banks (
fake_oauth_client_xf
,fake_client_xf
are mandatory) and at least one Sandbox (to your discretion). - The partner consent should be revoked when the connection is deleted from the app.
- The lead should be able to refresh and reconnect (mandatory for recurring access) an existing connection to a financial provider.
- The Two-factor authentication must be enabled for your account and all your teammates;
- In order to avoid legal issues with end-users and data providers, the client must ensure that end-users read and agree to End-user Dashboard Terms of Service and End-user Dashboard Privacy Policy, both as incorporated by reference into Partner’s own Terms of Service and Privacy Policy.
- Be sure to indicate
Incident reporting Email
in the dashboard settings on the Company page.
After your Account Manager at Salt Edge has reviewed the app’s integration with Partners API, the account’s status will be upgraded to live. The review usually takes two business days if no issues are detected.
Callbacks
The most important parts of Salt Edge Partners API (e.g. Connection management) are asynchronous.
Every Web application has to provide a set of valid URLs which we will use to notify about the fetching progress. Applications can also poll Salt Edge Partners API in order to retrieve the updated information.
There are several common points about the request we send to the callback URLs provided by the client:
- The
Content-Type
header isapplication/json
; - There is a
Signature
header that identifies the request was signed by Salt Edge Partners API; - The request method is always
POST
; - The JSON object sent will always have a
data
field; - The
meta
field will display the version of the callbacks API.
You can set the callback URLs for your application by accessing your callbacks page.
Due to security reasons, the callbacks can be sent to port 80/HTTP only in test and pending modes.
Port 443/HTTPS is accepted by all modes.
Also, the callbacks do not follow redirects!
Signature
Signature
In order for the client to identify that the request is coming from Salt Edge Partners API, there is a Signature header in the request.
Signature
- base64
encoded SHA256
signature of the string represented in the
form callback_url|post_body
- 2 parameters concatenated
with a vertical bar |
, signed with a Salt Edge Partners API’s private key. You can find the version of the signature key used to sign the callback in the Signature-key-version
header. The current version is 5.0
which corresponds to the following public key:
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvL/Xxdmj7/cpZgvDMvxr
nTTU/vkHGM/qkJ0Q+rmfYLru0Z/rSWthPDEK3orY5BTa0sAe2wUV5Fes677X6+Ib
roCF8nODW5hSVTrqWcrQ55I7InpFkpTxyMkiFN8XPS7qmYXl/xofbYq0olcwE/aw
9lfHlZD7iwOpVJqTsYiXzSMRu92ZdECV895kYS/ggymSEtoMSW3405dQ6OfnK53x
7AJPdkAp0Wa2Lk4BNBMd24uu2tasO1bTYBsHpxonwbA+o8BXffdTEloloJgW7pV+
TWvxB/Uxil4yhZZJaFmvTCefxWFovyzLdjn2aSAEI7D1y4IYOdByMOPYQ6Mn7J9A
9wIDAQAB
-----END PUBLIC KEY-----
An example of the string that is to be used to generate the signature looks as follows:
https://www.client.com/api/callbacks/success|{"data":{"connection_id":"111111111111111111","customer_id":"222222222222222222","custom_fields":{}},"meta":{"version":"5","time":"2020-01-03T13:00:28Z"}}
The pseudocode that we use to generate the signature looks like this:
base64(sha256_signature(private_key, "callback_url|post_body"))
Success
We send a callback to your application’s success URL whenever any triggered operation has caused a change in the data we store for a particular connection.
For instance, the user was redirected to the Connect page, selected a provider, filled in the credentials and pressed Proceed
, we’ll send you a success callback.
This callback will contain the customer identifier and the id
of the newly created connection.
Afterwards, your application will be able to use the show connection route and query the information about this connection.
You could also fetch the connection’s accounts and query the accounts (if any exist at the moment we sent the callback).
Whenever we have more information about the connection, we will send another success callback.
A success callback marks a change in the data and you can generally expect from one to three success callbacks with the same payload within several minutes. We recommend that your application fetch the full connection data, along with the accounts and transactions at each callback, as some information might change during the fetching process.
Here’s an example callback sent to the /success route of your app:
{
"data": {
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"custom_fields": { "key": "value" },
"stage": "finish"
},
"meta": {
"version": "5",
"time": "2024-10-08T14:41:01.378Z"
}
}
You can now use the show connection route and obtain the provider, country and some other attributes of the new connection.
The possible stages sent in a success callback are as follows:
connect
- connecting to the data source;fetch_holder_info
- fetching the information about account holder;fetch_accounts
- fetching the accounts;fetch_recent
- fetching the transactions;finish
- wrapping up the fetching process.
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 end-user, the credentials are wrong or we could not perform one of the steps of the fetching process.
In this case, you will receive a fail
callback, containing a JSON similar to the following:
{
"data": {
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"custom_fields": { "key": "value" },
"error_class": "InvalidCredentials",
"error_message": "Invalid credentials."
},
"meta": {
"version": "5",
"time": "2024-10-08T14:41:01.384Z"
}
}
After you get this callback, you need to fetch the connection to check for its updates. Please note that even if there’s an error, we still store the connection.
You can also receive a fail
callback if the lead revokes the partner’s consent of the connection:
{
"data": {
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"custom_fields": { "key": "value" },
"error_class": "PartnerConsentRevoked",
"error_message": "The partner consent was revoked by the end-user"
},
"meta": {
"version": "5",
"time": "2024-10-08T14:41:01.384Z"
}
}
Additional callbacks
There are additional callbacks that your app needs to implement in order to use the API-only version of Salt Edge Partners API.
Notify
Salt Edge can inform you about the progress of a connection using Notify callback.
Your app can expect the notify callback several times, depending on the type of the connection, but you can use this information to inform your user about what’s happening with the connection.
The possible stages sent in a notify callback are as follows:
start
- the fetching process has just begun;connect
- connecting to the data source;interactive
- waiting for the interactive credentials;fetch_holder_info
- fetching the information about account holder;fetch_accounts
- fetching the accounts;fetch_recent
- fetching the data for a recent period (several months);fetch_full
- fetching the data for a longer period;disconnect
- disconnecting from the data source;finish
- wrapping up the fetching process.
Note that for some of the connections, you might not receive all the stages.
Notify callback will not be triggered for daily attempts.
Here’s an example callback sent to the /notify
route of your app:
{
"data": {
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"custom_fields": { "key": "value" },
"stage": "start"
},
"meta": {
"version": "5",
"time": "2024-10-07T14:41:01Z"
}
}
Destroy
Whenever a connection gets removed, we will send a callback to your application’s destroy URL, if such exists.
An example callback sent to your app’s /destroy
route:
{
"data": {
"connection_id": "111111111111111111",
"customer_id": "222222222222222222"
},
"meta": {
"version": "5",
"time": "2020-05-17T14:29:35Z"
}
}
Service
If the connection had issues in the past and a change was made in connection’s provider codebase, your application will receive a callback informing you that a refresh is needed in order to update the connection’s data.
The possible reasons sent in a service callback are as follows:
fixed
- a fix was made;updated
- an update was made;
Here’s an example callback sent to the /service
route of your app:
{
"data": {
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"custom_fields": { "key": "value" },
"reason": "updated"
},
"meta": {
"version": "5",
"time": "2024-10-07T14:41:01Z"
}
}
Financial Insights
Whenever the Financial Insights Report is succesfully generated, your application will receive a callback.
The callback URL can be set by accessing Settings
-> Applications
-> Callbacks
-> Financial Insights
in the Dashboard.
Here’s an example callback sent to the Financial Insights route of your app:
{
"data": {
"report_id": "12345",
"status": "success",
"customer_id": "222222222222222222"
},
"meta": {
"version": "1",
"time": "2022-06-27T10:09:26.141Z"
}
}
Provider Changes
Whenever the Provider’s status changes, Salt Edge will send notifications to the Provider changes URL
callback route.
You can set the callback URLs for your application on the callbacks page.
Example Callback Payload:
{
"data": {
"provider_status": "inactive",
"provider_code": "fake_client_xf"
},
"meta": {
"version": 5,
"time": "2023-09-21T09:49:13.472Z"
}
}
Parameters sent to the callback URL
data
object
meta
object
data
object
meta
object
The possible statuses are:
active
- the provider is active and can be used for connections;inactive
- the provider is inactive and cannot be used for connections;
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.
Holder info route returns the information fetched from customer’s account with the particular provider.
Depending on the provider, the following attributes might be returned in the holder_info
:
names
- returns the name(s) on the customer’s account with the provider, e.g.["John Doe"]
;emails
- returns email(s) registered within customer’s account with the provider, e.g.["john.doe@example.com", "johndoe@gmail.com"]
;phone_numbers
- returns the phone number(s) registered in the customer’s account with the provider, e.g.["+16135550175", "+40981233422"]
;addresses
- returns the address(es) on the customer’s account with the provider, e.g.
For some providers extra fields, e.g. Social Security Number or Cadastro de Pessoas Físicas, can also be returned.
Holder info can be fetched independently or along with other connection information, e.g. accounts and transactions.
In order to test the holder_info
attribute, you can connect the fakebank_simple_xf
fake provider.
Sample response (as provider attribute)
"holder_info": ["names", "emails", "addresses"]
Sample response (as separate route)
{
"data": {
"names": ["John Doe"],
"emails": ["john.doe@example.com"]
"addresses": [
{
"city": "Cupertino",
"state": "CA",
"street": "1 Infinite Loop",
"country_code": "US",
"post_code": "95014"
}
]
}
}
Errors
The Account Information API can return multiple errors for any operation, each having its meaning and usage.
Error attributes
class
string
The class of the error
message
string
A message describing the error
documentation_url
string
A link for error documentation
request_id
string
A unique identifier for this specific HTTP request. Can be sent to support for debugging
request
object
The body of the request that caused the error
class
string
The class of the error
message
string
A message describing the error
documentation_url
string
A link for error documentation
request_id
string
A unique identifier for this specific HTTP request. Can be sent to support for debugging
request
object
The body of the request that caused the error
Error codes
[400] Bad Request
[404] Not Found
[406] Not Acceptable
[409] Duplicated
[429] Too Many Requests
Sample response
{
"error": {
"class": "ConnectionNotFound",
"message": "Connection with id: '111111111111111111' was not found.",
"documentation_url": "https://docs.saltedge.com/account_information/v5/#errors-connection_not_found",
"request_id": "313b4518-10d4-4c15-a18e-34ddd583ebdf"
},
"request": {
"connection_id": "111111111111111111"
}
}
Bank integration layer
- Errors could take place either between Salt Edge and the bank, or on the bank’s end.
- Some of the errors are displayed to the end-users, while others are hidden.
- There are multiple reasons which cause the errors, for example, bank issues, incorrect user actions, invalid PSD2 access, etc.
ProviderError
,ExecutionTimeout
andProviderUnavailable
(unless the bank states it’s temporarily unavailable) should be reported to Salt Edge.ProviderAccessNotGranted
means that either the user has not finished the authorization on the bank’s end or has not returned from the bank’s end to us, for an unknown reason. The reason can be identified only having the user’s comments and feedback. Such errors should be reported to Salt Edge so that we can contact the bank for assistance and clarifications.
In order for Salt Edge to be able to handle such cases, while reporting them to us, please provide the following details on what happened during authorization on the bank’s end:
- When the user was redirected to the bank’s page, how did that page open? In the same window or in a new window? Here a screenshot (all the sensitive data to be hidden) or a screen recording would help.
- Overall, did the authorization complete successfully on the bank’s end? If not, during which authorization step did the process end?
- Afterwards, was the user redirected back to the application, or did the user close the window themselves?
- Also, did the user notice any unexpected behavior while connecting? (a blank screen, a specific error mentioned on the page, etc.)
- If the authorization completed successfully on the bank’s end, please ask the user to describe how the error has occurred.
- The rest of the errors from the below table are caused by incorrect actions of the end-users.
Error class | HTTP code | Description |
---|---|---|
ExecutionTimeout | 406 | The whole fetching process took too long to execute |
FetchingTimeout | 406 | One of the steps of the fetching process took too long to execute |
InteractiveAdapterTimeout | 406 | The interactive step of the fetching process took too long to execute |
InvalidCredentials | 406 | The customer tried to create/reconnect a connection with invalid credentials |
InvalidInteractiveCredentials | 406 | Interactive credentials that were sent are wrong |
ProviderAccessNotGranted | 406 | The authorization on the bank’s side did not complete successfully |
ProviderError | 406 | There’s an error on the provider’s side which obstructs us from obtaining the data for the connection |
ProviderUnavailable | 406 | The provider is temporarily unavailable |
AISP API Reference
- Errors can occur if the client configures API requests incorrectly.
- These errors are not displayed to end-users.
Error class | HTTP code | Description |
---|---|---|
AccountNotFound | 404 | An account with the sent |
AispConsentAlreadyRevoked | 406 | The consent has already been revoked |
AispConsentExpired | 406 | Refresh is not possible because the consent has expired |
AispConsentNotFound | 404 | A consent with such an |
AispConsentRevoked | 406 | Refresh is not possible because the consent has been revoked |
AispConsentScopesInvalid | 406 | The value of consent |
AispConsentScopesNotAllowed | 406 | The value of consent |
AllAccountsExcluded | 406 | You have excluded all the accounts from the connection fetching process |
AttemptNotFound | 404 | An attempt with such an |
BackgroundFetchLimitExceeded | 406 | Background fetch limit (4 times in a 24 hour period) was exceeded (without the user’s presence). This restriction applies only to PSD2 providers (those with |
BadRequest | 400 | The format of the create request of the Financial Insights report is not valid |
BatchSizeLimitExceeded | 406 | More than 100 objects were sent in the request (100 is the limit) |
CategorizationLimitReached | 406 | One partner can categorize at most 1000 transactions per day. This error is applicable only to partners in |
ConnectionAlreadyAuthorized | 409 | The connection has been already authorized |
ConnectionAlreadyProcessing | 409 | The connection is already being processed |
ConnectionCannotBeRefreshed | 406 | The next refresh attempt will be allowed according to |
ConnectionDisabled | 406 | The partner tried to |
ConnectionDuplicated | 409 | The partner tried to |
ConnectionFetchingStopped | 406 | Connection fetching had stopped because of fetching timeout or connection has been deleted during the fetching process |
ConnectionLimitReached | 406 | The partner tried to create more connections than possible for a partner which is in |
ConnectionNotFound | 404 | We could not find a connection with the requested |
CountryNotFound | 404 | Sending a |
CredentialsNotMatch | 406 | New connection credentials do not match the old ones on reconnect. Please contact us in case you encountered this error. It can happen only during Embedded/Decoupled authentication flow. |
CustomFieldsFormatInvalid | 406 | The |
CustomFieldsSizeTooBig | 406 | The |
CustomerLocked | 406 | Customer is locked. May be unlocked |
CustomerNotFound | 404 | A customer with such |
DateFormatInvalid | 400 | We have received an invalid Date format |
DateOutOfAispConsentRange | 400 | The passed |
DateOutOfRange | 400 | Sending a date value that does not fit in admissible range |
DateTimeFormatInvalid | 400 | We have received an invalid DateTime format |
DateTimeOutOfRange | 400 | Sending a datetime value that does not fit in admissible range |
EmailInvalid | 400 | The email is invalid |
FetchScopesInvalid | 406 | The value of |
FetchScopesNotAllowed | 406 | The value of |
FileError | 406 | An error has occured while uploading and/or processing the file |
FileNotProvided | 400 | Provider with the |
FileNotSaved | 400 | File was not saved because of an error |
HolderInfoNotSupported | 406 | Fetching |
IdentifierInvalid | 406 | Invalid identifier sent for creatinng a customer |
InteractiveTimeout | 400 | It took too long to respond to the interactive question |
InvalidAispConsentFromDate | 406 | Invalid consent |
InvalidAispConsentPeriod | 406 | Invalid consent |
InvalidFromDate | 406 | Invalid |
InvalidToDate | 406 | Invalid |
InvalidURI | 400 | The format of the URI could not be determined |
JsonParseError | 400 | Either we have received some other request format instead of JSON, or the body could not be parsed |
PartnerConsentAlreadyRevoked | 406 | The partner consent has already been revoked |
PartnerConsentNotFound | 406 | A partner consent with such an |
PartnerConsentRevoked | 406 | The partner consent has been revoked by the end-user |
ProviderDisabled | 406 | The accessed provider has the |
ProviderInactive | 406 | The requested provider has the |
ProviderNotFound | 404 | Sending a |
ProviderNotInteractive | 406 | The connection’s provider does not have an interactive step |
RateLimitExceeded | 406 | Too many connections are being processed at the same time from one application |
ReportNotFound | 404 | The requested Financial Insights |
RequestExpired | 400 | The request has expired, took longer than mentioned in the |
ReturnURLInvalid | 406 | The |
ReturnURLTooLong | 406 | The |
RouteNotFound | 404 | The action and/or the endpoint you are trying to access does not exist |
TransactionNotFound | 404 | A transaction with the sent |
ValueOutOfRange | 400 | Sending a value (e.g. |
WrongProviderMode | 406 | We do not support the received |
WrongRequestFormat | 400 | The JSON request is incorrectly formed |
Partner Configuration
Error class | HTTP code | Description |
---|---|---|
ActionNotAllowed | 400 | The partner has no access to the required route or direct API access is not permitted. For assistance, feel free to contact your Account Manager at Salt Edge or our Sales team via contact us. |
ApiKeyNotFound | 404 | The API key with the provided |
AppIdNotProvided | N/A | The |
AppsRestricted | 400 | The API key used in the request has |
ClientDisabled | 406 | The partner has been disabled. You can find out more about the |
ClientNotFound | 404 | The API key used in the request does not belong to the partner |
ClientPending | 406 | The partner is pending approval. You can find out more about the pending status on Pending guides page. |
ClientRestricted | 406 | The partner is in restricted status. You can find out more about |
ConnectionFailed | 406 | Some network errors appear while fetching data |
ConnectionLost | N/A | Internet connection was lost in the process |
ExpiresAtInvalid | 400 | The |
InternalServerError | 500 | An internal error has occurred |
InvalidEncoding | 400 | Invalid JSON encoded values |
MissingExpiresAt | 400 | The |
MissingSignature | 400 | The |
ProviderKeyNotFound | 404 | The chosen provider does not have provider keys |
PublicKeyNotProvided | 400 | The public key was not specified on Keys & secrets page |
SecretNotProvided | 400 | The |
SignatureNotMatch | 400 | The |
TooManyRequests | 400 | Too many requests have occurred for connecting/reconnecting a connection from one IP address in a short period of time |
WrongClientToken | 400 | We have received a wrong combination of |
WrongReportType | 400 | We have received a wrong report type |
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 Salt Edge Partners API.
Parameters
include_fake_providers
boolean, optional
Whether you wish to fetch the fake countries, defaults to false
include_fake_providers
boolean, optional
Whether you wish to fetch the fake countries, defaults to false
Response
name
string
Name of the country
code
string
Country code as dated in ISO 3166-1 alpha-2
refresh_start_time
integer
Local country time when connections will be automatically refreshed. Possible values: 0
to 23
name
string
Name of the country
code
string
Country code as dated in ISO 3166-1 alpha-2
refresh_start_time
integer
Local country time when connections will be automatically refreshed. Possible values: 0
to 23
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/countries
https://www.saltedge.com/api/partners/v1/countries
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/countries
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/countries
Sample response
{
"data": [
{
"code": "CZ",
"name": "Czech Republic",
"refresh_start_time": 2
},
{
"code": "IL",
"name": "Israel",
"refresh_start_time": 2
},
{
"code": "MD",
"name": "Moldova",
"refresh_start_time": 2
},
{
"code": "RO",
"name": "Romania",
"refresh_start_time": 2
},
{
"code": "RU",
"name": "Russia",
"refresh_start_time": 2
},
{
"code": "UA",
"name": "Ukraine",
"refresh_start_time": 2
},
{
"code": "XF",
"name": "Fake",
"refresh_start_time": 2
},
{
"code": "XO",
"name": "Other",
"refresh_start_time": 2
},
...
]
}
Providers
A provider is a source of financial data. We recommend you update all of the provider’s fields at least daily.
Attributes
id
string
Provider’s id
code
string
Provider’s code
name
string
Provider’s name
modes
string
Possible values are:
oauth
- access through the bank’s dedicated API (regulated: true
). The user is redirected to the bank’s page for authorization.web
- access through the bank’s WEB interface using screen scraping technology. Therefore, a user undergoes the same authorization flow as in their bank’s web interface with an identical set of credentials.api
- access through a dedicated (regulated: true
) or non-dedicated (regulated: false
) bank’s API. Some required credentials fields might be present which the user should complete (IBAN, username, etc.). In case of a dedicated API, an interactive redirect might be present, but there are required credentials fields which the user should complete (IBAN, username, etc.). Using these credentials, we authorize the user on the bank’s side.file
- access through uploading a file of certain format (XLS, CSV, etc.), which is processed to extract information of their accounts and transactions.
status
string
Possible values are: active
, inactive
, disabled
- The providers with the
inactive
status are returned on the providers list endpoint, but are not visible on the Connect widget for the end-users. - The providers with
disabled
status are neither returned on the providers list endpoint, nor visible on the Connect widget for the end-users.
automatic_fetch
boolean
Whether the provider’s connections can be automatically fetched. However, its performance also depends on optional_interactivity
flag
dynamic_registration_code
string
The dynamic registration code assigned to the Provider
group_code
string
The code of the group to which the Provider belongs
group_name
string
It can be equal to provider_code
, but may also change independently, regardless of the provider_code
hub
string
The hub that the Provider is affiliated with
customer_notified_on_sign_in
boolean
Whether the provider will notify the customer on log in attempt
interactive
boolean
Whether the provider requires interactive input
instruction
string
Instructions on how to connect the bank, in English
home_url
string
The URL of the main page of the provider
login_url
string
Point of entrance to provider’s login web interface
logo_url
string
The URL for the provider logo, may have a placeholder for providers with missing logos
country_code
string
Code of the provider’s country
refresh_timeout
integer
Amount of time (in minutes) after which the provider’s connections are allowed to be refreshed
holder_info
array
Contains information on the account holder details that can be fetched from this provider
max_consent_days
integer
Maximum allowed consent duration. If it is null
then there are no limits
created_at
datetime
Time and date when the provider was integrated
updated_at
datetime
The last time when any of provider’s attributes were changed
timezone
string
Time zone data of capital/major city in a region corresponding to a 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 is integrated via a regulated channel under Open Banking/PSD2
max_fetch_interval
integer
Max period in days that can be fetched form from the provider’s 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_natures
array
Array of possible account natures to be fetched. Non-payment natures: bonus
, credit
, insurance
, investment
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
payment_templates
array of strings
Identifiers of the payment templates that are supported by this provider
supported_payment_fields
object
If these fields are passed, they will be used by the provider. Otherwise, the payment will we processed even without them.
required_payment_fields
object
Mandatory payment attributes. If any of these fields are not passed, the payment will not be initiated successfully.
no_funds_rejection_supported
boolean
A flag which indicates whether the bank supports explicit handling of payment rejection due to insufficient funds.
For example, it can be a header in the request (TPP-Rejection-NoFunds-Preferred
) which set to true
will automatically reject the payment in case of insufficient funds. Note that many banks handle this behaviour by default, but some of them offer the possibility to choose the outcome of insufficient funds.
id
string
Provider’s id
code
string
Provider’s code
name
string
Provider’s name
modes
string
Possible values are:
oauth
- access through the bank’s dedicated API (regulated: true
). The user is redirected to the bank’s page for authorization.web
- access through the bank’s WEB interface using screen scraping technology. Therefore, a user undergoes the same authorization flow as in their bank’s web interface with an identical set of credentials.api
- access through a dedicated (regulated: true
) or non-dedicated (regulated: false
) bank’s API. Some required credentials fields might be present which the user should complete (IBAN, username, etc.). In case of a dedicated API, an interactive redirect might be present, but there are required credentials fields which the user should complete (IBAN, username, etc.). Using these credentials, we authorize the user on the bank’s side.file
- access through uploading a file of certain format (XLS, CSV, etc.), which is processed to extract information of their accounts and transactions.
status
string
Possible values are: active
, inactive
, disabled
- The providers with the
inactive
status are returned on the providers list endpoint, but are not visible on the Connect widget for the end-users. - The providers with
disabled
status are neither returned on the providers list endpoint, nor visible on the Connect widget for the end-users.
automatic_fetch
boolean
Whether the provider’s connections can be automatically fetched. However, its performance also depends on optional_interactivity
flag
dynamic_registration_code
string
The dynamic registration code assigned to the Provider
group_code
string
The code of the group to which the Provider belongs
group_name
string
It can be equal to provider_code
, but may also change independently, regardless of the provider_code
hub
string
The hub that the Provider is affiliated with
customer_notified_on_sign_in
boolean
Whether the provider will notify the customer on log in attempt
interactive
boolean
Whether the provider requires interactive input
instruction
string
Instructions on how to connect the bank, in English
home_url
string
The URL of the main page of the provider
login_url
string
Point of entrance to provider’s login web interface
logo_url
string
The URL for the provider logo, may have a placeholder for providers with missing logos
country_code
string
Code of the provider’s country
refresh_timeout
integer
Amount of time (in minutes) after which the provider’s connections are allowed to be refreshed
holder_info
array
Contains information on the account holder details that can be fetched from this provider
max_consent_days
integer
Maximum allowed consent duration. If it is null
then there are no limits
created_at
datetime
Time and date when the provider was integrated
updated_at
datetime
The last time when any of provider’s attributes were changed
timezone
string
Time zone data of capital/major city in a region corresponding to a 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 is integrated via a regulated channel under Open Banking/PSD2
max_fetch_interval
integer
Max period in days that can be fetched form from the provider’s 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_natures
array
Array of possible account natures to be fetched. Non-payment natures: bonus
, credit
, insurance
, investment
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
payment_templates
array of strings
Identifiers of the payment templates that are supported by this provider
supported_payment_fields
object
If these fields are passed, they will be used by the provider. Otherwise, the payment will we processed even without them.
required_payment_fields
object
Mandatory payment attributes. If any of these fields are not passed, the payment will not be initiated successfully.
no_funds_rejection_supported
boolean
A flag which indicates whether the bank supports explicit handling of payment rejection due to insufficient funds.
For example, it can be a header in the request (TPP-Rejection-NoFunds-Preferred
) which set to true
will automatically reject the payment in case of insufficient funds. Note that many banks handle this behaviour by default, but some of them offer the possibility to choose the outcome of insufficient funds.
Sample object
{
"id": "111111111111111111",
"code": "fakebank_simple_xf",
"name": "Fake Bank",
"mode": "web",
"status": "active",
"automatic_fetch": true,
"dynamic_registration_code": null,
"group_code": "fake",
"group_name": "Fake",
"hub": null,
"customer_notified_on_sign_in": false,
"interactive": false,
"identification_mode": "saltedge",
"instruction": "Please fill in all the fields.",
"home_url": "http://example.com",
"login_url": "http://example.com/login",
"logo_url": "https://cdn.com/logos/providers/xf/fake.svg",
"country_code": "XF",
"refresh_timeout": 60,
"holder_info": ["names", "emails", "phone_numbers"],
"max_consent_days": 10,
"created_at": "2024-09-28T14:41:01Z",
"updated_at": "2024-10-03T14:41:01Z",
"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
.
Parameters
provider_code
string
Provider’s code
include_payments_fields
boolean, optional
Whether you wish to include supported_payment_fields
and required_payment_fields
, defaults to false
provider_code
string
Provider’s code
include_payments_fields
boolean, optional
Whether you wish to include supported_payment_fields
and required_payment_fields
, defaults to false
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/providers/{provider.code}
https://www.saltedge.com/api/partners/v1/providers/{provider.code}
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/providers/fakebank_interactive_xf
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/providers/fakebank_interactive_xf
Sample response
{
"data": {
"id": "111111111111111111",
"code": "fakebank_interactive_xf",
"name": "Fake Bank with SMS",
"mode": "web",
"status": "active",
"automatic_fetch": false,
"dynamic_registration_code": null,
"group_code": "fake",
"group_name": "Fake",
"hub": null,
"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": "2020-03-19T17:55:44Z",
"updated_at": "2020-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.
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_payments_fields
boolean, optional
Whether you wish to include supported_payment_fields
and required_payment_fields
, defaults to false
from_id
string, optional
The id
of the record starting the next page, defaults to null
from_date
date, optional
Filtering providers created or updated starting from this date, defaults to null
country_code
string, optional
Filtering providers by country, defaults to null
mode
string, optional
Filtering providers by mode, possible values are: oauth
, web
, api
, file
include_fake_providers
boolean, optional
Whether you wish to fetch the fake providers, defaults to false
include_payments_fields
boolean, optional
Whether you wish to include supported_payment_fields
and required_payment_fields
, defaults to false
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/providers
https://www.saltedge.com/api/partners/v1/providers
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/providers
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/providers
Sample Response
{
"data": [
{
"id": "111111111111111111",
"code": "fakebank_image_xf",
"name": "Fake Bank with Image",
"mode": "web",
"status": "active",
"automatic_fetch": false,
"dynamic_registration_code": null,
"group_code": "fake",
"group_name": "Fake",
"hub": null,
"customer_notified_on_sign_in": true,
"interactive": true,
"identification_mode": "saltedge",
"instruction": "Please fill in all the fields.",
"home_url": "http://example.com",
"login_url": "http://example.com/login",
"logo_url": "https://cdn.com/logos/providers/xf/fake.svg",
"country_code": "XF",
"refresh_timeout": 60,
"holder_info": ["names", "emails", "phone_numbers"],
"max_consent_days": 10,
"created_at": "2024-09-28T14:41:01Z",
"updated_at": "2024-10-03T14:41:01Z",
"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
}
}
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_with_dynamic_select_xf
- allows to test thedynamic_select
credentials field;fakebank_image_xf
- the user needs to solve a CAPTCHA for authentication;fakebank_inactive_xf
- reproduces theProviderInactive
error;fakebank_interactive_xf
- asks for a fake SMS code;fake_delayed_oauth_client_xf
- will delay the payment initiation by a few seconds;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).fakebank_two_step_interactive_xf
- asks for interactive data twice during the fetching process;fakebank_semi_interactive_xf
- occasionally requires an SMS code;fake_oauth_interactive_client_xf
- has an interactive redirect during the attempt besides the first authorize redirect;fake_oauth_interactive_no_callback_client_xf
- allows testing scenario for additional redirect during the SCA process;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;fake_with_partial_data_xf
- has a dropdown list with some options for the user to choose from. Allows to test 3 different scenarios of partial data: incomplete accounts data, incomplete transactions data, and an error;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;fake_business_demobank_xf
- simulates the flow of a non-regulated API provider;fakebank_with_token_xf
- requires a username and a fake token;fake_with_dynamic_registration_oauth_client_xf
- linked to a fake dynamic registration. Once the dynamic registration is executed, the provider keys will be added automatically;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;fake_oauth_eidas_client_xf
- will raise an error if QWAC or QSeal certificates are not configured correctly in the client’s account;fakebank_with_crypto_assets_xf
- simulates the flow of a crypto provider;fakebank_with_natures_xf
- allows testing all the possiblesupported_account_natures
;fakebank_with_file_csv_xf
- extracts transactions from a csv file. You can download the sample here; Note: Testing this provider allows the client to test categorization and merchant identification for a desired country. For that, it is required to configure theCountry
andAccount Currency
fields accordingly;fake_with_error_client_xf
- allows testing multiple errors.
The Fake Bank with Error
(fake_with_error_client_xf
) allows selecting the error you would like to test. The choices are as follows:
Invalid SCA redirect URL
- no error. The user will be redirected to an invalid URL. As a result, the connection will fail withProviderAccessNotGranted
because the PSU (user) couldn’t complete the authorization step.Token Expired
- Error class: InvalidCredentials. Error message: Invalid token.Consent Invalid
- Error class: InvalidCredentials. Error message: Consent is not valid.Access declined
- Error class: InvalidCredentials. Error message: Access declined. Please contact your bank’s customer service.Too many requests
- Error class: ProviderUnavailable. Error message: Too many requests.ExecutionTimeout
- Error class: ExecutionTimeout. Error message: ExecutionTimeout error.InteractiveAdapterTimeout
- Error class: InteractiveAdapterTimeout. Error message: Interactive timeout.InvalidInteractiveCredentials
- Error class: InvalidInteractiveCredentials. Error message: Interactive action failed.AccountValidationError
- Error class: AccountValidationError. Error message: ‘Simple account 2’ already exists in account list.Payment failed with delay
- The payment will fail after 20 to 25 second from the moment of initialization. Error class: PaymentFailed. Error message: Payment failed.
Fake OAuth Bank with Client Keys (fake_oauth_client_xf
) allows selecting the successful scenario you would like to test. The choices are as follows:
Grant access
- The payment/attempt will be accepted.Accepted payment with delay
- The payment will be accepted after 20 to 25 second from the moment of initialization.
The ProviderNotFound
error may be reproduced by trying any inexistent and invalid provider_code
.
Note: The appropriate credentials for a particular provider are mentioned under the Instructions
field on its Connect page.
Sandbox
Sandbox is a live-testing environment of a regulated provider that allows Partners and Clients to test providers under Salt Edge’s supervision.
In order to help with testing regulated providers, Salt Edge offers the sandbox environment of each PSD2 bank. A sandbox is identified by the word Sandbox in the provider_name
(eg. Lloyds Bank (Sandbox)) with a designated provider_code
containing XF
as country code (eg.lloyds_oauth_client_gb_xf
).
Just as with the fake providers, sandbox providers can be tested if your application is in Test or Pending status. In the Connect page, we will let you select the fake country (having the country code XF
), and its sandbox providers.
The authorization instructions are mentioned under the Instructions
field on its Connect page.
Note: Some Sandboxes may not be available for an indefinite period of time due to the limited support sources of a provider.
Leads
The leads are the end-users (PSUs) that can create connections and share data with a partner.
Create
Allows to create or return an existing lead, thus bypassing the Sign Up stage which requires user input. The response contains the email of the lead and the associated customer_id
which can be used for creating a lead session.
It also allows to send Know Your Customer (KYC) information about the lead, both personal and/or legal information. If some of the KYC information is not sent via API, the lead may be asked about it during the payment session, depending on the partner configuration, as part of anti-money laundering check. If some of the KYC information is not known, the corresponding keys should not be sent.
Parameters
string, required
Email address
identifier
string, optional
An optional field that can be used for additional information about the lead, e.g IBAN, phone, reference_number, etc. Returned in response only if it was present in payload.
kyc
object, optional
Additional information about the lead
string, required
Email address
identifier
string, optional
An optional field that can be used for additional information about the lead, e.g IBAN, phone, reference_number, etc. Returned in response only if it was present in payload.
kyc
object, optional
Additional information about the lead
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/leads
https://www.saltedge.com/api/partners/v1/leads
Method
POST
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"email\": \"test@email.com\", \
\"identifier\": \"example-identifier\", \
\"kyc\": { \
\"full_name\": \"John Smith\", \
\"type_of_account\": \"own\", \
\"date_of_birth\": \"2020-01-01\", \
\"place_of_birth\": \"London\", \
\"gender\": \"male\", \
\"citizenship_code\": \"GB\", \
\"residence_address\": \"London, Independence str, block 5\", \
\"legal_name\": \"My Company Limited\", \
\"registered_office_code\": \"GB\", \
\"registered_office_address\": \"London, Independence str, block 5\", \
\"registration_number\": \"12345\" \
} \
} \
}" \
https://www.saltedge.com/api/partners/v1/leads
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"email\": \"test@email.com\", \
\"identifier\": \"example-identifier\", \
\"kyc\": { \
\"full_name\": \"John Smith\", \
\"type_of_account\": \"own\", \
\"date_of_birth\": \"2020-01-01\", \
\"place_of_birth\": \"London\", \
\"gender\": \"male\", \
\"citizenship_code\": \"GB\", \
\"residence_address\": \"London, Independence str, block 5\", \
\"legal_name\": \"My Company Limited\", \
\"registered_office_code\": \"GB\", \
\"registered_office_address\": \"London, Independence str, block 5\", \
\"registration_number\": \"12345\" \
} \
} \
}" \
https://www.saltedge.com/api/partners/v1/leads
Sample response
{
"data": {
"email": "test@email.com",
"customer_id": "222222222222222222",
"identifier": "example-identifier"
}
}
Remove
Deletes partner association with a lead.
Once a lead is de-associated with a partner account, the lead will not be able to share the consent with the partner’s account again. The lead and the connections remain accessible from the End-user dashboard and can be shared with any other partner(s).
When it’s needed to allow a de-associated lead to share the connections with the partner again, then the partner should use leads create route. In this case, the original email
used for the lead original creation should be sent as email
parameter in the lead’s create request. Once it’s done, the lead will have the possibility to share the connection(s) with the partner again.
Parameters
customer_id
string, required
The id
of the customer.
customer_id
string, required
The id
of the customer.
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/leads?customer_id={customer.id}
https://www.saltedge.com/api/partners/v1/leads
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/partners/v1/leads?customer_id=123
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/partners/v1/leads?customer_id=123
Sample response
{
"data": {
"deleted": true,
"lead_email": "lead@email.com"
}
}
Lead session
Lead session is a temporary object that links the Connect session with a new connection object that will be created once the user grants consent to Salt Edge Partners API to fetch data.
If a lead for which a connection is to be created did not previously exist, an email will be sent to the lead with instructions on how to set a password to access the Salt Edge Dashboard account.
Create
Allows you to create a lead session.
Parameters
customer_id
string, optional
The id
of the customer. If the id
is not sent in the request, the customer will be redirected to Sign Up/Sign In page.
If the id
is sent in the request, Sign Up/Sign In page will be skipped.
allowed_countries
array of strings, optional
The list of countries that will be accessible for the customer to choose from, defaults to EU and EEA region + XF
.
Full list: AT
, BE
, BG
, CY
, CZ
, DE
, DK
, EE
, ES
, FI
, FR
, GB
, GR
, HR
, HU
, IE
, IS
, IT
, LI
, LT
, LU
, LV
, MT
, NL
, NO
, PL
, PT
, RO
, SE
, SI
, SK
, XF
.
Example: ['CZ', 'DE']
country_code
string, optional
Returns the list of providers only from given country. Possible values: any country code from ISO 3166-1 alpha-2, e.g.: 'DE'
. Defaults to null
provider_code
string, optional
The code of the desired provider, defaults to null
skip_provider_select
boolean, optional
Whether the provider selection page should be skipped. In order for this to work, besides passing skip_provider_select
as true
, an OAuth provider’s provider_code
should be passed. Defaults to: false
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge, defaults to true
disable_provider_search
boolean, optional
Whether the provider search will be disabled, works only if provider_code
parameter is sent. Defaults to false
return_connection_id
boolean, optional
Whether to append connection_id
to return_to
URL. Will be accompanied by shared: true/false
to show whether access to this connection has been granted. Only works if return_to
in the attempt object is also passed. Defaults to true
provider_modes
array of strings, optional
Restrict the list of the providers to only the ones that have the mode included in the array.
Possible values inside the array are: oauth
, web
, api
, file
, defaults to the array containing all possible modes
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Default: personal
include_fake_providers
boolean, optional
return_error_class
boolean, optional
Whether to append error_class
to return_to
URL. Defaults to false
regulated
boolean, optional
Whether to show regulated providers in Connect. Passing true
will show only the regulated providers. Passing false
will show only the non-regulated providers. Defaults to null
, which will show both regulated and non-regulated providers
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.
javascript_callback_type
string, optional
Allows you to specify what kind of JavaScript callback method Connect should use. Possible value: post_message
.
kyc
object, optional
Additional information about the lead
allowed_countries
array of strings, optional
The list of countries that will be accessible for the customer to choose from, defaults to EU and EEA region + XF
.
Full list: AT
, BE
, BG
, CY
, CZ
, DE
, DK
, EE
, ES
, FI
, FR
, GB
, GR
, HR
, HU
, IE
, IS
, IT
, LI
, LT
, LU
, LV
, MT
, NL
, NO
, PL
, PT
, RO
, SE
, SI
, SK
, XF
.
Example: ['CZ', 'DE']
country_code
string, optional
Returns the list of providers only from given country. Possible values: any country code from ISO 3166-1 alpha-2, e.g.: 'DE'
. Defaults to null
provider_code
string, optional
The code of the desired provider, defaults to null
skip_provider_select
boolean, optional
Whether the provider selection page should be skipped. In order for this to work, besides passing skip_provider_select
as true
, an OAuth provider’s provider_code
should be passed. Defaults to: false
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge, defaults to true
disable_provider_search
boolean, optional
Whether the provider search will be disabled, works only if provider_code
parameter is sent. Defaults to false
return_connection_id
boolean, optional
Whether to append connection_id
to return_to
URL. Will be accompanied by shared: true/false
to show whether access to this connection has been granted. Only works if return_to
in the attempt object is also passed. Defaults to true
provider_modes
array of strings, optional
Restrict the list of the providers to only the ones that have the mode included in the array.
Possible values inside the array are: oauth
, web
, api
, file
, defaults to the array containing all possible modes
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Default: personal
include_fake_providers
boolean, optional
return_error_class
boolean, optional
Whether to append error_class
to return_to
URL. Defaults to false
regulated
boolean, optional
Whether to show regulated providers in Connect. Passing true
will show only the regulated providers. Passing false
will show only the non-regulated providers. Defaults to null
, which will show both regulated and non-regulated providers
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.
javascript_callback_type
string, optional
Allows you to specify what kind of JavaScript callback method Connect should use. Possible value: post_message
.
kyc
object, optional
Additional information about the lead
Possible Errors
- AispConsentScopesInvalid
- AispConsentScopesNotAllowed
- ClientDisabled
- ClientNotFound
- ClientRestricted
- ConnectionNotFound
- CountryNotFound
- CustomerLocked
- CustomerNotFound
- DateOutOfAispConsentRange
- DateTimeFormatInvalid
- DateTimeOutOfRange
- FetchScopesNotAllowed
- InvalidAispConsentFromDate
- InvalidAispConsentPeriod
- InvalidFromDate
- InvalidToDate
- JsonParseError
- ProviderNotFound
- ReturnURLInvalid
- ReturnURLTooLong
- WrongProviderMode
- WrongRequestFormat
URL
https://www.saltedge.com/api/partners/v1/lead_sessions/create
https://www.saltedge.com/api/partners/v1/lead_sessions/create
Method
POST
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"consent\": { \
\"from_date\": \"2020-01-01\", \
\"period_days\": 90, \
\"scopes\": [ \
\"account_details\", \
\"transactions_details\" \
] \
}, \
\"attempt\": { \
\"from_date\": \"2020-02-01\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
], \
\"custom_fields\": { \
\"test\": true \
} \
} \
} \
}" \
https://www.saltedge.com/api/partners/v1/lead_sessions/create
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"consent\": { \
\"from_date\": \"2020-01-01\", \
\"period_days\": 90, \
\"scopes\": [ \
\"account_details\", \
\"transactions_details\" \
] \
}, \
\"attempt\": { \
\"from_date\": \"2020-02-01\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
], \
\"custom_fields\": { \
\"test\": true \
} \
} \
} \
}" \
https://www.saltedge.com/api/partners/v1/lead_sessions/create
Sample response
{
"data": {
"expires_at": "2024-10-08T15:41:01Z",
"redirect_url": "https://www.saltedge.com/dashboard/sign_up?invitation_token=GENERATED_TOKEN"
}
}
Reconnect
Allows you to create a lead session to reconnect an existing connection.
Reconnect requires a new consent to be given. The consent confirmation in this case can be handled either on the client’s side (the ‘access terms’ on which the customer has agreed should be sent) or on Salt Edge side (‘access terms’ on which the customer has to agree should be sent).
Reconnect will prompt a new partner consent to be given and is only possible if the connection was previously shared with you.
Parameters
customer_id
string, required
The id
of the customer.
connection_id
string, required
The id
of the connection you wish to reconnect
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge, defaults to true
return_connection_id
boolean, optional
Whether to append connection_id
to return_to
URL. Will be accompanied by shared: true/false
to show whether access to this connection has been granted. Only works if return_to
in the attempt object is also passed. Defaults to true
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Default: personal
include_fake_providers
boolean, optional
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.
javascript_callback_type
string, optional
Allows you to specify what kind of JavaScript callback method Connect should use. Possible value: post_message
.
connection_id
string, required
The id
of the connection you wish to reconnect
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge, defaults to true
return_connection_id
boolean, optional
Whether to append connection_id
to return_to
URL. Will be accompanied by shared: true/false
to show whether access to this connection has been granted. Only works if return_to
in the attempt object is also passed. Defaults to true
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Default: personal
include_fake_providers
boolean, optional
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.
javascript_callback_type
string, optional
Allows you to specify what kind of JavaScript callback method Connect should use. Possible value: post_message
.
Possible Errors
- AispConsentScopesInvalid
- AispConsentScopesNotAllowed
- ClientDisabled
- ClientNotFound
- ClientRestricted
- ConnectionNotFound
- CountryNotFound
- CustomerLocked
- CustomerNotFound
- DateOutOfAispConsentRange
- DateTimeFormatInvalid
- DateTimeOutOfRange
- FetchScopesNotAllowed
- InvalidAispConsentFromDate
- InvalidAispConsentPeriod
- InvalidFromDate
- InvalidToDate
- JsonParseError
- ProviderNotFound
- ReturnURLInvalid
- ReturnURLTooLong
- WrongProviderMode
- WrongRequestFormat
URL
https://www.saltedge.com/api/partners/v1/lead_sessions/reconnect
https://www.saltedge.com/api/partners/v1/lead_sessions/reconnect
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\": \"222222222222222222\", \
\"connection_id\": \"111111111111111111\", \
\"consent\": { \
\"from_date\": \"2020-01-01\", \
\"period_days\": 90, \
\"scopes\": [ \
\"account_details\", \
\"transactions_details\" \
] \
}, \
\"attempt\": { \
\"from_date\": \"2020-02-01\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
], \
\"custom_fields\": { \
\"test\": true \
} \
} \
} \
}" \
https://www.saltedge.com/api/partners/v1/lead_sessions/reconnect
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"222222222222222222\", \
\"connection_id\": \"111111111111111111\", \
\"consent\": { \
\"from_date\": \"2020-01-01\", \
\"period_days\": 90, \
\"scopes\": [ \
\"account_details\", \
\"transactions_details\" \
] \
}, \
\"attempt\": { \
\"from_date\": \"2020-02-01\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
], \
\"custom_fields\": { \
\"test\": true \
} \
} \
} \
}" \
https://www.saltedge.com/api/partners/v1/lead_sessions/reconnect
Sample response
{
"data": {
"expires_at": "2024-10-08T15:41:01Z",
"redirect_url": "https://www.saltedge.com/dashboard/connect?token=GENERATED_TOKEN"
}
}
Refresh
Allows you to create a lead session to refresh an existing connection.
Refresh does not require a new consent, it is based on the limitations of the current active consent. If the latest consent has been revoked, only a reconnect is possible.
Parameters
customer_id
string, required
The id
of the customer.
connection_id
string, required
The id
of the connection you wish to refresh
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge, defaults to true
return_connection_id
boolean, optional
Whether to append connection_id
to return_to
URL. Will be accompanied by shared: true/false
to show whether access to this connection has been granted. Only works if return_to
in the attempt object is also passed. Defaults to true
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Default: personal
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.
javascript_callback_type
string, optional
Allows you to specify what kind of JavaScript callback method Connect should use. Possible value: post_message
.
connection_id
string, required
The id
of the connection you wish to refresh
daily_refresh
boolean, optional
Whether the connection should be automatically refreshed by Salt Edge, defaults to true
return_connection_id
boolean, optional
Whether to append connection_id
to return_to
URL. Will be accompanied by shared: true/false
to show whether access to this connection has been granted. Only works if return_to
in the attempt object is also passed. Defaults to true
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Default: personal
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.
javascript_callback_type
string, optional
Allows you to specify what kind of JavaScript callback method Connect should use. Possible value: post_message
.
Possible Errors
- ClientDisabled
- ClientNotFound
- ClientRestricted
- ConnectionNotFound
- CountryNotFound
- CustomerLocked
- CustomerNotFound
- DateOutOfAispConsentRange
- DateTimeFormatInvalid
- DateTimeOutOfRange
- FetchScopesNotAllowed
- InvalidFromDate
- InvalidToDate
- JsonParseError
- ProviderNotFound
- ReturnURLInvalid
- ReturnURLTooLong
- WrongProviderMode
- WrongRequestFormat
URL
https://www.saltedge.com/api/partners/v1/lead_sessions/refresh
https://www.saltedge.com/api/partners/v1/lead_sessions/refresh
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\": \"222222222222222222\", \
\"connection_id\": \"111111111111111111\", \
\"attempt\": { \
\"from_date\": \"2020-02-01\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
], \
\"custom_fields\": { \
\"test\": true \
} \
} \
} \
}" \
https://www.saltedge.com/api/partners/v1/lead_sessions/refresh
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"222222222222222222\", \
\"connection_id\": \"111111111111111111\", \
\"attempt\": { \
\"from_date\": \"2020-02-01\", \
\"fetch_scopes\": [ \
\"accounts\", \
\"transactions\" \
], \
\"custom_fields\": { \
\"test\": true \
} \
} \
} \
}" \
https://www.saltedge.com/api/partners/v1/lead_sessions/refresh
Sample response
{
"data": {
"expires_at": "2024-10-08T15:41:01Z",
"redirect_url": "https://www.saltedge.com/dashboard/connect?token=GENERATED_TOKEN"
}
}
Partner consents
Partner consent is a part of the combined consent shown to the customer that allows Salt Edge to share account, transaction and holder info data with the registered partner, based on the right to data portability enforced by the EU General Data Protection Regulation (GDPR).
Attributes
id
string
The id
of the partner consent
status
string
Possible values are: active
, revoked
revoked_by
string
Entity who revoked the partner consent. Possible values: partner
, lead
, saltedge
revoked_at
date
When the partner consent was revoked
created_at
date
When the partner consent was created
updated_at
date
When the partner consent was updated
id
string
The id
of the partner consent
status
string
Possible values are: active
, revoked
revoked_by
string
Entity who revoked the partner consent. Possible values: partner
, lead
, saltedge
revoked_at
date
When the partner consent was revoked
created_at
date
When the partner consent was created
updated_at
date
When the partner consent was updated
List
Returns all the partner consents accessible to your application for a certain customer.
The partner consents are sorted in ascending order of their id
, so the latest partner consents will come last.
You can read more about next_id
field, in the pagination section of the reference.
Parameters
connection_id
string, optional
The id
of the connection containing the partner consents
customer_id
string, optional
The id
of the customer containing the partner consents.
Note: Will be ignored if connection_id
is present.
from_id
string, optional
The id
from which the next page of partner consents starts
from_id
string, optional
The id
from which the next page of partner consents starts
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/partner_consents?connection_id={connection.id}
https://www.saltedge.com/api/partners/v1/partner_consents
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/partner_consents?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/partner_consents
Sample Response
{
"data": [
{
"id": "555555555555555555",
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"status": "active",
"revoked_by": null,
"revoked_at": null,
"created_at": "2024-10-08T11:41:01Z",
"updated_at": "2024-10-08T11:41:01Z"
}
],
"meta" : {
"next_id": "555555555555555556",
"next_page": "/api/partners/v1/partner_consents?connection_id=111111111111111111&from_id=555555555555555556"
}
}
{
"data": [
{
"id": "555555555555555555",
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"status": "active",
"revoked_by": null,
"revoked_at": null,
"created_at": "2024-10-08T11:41:01Z",
"updated_at": "2024-10-08T11:41:01Z"
}
],
"meta" : {
"next_id": "555555555555555556",
"next_page": "/api/partners/v1/partner_consents?from_id=555555555555555556"
}
}
Show
Returns the partner consent object.
Parameters
connection_id
string, optional
The id
of the connection containing the consents
customer_id
string, optional
The id
of the customer containing the consents.
Note: Will be ignored if connection_id
is present.
id
string, required
The id
of the consent
id
string, required
The id
of the consent
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/partner_consents/{consent.id}?connection_id={connection.id}
https://www.saltedge.com/api/partners/v1/partner_consents/{consent.id}
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/partner_consents/555555555555555555?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/partner_consents/555555555555555555
Sample Response
{
"data": {
"id": "555555555555555555",
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"status": "active",
"revoked_by": null,
"revoked_at": null,
"created_at": "2024-10-08T11:41:01Z",
"updated_at": "2024-10-08T11:41:01Z"
}
}
{
"data": {
"id": "555555555555555555",
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"status": "active",
"revoked_by": null,
"revoked_at": null,
"created_at": "2024-10-08T11:41:01Z",
"updated_at": "2024-10-08T11:41:01Z"
}
}
Revoke
Partner consent revoke is an action that allows you to revoke a partner consent given by a specific customer.
Attributes
connection_id
string, optional
The id
of the connection containing the consents
customer_id
string, optional
The id
of the customer containing the consents.
Note: Will be ignored if connection_id
is present.
id
string, required
The id
of the partner consent
id
string, required
The id
of the partner consent
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/partner_consents/{consent.id}/revoke?connection_id={connection.id}
https://www.saltedge.com/api/partners/v1/partner_consents/{consent.id}/revoke
Method
PUT
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X PUT \
https://www.saltedge.com/api/partners/v1/partner_consents/555555555555555555/revoke?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X PUT \
https://www.saltedge.com/api/partners/v1/partner_consents/555555555555555555/revoke
Sample Response
{
"data": {
"id": "555555555555555555",
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"status": "revoked",
"revoked_by": "partner",
"revoked_at": "2024-10-08T11:41:01Z",
"created_at": "2024-10-08T11:41:01Z",
"updated_at": "2024-10-08T11:41:01Z"
}
}
{
"data": {
"id": "555555555555555555",
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"status": "revoked",
"revoked_by": "partner",
"revoked_at": "2024-10-08T11:41:01Z",
"created_at": "2024-10-08T11:41:01Z",
"updated_at": "2024-10-08T11:41:01Z"
}
}
Customers
A customer represents a single end-user of the Salt Edge Partners API.
- Customer - a single end-user;
- Connection - a single connection to a provider. A single customer can have multiple connections to multiple banks;
- Account - an account returned by the provider. Corresponds to a customer’s bank account;
- Transaction - a single transaction made within an account. Can be a transfer transaction;
Here’s a diagram that illustrates the Customer and its associated concepts:
You need to store the id
returned in the callbacks, which is necessary when listing Connections.
We give you the following customer API actions so that the customer will be successfully identified within Salt Edge.
Show
Returns the customer object.
Parameters
id
string, required
The id
of the customer
id
string, required
The id
of the customer
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/customers/{customer.id}
https://www.saltedge.com/api/partners/v1/customers/{customer.id}
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/customers/222222222222222222
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/customers/222222222222222222
Sample Response
{
"data": {
"id": "222222222222222222",
"identifier": "12rv1212f1efxchsdhbgv",
"created_at": "2020-03-12T09:20:01Z",
"updated_at": "2020-03-12T09:20:01Z"
}
}
List
List all of your app customers. This route is available only for web applications, not mobile ones.
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/customers
https://www.saltedge.com/api/partners/v1/customers
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/customers
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/customers
Sample Response
{
"data": [
{
"id": "222222222222222222",
"identifier": "unique_customer_identifier",
"created_at": "2020-03-12T09:20:01Z",
"updated_at": "2020-03-12T09:20:01Z"
},
{
"id": "222222222222222223",
"identifier": "unique_customer_identifier_2",
"created_at": "2020-03-12T09:20:01Z",
"updated_at": "2020-03-12T09:20:01Z"
}
],
"meta": {
"next_id": "222222222222222224",
"next_page": "/api/partners/v1/customers?from_id=222222222222222224"
}
}
Connections
A connection represents a set of credentials required to access the accounts and transactions through a specific provider.
Within Salt Edge Partners API, a connection can have one of the following statuses:
active
- the current set of credentials is valid and allows us to properly fetch the data;inactive
- an error appeared while fetching the connection;The conditions when a connection will have
inactive
status:- Any attempt that fails with
Invalid credentials
error will mark the connection’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 connection.
Attributes
id
string
The id
of the connection
provider_id
string
The id
of the provider the connection belongs to
provider_code
string
The code of the provider the connection belongs to
provider_name
string
The name of the provider the connection belongs to
daily_refresh
boolean
Whether the connection will be refreshed daily
customer_id
string
The id
of the customer
created_at
datetime
Time and date when the connection was added
updated_at
datetime
The last time when the connection’s balance was changed, new accounts were imported or new transactions added/removed
last_success_at
datetime
Time when the connection was successfully fetched
status
string
Possible values are: active
, inactive
, disabled
country_code
string
Code of the country the provider belongs to
next_refresh_possible_at
datetime
When the next refresh will be available. May contain null
value if the connection has automatic_fetch
set as false
, or is already processing
show_consent_confirmation
boolean
Whether any consent was given for this login on Salt Edge side
id
string
The id
of the connection
provider_id
string
The id
of the provider the connection belongs to
provider_code
string
The code of the provider the connection belongs to
provider_name
string
The name of the provider the connection belongs to
daily_refresh
boolean
Whether the connection will be refreshed daily
customer_id
string
The id
of the customer
created_at
datetime
Time and date when the connection was added
updated_at
datetime
The last time when the connection’s balance was changed, new accounts were imported or new transactions added/removed
last_success_at
datetime
Time when the connection was successfully fetched
status
string
Possible values are: active
, inactive
, disabled
country_code
string
Code of the country the provider belongs to
next_refresh_possible_at
datetime
When the next refresh will be available. May contain null
value if the connection has automatic_fetch
set as false
, or is already processing
show_consent_confirmation
boolean
Whether any consent was given for this login on Salt Edge side
Sample object
{
"country_code": "XF",
"created_at": "2024-10-07T14:41:01Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"show_consent_confirmation": true,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"daily_refresh": false,
"categorization": "personal",
"created_at": "2024-10-08T14:41:01Z",
"customer_last_logged_at": "2024-10-08T11:41:01Z",
"custom_fields": {},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": ["accounts", "transactions"],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"success_at": "2024-10-08T14:41:01Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T14:41:01Z",
"show_consent_confirmation": true,
"consent_id": "555555555555555555",
"include_natures": ["account", "card", "bonus"],
"last_stage": {
"created_at": "2024-10-08T14:41:01Z",
"id": "888888888888888888",
"name": "finish",
"updated_at": "2024-10-08T14:41:01Z"
}
},
"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": "2024-10-08T14:41:01Z",
"next_refresh_possible_at": "2020-02-02T17:16:19Z",
"provider_id": "1234",
"provider_code": "fakebank_simple_xf",
"provider_name": "Fakebank Simple",
"status": "active",
"updated_at": "2024-10-08T14:41:01Z"
}
List
Returns all the connections accessible to your application for a certain customer.
The connections are sorted in ascending order of their id
, so the newest connections will come last.
We recommend you fetch the whole list of connections to check whether any of the properties have changed.
You can read more about next_id
field, in the pagination section of the reference.
Parameters
customer_id
string, required
The id
of the customer, allows to fetch connections only for a certain customer
from_id
string, optional
The id
of the record starting the next page
customer_id
string, required
The id
of the customer, allows to fetch connections only for a certain customer
from_id
string, optional
The id
of the record starting the next page
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/connections?customer_id={customer.id}
https://www.saltedge.com/api/partners/v1/connections?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/partners/v1/connections?customer_id=$CUSTOMER_ID
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/connections?customer_id=$CUSTOMER_ID
Sample Response
{ "data":
[
{
"country_code": "XF",
"created_at": "2024-10-07T14:41:01Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"show_consent_confirmation": true,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"daily_refresh": false,
"categorization": "personal",
"created_at": "2024-10-08T14:01:01Z",
"customer_last_logged_at": "2024-10-08T11:41:01Z",
"custom_fields": {},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": ["accounts", "transactions"],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"success_at": "2024-10-08T14:01:01Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T14:01:01Z",
"show_consent_confirmation": true,
"consent_id": "555555555555555555",
"include_natures": ["account", "card", "bonus"],
"last_stage": {
"created_at": "2024-10-08T14:01:01Z",
"id": "888888888888888888",
"name": "finish",
"updated_at": "2024-10-08T14:01:01Z"
}
},
"last_success_at": "2024-10-08T14:01:01Z",
"next_refresh_possible_at": "2020-02-02T17:16:19Z",
"provider_id": "1234",
"provider_code": "fakebank_simple_xf",
"provider_name": "Fakebank Simple",
"status": "active",
"updated_at": "2024-10-08T14:01:01Z"
}
],
"meta" : {
"next_id": "111111111111111112",
"next_page": "/api/partners/v1/connections?customer_id=222222222222222222&from_id=111111111111111112"
}
}
Show
Returns a single connection object.
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/connections/{connection.id}
https://www.saltedge.com/api/partners/v1/connection
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/connections/111111111111111111
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/connection
Sample Response
{
"data": {
"country_code": "MD",
"created_at": "2020-10-24T20:09:02Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"show_consent_confirmation": true,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"daily_refresh": false,
"categorization": "personal",
"created_at": "2020-02-02T16:14:53Z",
"customer_last_logged_at": "2024-10-08T11:41:01Z",
"custom_fields": {},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": ["accounts", "transactions"],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"success_at": "2020-02-02T16:16:19Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2020-02-02T16:16:19Z",
"show_consent_confirmation": true,
"consent_id": "555555555555555555",
"include_natures": ["account", "card", "bonus"],
"last_stage": {
"created_at": "2020-02-02T16:16:19Z",
"id": "888888888888888888",
"name": "finish",
"updated_at": "2020-02-02T16:16:19Z"
}
},
"last_success_at": "2020-02-02T16:16:19Z",
"next_refresh_possible_at": "2020-02-02T17:16:19Z",
"provider_id": "1234",
"provider_code": "moldindconbank_wb_md",
"provider_name": "Moldindconbank Web Banking",
"status": "active",
"updated_at": "2020-02-04T09:41:23Z"
}
}
{
"data": {
"country_code": "MD",
"created_at": "2020-10-24T20:09:02Z",
"customer_id": "222222222222222222",
"daily_refresh": false,
"id": "111111111111111111",
"show_consent_confirmation": true,
"last_consent_id": "555555555555555555",
"last_attempt": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"daily_refresh": false,
"categorization": "personal",
"created_at": "2020-02-02T16:14:53Z",
"customer_last_logged_at": "2024-10-08T11:41:01Z",
"custom_fields": {},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": ["accounts", "transactions"],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"success_at": "2020-02-02T16:16:19Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2020-02-02T16:16:19Z",
"show_consent_confirmation": true,
"consent_id": "555555555555555555",
"include_natures": ["account", "card", "bonus"],
"last_stage": {
"created_at": "2020-02-02T16:16:19Z",
"id": "888888888888888888",
"name": "finish",
"updated_at": "2020-02-02T16:16:19Z"
}
},
"last_success_at": "2020-02-02T16:16:19Z",
"next_refresh_possible_at": "2020-02-02T17:16:19Z",
"provider_id": "1234",
"provider_code": "moldindconbank_wb_md",
"provider_name": "Moldindconbank Web Banking",
"status": "active",
"updated_at": "2020-02-04T09:41:23Z"
}
}
Consents
A consent represents the access to data and the limits of this access agreed on by a customer. It is required to access the accounts, transactions and holder information through a specific provider.
The limits of a consent are represented by:
- data that is allowed to be accessed;
- period of time the data can be accessed for;
- interval of time to which the accessed data belongs to.
Attributes
id
string
The id
of the consent
scopes
array of strings, required
Data that is allowed to be fetched. Possible values: ['account_details']
, ['holder_information']
, ['account_details', 'holder_information']
, ['account_details', 'transactions_details']
, ['account_details', 'holder_information', 'transactions_details']
period_days
integer
The period the consent will be valid for
expires_at
date
The date when the consent will expire
from_date
date
The date from which the data has been allowed to be fetched
to_date
date
The date until which the data has been allowed to be fetched
status
string, required
Consent status. Possible values: active
, expired
, revoked
revoked_at
date
The date when consent was revoked
created_at
date
When the consent was created
updated_at
date
When the consent was updated
id
string
The id
of the consent
scopes
array of strings, required
Data that is allowed to be fetched. Possible values: ['account_details']
, ['holder_information']
, ['account_details', 'holder_information']
, ['account_details', 'transactions_details']
, ['account_details', 'holder_information', 'transactions_details']
period_days
integer
The period the consent will be valid for
expires_at
date
The date when the consent will expire
from_date
date
The date from which the data has been allowed to be fetched
to_date
date
The date until which the data has been allowed to be fetched
status
string, required
Consent status. Possible values: active
, expired
, revoked
revoked_at
date
The date when consent was revoked
created_at
date
When the consent was created
updated_at
date
When the consent was updated
List
Returns all the consents accessible to your application for a certain customer or connection.
The consents are sorted in ascending order of their id
, so the latest consents will come last.
You can read more about next_id
field, in the pagination section of the reference.
Parameters
connection_id
string, optional
The id
of the connection containing the consents
customer_id
string, optional
The id
of the customer containing the consents.
Note: Will be ignored if connection_id
is present.
from_id
string, optional
The id
from which the next page of consents starts
from_id
string, optional
The id
from which the next page of consents starts
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/consents?connection_id={connection.id}
https://www.saltedge.com/api/partners/v1/consents
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/consents?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/consents
Sample Response
{
"data": [
{
"id": "555555555555555555",
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"scopes": [
"account_details",
"transactions_details"
],
"period_days": 60,
"expires_at": "2024-12-07T11:41:01Z",
"from_date": "2024-09-08",
"to_date": null,
"status": "active",
"collected_by": "client",
"revoked_at": null,
"revoke_reason": null,
"created_at": "2024-10-08T11:41:01Z",
"updated_at": "2024-10-08T11:41:01Z"
}
],
"meta" : {
"next_id": "555555555555555556",
"next_page": "/api/partners/v1/consents?connection_id=111111111111111111&from_id=555555555555555556"
}
}
{
"data": [
{
"id": "555555555555555555",
"scopes": [
"account_details",
"transactions_details"
],
"period_days": 60,
"expires_at": "2024-12-07T11:41:01Z",
"from_date": "2024-09-08",
"to_date": null,
"status": "active",
"collected_by": "client",
"revoked_at": null,
"revoke_reason": null,
"created_at": "2024-10-08T11:41:01Z",
"updated_at": "2024-10-08T11:41:01Z"
}
],
"meta" : {
"next_id": "555555555555555556",
"next_page": "/api/partners/v1/consents?from_id=555555555555555556"
}
}
Show
Returns the consent object.
Parameters
connection_id
string, optional
The id
of the connection containing the consent, required unless customer_id
parameter is sent
customer_id
string, optional
The id
of the customer containing the consent, required unless connection_id
parameter is sent.
id
string, required
The id
of the consent
id
string, required
The id
of the consent
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/consents/{consent.id}?connection_id={connection.id}
https://www.saltedge.com/api/partners/v1/consents/{consent.id}
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/consents/555555555555555555?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/consents/555555555555555555
Sample Response
{
"data": {
"id": "555555555555555555",
"connection_id": "111111111111111111",
"customer_id": "222222222222222222",
"scopes": [
"account_details",
"transactions_details"
],
"period_days": 60,
"expires_at": "2024-12-07T11:41:01Z",
"from_date": "2024-09-08",
"to_date": null,
"status": "active",
"collected_by": "client",
"revoked_at": null,
"revoke_reason": null,
"created_at": "2024-10-08T11:41:01Z",
"updated_at": "2024-10-08T11:41:01Z"
}
}
{
"data": {
"id": "555555555555555555",
"scopes": [
"account_details",
"transactions_details"
],
"period_days": 60,
"expires_at": "2024-12-07T11:41:01Z",
"from_date": "2024-09-08",
"to_date": null,
"status": "active",
"collected_by": "client",
"revoked_at": null,
"revoke_reason": null,
"created_at": "2024-10-08T11:41:01Z",
"updated_at": "2024-10-08T11:41:01Z"
}
}
Parameters object
The following represents the consent parameters object that is passed in requests.
scopes
array of strings, required
Data to be allowed for fetching. Possible values: ['account_details']
, ['holder_information']
, ['account_details', 'holder_information']
, ['account_details', 'transactions_details']
, ['account_details', 'holder_information', 'transactions_details']
Note: The allowed values for this parameter must fall within the client’s allowed_fetch_scopes
and/or provider’s supported_fetch_scopes
restrictions. To change the client’s allowed scopes, please contact our sales team.
account_details
scope covers both accounts
and accounts_without_balance
attempt’s fetch_scopes.
from_date
date, optional
Date to be allowed for fetching the data from.
Note: This parameter is used when scopes
parameter contains transactions_details
. The allowed values for this parameter must be within exactly 365 days ago.
to_date
date, optional
Date to be allowed for fetching the data untill. Default: null
(limitless).
Note: The allowed values for this parameter must be equal or more than from_date
.
period_days
integer, optional
Determines the period the consent will be valid for. Default: null
(limitless) or provider’s max_consent_days
.
Note: The allowed value for this parameter must not be higher than the provider’s max_consent_days
.
scopes
array of strings, required
Data to be allowed for fetching. Possible values: ['account_details']
, ['holder_information']
, ['account_details', 'holder_information']
, ['account_details', 'transactions_details']
, ['account_details', 'holder_information', 'transactions_details']
Note: The allowed values for this parameter must fall within the client’s allowed_fetch_scopes
and/or provider’s supported_fetch_scopes
restrictions. To change the client’s allowed scopes, please contact our sales team.
account_details
scope covers both accounts
and accounts_without_balance
attempt’s fetch_scopes.
from_date
date, optional
Date to be allowed for fetching the data from.
Note: This parameter is used when scopes
parameter contains transactions_details
. The allowed values for this parameter must be within exactly 365 days ago.
to_date
date, optional
Date to be allowed for fetching the data untill. Default: null
(limitless).
Note: The allowed values for this parameter must be equal or more than from_date
.
period_days
integer, optional
Determines the period the consent will be valid for. Default: null
(limitless) or provider’s max_consent_days
.
Note: The allowed value for this parameter must not be higher than the provider’s max_consent_days
.
Attempts
The attempt resource represents a detailed description of a particular connection attempt. They are meant to provide you with more information about the established connections for further usage in technical and statistical purposes.
Attributes
api_mode
string
The API mode of the customer that queried the API. Possible values: app
, service
api_version
string
The API version in which the attempt was created
automatic_fetch
boolean
Whether the connection related to the attempt can be automatically fetched
daily_refresh
boolean
Latest assigned value for daily_refresh
in connection. If the connection has no active partner consent, then daily_refresh
is false
. During reconnect of such a connection, the desired value of the daily_refresh
attribute should be sent.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Default: personal
created_at
datetime
When the attempt was created
custom_fields
object
The custom fields that had been sent when creating connection/connect_session/oauth_provider
device_type
string
The type of the device that created the attempt. Possible values: desktop
, tablet
, mobile
remote_ip
string
The IP of the device that created the attempt
customer_last_logged_at
datetime
The datetime when user was last active in your application
fail_at
datetime
When the attempt failed to finish
fail_error_class
string
Class of error that triggered the fail for the 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']
, ['accounts_without_balance']
, ['accounts_without_balance', 'holder_info']
finished
boolean
Whether the connection has finished fetching
finished_recent
boolean
Whether the connection has finished data for recent range (2 months)
from_date
date
Date from which the data has been fetched
id
string
The id
of the attempt
interactive
boolean
Whether the connection related to the attempt is interactive
locale
string
The language of the Connect widget and of the returned error message(s) 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
, sv
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). Defaults to en
.
partial
boolean
Whether the connection was partially fetched
success_at
datetime
When the attempt succeeded and finished
to_date
date
Date until which the data has been fetched
updated_at
datetime
When last attempt update occurred
show_consent_confirmation
boolean
Whether any consent was given for this connection
include_natures
array of strings
The natures of the accounts that need to be fetched
unduplication_strategy
This parameter mandates how duplicated transactions are managed.
Possible values include: mark_as_pending
, mark_as_duplicate
, delete_transactions
.
The default is set to mark_as_pending
.
The provided value remains unchanged until another value is sent during lead_session/reconnect or lead_session/refresh.
mark_as_pending
- leaves identified duplicated transactions inPending
status for Clients that establish connections with providers having a non-nullcustom_pendings_period
;mark_as_duplicate
- marks identified transactions as duplicated and changes theduplicated
flag totrue
.delete_transactions
- deletes identified duplicated transactions.
api_mode
string
The API mode of the customer that queried the API. Possible values: app
, service
api_version
string
The API version in which the attempt was created
automatic_fetch
boolean
Whether the connection related to the attempt can be automatically fetched
daily_refresh
boolean
Latest assigned value for daily_refresh
in connection. If the connection has no active partner consent, then daily_refresh
is false
. During reconnect of such a connection, the desired value of the daily_refresh
attribute should be sent.
categorization
string, optional
The type of categorization applied. Possible values: none
, personal
, business
. Default: personal
created_at
datetime
When the attempt was created
custom_fields
object
The custom fields that had been sent when creating connection/connect_session/oauth_provider
device_type
string
The type of the device that created the attempt. Possible values: desktop
, tablet
, mobile
remote_ip
string
The IP of the device that created the attempt
customer_last_logged_at
datetime
The datetime when user was last active in your application
fail_at
datetime
When the attempt failed to finish
fail_error_class
string
Class of error that triggered the fail for the 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']
, ['accounts_without_balance']
, ['accounts_without_balance', 'holder_info']
finished
boolean
Whether the connection has finished fetching
finished_recent
boolean
Whether the connection has finished data for recent range (2 months)
from_date
date
Date from which the data has been fetched
id
string
The id
of the attempt
interactive
boolean
Whether the connection related to the attempt is interactive
locale
string
The language of the Connect widget and of the returned error message(s) 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
, sv
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). Defaults to en
.
partial
boolean
Whether the connection was partially fetched
success_at
datetime
When the attempt succeeded and finished
to_date
date
Date until which the data has been fetched
updated_at
datetime
When last attempt update occurred
show_consent_confirmation
boolean
Whether any consent was given for this connection
include_natures
array of strings
The natures of the accounts that need to be fetched
unduplication_strategy
This parameter mandates how duplicated transactions are managed.
Possible values include: mark_as_pending
, mark_as_duplicate
, delete_transactions
.
The default is set to mark_as_pending
.
The provided value remains unchanged until another value is sent during lead_session/reconnect or lead_session/refresh.
mark_as_pending
- leaves identified duplicated transactions inPending
status for Clients that establish connections with providers having a non-nullcustom_pendings_period
;mark_as_duplicate
- marks identified transactions as duplicated and changes theduplicated
flag totrue
.delete_transactions
- deletes identified duplicated transactions.
Note: The values of the interactive
and automatic_fetch
are subject to change, since the customers can activate or deactivate the interactive requirements separately with their banks.
Sample object
{
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"categorization": "personal",
"created_at": "2024-10-08T12:41:01Z",
"customer_last_logged_at": "2024-10-08T11:41:01Z",
"custom_fields": {},
"daily_refresh": false,
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": ["accounts", "transactions"],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"partial": false,
"success_at": "2024-10-08T13:41:01Z",
"to_date": null,
"updated_at": "2024-10-08T13:41:01Z",
"show_consent_confirmation": true,
"include_natures": ["account", "card", "bonus"],
"unduplication_strategy": "delete_transactions",
"last_stage": {
"created_at": "2024-10-08T13:41:01Z",
"id": "888888888888888888",
"name": "finish",
"updated_at": "2024-10-08T13:41:01Z"
}
}
Stages
The following represents the objects you get in the stages
field of the attempt object.
created_at
datetime
When the stage was created
id
string
The id
of the stage
name
string
The name of the stage. Possible values: start
, connect
, interactive
, fetch_holder_info
, fetch_accounts
, fetch_recent
, fetch_full
, disconnect
, finish
updated_at
datetime
When the stage was last updated
created_at
datetime
When the stage was created
id
string
The id
of the stage
name
string
The name of the stage. Possible values: start
, connect
, interactive
, fetch_holder_info
, fetch_accounts
, fetch_recent
, fetch_full
, disconnect
, finish
updated_at
datetime
When the stage was last updated
List
Returns a paginated list of all attempts for a specific connection.
Parameters
connection_id
string
The id
of the connection whose attempts are to be fetched
URL
https://www.saltedge.com/api/partners/v1/attempts?connection_id={connection.id}
https://www.saltedge.com/api/partners/v1/attempts
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/attempts?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/attempts
Sample response
{
"data": {
[
{
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"categorization": "personal",
"created_at": "2024-10-08T12:41:01Z",
"customer_last_logged_at": "2024-10-08T11:41:01Z",
"custom_fields": {},
"device_type": "desktop",
"daily_refresh": false,
"remote_ip": "93.184.216.34",
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": ["accounts", "transactions"],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"success_at": "2024-10-08T13:41:01Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T13:41:01Z",
"show_consent_confirmation": true,
"include_natures": ["account", "card", "bonus"],
"last_stage": {
"created_at": "2024-10-08T13:41:01Z",
"id": "888888888888888888",
"name": "finish",
"updated_at": "2024-10-08T13:41:01Z"
}
}
]
},
"meta": {
"next_id": "777777777777777778",
"next_page": "/api/partners/v1/attempts?connection_id=111111111111111111&from_id=777777777777777778"
}
}
{
"data": {
[
{
"api_mode": "app",
"api_version": "5",
"automatic_fetch": true,
"categorization": "personal",
"created_at": "2024-10-08T12:41:01Z",
"customer_last_logged_at": "2024-10-08T11:41:01Z",
"custom_fields": {},
"device_type": "desktop",
"daily_refresh": false,
"remote_ip": "93.184.216.34",
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": ["accounts", "transactions"],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"success_at": "2024-10-08T13:41:01Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T13:41:01Z",
"show_consent_confirmation": true,
"include_natures": ["account", "card", "bonus"],
"last_stage": {
"created_at": "2024-10-08T13:41:01Z",
"id": "888888888888888888",
"name": "finish",
"updated_at": "2024-10-08T13:41:01Z"
}
}
]
},
"meta": {
"next_id": "777777777777777778",
"next_page": "/api/partners/v1/attempts?from_id=777777777777777778"
}
}
Show
Returns a single attempt object.
Parameters
connection_id
string
The id
of the connection whose attempts are to be fetched
URL
https://www.saltedge.com/api/partners/v1/attempts/{attempt.id}?connection_id={connection.id}
https://www.saltedge.com/api/partners/v1/attempts/{attempt.id}
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/attempts/777777777777777777?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/attempts/777777777777777777
Sample response
{
"data": {
"api_mode": "service",
"api_version": "5",
"automatic_fetch": true,
"daily_refresh": false,
"categorization": "personal",
"created_at": "2024-10-08T12:41:01Z",
"customer_last_logged_at": "2024-10-08T11:41:01Z",
"custom_fields": {},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": ["accounts", "transactions"],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"success_at": "2024-10-08T13:41:01Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T13:41:01Z",
"show_consent_confirmation": true,
"include_natures": ["account", "card", "bonus"],
"stages": [
{
"created_at": "2024-10-08T12:41:01Z",
"id": "888888888888888881",
"name": "start",
"updated_at": "2024-10-08T12:41:01Z"
},
{
"created_at": "2024-10-08T12:51:01Z",
"id": "888888888888888882",
"name": "connect",
"updated_at": "2024-10-08T12:51:01Z"
},
{
"created_at": "2024-10-08T13:41:01Z",
"id": "888888888888888883",
"name": "finish",
"updated_at": "2024-10-08T13:41:01Z"
}
]
}
}
{
"data": {
"api_mode": "app",
"api_version": "5",
"automatic_fetch": true,
"daily_refresh": false,
"categorization": "personal",
"created_at": "2024-10-08T12:41:01Z",
"customer_last_logged_at": "2024-10-08T11:41:01Z",
"custom_fields": {},
"device_type": "desktop",
"remote_ip": "93.184.216.34",
"fail_at": null,
"fail_error_class": null,
"fail_message": null,
"fetch_scopes": ["accounts", "transactions"],
"finished": true,
"finished_recent": true,
"from_date": null,
"id": "777777777777777777",
"interactive": false,
"locale": "en",
"partial": false,
"success_at": "2024-10-08T13:41:01Z",
"to_date": null,
"unduplication_strategy": "mark_as_duplicate",
"updated_at": "2024-10-08T13:41:01Z",
"show_consent_confirmation": true,
"include_natures": ["account", "card", "bonus"],
"stages": [
{
"created_at": "2024-10-08T12:41:01Z",
"id": "888888888888888881",
"name": "start",
"updated_at": "2024-10-08T12:41:01Z"
},
{
"created_at": "2024-10-08T12:51:01Z",
"id": "888888888888888882",
"name": "connect",
"updated_at": "2024-10-08T12:51:01Z"
},
{
"created_at": "2024-10-08T13:41:01Z",
"id": "888888888888888883",
"name": "finish",
"updated_at": "2024-10-08T13:41:01Z"
}
]
}
}
Parameters object
The following represents the attempt parameters object that is passed in requests.
fetch_scopes
array of strings, optional
Fetching mode. Possible values: ['accounts']
, ['holder_info']
, ['accounts', 'holder_info']
, ['accounts', 'transactions']
, ['accounts', 'holder_info', 'transactions']
, ['accounts_without_balance']
, ['accounts_without_balance', 'holder_info']
. Default: consent scopes.
Note: The allowed values for this parameter must comply to the consent scopes
restriction.
from_date
date, optional
to_date
date, optional
Date until which you want to fetch data for your connection. Default: null
(today).
Note: The allowed values for this parameter must be equal or more than from_date
and less or equal than tomorrow. Also it should comply to the fetching period restrictions in the consent.
fetched_accounts_notify
boolean, optional
Whether Salt Edge should send a success callback after fetching accounts. Defaults to false
custom_fields
object, optional
A JSON object, which will be sent back on any of your callbacks, defaults to empty object
locale
string, optional
The language of the Connect widget and of the returned error message(s) 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
, sv
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). Defaults to en
.
include_natures
array of strings, optional
The natures of the accounts that need to be fetched. Check accounts attributes for possible values. Default value: null
(all accounts will be fetched)
customer_last_logged_at
datetime, optional
The datetime when the user was last active in your application
unduplication_strategy
string, optional
This parameter mandates how duplicated transactions are managed.
Possible values include: mark_as_pending
, mark_as_duplicate
, delete_transactions
. The default is set to mark_as_pending
.
The provided value remains unchanged until another value is sent during leed_session/reconnect or leed_session/refresh.
- mark_as_pending
: leaves identified duplicated transactions in Pending
status for clients that establish connections with providers having a non-null custom_pendings_period
.
- mark_as_duplicate
: identifies transactions as duplicated and sets the duplicated
flag to true
.
- delete_transactions
: removes identified duplicated transactions.
return_to
string, optional
The URL the user will be redirected to. Defaults to client’s home URL (if set and valid) or Lead’s Dashboard
fetch_scopes
array of strings, optional
Fetching mode. Possible values: ['accounts']
, ['holder_info']
, ['accounts', 'holder_info']
, ['accounts', 'transactions']
, ['accounts', 'holder_info', 'transactions']
, ['accounts_without_balance']
, ['accounts_without_balance', 'holder_info']
. Default: consent scopes.
Note: The allowed values for this parameter must comply to the consent scopes
restriction.
from_date
date, optional
to_date
date, optional
Date until which you want to fetch data for your connection. Default: null
(today).
Note: The allowed values for this parameter must be equal or more than from_date
and less or equal than tomorrow. Also it should comply to the fetching period restrictions in the consent.
fetched_accounts_notify
boolean, optional
Whether Salt Edge should send a success callback after fetching accounts. Defaults to false
custom_fields
object, optional
A JSON object, which will be sent back on any of your callbacks, defaults to empty object
locale
string, optional
The language of the Connect widget and of the returned error message(s) 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
, sv
, tr
, uk
, zh-HK
(Traditional), zh
(Simplified). Defaults to en
.
include_natures
array of strings, optional
The natures of the accounts that need to be fetched. Check accounts attributes for possible values. Default value: null
(all accounts will be fetched)
customer_last_logged_at
datetime, optional
The datetime when the user was last active in your application
unduplication_strategy
string, optional
This parameter mandates how duplicated transactions are managed.
Possible values include: mark_as_pending
, mark_as_duplicate
, delete_transactions
. The default is set to mark_as_pending
.
The provided value remains unchanged until another value is sent during leed_session/reconnect or leed_session/refresh.
- mark_as_pending
: leaves identified duplicated transactions in Pending
status for clients that establish connections with providers having a non-null custom_pendings_period
.
- mark_as_duplicate
: identifies transactions as duplicated and sets the duplicated
flag to true
.
- delete_transactions
: removes identified duplicated transactions.
return_to
string, optional
The URL the user will be redirected to. Defaults to client’s home URL (if set and valid) or Lead’s Dashboard
Accounts
Any connection can have one or more accounts. The accounts are bound to a currency such that all the transactions within a single account have the same currency.
Sometimes, the provider allows the user to have several currencies grouped under the same account. For example, if a user holds a debit card that supports 3 currencies, the corresponding connection will have 3 accounts, each with one of the debit card’s currencies.
Attributes
id
string
The id
of the account
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: 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.
connection_id
string
The id
of the connection the account belongs to
created_at
datetime
Time and date when the account was imported
updated_at
datetime
The last time when the account’s balance was changed or new transactions were imported
id
string
The id
of the account
name
string
The unique name of the account.
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: 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.
connection_id
string
The id
of the connection the account belongs to
created_at
datetime
Time and date when the account was imported
updated_at
datetime
The last time when the account’s balance was changed or new transactions were imported
Sample Object
{
"id": "333333333333333333",
"name": "Fake account 2",
"nature": "account",
"balance": 2012.7,
"currency_code": "USD",
"extra": {
"cards": [
"1234....5678",
"*8765"
],
"transactions_count": {
"posted": 22,
"pending": 1
}
},
"connection_id": "111111111111111111",
"created_at": "2024-10-08T12:41:01Z",
"updated_at": "2024-10-08T12:41:01Z"
}
List
You can see the list of accounts of a connection.
The accounts are sorted in ascending order of their id
, so the newest accounts will come last.
You can read more about next_id
field, in the pagination section of the reference.
Parameters
connection_id
string
The id
of the connection whose attempts are to be fetched
from_id
string, optional
The id
from which the next page of accounts starts
customer_id
string, optional
The id
of the customer containing the accounts. It is required unless connection_id
parameter is sent.
Note: Will be ignored if connection_id
is present.
from_id
string, optional
The id
from which the next page of accounts starts
customer_id
string, optional
The id
of the customer containing the accounts. It is required unless connection_id
parameter is sent.
Note: Will be ignored if connection_id
is present.
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/accounts?connection_id={connection.id}
https://www.saltedge.com/api/partners/v1//accounts
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/accounts?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/accounts
Sample Response
{
"data": [
{
"id": "333333333333333333",
"name": "Fake account 1",
"nature": "card",
"balance": 2007.2,
"currency_code": "EUR",
"extra": {
"client_name": "Fake name"
},
"connection_id": "111111111111111111",
"created_at": "2024-10-08T11:41:01Z",
"updated_at": "2024-10-08T11:41:01Z"
},
{
"id": "333333333333333334",
"name": "Fake account 2",
"nature": "account",
"balance": 2012.7,
"currency_code": "USD",
"extra": {
"cards": [
"1234....5678",
"*8765"
],
"transactions_count": {
"posted": 22,
"pending": 1
}
},
"connection_id": "111111111111111111",
"created_at": "2024-10-08T12:41:01Z",
"updated_at": "2024-10-08T12:41:01Z"
}
],
"meta" : {
"next_id": "333333333333333335",
"next_page": "/api/partners/v1/accounts?connection_id=111111111111111111&from_id=333333333333333335"
}
}
{
"data": [
{
"id": "333333333333333333",
"name": "Fake account 1",
"nature": "card",
"balance": 2007.2,
"currency_code": "EUR",
"extra": {
"client_name": "Fake name"
},
"created_at": "2024-10-08T11:41:01Z",
"updated_at": "2024-10-08T11:41:01Z"
},
{
"id": "333333333333333334",
"name": "Fake account 2",
"nature": "account",
"balance": 2012.7,
"currency_code": "USD",
"extra": {
"cards": [
"1234....5678",
"*8765"
],
"transactions_count": {
"posted": 22,
"pending": 1
}
},
"connection_id": "111111111111111111",
"created_at": "2024-10-08T12:41:01Z",
"updated_at": "2024-10-08T12:41:01Z"
}
],
"meta" : {
"next_id": "333333333333333335",
"next_page": "/api/partners/v1/accounts?from_id=333333333333333335"
}
}
Nature
An account can be of one of the several types, as described by the nature
field:
Payment account natures:
- account (nature assigned to current account or when the account type could not be identified)
- card (the type of card could not be identified)
- checking
- credit_card
- debit_card
- ewallet
- loan*
- mortgage*
- savings*
* Depending on the bank, it can be handled as payment
or non-payment
account
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.
General accounts extra fields:
account_name
string
Changeable name of the account
account_number
string
Internal bank account number
assets
array of objects
Array of crypto codes and their amounts assigned to investment account
available_amount
decimal
Available amount in the account’s currency
balance_type
string
Examples: interimAvailable
, closingBooked
, interimBooked
, authorised
, expected
, BOOKED
, CLAV
, CLBD
, XPCD
, OTHR
, etc.
Note: The value is specific to the financial institution and can vary depending on the API standard, the bank’s implementation, the account’s type, country/region peculiarities, etc. This field holds an informative meaning. Usually, it is used to verify the balance consistency between customers of the same bank or between banks within the same country.
blocked_amount
decimal
The amount currently blocked in the 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 the accounting period
credit_limit
decimal
Credit limit in the 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 the bank’s side
provider_account_id
string
A unique ID assigned by the Provider to identify an account within its system
raw_balance
string
The original account balance response returned by the bank. It is added only for regulated: true
providers. It is returned only if the separate balances
parameter is present in the bank’s original response.
sort_code
string
Routing number(US)/BSB code(Australia)/sort code(UK)
statement_cut_date
date
Date when the current statement becomes previous one
status
string
Shows whether the account is active
, inactive
or unauthorized
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
account_name
string
Changeable name of the account
account_number
string
Internal bank account number
assets
array of objects
Array of crypto codes and their amounts assigned to investment account
available_amount
decimal
Available amount in the account’s currency
balance_type
string
Examples: interimAvailable
, closingBooked
, interimBooked
, authorised
, expected
, BOOKED
, CLAV
, CLBD
, XPCD
, OTHR
, etc.
Note: The value is specific to the financial institution and can vary depending on the API standard, the bank’s implementation, the account’s type, country/region peculiarities, etc. This field holds an informative meaning. Usually, it is used to verify the balance consistency between customers of the same bank or between banks within the same country.
blocked_amount
decimal
The amount currently blocked in the 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 the accounting period
credit_limit
decimal
Credit limit in the 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 the bank’s side
provider_account_id
string
A unique ID assigned by the Provider to identify an account within its system
raw_balance
string
The original account balance response returned by the bank. It is added only for regulated: true
providers. It is returned only if the separate balances
parameter is present in the bank’s original response.
sort_code
string
Routing number(US)/BSB code(Australia)/sort code(UK)
statement_cut_date
date
Date when the current statement becomes previous one
status
string
Shows whether the account is active
, inactive
or unauthorized
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
Investment accounts extra fields:
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
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
)
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
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
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
financial_consultant
string
Financial consultant name
total_reversionary_bonus
decimal
Reversionary bonus accumulated amount
gross_surrender
decimal
Current Gross Surrender value
guaranteed_gross_surrender
decimal
Guaranteed Gross Surrender value
reversionary_bonus_cash_value
decimal
Cash value of reversionary bonus
owned_policy_amount
decimal
Amount currently own on policy
policy_loan_limit
decimal
Maximum amount of additional Policy Loan
policy_converted_to_paid_up
decimal
New assured sum if Policy is converted to paid up
paid_up_conversion_reversionary_bonus
decimal
Reversionary bonus amount after ‘Policy to paid up’ conversion
policy_components
object
Policy components with own values such as (status
, amount_assured
, amount_premium
, start_date
, expiry_date
, premium_expiry_date
, assured_name
)
Transactions
A transaction represents a movement of funds. Any transaction can represent a monetary transfer, withdrawal, income or expense interchange. Transactions are retained in a connection’s accounts, and are imported from one of the providers.
Category
Salt Edge Partners API uses an algorithm for automatic categorization of transactions. Thus, when importing a connection, all the transactions corresponding to the connection will be assigned to one of the categories.
Attributes
id
string
The id
of the transaction
mode
string
Possible values are: normal
, fee
, transfer
status
string
Possible values are: posted
, pending
made_on
date
The date when the transaction was made
amount
decimal
Transaction’s amount
currency_code
string
Transaction’s currency code
description
string
Transaction’s description
category
string
Transaction’s category
duplicated
boolean
Whether the transaction is duplicated or not
account_id
string
The id
of the account the transaction belongs to
created_at
datetime
Time and date when the transaction was imported
updated_at
datetime
The last time when the transaction’s attributes (duplicated flag set, category learned applied) were changed by the client
id
string
The id
of the transaction
mode
string
Possible values are: normal
, fee
, transfer
status
string
Possible values are: posted
, pending
made_on
date
The date when the transaction was made
amount
decimal
Transaction’s amount
currency_code
string
Transaction’s currency code
description
string
Transaction’s description
category
string
Transaction’s category
duplicated
boolean
Whether the transaction is duplicated or not
account_id
string
The id
of the account the transaction belongs to
created_at
datetime
Time and date when the transaction was imported
updated_at
datetime
The last time when the transaction’s attributes (duplicated flag set, category learned applied) were changed by the client
Sample object
{
"id": "444444444444444444",
"duplicated": false,
"mode": "normal",
"status": "posted",
"made_on": "2020-05-03",
"amount": -200.0,
"currency_code": "USD",
"description": "Money spent on company advertising",
"category": "advertising",
"extra": {
"merchant_id": "b3e8ec2349df872072c051e0c...",
"original_amount": -3974.60,
"original_currency_code": "CZK",
"posting_date": "2020-05-07",
"time": "23:56:12"
},
"account_id": "333333333333333333",
"created_at": "2024-10-06T14:41:01Z",
"updated_at": "2024-10-07T14:41:01Z"
}
List
It imports the non-duplicated posted
transactions of an account.
In order to get all the data, please read more about the next_id
field in the pagination section of the reference.
Note: This endpoint imports only posted
transactions. For obtaining pending
transactions, please call transactions-pending route.
Parameters
connection_id
string, required
The id
of the connection
account_id
string, optional
The id
of the account
from_id
string, optional
The id
from which the next page of transactions starts
account_id
string, optional
The id
of the account
from_id
string, optional
The id
from which the next page of transactions starts
All of the optional parameters for transactions list can be combined in any possible manner.
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/transactions?connection_id={connection.id}&account_id={account.id}
https://www.saltedge.com/api/partners/v1/transactions?account_id={account.id}
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/transactions?connection_id=111111111111111111&account_id=333333333333333333
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/transactions?account_id=333333333333333333
Sample response
{
"data": [
{
"id": "444444444444444444",
"duplicated": false,
"mode": "normal",
"status": "posted",
"made_on": "2020-05-03",
"amount": -200.0,
"currency_code": "USD",
"description": "test transaction",
"category": "advertising",
"extra": {
"original_amount": -3974.60,
"original_currency_code": "CZK",
"posting_date": "2020-05-07",
"time": "23:56:12"
},
"account_id": "333333333333333333",
"created_at": "2024-10-06T14:41:01Z",
"updated_at": "2024-10-07T14:41:01Z"
},
{
"id": "444444444444444445",
"duplicated": false,
"mode": "normal",
"status": "posted",
"made_on": "2020-05-03",
"amount": 50.0,
"currency_code": "USD",
"description": "business expense",
"category": "business_services",
"extra": {
"original_amount": 993.90,
"original_currency_code": "CZK",
"posting_date": "2020-05-06",
"time": "12:16:25"
},
"account_id": "333333333333333333",
"created_at": "2024-10-06T14:41:01Z",
"updated_at": "2024-10-07T14:41:01Z"
}
],
"meta" : {
"next_id": "444444444444444446",
"next_page": "/api/partners/v1/transactions/?connection_id=111111111111111111&account_id=333333333333333333&from_id=444444444444444446"
}
}
"data": [
{
"id": "444444444444444444",
"duplicated": false,
"mode": "normal",
"status": "posted",
"made_on": "2020-05-03",
"amount": -200.0,
"currency_code": "USD",
"description": "test transaction",
"category": "advertising",
"extra": {
"original_amount": -3974.60,
"original_currency_code": "CZK",
"posting_date": "2020-05-07",
"time": "23:56:12"
},
"account_id": "333333333333333333",
"created_at": "2024-10-06T14:41:01Z",
"updated_at": "2024-10-07T14:41:01Z"
},
{
"id": "444444444444444445",
"duplicated": false,
"mode": "normal",
"status": "posted",
"made_on": "2020-05-03",
"amount": 50.0,
"currency_code": "USD",
"description": "business expense",
"category": "business_services",
"extra": {
"original_amount": 993.90,
"original_currency_code": "CZK",
"posting_date": "2020-05-06",
"time": "12:16:25"
},
"account_id": "333333333333333333",
"created_at": "2024-10-06T14:41:01Z",
"updated_at": "2024-10-07T14:41:01Z"
}
],
"meta" : {
"next_id": "444444444444444445",
"next_page": "/api/partners/v1/transactions/?account_id=333333333333333333&from_id=444444444444444445"
}
}
Pending
You can use this route to obtain the currently pending transactions for an account. Note that although pending transactions have the same structure as the regular transactions, they behave differently.
The provider may delete the pending transactions and modify some of its attributes. Thus, every time a connection is refreshed, the existing pending transactions will be replaced by the currently pending transactions.
This means that your app should not rely on the pending transactions having an id
, since they might be replaced with similar transactions having a different id
.
We also recommend to remove the account’s pending transactions from your app every time you fetch the transactions.
Parameters
connection_id
string, required
The id
of the connection
account_id
string, optional
The id
of the account
from_id
string, optional
The id
from which the next page of transactions starts
account_id
string, optional
The id
of the account
from_id
string, optional
The id
from which the next page of transactions starts
As with the list route, you can combine the parameters.
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/transactions/pending?connection_id={connection.id}&account_id={account.id}
https://www.saltedge.com/api/partners/v1/transactions/pending?account_id={account.id}
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/transactions/pending?connection_id=111111111111111111&account_id=333333333333333333
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/transactions/pending?account_id=333333333333333333
Sample response
{
"data": [
{
"id": "444444444444444444",
"duplicated": false,
"mode": "normal",
"status": "pending",
"made_on": "2020-05-03",
"amount": -200.0,
"currency_code": "USD",
"description": "ads expense",
"category": "advertising",
"extra": {
"original_amount": -3974.60,
"original_currency_code": "CZK",
"posting_date": "2020-05-07",
"time": "23:56:12"
},
"account_id": "333333333333333333",
"created_at": "2024-10-06T14:41:01Z",
"updated_at": "2024-10-07T14:41:01Z"
}
],
"meta" : {
"next_id": "444444444444444445",
"next_page": "/api/v1/transactions/pending?connection_id=111111111111111111&account_id=333333333333333333&from_id=444444444444444445"
}
}
{
"data": [
{
"id": "444444444444444444",
"duplicated": false,
"mode": "normal",
"status": "pending",
"made_on": "2020-05-03",
"amount": -200.0,
"currency_code": "USD",
"description": "ads expense",
"category": "advertising",
"extra": {
"original_amount": -3974.60,
"original_currency_code": "CZK",
"posting_date": "2020-05-07",
"time": "23:56:12"
},
"account_id": "333333333333333333",
"created_at": "2024-10-06T14:41:01Z",
"updated_at": "2024-10-07T14:41:01Z"
}
],
"meta" : {
"next_id": "444444444444444445",
"next_page": "/api/v1/transactions/pending?account_id=333333333333333333&from_id=444444444444444445"
}
}
List Duplicates
You can see the list of duplicated transactions of an account.
Parameters
connection_id
string, required
The id
of the connection
account_id
string, optional
The id
of the account
from_id
string, optional
The id
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/partners/v1/transactions/duplicates?connection_id={connection.id}&account_id={account.id}
https://www.saltedge.com/api/partners/v1/transactions/duplicates&account_id=333333333333333333
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/transactions/duplicates?connection_id=111111111111111111&account_id=333333333333333333
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/transactions/duplicates?account_id=333333333333333333
Sample response
{
"data": [
{
"id": "444444444444444444",
"duplicated": true,
"mode": "normal",
"status": "posted",
"made_on": "2020-05-03",
"amount": -200.0,
"currency_code": "USD",
"description": "test transaction",
"category": "advertising",
"extra": {
"original_amount": -3974.60,
"original_currency_code": "CZK",
"posting_date": "2020-05-07",
"time": "23:56:12"
},
"account_id": "333333333333333333",
"created_at": "2024-10-06T14:41:01Z",
"updated_at": "2024-10-07T14:41:01Z"
},
{
"id": "444444444444444445",
"duplicated": true,
"mode": "normal",
"status": "posted",
"made_on": "2020-05-03",
"amount": 50.0,
"currency_code": "USD",
"description": "business expense",
"category": "business_services",
"extra": {
"original_amount": 993.90,
"original_currency_code": "CZK",
"posting_date": "2020-05-06",
"time": "12:16:25"
},
"account_id": "333333333333333333",
"created_at": "2024-10-06T14:41:01Z",
"updated_at": "2024-10-07T14:41:01Z"
}
],
"meta" : {
"next_id": "444444444444444445",
"next_page": "/api/v1/transactions/?connection_id=111111111111111111&account_id=333333333333333333&from_id=444444444444444445"
}
}
{
"data": [
{
"id": "444444444444444447",
"duplicated": true,
"mode": "normal",
"status": "posted",
"made_on": "2020-05-03",
"amount": -200.0,
"currency_code": "USD",
"description": "test transaction",
"category": "advertising",
"extra": {
"original_amount": -3974.60,
"original_currency_code": "CZK",
"posting_date": "2020-05-07",
"time": "23:56:12"
},
"account_id": "333333333333333333",
"created_at": "2024-10-06T14:41:01Z",
"updated_at": "2024-10-07T14:41:01Z"
},
{
"id": "444444444444444448",
"duplicated": true,
"mode": "normal",
"status": "posted",
"made_on": "2020-05-03",
"amount": 50.0,
"currency_code": "USD",
"description": "business expense",
"category": "business_services",
"extra": {
"original_amount": 993.90,
"original_currency_code": "CZK",
"posting_date": "2020-05-06",
"time": "12:16:25"
},
"account_id": "333333333333333333",
"created_at": "2024-10-06T14:41:01Z",
"updated_at": "2024-10-07T14:41:01Z"
}
],
"meta" : {
"next_id": "444444444444444449",
"next_page": "/api/v1/transactions/?account_id=333333333333333333&from_id=444444444444444449"
}
}
Extra
The following represents the object you get in the extra
field of the transaction object.
account_balance_snapshot
decimal
The balance of the account at the moment of the attempt when the transaction was imported
account_number
string
Number of the account the transaction belongs to
additional
string
Additional information (recommended to use in concatenation with original description, if present)
asset_amount
decimal
Original transaction amount in asset units
asset_code
string
Asset common used abbreviation (Ex.: BTC
- Bitcoin, XAU
- Gold etc.)
categorization_confidence
float
Value from 0 to 1, the probability that the current category is the correct one
check_number
string
Payee’s transaction check number
closing_balance
decimal
Account balance after the transaction has been made
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
exchange_rate
float
The exchange rate that was applied to the converted transaction
id
string
Transaction’s identifier on the bank’s end (do not confuse it with Salt Edge 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 the transaction has been made
installment_debt_amount
decimal
Amount of the total 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
posted_by_aspsp
boolean
Indicates that transaction is marked as posted (or booked) by the bank, but has the pending status assigned by Salt Edge due to custom_pendings_period
logic.
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
User defined information in the bank or e-wallet interface, assigned to a transaction record (not category)
time
time
Time when the transaction was made
transfer_account_name
string
Name of the linked account
type
string
Transaction type
unit_price
decimal
Price per unit (used with units, available for investment accounts nature only)
units
decimal
Amount of units owned (used with unit_price, available for investment accounts nature only)
variable_code
string
Identifies the tax subject to the tax office, used for domestic payments (transfers)
account_balance_snapshot
decimal
The balance of the account at the moment of the attempt when the transaction was imported
account_number
string
Number of the account the transaction belongs to
additional
string
Additional information (recommended to use in concatenation with original description, if present)
asset_amount
decimal
Original transaction amount in asset units
asset_code
string
Asset common used abbreviation (Ex.: BTC
- Bitcoin, XAU
- Gold etc.)
categorization_confidence
float
Value from 0 to 1, the probability that the current category is the correct one
check_number
string
Payee’s transaction check number
closing_balance
decimal
Account balance after the transaction has been made
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
exchange_rate
float
The exchange rate that was applied to the converted transaction
id
string
Transaction’s identifier on the bank’s end (do not confuse it with Salt Edge 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 the transaction has been made
installment_debt_amount
decimal
Amount of the total 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
posted_by_aspsp
boolean
Indicates that transaction is marked as posted (or booked) by the bank, but has the pending status assigned by Salt Edge due to custom_pendings_period
logic.
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
User defined information in the bank or e-wallet interface, assigned to a transaction record (not category)
time
time
Time when the transaction was made
transfer_account_name
string
Name of the linked account
type
string
Transaction type
unit_price
decimal
Price per unit (used with units, available for investment accounts nature only)
units
decimal
Amount of units owned (used with unit_price, available for investment accounts nature only)
variable_code
string
Identifies the tax subject to the tax office, used for domestic payments (transfers)
Show Holder Info
You can query essential information about the account holder. Make sure to request this feature to be enabled for your client account.
Attributes
connection_id
string
The id
of the connection whose holder info is to be fetched
names
array
Account holder’s name(s)
emails
array
Account holder’s email(s)
phone_numbers
array
Account holder’s phone number(s)
addresses
array of objects
Account holder’s address(es)
names
array
Account holder’s name(s)
emails
array
Account holder’s email(s)
phone_numbers
array
Account holder’s phone number(s)
addresses
array of objects
Account holder’s address(es)
Extra
Depending on the 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)birth_date
- account holder’s date of birthdocument_number
- account holder’s identification number
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/holder_info?connection_id={connection.id}
https://www.saltedge.com/api/partners/v1/holder_info
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/holder_info?connection_id=111111111111111111
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Connection-secret: $CONNECTION_SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/holder_info
Sample Response
{
"data": {
"names": ["John Doe"],
"emails": ["john.doe@example.com", "johndoe@gmail.com"],
"phone_numbers": ["+40981233422"],
"addresses": [
{
"city": "Cupertino",
"state": "CA",
"street": "1 Infinite Loop",
"country_code": "US",
"post_code": "95014"
}
]
}
}
Transaction Categorization
Salt Edge API automatically categorizes all the transactions. Thus, when importing a connection, all the transactions corresponding to the connection will be assigned to one of the categories.
There are 2 types of categories: personal categories and business categories, which help to categorize transactions, made by physical persons or legal entities.
The categories are represented as strings.
They are structured as parent
and child
categories, which can be identified by the tree structure sent in the Listing categories request.
This arrangement is represented as a reference. You can change it as you wish.
You can test the categorization, using the fakebank_with_file_csv_xf
provider. Fill out the predefined sample.csv template. The file size limit is 5MB.
Note: Country
and Account Currency
defaults to GB
and GBP
respectively. In order to test the transaction categorization in other countries, the two codes must be configured accordingly.
How to use
By default, transactions are categorized, using the list of personal
categories, via parameter categorization
set on routes: lead sessions #create, #refresh, #reconnect, as you need.
We also expose an API route for your applications to provide the possibility for your users to update categories for their transactions with certain description.
List
You can get the list of all the categories that we support.
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/categories
https://www.saltedge.com/api/partners/v1/categories
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/categories
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/categories
Sample Response
{
"data": {
"business": {
"equipment_and_materials": [
"electronics",
"software",
"supplies_and_furniture",
"raw_materials",
"consumer_goods"
],
"financials": [
"dividends",
"donations",
"interest",
"fees",
"fines",
"loans"
],
"human_resources": [
"wages",
"bonus",
"employee_benefits",
"education_and_trainings",
"staff_outsourcing",
"travel",
"entertainment",
"meals"
],
"income": [
"investments",
"sales",
"returns",
"prepayments"
],
"insurance": [
"business_insurance",
"liability_insurance",
"health_insurance",
"equipment_insurance",
"vehicle_insurance",
"professional_insurance"
],
"real_estate": [
"office_rent",
"mortgage",
"construction_and_repair"
],
"services": [
"contractors",
"accounting_and_auditing",
"legal",
"consulting",
"storage",
"marketing_and_media",
"online_subscriptions",
"it_services",
"cleaning"
],
"taxes": [
"vat",
"federal_taxes",
"property_taxes",
"income_taxes",
"duty_taxes",
"tax_return",
"payroll_taxes"
],
"transport": [
"shipping",
"leasing",
"gas_and_fuel",
"taxi",
"service_and_parts"
],
"uncategorized": [],
"utilities": [
"internet",
"phone",
"water",
"gas",
"electricity"
]
},
"personal": {
"auto_and_transport": [
"car_rental",
"gas_and_fuel",
"parking",
"public_transportation",
"service_and_parts",
"taxi"
],
"bills_and_utilities": [
"internet",
"phone",
"television",
"utilities"
],
"business_services": [
"advertising",
"office_supplies",
"shipping"
],
"education": [
"books_and_supplies",
"student_loan",
"tuition"
],
"entertainment": [
"amusement",
"arts",
"games",
"movies_and_music",
"newspapers_and_magazines"
],
"fees_and_charges": [
"provider_fee",
"loans",
"service_fee",
"taxes"
],
"food_and_dining": [
"alcohol_and_bars",
"cafes_and_restaurants",
"groceries"
],
"gifts_and_donations": [
"charity",
"gifts"
],
"health_and_fitness": [
"doctor",
"personal_care",
"pharmacy",
"sports",
"wellness"
],
"home": [
"home_improvement",
"home_services",
"home_supplies",
"mortgage",
"rent"
],
"income": [
"bonus",
"investment_income",
"paycheck"
],
"insurance": [
"car_insurance",
"health_insurance",
"life_insurance",
"property_insurance"
],
"kids": [
"allowance",
"babysitter_and_daycare",
"baby_supplies",
"child_support",
"kids_activities",
"toys"
],
"pets": [
"pet_food_and_supplies",
"pet_grooming",
"veterinary"
],
"shopping": [
"clothing",
"electronics_and_software",
"sporting_goods"
],
"transfer": [],
"travel": [
"hotel",
"transportation",
"vacation"
],
"uncategorized": []
}
}
}
Learn
Your customers can change the category of some of their transactions, thus improving the categorization accuracy.
The custom category will be applicable only for the customer’s new transactions, which have similar description.
The customer can change the category to the one already existing in categories list - in this case custom category is located in transaction extra
as customer_category_code
.
The customers can set their own category - in this case a custom category is located in the transaction extra
as customer_category_name
.
Note: To update the custom category, a new request should be sent for Learn with customer_id
, id
(the id
of the transaction) and the new category_code
.
Request body
transactions
array of objects
transactions
array of objects
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/categories/learn
https://www.saltedge.com/api/partners/v1/categories/learn
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\", \
\"transactions\": [ \
{ \
\"id\": \"444444444444444444\", \
\"category_code\": \"paycheck\", \
\"immediate\": true \
}, \
{ \
\"id\": \"444444444444444445\", \
\"category_code\": \"car_rental\", \
\"immediate\": false \
} \
] \
} \
}" \
https://www.saltedge.com/api/partners/v1/categories/learn
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-H "Customer-secret: $CUSTOMER_SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"transactions\": [ \
{ \
\"id\": \"444444444444444444\", \
\"category_code\": \"paycheck\", \
\"immediate\": true \
}, \
{ \
\"id\": \"444444444444444445\", \
\"category_code\": \"car_rental\", \
\"immediate\": false \
} \
] \
} \
}" \
https://www.saltedge.com/api/partners/v1/categories/learn
Sample Response
{
"data": {
"learned": true
}
}
Merchant Identification
A merchant
represents a company that sells goods, or provides services to a customer
.
Identification
Merchant identification is an option that allows to identify merchant names and other useful information about them, basing on transactions’ data.
Europe
- Austria
- Belgium
- Croatia
- Czech Republic
- Estonia
- France
- Germany
- Hungary
- Italy
- Latvia
- Lithuania
- Luxembourg
- Netherlands
- Poland
- Portugal
- Republic of Ireland
- Romania
- Russia
- Slovenia
- Spain
- United Kingdom
Asia
- Hong Kong
- India
- Indonesia
- Israel
- Malaysia
- Philippines
- Saudi Arabia
- Singapore
- Turkey
- United Arab Emirates
Australia/Oceania
- Australia
- New Zealand
North America
- Mexico
South America
- Brazil
You can test the merchant identification, using the fakebank_with_file_csv_xf
provider. Fill out the predefined sample.csv template. The file size limit is 5MB.
Note: Country
and Account Currency
defaults to GB
and GBP
respectively. In order to test the merchant identification in other countries, the two codes must be configured accordingly.
How to use
To start using this option, all you need to do is:
- on lead sessions #create, #refresh and #reconnect, when the connection creation succeeds and only if the merchant is identified, you will receive a
merchant_id
in theextra
field of the transaction; - send all the
merchant_ids
you want to fetch the additional info for, to merchants.
Also, you can test it, using the fakebank_simple_xf
provider, available for the fake XF
country.
The API accepts batches of at most 100 objects.
Show
To fetch the name and additional info, available for identified merchants, pass the desired merchant_ids
in an array to route https://www.saltedge.com/api/partners/v1/merchants
.
Note that the first priority of this feature is to identify the merchant name
, that’s why arrays with name
and transliterated_name
are always presented.
Sometimes, the transaction’s descriptional fields, can display additional information about the merchant, such as: shop number, or address of sale point, with city, post code and street numbers. In this case, it’s possible to identify the exact place where the customer’s transaction was made. If we find the point of sale corresponding to the transaction in our database, then we can return more granular information with contact and address details, including geo-coordinates.
The API accepts batches of at most 100 objects.
Attributes
id
string
The id
of the merchant
names
array of objects
Merchant names that are used to name a company, corporation, brand name, franchise name or any other entity who has participated in the customer’s transaction
Possible values are: name
, transliterated_name
, alternative_name
, brand
, operator
address
object
Merchant address may include the following 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 via which the merchant can be accessed, eg. via website, phone or social media
Possible values are: email
, viber
, phone
, fax
, website
, facebook
, twitter
, google_plus
, linkedin
, instagram
, skype
, vk
, flickr
, youtube
id
string
The id
of the merchant
names
array of objects
Merchant names that are used to name a company, corporation, brand name, franchise name or any other entity who has participated in the customer’s transaction
Possible values are: name
, transliterated_name
, alternative_name
, brand
, operator
address
object
Merchant address may include the following 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 via which the merchant can be accessed, eg. via website, phone or social media
Possible values are: email
, viber
, phone
, fax
, website
, facebook
, twitter
, google_plus
, linkedin
, instagram
, skype
, vk
, flickr
, youtube
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/merchants
https://www.saltedge.com/api/partners/v1/merchants
Method
POST
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": [ \
\"0e81d5f8be1e3e73e4e604a36...\", \
\"b3e8ec2349df872072c051e0c...\" \
] \
}" \
https://www.saltedge.com/api/partners/v1/merchants
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": [ \
\"0e81d5f8be1e3e73e4e604a36...\", \
\"b3e8ec2349df872072c051e0c...\" \
] \
}" \
https://www.saltedge.com/api/partners/v1/merchants
Sample Response
{
"data": [
{
"id": "f6dabf8bb3e1cbc7cce2f4571...",
"names": [
{
"mode": "name",
"value": "Amazon"
},
{
"mode": "transliterated_name",
"value": "amazon"
}
],
"contact": [
{
"mode": "website",
"value": "www.amazon.com"
}
],
"address": {
"country_code": "GB"
}
},
{
"id": "ae316a83508ecaa8897e90321...",
"names": [
{
"mode": "name",
"value": "Boots"
},
{
"mode": "transliterated_name",
"value": "boots"
},
{
"mode": "operator",
"value": "Boots Uk Limited"
}
],
"contact": [
{
"mode": "phone",
"value": "+44 20 73818651"
},
{
"mode": "website",
"value": "http://www.boots.com/stores/773-london-fulham-palace-road-w6-9pa"
}
],
"address": {
"country_code": "GB",
"city": "London",
"transliterated_city": "london",
"street": "Fulham Palace Road",
"transliterated_street": "fulham palace road",
"post_code": "W6 9Pa",
"coordinates": {
"latitude": "51.48467107",
"longitude": "-0.220126411"
},
"extra": {
"building_number": "198-200",
"shop_number": "773",
"type_of_shop": "Chemist"
}
}
}
]
}
Financial Insights
Financial Insights represents a report based on all the activities of a single customer. It analyzes all the unique accounts of customer’s connections to the providers for a selected period of time.
Financial Insights report is provided as an additional service. Please get in touch with our Sales team in order to discuss your use case and receive a quote.
Attributes
id
string
The id
of the general report generated based on the customer’s data
partner_id
string
The id
of the Salt Edge Partner, who requested the Financial Insights report
lead_email
string
Lead’s email address
status
string
Current report’s status. Possible values are: initialized
, calculating
, success
, failed
connection_ids
array of strings
Ids
of connections included in the report
Note: We do not include the duplicated accounts in the report’s calculation. If any connection is not included in the report, that means that this connection contains only duplicated account data. Also the connection will not be included in the report, if there are no successful attempts to fetch the data for this connection.
include_account_natures
array of strings, optional
Accounts with specified account natures are included in the report. Possible values are: account
, bonus
, card
, checking
, credit
, credit_card
, debit_card
, ewallet
, insurance
, investment
, loan
, mortgage
, savings
from_date
date
The date from which the data in the report is included
to_date
date
The date to which the data in the report is included
report_types
array of strings
Types of reports. Possible values are: balance
, expense
, income
, savings
, expense_categories
, income_categories
, inbound_transfers
, outbound_transfers
.
Note: for an extended Financial Insights PDF report, the following types of reports are used: balance
, expense
, income
, savings
. For a compact PDF report, the following are mostly used: expense_categories
, income_categories
, inbound_transfers
, outbound_transfers
, as well as, some other parameters from the rest of the reports
created_at
datetime
The date when the report was created
updated_at
datetime
The date when the report was last updated
id
string
The id
of the general report generated based on the customer’s data
partner_id
string
The id
of the Salt Edge Partner, who requested the Financial Insights report
lead_email
string
Lead’s email address
status
string
Current report’s status. Possible values are: initialized
, calculating
, success
, failed
connection_ids
array of strings
Ids
of connections included in the report
Note: We do not include the duplicated accounts in the report’s calculation. If any connection is not included in the report, that means that this connection contains only duplicated account data. Also the connection will not be included in the report, if there are no successful attempts to fetch the data for this connection.
include_account_natures
array of strings, optional
Accounts with specified account natures are included in the report. Possible values are: account
, bonus
, card
, checking
, credit
, credit_card
, debit_card
, ewallet
, insurance
, investment
, loan
, mortgage
, savings
from_date
date
The date from which the data in the report is included
to_date
date
The date to which the data in the report is included
report_types
array of strings
Types of reports. Possible values are: balance
, expense
, income
, savings
, expense_categories
, income_categories
, inbound_transfers
, outbound_transfers
.
Note: for an extended Financial Insights PDF report, the following types of reports are used: balance
, expense
, income
, savings
. For a compact PDF report, the following are mostly used: expense_categories
, income_categories
, inbound_transfers
, outbound_transfers
, as well as, some other parameters from the rest of the reports
created_at
datetime
The date when the report was created
updated_at
datetime
The date when the report was last updated
Sample object
{
"id": "509574324735183486",
"customer_id": "499952892392769962",
"partner_id": "962",
"lead_email": "test@mail.com",
"status": "success",
"connection_ids": [
"499953130209806766"
],
"include_account_natures": [
"account",
"card",
"debit_card",
"credit_card",
"checking",
"savings",
"investment",
"bonus",
"loan",
"credit",
"insurance",
"ewallet",
"mortgage"
],
"currency_code": "GBP",
"from_date": "2021-01-01",
"to_date": "2021-04-22",
"report_types": [
"balance",
"expense",
"income",
"savings",
"income_categories",
"expense_categories",
"inbound_transfers",
"outbound_transfers"
],
"data": {
},
"created_at": "2024-10-08T11:41:01Z",
"updated_at": "2024-10-08T11:41:01Z"
}
Create
Allows you to create a report for a customer for a specific date range.
Parameters
report_types
array of strings, required
Types of reports that can be generated. Possible values are: balance
, expense
, income
, savings
, expense_categories
, income_categories
, inbound_transfers
, outbound_transfers
Note: at least one report type should be requested
Note: for an extended Financial Insights PDF report, the following types of reports are used: balance
, expense
, income
, savings
. For a compact PDF report, the following are mostly used: expense_categories
, income_categories
, inbound_transfers
, outbound_transfers
, as well as, some other parameters from the rest of the reports
include_account_natures
array of strings, optional
Accounts with specified account natures can be included in the report. Possible values are: account
, bonus
, card
, checking
, credit
, credit_card
, debit_card
, ewallet
, insurance
, investment
, loan
, mortgage
, savings
currency_code
string, required
Main currency code to be used for the report’s generation and value conversion
from_date
string, required
The date from which the data in the report will be included
to_date
string, required
The date to which the data in the report will be included
report_types
array of strings, required
Types of reports that can be generated. Possible values are: balance
, expense
, income
, savings
, expense_categories
, income_categories
, inbound_transfers
, outbound_transfers
Note: at least one report type should be requested
Note: for an extended Financial Insights PDF report, the following types of reports are used: balance
, expense
, income
, savings
. For a compact PDF report, the following are mostly used: expense_categories
, income_categories
, inbound_transfers
, outbound_transfers
, as well as, some other parameters from the rest of the reports
include_account_natures
array of strings, optional
Accounts with specified account natures can be included in the report. Possible values are: account
, bonus
, card
, checking
, credit
, credit_card
, debit_card
, ewallet
, insurance
, investment
, loan
, mortgage
, savings
currency_code
string, required
Main currency code to be used for the report’s generation and value conversion
from_date
string, required
The date from which the data in the report will be included
to_date
string, required
The date to which the data in the report will be included
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/reports
https://www.saltedge.com/api/partners/v1/reports
Method
POST
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"$CUSTOMER_ID\", \
\"report_types\": [ \
\"balance\", \
\"expense\", \
\"income\", \
\"savings\", \
\"expense_categories\", \
\"income_categories\", \
\"inbound_transfers\", \
\"outbound_transfers\" \
], \
\"include_account_natures\": [ \
\"account\", \
\"bonus\", \
\"card\", \
\"checking\", \
\"credit\", \
\"credit_card\", \
\"debit_card\", \
\"ewallet\", \
\"insurance\", \
\"investment\", \
\"loan\", \
\"mortgage\", \
\"savings\" \
], \
\"currency_code\": \"GBP\", \
\"from_date\": \"2021-01-01\", \
\"to_date\": \"2021-04-22\" \
} \
}" \
https://www.saltedge.com/api/partners/v1/reports
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X POST \
-d "{ \
\"data\": { \
\"customer_id\": \"$CUSTOMER_ID\", \
\"report_types\": [ \
\"balance\", \
\"expense\", \
\"income\", \
\"savings\", \
\"expense_categories\", \
\"income_categories\", \
\"inbound_transfers\", \
\"outbound_transfers\" \
], \
\"include_account_natures\": [ \
\"account\", \
\"bonus\", \
\"card\", \
\"checking\", \
\"credit\", \
\"credit_card\", \
\"debit_card\", \
\"ewallet\", \
\"insurance\", \
\"investment\", \
\"loan\", \
\"mortgage\", \
\"savings\" \
], \
\"currency_code\": \"GBP\", \
\"from_date\": \"2021-01-01\", \
\"to_date\": \"2021-04-22\" \
} \
}" \
https://www.saltedge.com/api/partners/v1/reports
Sample response
{
"data": {
"id": "509574324735183486",
"customer_id": "499952892392769962",
"lead_email": "test@email.com",
"connection_ids": [
"499953130209806766",
"499953130209806767",
"499953130209806768"
],
"status": "initialized",
"created_at": "2024-10-08T14:41:01Z"
}
}
Show
Shows the generated report with all the details.
The Report can be downloaded in PDF format via API as well, by adding .pdf
after report_id
parameter.
URL example: https://www.saltedge.com/api/partners/v1/reports/{report.id}.pdf
Parameters
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/reports/{report.id}
https://www.saltedge.com/api/partners/v1/reports/{report.id}
Method
GET
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/reports/999999999999999999
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/reports/999999999999999999
Sample response
{
"data": {
"id": "509574324735183486",
"customer_id": "499952892392769962",
"partner_id": "962",
"lead_email": "test@mail.com",
"status": "success",
"connection_ids": [
"499953130209806766"
],
"include_account_natures": [
"account",
"card",
"debit_card",
"credit_card",
"checking",
"savings",
"investment",
"bonus",
"loan",
"credit",
"insurance",
"ewallet",
"mortgage"
],
"currency_code": "GBP",
"from_date": "2021-01-01",
"to_date": "2021-04-22",
"report_types": [
"balance",
"expense",
"income",
"savings",
"income_categories",
"expense_categories",
"inbound_transfers",
"outbound_transfers"
],
"data": {
"result": {
"accounts": [
{
"id": "499953244512979380",
"name": "2445***156",
"nature": "card",
"connection_id": "499953130209806766",
"start_date": "2021-01-01",
"end_date": "2021-04-21",
"whole_months_count": 3,
"days_count": 112,
"monthly_average_transactions_count": {
"total": 17,
"income": 3,
"expense": 14
},
"balance": {},
"income": {},
"expense": {},
"savings": {},
"expense_categories": {},
"income_categories": {},
"inbound_transfers": {},
"outbound_transfers": {}
}
],
"accounts_summary": {
"start_date": "2021-01-01",
"end_date": "2021-04-21",
"whole_months_count": 3,
"days_count": 112,
"transactions_count": 64,
"monthly_average_transactions_count": {
"total": 17,
"income": 3,
"expense": 14
},
"balance": {},
"income": {},
"expense": {},
"savings": {},
"expense_categories": {},
"income_categories": {},
"inbound_transfers": {},
"outbound_transfers": {}
}
},
"customer_id": 499952892392769962,
"connection_ids": [
"499953130209806766"
],
"connections": [
{
"id": "499953130209806766",
"customer_id": 499952892392769962,
"provider_code": "fakebank_with_file_csv_xf",
"provider_name": "Fakebank with file CSV",
"accounts": [
{
"id": "499953244512979380",
"name": "2445***156",
"nature": "card",
"balance": 6412.0,
"original_balance": 6412.0,
"original_currency_code": "GBP",
"transactions": {
"start_date": "2021-01-01",
"end_date": "2021-04-21",
"first_id": "499953313559611829",
"last_id": "499953322376038900",
"count": 64
}
}
],
"holder_info": {
"names": [
"John Doe"
]
},
"client_name": "test app"
}
],
"currency_code": "GBP",
"exchange_rates": {
"EUR": "1.083599",
"USD": "1.2341013636"
},
"report_id": 509574324735183486,
"report_types": [
"balance",
"expense",
"income",
"savings",
"income_categories",
"expense_categories",
"inbound_transfers",
"outbound_transfers"
],
"status": "success",
"from_date": "2021-01-01",
"to_date": "2021-04-22"
},
"created_at": "2021-06-21T14:19:29Z",
"updated_at": "2021-06-21T14:19:48Z"
}
}
List
Returns all the general available reports for a customer.
Parameters
from_id
string, optional
The id
of the report which the list starts with
from_id
string, optional
The id
of the report which the list starts with
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/reports?customer_id={customer.id}
https://www.saltedge.com/api/partners/v1/reports?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/partners/v1/reports?customer_id=$CUSTOMER_ID
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X GET \
https://www.saltedge.com/api/partners/v1/reports?customer_id=$CUSTOMER_ID
Sample response
{
"data": [
{
"id": "509574324735183486",
"customer_id": "499952892392769962",
"lead_email": "test@mail.com",
"connection_ids": [
"499953130209806766",
"499953130209806767"
],
"status": "success",
"created_at": "2024-10-07T14:41:01Z"
},
{
"id": "509574324735183487",
"customer_id": "499952892392769962",
"lead_email": "test@email.com",
"connection_ids": [
"499953130209806768",
"499953130209806769"
],
"status": "success",
"created_at": "2024-10-07T14:41:01Z"
}
],
"meta": {
"next_id": "509574324735183488",
"next_page": "/api/v5/reports/?from_id=509574324735183488"
}
}
Remove
Deletes a report.
Parameters
report_id
string, required
The id
of the general report
report_id
string, required
The id
of the general report
Possible Errors
URL
https://www.saltedge.com/api/partners/v1/reports/{report.id}
https://www.saltedge.com/api/partners/v1/reports/{report.id}
Method
DELETE
Sample request
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X DELETE \
https://www.saltedge.com/api/partners/v1/reports/999999999999999999
curl -v -H "Accept: application/json" \
-H "Content-type: application/json" \
-H "App-id: $APP_ID" \
-H "Secret: $SECRET" \
-X DELETE \
https://www.saltedge.com/api/partners/v1/reports/999999999999999999
Sample response
{
"data": {
"id": "509574324735183486",
"deleted": true
}
}
Report Object
result
string
Report result
connection_ids
array of strings
Ids
of connections included in the report
Note: We do not include the duplicated accounts in the report’s calculation. If any connection is not included in the report, that means that this connection contains only duplicated account data. Also the connection will not be included in the report, if there are no successful attempts to fetch the data for this connection.
connections
array of objects
Information related to connections included in report
exchange_rates
object
A list of exchange rates at the time of report creation
report_id
integer
The id
of the generated report
report_types
array of strings
Types of generated reports. Possible values are: balance
, expense
, income
, savings
, expense_categories
, income_categories
, inbound_transfers
, outbound_transfers
status
string
Current report’s status. Possible values are: initialized
, calculating
, success
, failed
from_date
date
The date from which the data in the report is included
to_date
date
The date to which the data in the report is included
result
string
Report result
connection_ids
array of strings
Ids
of connections included in the report
Note: We do not include the duplicated accounts in the report’s calculation. If any connection is not included in the report, that means that this connection contains only duplicated account data. Also the connection will not be included in the report, if there are no successful attempts to fetch the data for this connection.
connections
array of objects
Information related to connections included in report
exchange_rates
object
A list of exchange rates at the time of report creation
report_id
integer
The id
of the generated report
report_types
array of strings
Types of generated reports. Possible values are: balance
, expense
, income
, savings
, expense_categories
, income_categories
, inbound_transfers
, outbound_transfers
status
string
Current report’s status. Possible values are: initialized
, calculating
, success
, failed
from_date
date
The date from which the data in the report is included
to_date
date
The date to which the data in the report is included
Sample object
{
"result": {
"accounts": [
{
"id": "499953244512979380",
"name": "2445***156",
"nature": "card",
"connection_id": "499953130209806766",
"start_date": "2021-01-01",
"end_date": "2021-04-21",
"whole_months_count": 3,
"days_count": 112,
"monthly_average_transactions_count": {
"total": 17,
"income": 3,
"expense": 14
},
"balance": { },
"income": { },
"expense": { },
"savings": { },
"expense_categories": { },
"income_categories": { },
"inbound_transfers": { },
"outbound_transfers": { }
}
],
"accounts_summary": {
"start_date": "2021-01-01",
"end_date": "2021-04-21",
"whole_months_count": 3,
"days_count": 112,
"transactions_count": 64,
"monthly_average_transactions_count": {
"total": 17,
"income": 3,
"expense": 14
},
"balance": { },
"income": { },
"expense": { },
"savings": { },
"expense_categories": { },
"income_categories": { },
"inbound_transfers": { },
"outbound_transfers": { }
}
},
"customer_id": 499952892392769962,
"connection_ids": [
"499953130209806766"
],
"connections": [
{
"id": "499953130209806766",
"customer_id": 499952892392769962,
"provider_code": "fakebank_with_file_csv_xf",
"provider_name": "Fakebank with file CSV",
"accounts": [
{
"id": "499953244512979380",
"name": "2445***156",
"nature": "card",
"balance": 6412.0,
"original_balance": 6412.0,
"original_currency_code": "GBP",
"transactions": {
"start_date": "2021-01-01",
"end_date": "2021-04-21",
"first_id": "499953313559611829",
"last_id": "499953322376038900",
"count": 64
}
}
],
"holder_info": {
"names": [
"John Doe"
]
},
"client_name": "test app"
}
],
"currency_code": "GBP",
"exchange_rates": {
"EUR": "1.083599",
"USD": "1.2341013636"
},
"report_id": 509574324735183486,
"report_types": [
"balance",
"expense",
"income",
"savings",
"income_categories",
"expense_categories",
"inbound_transfers",
"outbound_transfers"
],
"status": "success",
"from_date": "2021-01-01",
"to_date": "2021-04-22"
}
Balance Report Object
minimum
decimal
The minimum balance registered for the report’s date range.
maximum
decimal
The maximum balance registered for the report’s date range.
average
object
Average balance
forecasted_average
object
Forecasted average balance
minimum
decimal
The minimum balance registered for the report’s date range.
maximum
decimal
The maximum balance registered for the report’s date range.
average
object
Average balance
forecasted_average
object
Forecasted average balance
Sample object
{
"start_date_amount": 1150.0,
"end_date_amount": 6412.0,
"minimum": 1000.0,
"maximum": 9341.0,
"average": {
"daily": {
"start_date": "2021-01-01",
"end_date": "2021-04-22",
"amount": 5581.81
},
"daily_per_month": [
{
"amount": 3566.25,
"is_whole_month": true,
"year": 2021,
"month": 1
},
{
"amount": 4753.78,
"is_whole_month": true,
"year": 2021,
"month": 2
},
{
"amount": 6911.96,
"is_whole_month": true,
"year": 2021,
"month": 3
},
{
"amount": 7601.45,
"is_whole_month": false,
"year": 2021,
"month": 4
}
],
"monthly": {
"amount": 5077.33,
"start_date": "2021-01-01",
"end_date": "2021-03-31"
},
"minimum_monthly": {
"amount": 3566.25,
"end_date": "2021-03-31",
"start_date": "2021-01-01"
},
"maximum_monthly": {
"amount": 6911.96,
"end_date": "2021-03-31",
"start_date": "2021-01-01"
},
"quarterly": {
"amount": null,
"end_date": null,
"start_date": null
},
"annual": {
"amount": null,
"start_date": null,
"end_date": null
}
},
"forecasted_average": {
"next_month": 8423.04,
"next_quarter": null,
"next_year": null
}
}
Income/Expense Report Object
last_year_amount
decimal
Total amount of income/expense for the last fully covered 12 months
total
decimal
Total amount of income/expense per the calculated period
total_per_month
array of objects
Total amount of income/expense per each month
average
object
Average amount of income/expense
forecasted_average
object
Forecasted average amount of income/expense
streams
object
Information on income/expense a customer receives/spends on a regular/irregular basis
last_year_amount
decimal
Total amount of income/expense for the last fully covered 12 months
total
decimal
Total amount of income/expense per the calculated period
total_per_month
array of objects
Total amount of income/expense per each month
average
object
Average amount of income/expense
forecasted_average
object
Forecasted average amount of income/expense
streams
object
Information on income/expense a customer receives/spends on a regular/irregular basis
Sample object
{
"start_date": "2021-01-02",
"end_date": "2021-04-03",
"transactions_count": 9,
"last_year_amount": null,
"total": 17100.0,
"total_per_month": [
{
"year": 2021,
"month": 1,
"is_whole_month": true,
"amount": 4100.0,
"count": 3
},
{
"year": 2021,
"month": 2,
"is_whole_month": true,
"amount": 4300.0,
"count": 3
},
{
"year": 2021,
"month": 3,
"is_whole_month": true,
"amount": 4350.0,
"count": 2
},
{
"year": 2021,
"month": 4,
"is_whole_month": false,
"amount": 4350.0,
"count": 1
}
],
"average": {
"monthly": 4250.0,
"quarterly": null,
"annual": null
},
"forecasted_average": {
"next_month": 4500.0,
"next_quarter": null,
"next_year": null
},
"streams": {
"regular_amount": 16800.0,
"irregular_amount": 300.0,
"count": {
"regular": 2,
"irregular": 1,
"maximum_overlapping": 2
},
"regular": [
{
"transactions_count": 4,
"transaction_ids": [
"499953314029373878",
"499953315832924614",
"499953317401594326",
"499953321084193257"
],
"start_date": "2021-01-02",
"end_date": "2021-04-03",
"amount": {
"total": 16500.0,
"average": 4125.0,
"median": 4125.0,
"stdev": 182.0
},
"frequency": "monthly",
"days_count": 30,
"category_code": "income",
"description": "Salary",
"merchant": {
"name": null,
"email": null,
"phone": null,
"address": null,
"website": null
}
},
{
"transactions_count": 3,
"transaction_ids": [
"499953314163591607",
"499953315832924615",
"499953317544200664"
],
"start_date": "2021-01-02",
"end_date": "2021-03-01",
"amount": {
"total": 300.0,
"average": 100.0,
"median": 100.0,
"stdev": 0.0
},
"frequency": "monthly",
"days_count": 29,
"category_code": "transfer",
"description": "transfer",
"merchant": {
"name": null,
"email": null,
"phone": null,
"address": null,
"website": null
}
}
],
"irregular": {
"transactions_count": 2,
"transaction_ids": [
"499953314876623296",
"499953316806003154"
],
"start_date": "2021-01-21",
"end_date": "2021-02-19"
}
}
}
Savings Report Object
total
decimal
Total amount of savings per the calculated period
per_month
array of objects
Information related to net savings per each month
average
object
Average savings
forecasted_average
object
Forecasted average savings
runway
decimal
Provides an estimate (number of months) on how long the current balance will be sufficient until the customer runs out of money. The customer’s income and expenses are taken into account.Note: This indicator is calculated only for cases when the customer has positive current balance and the amount of expenses exceeds the amount of income.
expense_to_savings_rate
decimal
Shows whether the customer increases or loses capital. Taking into account the customer’s income and expenses, this indicator shows the number of months during which the customer’s savings are either increased or reduced by an amount equal to 1 month of expenses.Note: This indicator is calculated only for cases when the customer has both savings/dissavings and expenses.
stress_runway
decimal
Provides an estimate (number of months) on how long the customer’s current balance will be sufficient to cover regular expenses in case income stops unexpectedly.Note: This indicator is calculated for all cases, except the one, when the customer has no expenses.
income_stability
decimal
Average weighted stability of income from all the sources
Note: it is close to 1, if customer has stable income
income_regularity
decimal
Average weighted regularity of income from all the sources
Note: it is close to 1, if customer has regular income
income_to_expense_rate
decimal
Ratio of average monthly income to average monthly expense
total
decimal
Total amount of savings per the calculated period
per_month
array of objects
Information related to net savings per each month
average
object
Average savings
forecasted_average
object
Forecasted average savings
runway
decimal
Provides an estimate (number of months) on how long the current balance will be sufficient until the customer runs out of money. The customer’s income and expenses are taken into account.Note: This indicator is calculated only for cases when the customer has positive current balance and the amount of expenses exceeds the amount of income.
expense_to_savings_rate
decimal
Shows whether the customer increases or loses capital. Taking into account the customer’s income and expenses, this indicator shows the number of months during which the customer’s savings are either increased or reduced by an amount equal to 1 month of expenses.Note: This indicator is calculated only for cases when the customer has both savings/dissavings and expenses.
stress_runway
decimal
Provides an estimate (number of months) on how long the customer’s current balance will be sufficient to cover regular expenses in case income stops unexpectedly.Note: This indicator is calculated for all cases, except the one, when the customer has no expenses.
income_stability
decimal
Average weighted stability of income from all the sources
Note: it is close to 1, if customer has stable income
income_regularity
decimal
Average weighted regularity of income from all the sources
Note: it is close to 1, if customer has regular income
income_to_expense_rate
decimal
Ratio of average monthly income to average monthly expense
Sample object
{
"total": 5262.0,
"per_month": [
{
"year": 2021,
"month": 1,
"is_whole_month": true,
"amount": 430.0
},
{
"year": 2021,
"month": 2,
"is_whole_month": true,
"amount": 1955.0
},
{
"year": 2021,
"month": 3,
"is_whole_month": true,
"amount": 1730.0
},
{
"year": 2021,
"month": 4,
"is_whole_month": false,
"amount": 1147.0
}
],
"average": {
"monthly": 1371.66,
"quarterly": null,
"annual": null
},
"forecasted_average": {
"next_month": 2671.66,
"next_quarter": null,
"next_year": null
},
"runway": null,
"expense_to_savings_rate": 2.098,
"stress_runway": 2.227,
"income_stability": 0.34,
"income_regularity": 0.934,
"income_to_expense_rate": 1.476
}
Expense Categories Report Object
categories
array of objects
Information on the expense categories a customer spends money on.
Note: outbound transfers are not considered.
categories
array of objects
Information on the expense categories a customer spends money on.
Note: outbound transfers are not considered.
Sample object
{
"categories": [
{
"category": "Education",
"amount": -3000.0,
"average": -1000.0,
"amounts_per_month": [
{
"month": "2021-01",
"amount": -1000.0
},
{
"month": "2021-02",
"amount": -1000.0
},
{
"month": "2021-03",
"amount": -1000.0
},
{
"month": "2021-04",
"amount": 0
}
]
},
{
"category": "Utilities",
"amount": -1980.0,
"average": -493.33,
"amounts_per_month": [
{
"month": "2021-01",
"amount": -500.0
},
{
"month": "2021-02",
"amount": -550.0
},
{
"month": "2021-03",
"amount": -430.0
},
{
"month": "2021-04",
"amount": -500.0
}
]
},
{
"category": "Shopping",
"amount": -1915.0,
"average": -155.0,
"amounts_per_month": [
{
"month": "2021-01",
"amount": -200.0
},
{
"month": "2021-02",
"amount": -165.0
},
{
"month": "2021-03",
"amount": -100.0
},
{
"month": "2021-04",
"amount": -1450.0
}
]
},
{
"category": "Home improvement",
"amount": -1206.0,
"average": -300.0,
"amounts_per_month": [
{
"month": "2021-01",
"amount": -300.0
},
{
"month": "2021-02",
"amount": -300.0
},
{
"month": "2021-03",
"amount": -300.0
},
{
"month": "2021-04",
"amount": -306.0
}
]
},
{
"category": "Service and parts",
"amount": -1100.0,
"average": -200.0,
"amounts_per_month": [
{
"month": "2021-01",
"amount": -600.0
},
{
"month": "2021-02",
"amount": 0
},
{
"month": "2021-03",
"amount": 0
},
{
"month": "2021-04",
"amount": -500.0
}
]
},
{
"category": "Other categories",
"amount": -2585.0,
"average": -730.0,
"amounts_per_month": [
{
"month": "2021-01",
"amount": -1070.0
},
{
"month": "2021-02",
"amount": -330.0
},
{
"month": "2021-03",
"amount": -790.0
},
{
"month": "2021-04",
"amount": -395.0
}
]
}
]
}
Income Categories Report Object
streams
array of objects
Information on the income a customer receives on a regular/irregular basis.
Note: inbound transfers and other categories of incoming transactions are not considered.
streams
array of objects
Information on the income a customer receives on a regular/irregular basis.
Note: inbound transfers and other categories of incoming transactions are not considered.
Sample object
{
"streams": {
"regular_amount": 16500.0,
"irregular_amount": 300.0,
"count": {
"regular": 1,
"irregular": 1
},
"regular": [
{
"transactions_count": 4,
"transaction_ids": [
"499953314029373878",
"499953315832924614",
"499953317401594326",
"499953321084193257"
],
"start_date": "2021-01-02",
"end_date": "2021-04-03",
"amount": {
"total": 16500.0,
"average": 4125.0,
"median": 4125.0,
"stdev": 182.0
},
"amounts_per_month": [
{
"year": 2021,
"month": 1,
"amount": 3900.0
},
{
"year": 2021,
"month": 2,
"amount": 4000.0
},
{
"year": 2021,
"month": 3,
"amount": 4250.0
},
{
"year": 2021,
"month": 4,
"amount": 4350.0
}
],
"frequency": "monthly",
"days_count": 30,
"category_code": "income",
"description": "Salary",
"merchant": {
"name": null,
"email": null,
"phone": null,
"address": null,
"website": null
}
}
],
"irregular": {
"transactions_count": 2,
"transaction_ids": [
"499953314876623296",
"499953316806003154"
],
"start_date": "2021-01-21",
"end_date": "2021-02-19",
"amounts_per_month": [
{
"year": 2021,
"month": 1,
"amount": 100.0
},
{
"year": 2021,
"month": 2,
"amount": 200.0
},
{
"year": 2021,
"month": 3,
"amount": 0.0
},
{
"year": 2021,
"month": 4,
"amount": 0.0
}
],
"average": 100.0
}
}
}
Inbound Transfers Report Object
streams
array of objects
Information on the transfers a customer receives on a regular/irregular basis.
Note: all the transfers incoming from one account to another are considered as inbound transfers, no matter if those accounts belong to the same customer or different.
streams
array of objects
Information on the transfers a customer receives on a regular/irregular basis.
Note: all the transfers incoming from one account to another are considered as inbound transfers, no matter if those accounts belong to the same customer or different.
Sample object
{
"streams": {
"regular_amount": 300.0,
"irregular_amount": 0,
"count": {
"regular": 1,
"irregular": 0
},
"regular": [
{
"transactions_count": 3,
"transaction_ids": [
"499953314163591607",
"499953315832924615",
"499953317544200664"
],
"start_date": "2021-01-02",
"end_date": "2021-03-01",
"amount": {
"total": 300.0,
"average": 100.0,
"median": 100.0,
"stdev": 0.0
},
"amounts_per_month": [
{
"year": 2021,
"month": 1,
"amount": 100.0
},
{
"year": 2021,
"month": 2,
"amount": 100.0
},
{
"year": 2021,
"month": 3,
"amount": 100.0
},
{
"year": 2021,
"month": 4,
"amount": 0.0
}
],
"frequency": "monthly",
"days_count": 29,
"category_code": "transfer",
"description": "transfer",
"merchant": {
"name": null,
"email": null,
"phone": null,
"address": null,
"website": null
}
}
],
"irregular": {
"transactions_count": 0,
"transaction_ids": [],
"start_date": null,
"end_date": null,
"amounts_per_month": null,
"average": null
}
}
}
Outbound Transfers Report Object
streams
array of objects
Information on the transfers a customer sends on a regular/irregular basis.
Note: all the transfers outgoing from one account to another are considered as outbound transfers, no matter if those accounts belong to the same customer or different.
streams
array of objects
Information on the transfers a customer sends on a regular/irregular basis.
Note: all the transfers outgoing from one account to another are considered as outbound transfers, no matter if those accounts belong to the same customer or different.
Sample object
{
"streams": {
"regular_amount": 0,
"irregular_amount": -52.0,
"count": {
"regular": 0,
"irregular": 1
},
"regular": [],
"irregular": {
"transactions_count": 1,
"transaction_ids":