API Reference

Callbacks

The callback URLs for the application can be set on the dedicated Dashboard callbacks page.

Success

A callback to Client’s application's success URL is sent whenever an operation causes a change in the data stored for a specific connection.

For example, once the User has been redirected to the Connect page, selected the Provider, filled in the credentials fields, and pressed the "Proceed" button, Salt Edge will send a success callback. This callback will include the customer_identifier and the connection_id of the newly created Connection.

Subsequently, the application can use the Connections/ Show route to query information about this Connection. Connections/ Accounts can also be retrieved and query the accounts (if any exist at the time the callback is sent).

Whenever an additional information about the Connection is available, another success callback will be sent.

Success

A change in the data is indicated by a success callback, and generally, one to three success callbacks with the same payload can be expected within several minutes. It is recommended that updated connection objects, Account balances, additional fields, and transactions be listed by the Client’s application using the from_id parameter to fetch newly imported records at each callback, as some information might change during the fetching process.

For instance, when the User creates a connection using Salt Edge Widget, we will send the following success callback:

  {
    "data": {
      "connection_id": "111111111111111111",
      "customer_id": "222222222222222222",
      "custom_fields": { "key": "value" },
      "stage": "finish"
    },
    "meta": {
      "version": "6",
      "time": "2024-01-25T10:40:47.965Z"
    }
  }

The Provider, country, and other attributes of the new Connection can be obtained using the Connections/ Show route.

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

  • connect - connecting to the data source.
  • fetch_holder_info - fetching information about the Account holder.
  • fetch_accounts - fetching the accounts.
  • fetch_transactions - fetching the transactions.
  • finish_fetching - wrapping up the fetching process.
  • start_categorization - starting the process of categorization (skipped, if categorization is disabled)
  • finish_categorization - finishing the process of categorization (skipped, if categorization is disabled)
  • finish - wrapping up the process.

Failure

Sometimes, information retrieval from the Provider's page may fail. This could be due to the User not sending interactive data, incorrect credentials, or a failure in one of the steps of the fetching process. In such instances, a fail callback will be received containing 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": "6",
      "time": "2024-01-25T10:40:47.979Z"
    }
  }

Upon receiving this callback, the Connection needs to be requested to check for updates. It's important to note that even if an error occurs, the Connection is still stored.

If the desire is to remove the erroneous connection, the Connections/ Remove route can be used. In the case of an InvalidCredentials error, a Reconnect is recommended.

Note

To prevent Connection duplication errors during new Connection creation, after receiving a fail callback, it is recommended to remove the Connection if the last_fail_error_class is equal to InvalidCredentials and the Connection has zero linked Accounts.


Additional callbacks need to be implemented by the app in order to use the API-only version of the Account Information API.

Notify

Information about the progress the Connection is undergoing can be conveyed by Salt Edge through the usage of a Notify callback. If the appropriate notify URL is configured in the Client Account, it will be dispatched for Create, Reconnect, Refresh, Refresh (without Widget) and Background refresh attempts.

The Notify callback can be expected to be received by the app multiple times, depending on the type of Connection. This information can be used to keep the Users informed about the status of their Connection.

The potential stages included in a Notify callback are as follows:

  • start - the fetching process has just begun
  • connect - connecting to the data source
  • fetch_holder_info - fetching information about the Account holder
  • fetch_accounts - fetching the accounts
  • fetch_transactions - fetching data for a recent period (several months)
  • finish_fetching - wrapping up the fetching process
  • start_categorization - starting the process of categorization (skipped if categorization is disabled)
  • finish_categorization - finishing the process of categorization (skipped if categorization is disabled)
  • finish - wrapping up the process

An example callback sent to the notify route of the Client’s app is as follows:

  {
    "data": {
      "connection_id": "111111111111111111",
      "customer_id": "222222222222222222",
      "custom_fields": { "key": "value" },
      "stage": "start"
    },
    "meta": {
      "version": "6",
      "time": "2024-01-24T10:40:47Z"
    }
  }
Note

It's important to note that all stages may not be received for some Connections and notify callbacks will not be triggered for daily attempts.

Destroy

Whenever a Connection is removed, a callback will be sent to the Client’s application’s destroy URL, if it is set in the Client Account.

Here’s an example callback sent to the Client’s app’s, destroy route:

  {
    "data": {
      "connection_id": "111111111111111111",
      "customer_id": "222222222222222222",
        "custom_fields": { "key": "value" },
    },
    "meta": {
      "version": "6",
      "time": "2024-01-24T10:40:48Z"
    }
  }

Provider changes

Whenever the Provider's status changes, notifications will be sent to the Provider Changes URL callback route by Salt Edge.

The callback URLs for Client’s application can be set on the dedicated Dashboard callbacks page.

  {
    "data": {
      "provider_status": "inactive",
      "provider_code": "fake_client_xf"
    },
    "meta": {
      "version": 5,
      "time": "2023-09-21T09:49:13.472Z"
    }
  }

Countries

It is represented solely as a string, using ISO 3166-1 alpha-2 country codes. Consequently, all country codes will consist of precisely two uppercase letters. Two special cases are observed:

  • "Other" is encoded as XO.
  • "Fake" is encoded as XF.
Note

Fake country is exclusively available for Clients in Test and Pending statuses.

For Clients in Live status, send include_fake_providers: true

Attributes

  • namestring
    Name of the country
  • codestring
    Country code as dated in ISO 3166-1 alpha-2
  • refresh_start_timeinteger
    The local country time when Connections will be automatically refreshed

ListGET

Returns a list of countries supported by the API.

Query Parameters

  • include_fake_providersboolean
    Whether to display Sandboxes and Fake Providers or not.
    true (for Clients in Pending & Test status); false (for Live Clients)
    Possible values: true, false
    Default value: true

Possible errors

No specific errors

URL

https://www.saltedge.com/api/v6/countries?include_sandboxes=true

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/v6/countries?include_sandboxes=true
Sample response
{
  "data": [
    {
      "name": "United Arab Emirates",
      "code": "AE",
      "refresh_start_time": 21
    },
    {
      "name": "Armenia",
      "code": "AM",
      "refresh_start_time": 22
    },
    {
      "name": "Argentina",
      "code": "AR",
      "refresh_start_time": 5
    },
    {
      "name": "Austria",
      "code": "AT",
      "refresh_start_time": 1
    },
    {
      "name": "Australia",
      "code": "AU",
      "refresh_start_time": 16
    },
    {
      "name": "Azerbaijan",
      "code": "AZ",
      "refresh_start_time": 22
    },
    {
      "name": "Bosnia and Herzegovina",
      "code": "BA",
      "refresh_start_time": 0
    },
    {
      "name": "Barbados",
      "code": "BB",
      "refresh_start_time": 6
    },
    {
      "name": "Bangladesh",
      "code": "BD",
      "refresh_start_time": 20
    },
    {
      "name": "Belgium",
      "code": "BE",
      "refresh_start_time": 0
    }
  ]
}

Providers

A Provider serves as a source of financial data. It is recommended that all of the Providers' fields are updated at least daily.

A better understanding of which Providers have been integrated and whether a Provider is already supported by Salt Edge is provided by the coverage map with the integrated PSD2/ Open Banking and non-regulated Providers.

Attributes

  • idstringmandatory
    The id of the Provider
  • codestring
    A distinct code for identifying a Provider
  • namestring
    Provider’s name
  • country_codestring
    Provider’s country code in ISO 3166-1 alpha-2 format
  • bic_codesarray of strings
    List of BIC codes identifying supported branches of a specific Provider
  • dynamic_registration_codestring
    The dynamic registration code assigned to the Provider
  • identification_codesarray of strings
    The list of codes identifying the supported branches of a specific Provider
  • group_codestring
    The code of the group the Provider belongs to
  • group_namestring
    The name of the group the Provider belongs to
  • hubstring
    The hub that the Provider is affiliated with
  • statusstring
    Provider’s status that indicates its state.
    Possible values are:
    • active - Providers with active status are accessible, returned on both List and Show endpoints, and visible within the Salt Edge Widget for Users.
    • inactive - Providers with an inactive status are returned on both List and Show endpoints, but are not visible in the Salt Edge Widget for Users.
    • disabled - Providers with a disabled status are neither returned on List and Show endpoints, nor visible in the Salt Edge Widget for Users.
  • modestring
    The way a Provider is accessed.
    Possible values are:
    • oauth - access through the Provider's dedicated API redirects the User to the Provider's page for authorization.
    • web - access through the Provider's web interface using screen scraping technology. Therefore, the User undergoes the same authorization flow as on the Provider's web interface using identical credentials in the Salt Edge Widget.
    • api - access through a dedicated (regulated: true) or non-dedicated (regulated: false) Provider's API. Some required credential fields might be present, which the User must complete (such as IBAN, username, etc.). In the case of a dedicated API, an interactive redirect might be present, but required credential fields must still be completed by the User (e.g., IBAN, username, etc.). Using these credentials, the User is authorized on the Provider’s side.
  • regulatedboolean
    Whether the Provider is integrated via a regulated channel under Open Banking/ PSD2
  • logo_urlstring
    The URL for the Provider logo. May contain a placeholder for Providers with missing logos
  • timezonestring
    Time zone data for the capital/ major city in a region corresponding to the Provider
  • supported_iframe_embeddingboolean
    Indicates whether the Provider supports being embedded within an iframe.
    If set to true, the Provider's content can be securely displayed within an iframe on external websites.
  • optional_interactivityboolean
    Provider that supports toggling the interactive and automatic_fetch flags after connecting.
    Relevant for Providers with mode: web
  • customer_notified_on_sign_inboolean
    Whether the Provider will notify the Customer upon a login attempt
  • created_atstring (date-time)
    The timestamp indicating when the Provider was integrated
  • updated_atstring (date-time)
    The timestamp of the most recent update to any of the Provider's attributes
  • include_ais_fieldsboolean
    Returns the Account Information fields supported by the Provider
    Default value: false
    Hide child attributes
    • automatic_fetchboolean
      Whether the Provider's Connections can be automatically fetched, with performance contingent on the optional_interactivity flag
    • custom_pendings_periodinteger
      Populated when custom_pendings: true.
      Displays the number of days corresponding to the custom pending period implemented by the Provider.
    • holder_infoarray of strings
      Contains information on the Account holder details retrievable from the requested Provider
    • instruction_for_connectionsstring
      Provides instructions or guidance for establishing Connections with the Provider. It may contain information on the steps Users need to follow during the connection setup process.
    • interactive_for_connectionsboolean
      Indicates whether the Provider requires the User to perform an interactive step
    • max_fetch_intervalinteger
      The maximum number of days for which a Provider can return transaction data
    • max_interactive_delayinteger
      The delay in seconds before an Unfinished error is raised
    • refresh_timeoutinteger
      The amount of time, in minutes, after which the Provider's Connections are allowed to be refreshed
    • supported_account_extra_fieldsarray of strings
      An array of possible extra fields associated with Accounts that can be fetched
    • supported_account_naturesarray of strings
      An array of possible Account natures to be fetched
    • supported_account_typesarray of strings
      Corporate accounts are identified as Business accounts.
      Possible values: personal, business
    • supported_fetch_scopesarray of strings
      An array of supported fetch_scopes
    • supported_transaction_extra_fieldsarray of strings
      An array of possible transaction extra fields to be fetched
  • include_pis_fieldsboolean
    Returns the supported and required payment fields
    Default value: false
    Hide child attributes
    • payment_templatesarray of strings
      Identifiers of the payment templates supported by this Provider
    • instruction_for_paymentsstring
      Provides instructions or guidance for initiating Payments with the Provider
    • interactive_for_paymentboolean
      Indicates whether the Provider requires the User to perform an interactive step
    • required_payment_fieldsarray of strings
      The mandatory payment attributes. If any of these fields are not passed, the Payment will not be initiated successfully
    • supported_payment_fieldsarray of strings
      If these fields are passed, they will be used by the Provider. Otherwise, the Payment will be processed even without them
    • no_funds_rejection_supportedboolean
      A flag indicating whether the Provider supports explicit handling of Payment rejection due to insufficient funds
  • include_credentials_fieldsboolean
    The set of credentials and interactive elements required for the User to input during the Connection setup process.
    Default value: false
    Hide child attributes
    • credentials_fieldsarray of hashes
      Contains the types and details of credentials required from the User during the Connection setup process
    • interactive_fieldsarray of hashes
      Contains the types and details of interactive elements that the User may need to provide during the Connection setup process

ListGET

Query Parameters

  • include_sandboxesboolean
    Whether to display Sandboxes and Fake Providers or not.
    true (for Clients in Pending & Test status); false (for Live Clients).
    Default value: true
  • country_codestring
    Filters the Providers by country
  • include_ais_fieldsboolean
    Includes the Provider’s AIS fields
  • include_pis_fieldsboolean
    Includes supported and required Payment fields
  • include_credentials_fieldsboolean
    Includes credentials fields
  • exclude_inactiveboolean
    Excludes inactive Providers from the list
  • key_ownerstring
    Filters Providers by key owner
    Possible values: client, saltedge
  • modestring
    Filters Providers by mode
    Possible values: web, api, oauth
  • from_idinteger
    The id of the Provider which the list starts with
  • per_pageinteger
    The nr. of Providers to be listed per page

Possible errors:

Error ClassHTTP codeDescription
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/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/v6/providers?include_sandboxes=true&country_code=GB&include_ais_fields=false&include_pis_fields=false&include_credentials_fields=false&exclude_inactive=true&key_owner=saltedge&mode=web&from_id=220&per_page=150
Sample response
{
  "data": [
    {
      "id": "247",
      "code": "hbci_25451345_de",
      "country_code": "DE",
      "bic_codes": [
        "NOLADE21PMT"
      ],
      "dynamic_registration_code": null,
      "identification_codes": [
        "25451345"
      ],
      "group_code": "sparkasse",
      "group_name": "Sparkasse",
      "hub": null,
      "name": "Stadtsparkasse Bad Pyrmont HBCI",
      "status": "active",
      "mode": "api",
      "regulated": false,
      "logo_url": "https://d1uuj3mi6rzwpm.cloudfront.net/logos/providers/de/stadtsparkasse_oberhausen_de.svg",
      "timezone": "Europe/Berlin",
      "supported_iframe_embedding": true,
      "optional_interactivity": true,
      "customer_notified_on_sign_in": false,
      "created_at": "2014-08-21T09:07:38Z",
      "updated_at": "2023-06-29T10:41:25Z"
    },
    {
      "id": "248",
      "code": "hbci_25462680_de",
      "country_code": "DE",
      "bic_codes": [
        "GENODEF1COP"
      ],
      "dynamic_registration_code": null,
      "identification_codes": [
        "25462680"
      ],
      "group_code": "volksbank_raiffeisen",
      "group_name": "Volksbanken Raiffeisenbanken",
      "hub": null,
      "name": "Volksbank am Ith Coppenbrügge HBCI",
      "status": "active",
      "mode": "api",
      "regulated": false,
      "logo_url": "https://d1uuj3mi6rzwpm.cloudfront.net/logos/providers/de/frankfurter_volksbank_de.svg",
      "timezone": "Europe/Berlin",
      "supported_iframe_embedding": true,
      "optional_interactivity": true,
      "customer_notified_on_sign_in": false,
      "created_at": "2014-08-21T09:07:38Z",
      "updated_at": "2023-06-29T10:41:25Z"
    }
  ],
  "meta": {
    "next_id": "249",
    "next_page": "/api/v6/providers?from_id=249"
  }
}

ShowGET

Query Parameters

  • provider_codestringmandatory
    The code assigned by Salt Edge for a particular Provider includes the country code for easier differentiation. I.e.: all Spanish providers' codes end with _es.
  • include_ais_fieldsboolean
    Includes Provider AIS fields
    Default value: false
  • include_pis_fieldsboolean
    Includes supported and required payment fields
    Default value: false
  • include_credentials_fieldsboolean
    Includes supported and required credentials fields
    Default value: false

Possible errors:

Error ClassHTTP codeDescription
ProviderNotFound404A Provider with such a provider_code could not be found
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/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/v6/providers/fake_oauth_client_xf?include_ais_fields=false&include_credentials_fields=false&include_pis_fields=false
Sample response
{
  "data": {
    "id": "3099",
    "code": "fake_oauth_client_xf",
    "country_code": "XF",
    "bic_codes": [],
    "dynamic_registration_code": null,
    "identification_codes": [],
    "group_code": "fake",
    "group_name": "Fake",
    "hub": null,
    "name": "Fake OAuth Bank with Client Keys",
    "status": "active",
    "mode": "oauth",
    "regulated": true,
    "logo_url": "https://d1uuj3mi6rzwpm.cloudfront.net/logos/providers/xf/placeholder_global.svg",
    "timezone": "UTC",
    "supported_iframe_embedding": true,
    "optional_interactivity": true,
    "customer_notified_on_sign_in": false,
    "created_at": "2018-04-12T14:30:29Z",
    "updated_at": "2024-03-06T07:47:56Z"
  }
}

Fake

To assist with testing, a Fake country (with the country code XF) and a set of Fake Providers are provided. If the Client’s application is in the Test or Pending status, the selection of the Fake country and its Providers can be made on the Connect page.


The Account Information API offers several Fake Providers:

Sandboxes

The Sandbox is a live-testing environment provided by Salt Edge, enabling Partners and Clients to test regulated Providers under Salt Edge’s supervision.

To facilitate the testing of regulated Providers, Salt Edge offers a Sandbox environment for some PSD2 Providers - giving the possibility to test different flows. The Sandbox is identified by the term 'Sandbox' in the provider_name (e.g.: Rabobank (Sandbox)), with a designated provider_code containing 'XF' as the country code (e.g.: rabobank_oauth_client_nl_xf).

Similar to Fake Providers, Sandbox Providers can be tested when an application is in Test or Pending status. For Clients in Live status, use include_fake_providers: true. On the Connect page, the selection of the fake country (with the country code XF) and its corresponding Sandbox Providers is allowed.

Authorization instructions are provided under the Instructions field on the Connect page.

Note

Some Sandboxes may not be available indefinitely due to limited support sources for a particular Provider.

Customers

A Customer represents a single end-user of the Client’s/ Partner’s application.
The Client or Partner uses the API to create Connections, i.e. bank Connections, that are further used to aggregate the Customer’s financial data.

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

Diagram

For a more comprehensive description of the terms, please refer to the Glossary.

Note

The id returned from the response needs to be stored in the Client’s application, which is necessary when creating Connections.

Attributes

  • customer_idstring
    The id of the User
  • identifierstring
    The unique external identifier of a Customer (e.g email, id on the Client's side)
  • blocked_atstring (date-time)
    The date & time in UTC when a Customer has been blocked
  • created_atstring (date-time)
    The date & time in UTC when a Customer has been created
  • updated_atstring (date-time)
    The date & time in UTC when a Customer has been updated

CreatePOST

Creates a Customer and returns the Customer object.

Request Body ParametersClient

  • identifierstringmandatory
    A unique identifier of the User assigned by the Client
URL

https://www.saltedge.com/api/v6/customers/{customer_id}

Method

POST

Sample request
curl -v -H "Accept: application/json" \
         -H "Content-type: application/json" \
         -H "App-id: $APP_ID" \
         -H "Secret: $SECRET" \
         -X POST \
         -d "{ \ 
               \"data\": { \
                 \"identifier\": \"example_identifier\" \
               } \
             }" \
         https://www.saltedge.com/api/v6/customers/111111111111111111
Sample response
{
  "data": {
    "customer_id": "111111111111111111",
    "identifier": "example_identifier",
    "blocked_at": null,
    "created_at": "2023-02-08T14:06:41Z",
    "updated_at": "2023-02-08T14:06:41Z"
  }
}

Request Body ParametersPartner

  • emailstringmandatory
  • identifierstring
    A unique identifier of the User assigned by the Client
  • kycobject
    Hide child attributes
    • citizenship_codestring
      Possible values: country code as mentioned in ISO 3166-1 alpha-2
    • date_of_birthstring (date)
    • full_namestring
    • genderstring
      Possible values: male, female, other
    • place_of_birthstring
    • registered_office_codestring
      Possible values: country code as dated in ISO 3166-1 alpha-2
    • registered_office_addressstring
    • registration_numberstring
    • residence_addressstring
    • type_of_accountstring

Possible errors:

Error ClassHTTP codeDescription
DuplicatedCustomer409The User being attempted to be created already exists
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

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

Method

POST

Sample request
curl -v -H "Accept: application/json" \
         -H "Content-type: application/json" \
         -H "App-id: $APP_ID" \
         -H "Secret: $SECRET" \
         -X POST \
         -d "{ \ 
               \"data\": { \
                 \"email\": \"email@email.com\", \
                 \"identifier\": \"example_identifier\", \
                 \"kyc\": { \
                   \"citizenship_code\": \"GB\", \
                   \"date_of_birth\": \"2001-01-01\", \
                   \"full_name\": \"John Doe\", \
                   \"gender\": \"male\", \
                   \"legal_name\": \"Example Company Name\", \
                   \"place_of_birth\": \"London\", \
                   \"registered_office_code\": \"GB\", \
                   \"registered_office_address\": \"London, Independence str, block 5\", \
                   \"registration_number\": \"12345\", \
                   \"residence_address\": \"London, Independence str, block 5\", \
                   \"type_of_account\": \"own\" \
                 } \
               } \
             }" \
         https://www.saltedge.com/api/v6/customers
Sample response
{
  "data": {
    "customer_id": "111111111111111111",
    "identifier": "example_identifier",
    "blocked_at": null,
    "created_at": "2023-02-08T14:06:41Z",
    "updated_at": "2023-02-08T14:06:41Z"
  }
}

ListGET

Returns a list with all the application’s Customers

Query Parameters

  • from_idinteger
    The id of the Customer the list starts with
  • per_pageinteger
    The nr. of Customers to be listed per page

Possible errors

No specific errors

URL

https://www.saltedge.com/api/v6/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/v6/customers?from_id=11111111111111111&per_page=150
Sample response
{
  "data": [
    {
      "customer_id": "1111111111111111111",
      "identifier": "email@email.com",
      "blocked_at": null,
      "created_at": "2021-09-14T15:14:34Z",
      "updated_at": "2021-09-14T15:14:34Z"
    },
    {
      "customer_id": "222222222222222222",
      "identifier": "some_identifier",
      "blocked_at": null,
      "created_at": "2021-09-14T18:04:11Z",
      "updated_at": "2021-09-14T18:04:11Z"
    }
  ]
}

ShowGET

Returns the customer object.

Query Parameters

  • customer_idintegermandatory
    A unique id of the User assigned by Salt Edge

Possible errors:

Error ClassHTTP codeDescription
CustomerNotFound404The User with the provided customer_id does not exist
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/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/v6/customers/111111111111111111
Sample response
{
  "data": {
    "customer_id": "111111111111111111",
    "identifier": "email@email.com",
    "blocked_at": null,
    "created_at": "2023-02-08T14:06:41Z",
    "updated_at": "2023-02-08T14:06:41Z"
  }
}

RemoveDEL

Deletes a Customer and revokes all consents for this Customer.

Query Parameters

  • customer_idintegermandatory
    A unique id of the User assigned by Salt Edge

Possible errors:

Error ClassHTTP codeDescription
CustomerLocked406The User was locked manually in the Dashboard and may be unlocked
CustomerNotFound404The User with the provided customer_id does not exist
URL

https://www.saltedge.com/api/v6/customers/{customer_id}

Method

DELETE

Sample request
curl -v -H "Accept: application/json" \
         -H "Content-type: application/json" \
         -H "App-id: $APP_ID" \
         -H "Secret: $SECRET" \
         -X DELETE \
         https://www.saltedge.com/api/v6/customers/111111111111111111
Sample response
{
  "data": {
    "customer_id": "111111111111111111",
    "deleted": true
  }
}

Connections

A Connection represents a permanent Connection of a specific Customer to a Provider, with a set of credentials required for accessing the Accounts and Transactions.

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

  • Active - the current set of credentials is valid and enables Salt Edge to fetch the data properly;
  • Inactive - an error occurred while fetching the Connection. An inactive Connection cannot be refreshed; thus, it can only be reconnected.
  • Disabled - in case of non-compliance with our Terms of Service, the application’s owner may be contacted, and the Connection(s) may be disabled.
Note

When creating a Connection, it is advisable to check whether the Customer already exists to prevent the creation of duplicate Customers & Connections.

Additionally, creating multiple Connections for the same Customer with the same online banking access credentials is not recommended.

Attributes

Using the AIS Widget session the Client can perform: Connect, Reconnect, or Refresh a User's Connection.

It should be noted that the session will be subject to expiration after 60 seconds of inactivity within the Salt Edge Widget. Upon initiation of the session to redirect the User, the entire authentication and data retrieval process will take approximately 10 minutes. Subsequently, the Customer session will expire.

Note

Exceptions may arise with certain Providers, requiring longer periods for data retrieval, potentially extending the 10-minute timeout.

Before generating a request, it should be ensured that the User exists within the system or is created accordingly.

If the Client Account's status is in Pending mode, attempting to establish a Connection not using a Fake Provider, it will result in a ClientPending error.

Attributes

  • idstring
    The id of the created Connection
  • customer_idstring
    The id of the Customer to which the Connection belongs
  • provider_codestring
    The code assigned by Salt Edge for a particular Provider includes the country code for easier differentiation. I.e.: all Spanish providers' codes end with _es.
  • provider_namestring
    The Provider’s name used to establish the Connection
  • country_codestring
    Country code of the Provider
  • statusstring
    The current status of the Connection
    Possible values: active, inactive, disabled
  • categorizationstring
    The categorization type applied to transactions from this Connection
    Possible values: none, personal, business
  • categorization_vendorstring
    The categorization vendor used for transactions' categorization from this Connection.
    If no categorization is applied, the categorization_vendor is disregarded.
    Possible values: saltedge, fino
  • automatic_refreshboolean
    Whether the refresh is automatically performed for this Connection
  • next_refresh_possible_atstring (date-time)
    Determines when the next refresh will be available. This field may contain a null value if the Connection’s automatic_fetch: false or is already processing.
  • created_atstring (date-time)
    The date and time in UTC when the Connection was created
  • updated_atstring (date-time)
    The date and time in UTC when the Connection was updated
  • last_attemptobject
    Information about the latest executed attempt is provided
  • holder_infoobject
    Information about the holder of this Connection
    Hide child attributes
    • namesarray of strings
      Account holder’s name(s)
    • emailsarray of strings
      Account holder’s email(s)
    • phone_numbersarray of strings
      Account holder’s phone number(s)
    • addressesarray of objects
      Account holder’s address(es):
      Hide child attributes
      • citystring
      • statestring
      • streetstring
      • country_codestring
      • post_codestring
    • extraobject
      Hide child attributes
      • ssnstring
        Social Security Number shortened (last 4 digits)
      • cpfstring
        Cadastro de Pessoas Físicas (specific to Brazil)
      • birth_datestring
        Account holder’s date of birth
      • document_numberstring
        Account holder’s identification number
Note

api_mode: app is available only for Connections initiated via API V5.

ListGET

All Connections accessible to the Client’s application for a specific Customer are returned.
The Connections are sorted in ascending order based on their ID, so the newest Connections will appear last. It is recommended that the entire list of Connections be fetched to check for any changes in properties. More information about the next_id field can be found in the Pagination section.

Query Parameters

  • customer_idintegermandatory
    A unique id of the User assigned by Salt Edge
  • from_idinteger
    The id of the Connection the list starts with
  • per_pageinteger
    The nr. of Connections to be listed per page

Possible errors:

Error ClassHTTP codeDescription
CustomerNotFound404The User with the provided customer_id does not exist
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

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

Method

GET

Sample request
curl -v -H "Accept: application/json" \
         -H "Content-type: application/json" \
         -H "App-id: $APP_ID" \
         -H "Secret: $SECRET" \
         -X GET \
         https://www.saltedge.com/api/v6/connections?customer_id=111111111?from_id=111111111?per_page=120
Sample response
{
  "data": [
    {
      "id": "1111111111111111111",
      "customer_id": "1111111111111111111",
      "provider_code": "fake_oauth_client_xf",
      "provider_name": "Fake OAuth Bank with Client Keys",
      "country_code": "XF",
      "status": "active",
      "categorization": "none",
      "automatic_refresh": true,
      "next_refresh_possible_at": "2024-02-19T06:26:03Z",
      "created_at": "2024-01-03T14:39:58Z",
      "updated_at": "2024-02-19T06:11:03Z",
      "last_consent_id": "1111111111111111111",
      "last_attempt": {
        "id": "1111111111111111111",
        "consent_id": "1111111111111111111",
        "api_version": "6",
        "api_mode": "service",
        "automatic_fetch": true,
        "categorize": false,
        "custom_fields": {},
        "automatic_refresh": true,
        "exclude_accounts": [],
        "fetch_from_date": "2024-02-17",
        "fetch_to_date": "2024-02-19",
        "fetch_scopes": [
          "accounts",
          "balance",
          "transactions"
        ],
        "finished": true,
        "finished_recent": true,
        "include_natures": null,
        "interactive": false,
        "locale": "ro",
        "partial": false,
        "show_consent_confirmation": true,
        "store_credentials": true,
        "user_present": false,
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:121.0) Gecko/20100101 Firefox/121.0",
        "device_type": "desktop",
        "remote_ip": "10.9.9.9",
        "customer_last_logged_at": null,
        "created_at": "2024-02-19T06:10:13Z",
        "updated_at": "2024-02-19T06:11:03Z",
        "success_at": "2024-02-19T06:11:03Z",
        "fail_at": null,
        "fail_error_class": null,
        "fail_message": null,
        "last_stage": {
          "id": "1111111111111111111",
          "name": "finish",
          "created_at": "2024-02-19T06:11:03Z",
          "updated_at": "2024-02-19T06:11:03Z"
        }
      }
    },
    {
      "id": "1111111111111111112",
      "customer_id": "1111111111111111112",
      "provider_code": "fake_oauth_client_xf",
      "provider_name": "Fake OAuth Bank with Client Keys",
      "country_code": "XF",
      "status": "active",
      "categorization": "personal",
      "automatic_refresh": false,
      "next_refresh_possible_at": "2024-01-15T14:10:28Z",
      "created_at": "2024-01-03T14:58:19Z",
      "updated_at": "2024-01-15T13:55:28Z",
      "last_consent_id": "1111111111111111112",
      "last_attempt": {
        "id": "1111111111111111112",
        "consent_id": "1111111111111111112",
        "api_version": "6",
        "api_mode": "service",
        "automatic_fetch": true,
        "categorize": true,
        "custom_fields": {},
        "automatic_refresh": false,
        "exclude_accounts": [],
        "fetch_from_date": "2023-11-16",
        "fetch_to_date": "2024-01-15",
        "fetch_scopes": [
          "accounts",
          "balance",
          "holder_info",
          "transactions"
        ],
        "finished": true,
        "finished_recent": true,
        "include_natures": null,
        "interactive": false,
        "locale": "ro",
        "partial": false,
        "show_consent_confirmation": true,
        "store_credentials": true,
        "user_present": true,
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:120.0) Gecko/20100101 Firefox/120.0",
        "device_type": "desktop",
        "remote_ip": "10.9.9.9",
        "customer_last_logged_at": null,
        "created_at": "2024-01-15T13:55:11Z",
        "updated_at": "2024-01-15T13:55:28Z",
        "success_at": "2024-01-15T13:55:28Z",
        "fail_at": null,
        "fail_error_class": null,
        "fail_message": null,
        "last_stage": {
          "id": "1111111111111111112",
          "name": "finish",
          "created_at": "2024-01-15T13:55:28Z",
          "updated_at": "2024-01-15T13:55:28Z"
        }
      }
    }
  ],
  "meta": {
    "next_id": null,
    "next_page": null
  }
}

ShowGET

A single Connection object containing comprehensive information about the Connection is returned.

Query Parameters

  • connection_idintegermandatory
    The id of the Connection
  • include_holder_infoboolean
    Whether the Connection holder's information should be displayed
    Default value: false

Possible errors:

Error ClassHTTP codeDescription
ConnectionNotFound404The requested connection_id does not match any existing Connections
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/connections/{connection_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/v6/connections/11111111111111
Sample response
{
  "data": {
    "id": "11111111111111",
    "customer_id": "11111111111111",
    "provider_code": "fake_oauth_client_xf",
    "provider_name": "Fake OAuth Bank with Client Keys",
    "country_code": "XF",
    "status": "active",
    "categorization": "personal",
    "categorization_vendor": "saltedge",
    "automatic_refresh": false,
    "next_refresh_possible_at": "2024-01-15T14:10:28Z",
    "created_at": "2024-01-03T14:58:19Z",
    "updated_at": "2024-01-15T13:55:28Z",
    "last_consent_id": "11111111111111",
    "last_attempt": {
      "id": "11111111111111",
      "consent_id": "11111111111111",
      "api_version": "6",
      "api_mode": "service",
      "automatic_fetch": true,
      "categorize": true,
      "custom_fields": {},
      "automatic_refresh": false,
      "exclude_accounts": [],
      "fetch_from_date": "2023-11-16",
      "fetch_to_date": "2024-01-15",
      "fetch_scopes": [
        "accounts",
        "balance",
        "holder_info",
        "transactions"
      ],
      "finished": true,
      "finished_recent": true,
      "include_natures": null,
      "interactive": false,
      "locale": "ro",
      "partial": false,
      "show_consent_confirmation": true,
      "store_credentials": true,
      "user_present": true,
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:120.0) Gecko/20100101 Firefox/120.0",
      "device_type": "desktop",
      "remote_ip": "10.9.9.9",
      "customer_last_logged_at": null,
      "created_at": "2024-01-15T13:55:11Z",
      "updated_at": "2024-01-15T13:55:28Z",
      "success_at": "2024-01-15T13:55:28Z",
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "last_stage": {
        "id": "11111111111111",
        "name": "finish",
        "created_at": "2024-01-15T13:55:28Z",
        "updated_at": "2024-01-15T13:55:28Z"
      }
    }
  }
}

ConnectPOST

Note

Please examine the sequence diagram for details on how Connections/ Connect flow works.

If the User already has a Connection with the same Provider and credentials, initiating a new Connection will perform a reconnect for the existing one.

Relevant for Providers with mode: web and api

Request Body Parameters

  • customer_idstringmandatoryPartner
    A unique id of the User assigned by Salt Edge
  • customer_identifierstring
    A unique id of the User assigned by the Client
    Note
    Clients who own their license should use either customer_id or customer_identifier.
    Partners should use customer_id at all times, whereas customer_identifier is optional.
  • attemptobject
    Hide child attributes
    • fetch_scopesarray of strings
      A list of scopes requested by Clients from the Provider, deriving from the consent_scopes options.
      Possible values: holder_info, accounts, balance, transactions.
      Accounts consent_scopes covers accounts and balance fetch_scopes.
    • fetch_from_datestring (date)
      The starting date for fetching the data
    • fetch_to_datestring (date)
      The ending date for fetching the data
    • account_naturesarray of strings
      Possible values: account, bonus, card, checking, credit, credit_card, debit_card, ewallet, insurance, investment, loan, mortgage, savings
    • custom_fieldsobject
      A JSON object that will be sent back on any of the Client's callbacks
    • localestring
      The language of the Widget and the language of the returned error message(s).
      Possible values: any locale in ISO 639-1 format
    • store_credentialsboolean
      Whether credentials are stored on Salt Edge's side or not.
      Relevant for Providers with mode: web and api
      Default value: true
    • unduplication_strategystring
      The unduplication strategy used for duplicated transactions.
      The provided value remains unchanged until another value is sent during Connections/reconnect or Connections/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_duplicated: removes identified duplicated transactions.

      Possible values: mark_as_pending, mark_as_duplicate, delete_duplicated
      Default value: mark_as_pending
    • return_tostring
      The URL to which the User will be redirected
      Default value: Client's home URL
  • widgetobject
    Hide child attributes
    • show_account_overviewboolean
      Displays information about connected accounts in the Widget
      Default value: false
    • credentials_strategystring
      The strategy for storing the User’s credentials.
      Relevant for Providers with mode: web and api.
      Possible values: store, do_not_store, ask
      Default value: store
    • javascript_callback_typestring
      How the Widget interacts with the opener/ parent window
      Possible values: iframe, post_message
    • skip_provider_selectionboolean
      Enables Users to skip the Provider selection page
      Default value: false
    • skip_stages_screenboolean
      Allows Users to skip the stage screen
      Default value: false
    • templatestring
      Enables Clients to specify the template for the Widget
      Default value: default_v3
    • themestring
      Allows Clients to specify the theme for the Widget
      Possible values: dark, default, light
      Default value: default (according to the User's OS preferences)
    • allowed_countriesarray of strings
      Displays Providers only from specified countries
  • providerobject
    Hide child attributes
    • codestring
      The code of the required Provider
    • include_sandboxesboolean
      Whether to display Sandboxes and Fake Providers in Provider search or not
      Default value: true
    • modesarray of strings
      Restricts the list of Providers to only those that have the mode included in the array
      Possible values: oauth, web, api
  • kycobjectmandatoryPartner
    Hide child attributes
    • type_of_accountstring
      The type of Account to be connected, only for KYC purposes
      Possible values: personal, shared, business
  • return_connection_idboolean
    Appends connection_id to the return_to URL
    Default value: false
  • return_error_classboolean
    Appends error_class to the return_to URL
    Default value: false
  • categorizationstring
    Enables Clients to change the applied categorization type
    Possible values: none, personal, business
    Default value: none
  • categorization_vendorstring
    The categorization vendor used for transactions' categorization.
    If categorization is none then the categorization_vendor is ignored.
    Possible values: saltedge, fino
    Default value: saltedge (if categorization is not none)
  • automatic_refreshboolean
    Allows Clients to enable/ disable automatic refresh
    Default value: false (Client), true (Partner)

Possible errors:

Error ClassHTTP codeDescription
ClientPending406The Client is pending approval. More information about the pending status can be found on the Pending guides page
ClientRestricted406The Client is in restricted status. More information about the restricted status can be found on the Restricted guides page
CustomerLocked406The User was locked manually in the Dashboard and may be unlocked
CustomerNotFound404The User with the provided customer_id does not exist
ProviderDisabled406The accessed Provider has been disabled. Consequently, it is no longer supported.
ProviderInactive406The requested Provider has the inactive status. This means that new Connections cannot be created, while the current ones cannot be refreshed or reconnected.
ProviderKeyNotFound404The Client does not possess a key for the selected Provider
RateLimitExceeded406Too many connections are being processed at the same time from one application
TPPregistration406Issues related to the certificates and/ or app ID have been detected
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/connections/connect

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\": 111111111111, \
                 \"consent\": { \
                   \"scopes\": [ \
                     \"accounts\", \
                     \"holder_info\" \
                   ], \
                   \"from_date\": \"2023-11-05\", \
                   \"to_date\": \"2023-11-20\", \
                   \"period_days\": 15 \
                 }, \
                 \"attempt\": { \
                   \"fetch_scopes\": [ \
                     \"holder_info\", \
                     \"accounts\" \
                   ], \
                   \"fetch_from_date\": \"2023-09-30\", \
                   \"fetch_to_date\": \"2023-10-25\", \
                   \"account_natures\": [ \
                     \"account\", \
                     \"bonus\", \
                     \"card\", \
                     \"checking\" \
                   ], \
                   \"custom_fields\": {}, \
                   \"locale\": \"DE\", \
                   \"store_credentials\": true, \
                   \"unduplication_strategy\": \"delete_duplicated\", \
                   \"return_to\": \"http://example.com\" \
                 }, \
                 \"widget\": { \
                   \"show_account_overview\": true, \
                   \"show_consent_confirmation\": false, \
                   \"credentials_strategy\": \"ask\", \
                   \"javascript_callback_type\": \"iframe\", \
                   \"disable_provider_search\": false, \
                   \"skip_provider_selection\": false, \
                   \"skip_stages_screen\": true, \
                   \"template\": \"default_v3\", \
                   \"theme\": \"default\", \
                   \"allowed_countries\": [ \
                     \"XF\", \
                     \"GB\", \
                     \"DE\" \
                   ], \
                   \"country_code\": [ \
                     \"XF\" \
                   ] \
                 }, \
                 \"provider\": { \
                   \"code\": \"fake_oauth_client_xf\", \
                   \"include_sandboxes\": true, \
                   \"modes\": [ \
                     \"oauth\" \
                   ] \
                 }, \
                 \"kyc\": { \
                   \"type_of _account\": \"personal\" \
                 }, \
                 \"return_connection_id\": false, \
                 \"return_error_class\": true, \
                 \"categorization\": \"personal\", \
                 \"categorization_vendor\": \"saltedge\", \
                 \"automatic_refresh\": true \
               } \
             }" \
         https://www.saltedge.com/api/v6/connections/connect
Sample response
{
  "data": {
    "expires_at": "2024-02-19T17:07:59Z",
    "connect_url": "https://www.saltedge.com/connect?token=78abc19673b5978ec2bed15bc7b395e5f4775ccfbc78ecf45cc41e64a9ac51d46",
    "customer_id": "1111111111111111111111"
  }
}

ReconnectPOST

To reconnect a Connection, the connection id and consent object must be sent by the Client's app.
The Widget object, attempt object, and other parameters could be sent by the Client’s app, to customize the User's experience.

Query Parameters

  • connection_idintegermandatory
    The id of the Connection

Request Body Parameters

  • attemptobject
    Hide child attributes
    • fetch_scopesarray of stringsmandatory
      A list of scopes requested by Clients from the Provider, deriving from the consent_scopes options.
      Possible values: holder_info, accounts, balance, transactions.
      Accounts consent_scopes covers accounts and balance fetch_scopes.
    • fetch_from_datestring (date)
      The starting date for fetching the data
    • fetch_to_datestring (date)
      The ending date for fetching the data
    • account_naturesarray of strings
      Possible values: account, bonus, card, checking, credit, credit_card, debit_card, ewallet, insurance, investment, loan, mortgage, savings
    • exclude_accountsarray of integers
      The IDs of accounts that do not require refreshing
    • custom_fieldsobject
      A JSON object that will be sent back on any of the Client's callbacks
    • localestring
      The language of the Widget and the language of the returned error message(s).
      Possible values: any locale in ISO 639-1 format.
    • store_credentialsboolean
      Whether credentials are stored on Salt Edge's side or not.
      Relevant for Providers with mode: web and api
      Default value: true
    • unduplication_strategystring
      The unduplication strategy used for duplicated transactions.
      The provided value remains unchanged until another value is sent during Connections/reconnect or Connections/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_duplicated: removes identified duplicated transactions.

      Possible values: mark_as_pending, mark_as_duplicate, delete_duplicated
      Default value: mark_as_pending
    • return_tostring
      The URL to which the User will be redirected.
      Default value: Client's home URL
  • widgetobject
    Hide child attributes
    • show_account_overviewboolean
      Displays information about connected accounts in the Widget
      Default value: false
    • credentials_strategystring
      The strategy for storing the User’s credentials.
      Relevant for Providers with mode: web and api.
      Possible values: store, do_not_store, ask
      Default value: store
    • javascript_callback_typestring
      How the Widget interacts with the opener/ parent window
      Possible values: iframe, post_message
    • skip_stages_screenboolean
      Allows Users to skip the stage screen
      Default value: false
    • templatestring
      Enables Clients to specify the template for the Widget
      Default value: default_v3
    • themestring
      Allows Clients to specify the theme for the Widget.
      Possible values: dark, default, light
      Default value: default (according to the User's OS preferences)
  • return_connection_idboolean
    Appends connection_id to the return_to URL
    Default value: false
  • return_error_classboolean
    Appends error_class to the return_to URL
    Default value: false
  • automatic_refreshboolean
    Allows Clients to enable/ disable automatic refresh
    Default value: false (Client), true (Partner)
  • override_credentials_strategystring
    Allows Clients to choose a strategy for credentials:
    ask - the User will be prompted to confirm the credentials override upon submitting the form
    override - new credentials will automatically override the old ones
    Possible values: ask, override

Possible errors:

Error ClassHTTP codeDescription
ActionNotSupported406Action is not supported by active eIDAS Certificate
AllAccountsExcluded406All accounts have been excluded from the Connection fetching process
ClientRestricted406The Client is in restricted status. More information about the restricted status can be found on the Restricted guides page
ConnectionDisabled406Connection, reconnection, or fetching a Connection was attempted by the Client, but it appears to have been disabled
ConnectionNotFound404The requested connection_id does not match any existing Connections
CustomerLocked406The User was locked manually in the Dashboard and may be unlocked
ProviderDisabled406The accessed Provider has been disabled. Consequently, it is no longer supported.
ProviderKeyNotFound404The Client does not possess a key for the selected Provider
RateLimitExceeded406Too many connections are being processed at the same time from one application
TPPregistration406Issues related to the certificates and/ or app ID have been detected
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/connections/{connection_id}/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\": { \
                 \"consent\": { \
                   \"scopes\": [ \
                     \"accounts\", \
                     \"holder_info\" \
                   ], \
                   \"from_date\": \"2023-11-05\", \
                   \"to_date\": \"2023-11-20\", \
                   \"period_days\": 15 \
                 }, \
                 \"attempt\": { \
                   \"fetch_scopes\": [ \
                     \"holder_info\", \
                     \"accounts\" \
                   ], \
                   \"fetch_from_date\": \"2023-09-30\", \
                   \"fetch_to_date\": \"2023-10-25\", \
                   \"account_natures\": [ \
                     \"account\", \
                     \"bonus\", \
                     \"card\", \
                     \"checking\" \
                   ], \
                   \"exclude_accounts\": [ \
                     1111111111111, \
                     22222222222222, \
                     3333333333333 \
                   ], \
                   \"custom_fields\": {}, \
                   \"locale\": \"DE\", \
                   \"store_credentials\": true, \
                   \"unduplication_strategy\": \"delete_duplicated\", \
                   \"return_to\": \"http://example.com\" \
                 }, \
                 \"widget\": { \
                   \"show_account_overview\": true, \
                   \"show_consent_confirmation\": false, \
                   \"credentials_strategy\": \"ask\", \
                   \"javascript_callback_type\": \"iframe\", \
                   \"skip_stages_screen\": true, \
                   \"template\": \"default_v3\", \
                   \"theme\": \"default\" \
                 }, \
                 \"return_connection_id\": false, \
                 \"return_error_class\": true, \
                 \"automatic_refresh\": true, \
                 \"override_credentials_strategy\": \"ask\" \
               } \
             }" \
         https://www.saltedge.com/api/v6/connections/111111111111111/reconnect
Sample response
{
  "data": {
    "expires_at": "2024-02-19T17:07:59Z",
    "connect_url": "https://www.saltedge.com/connect?token=78abc19673b5978ec2bed15bc7b395e5f4775ccfbc78ecf45cc41e64a9ac51d46",
    "customer_id": "1111111111111111111111"
  }
}

RefreshPOST

Enables the triggering of a refetch of the data associated with a specific Connection. It should be noted that a Connection can be refreshed only if it has an active consent. If the response is successful, the next_refresh_possible_at value will be included, and the usual callbacks of the fetching workflow can be expected.

The timing of the automatic refresh per Provider is manually set by Salt Edge, to maintain equal system load throughout the day.

Query Parameters

  • connection_idintegermandatory
    The id of the Connection

Request Body Parameters

  • return_connection_idboolean
    Appends connection_id to the return_to URL
    Default value: false
  • return_error_classboolean
    Appends error_class to the return_to URL
    Default value: false
  • automatic_refreshboolean
    Allows Clients to enable/ disable automatic refresh.
    Default value: the one that was used when the Connection had been created
  • override_credentials_strategystring
    Allows Clients to choose a strategy for credentials:
    ask - the User will be prompted to confirm the credentials override upon submitting the form
    override - new credentials will automatically override the old ones
    Possible values: ask, override
  • show_widgetboolean
    Enables initiating a refresh without having to open the Widget
  • attemptobject
    Hide child attributes
    • fetch_scopesarray of stringsmandatory
      A list of scopes requested by Clients from the Provider, deriving from the consent_scopes options.
      Possible values inside the array: holder_info, accounts, balance, transactions.
      Accounts consent_scopes covers accounts and balance fetch_scopes.
    • fetch_from_datestring (date)
      The starting date for fetching the data
    • fetch_to_datestring (date)
      The ending date for fetching the data
    • account_naturesarray of strings
      Possible values: account, bonus, card, checking, credit, credit_card, debit_card, ewallet, insurance, investment, loan, mortgage, savings
    • exclude_accountsarray of integers
      The IDs of accounts that do not require refreshing
    • custom_fieldsobject
      A JSON object that will be sent back on any of the Client's callbacks
    • localestring
      The language of the Widget and the language of the returned error message(s).
      Possible values: any locale in ISO 639-1 format.
    • unduplication_strategystring
      The unduplication strategy used for duplicated transactions.
      The provided value remains unchanged until another value is sent during Connections/reconnect or Connections/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_duplicated: removes identified duplicated transactions.

      Possible values: mark_as_pending, mark_as_duplicate, delete_duplicated
      Default value: mark_as_pending
    • return_tostring
      The URL to which the User will be redirected
      Default value: Client's home URL
  • widgetobject
    Hide child attributes
    • show_account_overviewboolean
      Displays information about connected accounts in the Widget
      Default value: false
    • javascript_callback_typestring
      How the Widget interacts with the opener/ parent window
      Possible values: iframe, post_message
    • skip_stages_screenboolean
      Allows Users to skip the stage screen
      Default value: false
    • templatestring
      Enables Clients to specify the template for the Widget
      Default value: default_v3
    • themestring
      Allows Clients to specify the theme for the Widget.
      Possible values: dark, default, light
      Default value: default (according to the User's OS preferences)

Possible errors:

Error ClassHTTP codeDescription
AllAccountsExcluded406All accounts have been excluded from the Connection fetching process
ClientRestricted406The Client is in restricted status. More information about the restricted status can be found on the Restricted guides page
ConnectionCannotBeRefreshed406The next refresh attempt will be allowed according to the next_refresh_possible attribute, or if the Connection's status is inactive
ConnectionDisabled406Connection, reconnection, or fetching a Connection was attempted by the Client, but it appears to have been disabled
ConnectionNotFound404The requested connection_id does not match any existing Connections
CustomerLocked406The User was locked manually in the Dashboard and may be unlocked
ProviderDisabled406The accessed Provider has been disabled. Consequently, it is no longer supported.
ProviderKeyNotFound404The Client does not possess a key for the selected Provider
RateLimitExceeded406Too many connections are being processed at the same time from one application
TPPregistration406Issues related to the certificates and/ or app ID have been detected
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/connections/{connection_id}/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\": { \
                 \"return_connection_id\": true, \
                 \"return_error_class\": false, \
                 \"automatic_refresh\": true, \
                 \"show_widget\": false, \
                 \"attempt\": { \
                   \"fetch_scopes\": [ \
                     \"holder_info\", \
                     \"accounts\" \
                   ], \
                   \"fetch_from_date\": \"2023-09-30\", \
                   \"fetch_to_date\": \"2023-10-25\", \
                   \"account_natures\": [ \
                     \"account\", \
                     \"bonus\", \
                     \"card\", \
                     \"checking\" \
                   ], \
                   \"exclude_accounts\": [ \
                     1111111111111, \
                     22222222222222, \
                     3333333333333 \
                   ], \
                   \"custom_fields\": {}, \
                   \"locale\": \"DE\", \
                   \"unduplication_strategy\": \"delete_duplicated\", \
                   \"return_to\": \"http://example.com\" \
                 }, \
                 \"widget\": { \
                   \"show_account_overview\": true, \
                   \"javascript_callback_type\": \"iframe\", \
                   \"skip_stages_screen\": true, \
                   \"template\": \"default_v3\", \
                   \"theme\": \"default\" \
                 } \
               } \
             }" \
         https://www.saltedge.com/api/v6/connections/11111111111111111/refresh
Sample response
{
  "data": {
    "expires_at": "2024-02-19T17:07:59Z",
    "connect_url": "https://www.saltedge.com/connect?token=78abc19673b5978ec2bed15bc7b395e5f4775ccfbc78ecf45cc41e64a9ac51d46",
    "customer_id": "1111111111111111111111"
  }
}

Background RefreshPOST

The triggering of a background refresh of the data associated with a specific Connection without User presence is enabled by calling this endpoint at the Client's convenience as an alternative to Salt Edge's timeslots for automatic refreshes. Subject to automatic refresh limit.

Query Parameters

  • connection_idintegermandatory

Request Body Parameters

  • attemptobject
    Hide child attributes
    • fetch_scopesarray of stringsmandatory
      A list of scopes requested by Clients from the Provider, deriving from the consent_scopes options.
      Possible values inside the array: holder_info, accounts, balance, transactions.
      Accounts consent_scopes covers accounts and balance fetch_scopes.
    • fetch_from_datestring (date)
      The starting date for fetching the data
    • fetch_to_datestring (date)
      The ending date for fetching the data
    • account_naturesarray of strings
      Possible values: account, bonus, card, checking, credit, credit_card, debit_card, ewallet, insurance, investment, loan, mortgage, savings
    • exclude_accountsarray of integers
      The IDs of accounts that do not require refreshing
    • custom_fieldsobject
      A JSON object that will be sent back on any of the Client's callbacks
    • unduplication_strategystring
      The unduplication strategy used for duplicated transactions.
      The provided value remains unchanged until another value is sent during Connections/reconnect or Connections/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_duplicated: removes identified duplicated transactions.

      Possible values: mark_as_pending, mark_as_duplicate, delete_duplicated
      Default value: mark_as_pending
  • automatic_refreshboolean
    Allows Clients to enable/ disable automatic refresh
    Default value: false

Possible errors:

Error ClassHTTP codeDescription
ActionNotAllowed400The Client has no access to the required route
ActionTemporarilyNotAllowed400This action is currently restricted by the Client Account settings. Please contact support to enable the necessary access.
AllAccountsExcluded406All accounts have been excluded from the Connection fetching process
ClientRestricted406The Client is in restricted status. More information about the restricted status can be found on the Restricted guides page
ConnectionCannotBeRefreshed406The next refresh attempt will be allowed according to the next_refresh_possible attribute, or if the Connection's status is inactive
ConnectionNotFound404The requested connection_id does not match any existing Connections
CustomerLocked406The User was locked manually in the Dashboard and may be unlocked
ProviderDisabled406The accessed Provider has been disabled. Consequently, it is no longer supported.
ProviderInactive406The requested Provider has the inactive status. This means that new Connections cannot be created, while the current ones cannot be refreshed or reconnected.
TPPregistration406Issues related to the certificates and/ or app ID have been detected
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/connections/{connection_id}/background_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\": { \
                 \"automatic_refresh\": true, \
                 \"attempt\": { \
                   \"fetch_scopes\": [ \
                     \"holder_info\", \
                     \"accounts\" \
                   ], \
                   \"fetch_from_date\": \"2023-09-30\", \
                   \"fetch_to_date\": \"2023-10-25\", \
                   \"account_natures\": [ \
                     \"account\", \
                     \"bonus\", \
                     \"card\", \
                     \"checking\" \
                   ], \
                   \"exclude_accounts\": [ \
                     1111111111111, \
                     22222222222222, \
                     3333333333333 \
                   ], \
                   \"custom_fields\": {}, \
                   \"unduplication_strategy\": \"delete_duplicated\" \
                 } \
               } \
             }" \
         https://www.saltedge.com/api/v6/connections/1111111111111111111/background_refresh
Sample response
{
  "data": {
    "id": "1111111111111111111",
    "customer_id": "1191191191191191191",
    "provider_code": "fake_oauth_client_xf",
    "provider_name": "Fake OAuth Bank with Client Keys",
    "country_code": "XF",
    "status": "inactive",
    "categorization": "personal",
    "automatic_refresh": true,
    "next_refresh_possible_at": null,
    "created_at": "2024-03-25T13:20:53Z",
    "updated_at": "2024-03-25T13:29:09Z",
    "last_consent_id": "1241241241241241241",
    "last_attempt": {
      "id": "1221122112211221122",
      "consent_id": "1241241241241241241",
      "api_version": "6",
      "api_mode": "service",
      "automatic_fetch": false,
      "categorize": true,
      "custom_fields": {
        "id2": "value",
        "id3": "value",
        "id4": "value"
      },
      "automatic_refresh": true,
      "exclude_accounts": [],
      "fetch_from_date": "2024-01-25",
      "fetch_to_date": "2024-01-25",
      "fetch_scopes": [
        "accounts",
        "holder_info",
        "transactions"
      ],
      "finished": false,
      "finished_recent": false,
      "include_natures": [
        "account"
      ],
      "interactive": false,
      "locale": "en",
      "partial": false,
      "show_consent_confirmation": false,
      "store_credentials": true,
      "user_present": false,
      "user_agent": null,
      "device_type": "desktop",
      "remote_ip": "127.0.0.1",
      "customer_last_logged_at": null,
      "created_at": "2024-03-25T13:29:09Z",
      "updated_at": "2024-03-25T13:29:09Z",
      "success_at": null,
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "last_stage": {
        "id": "1212121212121212121",
        "name": "initialize",
        "created_at": "2024-03-25T13:29:09Z",
        "updated_at": "2024-03-25T13:29:09Z"
      }
    }
  }
}

RemoveDEL

A Connection is removed from the Salt Edge system and the consent is revoked.
All associated accounts and transactions related to that Connection will also be destroyed.
A destroy callback will be sent to the Client’s web application by Salt Edge.
The Client has to make sure that the Destroy URL is specified in its Account, by accessing the callbacks page.

Query Parameters

  • connection_idintegermandatory
    The id of the Connection

Possible errors:

Error ClassHTTP codeDescription
ConnectionNotFound404The requested connection_id does not match any existing Connections
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/connections/{connection_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/v6/connections/11111111111111
Sample response
{
  "data": {
    "id": "11111111111111",
    "removed": true
  }
}

UpdatePUT

An update of the status, store_credentials, automatic_refresh, or categorization associated with a specific Connection can be triggered.

Note

Not all Connections can be automatically updated by Salt Edge, even if the automatic_refresh flag is set to true. In case a particular Provider requires User interaction during the update (such as SMS, OTP, Token, etc.), Salt Edge will not attempt to update it.

Query Parameters

  • connection_idintegermandatory
    The id of the Connection

Request Body Parameters

  • automatic_refreshboolean
    Allows Clients to enable/ disable automatic refresh.
    If no value is sent, the setting remains unchanged
  • categorizationstring
    The applied type of categorization can be changed by Clients. If no value is sent, the setting remains unchanged.
    Possible values: none, personal, business
  • categorization_vendorstring
    The applied categorization vendor used for transactions' categorization can be changed by Clients.
    If categorization is none then the categorization_vendor is ignored.
    Possible values: saltedge, fino
  • statusstring
    The status of the Connection can be changed to inactive by Clients.
    Possible values: inactive
    If no value is sent, the value remains unchanged
  • store_credentialsboolean
    Whether credentials are stored on Salt Edge's side or not.
    Relevant for Providers with mode: web and api.
    Possible values: false
    If no value is sent, the setting remains unchanged

Possible errors:

Error ClassHTTP codeDescription
ActionNotAllowed400The Client has no access to the required route
ConnectionNotFound404The requested connection_id does not match any existing Connections
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/connections/{connection_id}

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 \
         -d "{ \ 
               \"data\": { \
                 \"automatic_refresh\": true, \
                 \"categorization\": \"business\", \
                 \"status\": \"inactive\", \
                 \"store_credentials\": false \
               } \
             }" \
         https://www.saltedge.com/api/v6/connections/1111111111111111111111
Sample response
{
  "data": {
    "id": "11111111111111",
    "customer_id": "11111111111111",
    "provider_code": "fake_oauth_client_xf",
    "provider_name": "Fake OAuth Bank with Client Keys",
    "country_code": "XF",
    "status": "inactive",
    "categorization": "business",
    "categorization_vendor": "saltedge",
    "automatic_refresh": true,
    "next_refresh_possible_at": "2024-01-15T14:10:28Z",
    "created_at": "2024-01-03T14:58:19Z",
    "updated_at": "2024-01-15T13:55:28Z",
    "last_consent_id": "11111111111111",
    "last_attempt": {
      "id": "11111111111111",
      "consent_id": "11111111111111",
      "api_version": "6",
      "api_mode": "service",
      "automatic_fetch": true,
      "categorize": true,
      "custom_fields": {},
      "automatic_refresh": false,
      "exclude_accounts": [],
      "fetch_from_date": "2023-11-16",
      "fetch_to_date": "2024-01-15",
      "fetch_scopes": [
        "accounts",
        "balance",
        "holder_info",
        "transactions"
      ],
      "finished": true,
      "finished_recent": true,
      "include_natures": null,
      "interactive": false,
      "locale": "ro",
      "partial": false,
      "show_consent_confirmation": true,
      "store_credentials": true,
      "user_present": true,
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:120.0) Gecko/20100101 Firefox/120.0",
      "device_type": "desktop",
      "remote_ip": "10.9.9.9",
      "customer_last_logged_at": null,
      "created_at": "2024-01-15T13:55:11Z",
      "updated_at": "2024-01-15T13:55:28Z",
      "success_at": "2024-01-15T13:55:28Z",
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "last_stage": {
        "id": "11111111111111",
        "name": "finish",
        "created_at": "2024-01-15T13:55:28Z",
        "updated_at": "2024-01-15T13:55:28Z"
      }
    }
  }
}

Consents

The consent signifies the end-user granting permission to access their financial data. Access to Accounts, Transactions, and Holder information can be limited or permitted by the User.

The limits of a Consent include:

  • data that is allowed to be accessed;
  • period of time when data can be fetched by Salt Edge;
  • period of time when future data can be retrieved by Salt Edge.

Attributes

  • idstring
    The id of the created Consent
  • connection_idstring
    The id of the Connection to which the consent belongs
  • customer_idstring
    The id of the User who gave the consent
  • statusstring
    The current status of the consent
    Possible values: active, expired, revoked
  • scopesarray of strings
    Data to be allowed for fetching.
    The allowed values for this parameter must fall within the Client’s allowed_fetch_scopes and/ or the Provider's supported_fetch_scopes restrictions.
    Possible values: holder_info, accounts, transactions.
    Accounts covers both accounts and balance fetch_scopes.
  • period_daysinteger
    The duration of consent validity (in days)
  • expires_atstring (date-time)
    The date & time in UTC when the consent expires
  • from_datestring (date)
    Allows to fetch data starting from a specified date
  • to_datestring (date)
    Data can be fetched up until a specified date
  • collected_bystring
    The entity that collects the consent
    Possible values: client, saltedge
  • revoked_atstring (date-time)
    The date & time in UTC when the consent has been revoked
  • revoke_reasonstring
    The reason why the consent has been revoked
    Possible values: expired, client, provider, saltedge
  • created_atstring (date-time)
    The date & time in UTC when the consent has been created
  • updated_atstring (date-time)
    The date & time in UTC when the consent has been updated

ListGET

All the consents accessible to your application for a certain Customer or Connection are returned.
The consents are sorted in ascending order based on their IDs, so the latest consents will appear last.
More information about the next_id field can be found in the Pagination section.

Query Parameters

  • connection_idintegermandatory
    The id of the Connection to which the consent belongs
  • customer_idinteger
    A unique id of the User assigned by Salt Edge to which the consent belongs
  • from_idinteger
    The id of the consent the list starts with
  • per_pageinteger
    The nr. of consents to be listed per page
Note

The usage of connection_id or customer_id is mandatory when used independently.
However, one of them becomes optional when employed in conjunction with another one.

Possible errors:

Error ClassHTTP codeDescription
ConnectionNotFound404The requested connection_id does not match any existing Connections
CustomerNotFound404The User with the provided customer_id does not exist
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/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/v6/consents?connection_id=11111111111111111111111&customer_id=222222222222222222&from_id=33333333333333333&per_page=150
Sample response
{
  "data": [
    {
      "id": "33333333333333333333",
      "connection_id": "111111111111111111",
      "customer_id": "22222222222222222",
      "status": "active",
      "scopes": [
        "accounts",
        "transactions"
      ],
      "period_days": null,
      "expires_at": null,
      "from_date": "2021-06-14",
      "to_date": null,
      "collected_by": "saltedge",
      "revoked_at": null,
      "revoke_reason": null,
      "created_at": "2021-09-14T18:04:37Z",
      "updated_at": "2021-09-14T18:04:37Z"
    },
    {
      "id": "333333333333333334",
      "connection_id": "1111111111111111111",
      "customer_id": "222222222222222222",
      "status": "active",
      "scopes": [
        "accounts",
        "transactions"
      ],
      "period_days": null,
      "expires_at": null,
      "from_date": "2021-06-14",
      "to_date": null,
      "collected_by": "saltedge",
      "revoked_at": null,
      "revoke_reason": null,
      "created_at": "2021-09-14T18:04:37Z",
      "updated_at": "2021-09-14T18:04:37Z"
    }
  ],
  "meta": {
    "next_id": null,
    "next_page": null
  }
}

ShowGET

Returns the consent object.

Query Parameters

  • connection_idintegermandatory
    The id of the Connection to which the consent belongs
  • customer_idinteger
    A unique id of the User assigned by Salt Edge to which the consent belongs
Note

The usage of connection_id or customer_id is mandatory when used independently.
However, one of them becomes optional when employed in conjunction with another one.

Possible errors:

Error ClassHTTP codeDescription
ConnectionNotFound404The requested connection_id does not match any existing Connections
CustomerNotFound404The User with the provided customer_id does not exist
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/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/v6/consents/111111111111111111?connection_id=11111111111111111111111&customer_id=222222222222222222
Sample response
{
  "data": {
    "id": "111111111111111111",
    "connection_id": "2222222222222222222",
    "customer_id": "3333333333333333",
    "status": "active",
    "scopes": [
      "accounts",
      "transactions"
    ],
    "period_days": null,
    "expires_at": null,
    "from_date": "2021-06-14",
    "to_date": null,
    "collected_by": "saltedge",
    "revoked_at": null,
    "revoke_reason": null,
    "created_at": "2021-09-14T18:04:37Z",
    "updated_at": "2021-09-14T18:04:37Z"
  }
}

RevokeClientPUT

Revokes the consent.

Query Parameters

  • connection_idintegermandatory
    The id of the Connection to which the consent belongs
  • customer_idinteger
    A unique id of the User assigned by Salt Edge to which the consent belongs
Note

The usage of connection_id or customer_id is mandatory when used independently.
However, one of them becomes optional when employed in conjunction with another one.

Caution

A Partner can revoke the Consent only by deleting the Connection.

Possible errors:

Error ClassHTTP codeDescription
ConnectionNotFound404The requested connection_id does not match any existing Connections
CustomerNotFound404The User with the provided customer_id does not exist
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/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/v6/consents/111111111111111111/revoke?connection_id=2222222222222222222&customer_id=3333333333333333
Sample response
{
  "data": {
    "id": "111111111111111111",
    "connection_id": "2222222222222222222",
    "customer_id": "3333333333333333",
    "status": "revoked",
    "scopes": [
      "accounts",
      "transactions"
    ],
    "period_days": 90,
    "expires_at": "2024-09-12T13:13:21Z",
    "from_date": "2024-04-14",
    "to_date": null,
    "collected_by": "client",
    "revoked_at": "2024-06-25T13:20:03Z",
    "revoke_reason": "client",
    "created_at": "2024-06-14T13:13:21Z",
    "updated_at": "2024-06-25T13:20:03Z"
  }
}

Attempts

An attempt represents a trial to create or update a Connection in the following endpoints: Connections/ Connect, Reconnect and Refresh - intended to provide the Client with additional information about the established Connection for further usage in technical and statistical purposes.

Information about the last stage of an existing Connection can be retrieved from Connections/ List or Show endpoints.

Attributes

  • idinteger
    The id of the created attempt
  • api_versioninteger
    The API version in which the attempt was created
  • api_modestring
    The API mode of the Customer that queried the API.
    The App mode is a possible value only for Connections initiated via the previous API version.
    Possible values: app, service
  • automatic_fetchboolean
    Whether the Connection related to the attempt can be automatically fetched
  • categorizeboolean
    Whether categorization is applied to transactions fetched during this attempt
  • custom_fieldsobject
    The custom fields sent during attempt creation (any request on /connect, /reconnect or /refresh is considered a new attempt)
  • automatic_refreshboolean
    Whether the refresh is performed automatically for the Connection associated with this attempt
  • exclude_accountsarray of strings
    The IDs of accounts that shall not be refreshed
  • fetch_from_datestring (date)
    The starting date for fetching the data
  • fetch_to_datestring (date)
    The ending date for fetching the data
  • fetch_scopesarray of strings
    A list of scopes deriving from the consent_scopes options.
    Accounts consent_scopes covers accounts and balance fetch_scopes.
    Possible values inside the array: holder_info, accounts, balance, transactions.
  • finishedboolean
    Whether the attempt has finished fetching data
  • finished_recentboolean
    Whether the attempt has successfully started fetching data
  • include_naturesarray of strings
    The accounts' natures that are requested to be fetched
  • interactiveboolean
    Whether the attempt’s Connection has interactive steps in the Salt Edge Widget
  • localestring
    The language used in the Salt Edge Widget.
    Possible values: supported languages in the ISO 639-1 format.
  • partialboolean
    Whether the Connection is partially fetched
  • store_credentialsboolean
    Whether the credentials are stored on the Salt Edge’s side.
    Relevant for Providers with mode: web and api
  • user_presentboolean
    Whether the request is initiated by the User from the Client’s application
  • user_agentstring
    Information transmitted by a web browser or other Client application to a web server, during Attempt
  • device_typestring
    The type of device that created the attempt
    Possible values: mobile, tablet, desktop
  • remote_ipstring
    The IP of the device that created the attempt
  • customer_last_logged_atstring (date-time)
    The date & time when the User was last active in the Client’s application
  • created_atstring (date-time)
    The date & time when the attempt has been created
  • updated_atstring (date-time)
    The date & time when the attempt has been updated
  • success_atstring (date-time)
    The date & time when the attempt has been successfully finished
  • fail_atstring (date-time)
    The date & time when the attempt failed to finish
  • fail_error_classstring
    Class of error why the attempt failed
  • fail_messagestring
    Error message explaining why the attempt failed
  • last_stageobject
    Information about the last stage of the fetching process

Stages

A stage represents a step performed during fetching accounts, transactions, holder_info on Connect, Reconnect, or Refresh endpoints.

  • idinteger
    The id of the stage from the data fetching process
  • namestring
    The title of the stage in the data-fetching process
  • created_atstring (date-time)
    The date & time when the stage of the data fetching process has been created
  • updated_atstring (date-time)
    The date & time when the stage of the data fetching process has been updated

Accounts

One or more Accounts can be associated with any Connection. The Accounts are linked to a currency, ensuring that all transactions within a single Account share the same currency.

At times, the User is permitted by the Provider to have several currencies grouped under the same Account. For instance, if a Debit card supporting three currencies is held by a User, the corresponding Connection will feature three Accounts, each assigned one of the Debit card’s currencies.

Attributes

  • idstring
    The id of the Account
  • connection_idstring
    The id of the Connection the Account belongs to
  • namestring
    The unique name of the Account
  • naturestring
    The type of the Account
    Possible values: account, bonus, card, checking, credit, credit_card, debit_card, ewallet, insurance, investment, loan, mortgage, savings
  • balancenumber (float)
    The latest Account balance
  • currency_codestring
    The currency code of the Account in ISO 4217 format
  • extraobject
    Accounts extra associated with the Account
  • created_atstring (date-time)
    The date and time in UTC when the Account was imported
  • updated_atstring (date-time)
    The date and time in UTC when the Account’s balance has changed or new transactions have been fetched

ListGET

The list of accounts for a Connection that can be viewed is sorted in ascending order based on their IDs, so the newest accounts will appear last. More information about the next_id field can be found in the Pagination section of the documentation.

Query Parameters

  • connection_idintegermandatory
    The id of the Connection
  • customer_idintegermandatory
    A unique id of the User assigned by Salt Edge
  • from_idinteger
    The id of the Account the list starts with
  • per_pageinteger
    The nr. of Accounts to be listed per page
Note

The usage of connection_id or customer_id is mandatory when used independently.
However, one of them becomes optional when employed in conjunction with another one.

Possible errors:

Error ClassHTTP codeDescription
ConnectionNotFound404The requested connection_id does not match any existing Connections
CustomerNotFound404The User with the provided customer_id does not exist
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/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/v6/accounts?connection_id=1111111111111111111111&customer_id=22222222222222222&from_id=3333333333333333&per_page=150
Sample response
{
  "data": [
    {
      "id": "333333333333333333",
      "connection_id": "111111111111111111111",
      "name": "Simple account 1 MasterCard",
      "nature": "card",
      "balance": 2007.9,
      "currency_code": "EUR",
      "extra": {
        "iban": "DE5555555555555555555555",
        "swift": "ABCDEFGH",
        "status": "active",
        "card_type": "master_card",
        "sort_code": "65-43-21",
        "client_name": "John DOE",
        "account_name": "123456",
        "current_date": "2021-09-14",
        "current_time": "18:04:00",
        "account_number": "123456",
        "transactions_count": {
          "posted": 4,
          "pending": 0
        },
        "last_posted_transaction_id": "7777777777777777777"
      },
      "created_at": "2021-09-14T18:04:48Z",
      "updated_at": "2021-09-14T18:04:48Z"
    },
    {
      "id": "3333333333333334",
      "connection_id": "111111111111111111",
      "name": "Simple account 2",
      "nature": "account",
      "balance": 2012.14,
      "currency_code": "USD",
      "extra": {
        "iban": "DE77777777777777",
        "cards": [
          "1234....5678",
          "*8765"
        ],
        "swift": "ABCDEFGJ",
        "status": "active",
        "sort_code": "65-43-22",
        "client_name": "John Doe",
        "account_name": "123457",
        "current_date": "2021-09-14",
        "current_time": "18:04:00",
        "account_number": "123457",
        "transactions_count": {
          "posted": 5,
          "pending": 0
        },
        "last_posted_transaction_id": "444444444444444"
      },
      "created_at": "2021-09-14T18:04:48Z",
      "updated_at": "2021-09-14T18:04:48Z"
    }
  ],
  "meta": {
    "next_id": null,
    "next_page": null
  }
}

Extra

The following object is represented in the extra field of the Account object.

Note

The Provider may or may not choose to send the parameters listed below, depending on data availability.

General accounts extra fields

  • account_namestring
    Changeable title of the Account
  • account_numberstring
    Internal Bank Account Number
  • assetsarray of strings
    An array of crypto codes and their corresponding amounts assigned to the investment Account
  • available_amountnumber
    The available amount in the Account's currency
  • balance_typestring
    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 Provider’s implementation, the Account’s type, country/ region peculiarities, etc. This field serves an informative purpose, typically used to verify balance consistency among Customers of the same Provider or among Providers within the same country.
  • blocked_amountnumber
    The amount currently blocked in the Account’s currency
  • card_networkstring
    The card belonging to a specific financial system
    Possible values: american_express, china_unionpay, diners_club, jcb, maestro, master_card, uatp, visa, mir
  • cardsarray of strings
    A list of masked card numbers linked to the Account
  • holder_namestring
    The name of the individual or entity that owns the Account
  • closing_balancefloat
    Account balance at the end of an accounting period
  • credit_limitnumber
    Maximum amount of money that is allowed to be spent in the Account’s currency
  • current_datestring (date)
    Date of the Provider’s statement generation (applicable to Banks)
  • current_timestring (date-time)
    Time of Provider statement generation (applicable to Banks)
  • expiry_datestring (date)
    Card expiration date
  • ibanstring
    Account’s IBAN
  • bbanstring
    Basic Bank Account Number
  • interest_ratenumber
    The interest rate of the Account as a percentage value
  • interest_typestring
    The type of Account interest associated with the interest_rate
  • floating_interest_rateobject
    Minimum and maximum values of the interest rate
    Hide child attributes
    • min_valuenumber
    • max_valuenumber
  • masked_panstring
    Returns a partially hidden version of the typically 16-digit Primary Account Number (PAN)
  • remaining_paymentsinteger
    The number of remaining payments required to pay off the loan
  • penalty_amountnumber
    The penalty amount
  • next_payment_amountnumber
    Next payment amount for loans or credits
  • next_payment_datestring (date)
    Next payment date for loans or credits
  • open_datestring (date)
    The date when any type of Account or card was opened
  • opening_balancenumber
    Account balance carried forward from the end of one accounting period to the beginning of a new accounting period
  • partialboolean
    Account transactions were either not imported or only partially imported due to an internal error on the Provider’s side
  • provider_account_idstring
    A unique id is assigned by the Provider to identify an Account within its system
  • raw_balancestring
    • The original Account balance response returned by the Provider.
    • It is added only for regulated: true Providers.
    • It is returned only if the separate balances parameter is present in the Provider’s original response.
  • sort_codestring
    Routing number (US)/ BSB code (Australia)/ sort code (UK)
  • statement_cut_datestring (date)
    The date when the current statement transitions to the previous one
  • statusstring
    Shows whether the Account is active, inactive, or unauthorized
  • swiftstring
    Account SWIFT code
  • total_payment_amountnumber
    Total payment amount for loans or credits
  • transactions_countobject
    Number of transactions, categorized by posted and pending
    Hide child attributes
    • postedinteger
    • pendinginteger
  • payment_typestring
    Account payment method
  • cashback_amountnumber
    Accumulated CashBack/ Cash Benefit
  • monthly_total_paymentnumber
    The amount paid to a borrower for a month
  • minimum_paymentnumber
    The lowest amount that can be paid on the credit card to avoid penalties

Investment accounts extra fields

  • investment_amountnumber
    Total amount invested
  • unit_pricefloat
    Price per unit (when used with units)
  • unitsfloat
    Nr of units owned (when used with unit_price)
  • indicative_unit_pricenumber
    Indicative price per unit (when used with units)
  • interest_incomenumber
    Amount of interest income/ profit
  • interest_amountnumber
    Amount of interest in currency
  • profit_amountnumber
    Amount of profit/ loss of the investment Account
  • profit_ratenumber
    Rate of profit/ loss of the investment Account as a percentage value
  • asset_classstring
    Class of investment asset
  • product_typestring
    Type of investment product
  • total_unit_valuenumber
    Total unit value of fundholding
  • fund_holdingsobject
    Fund holdings list with own values such as investment_percentage, balance, bid_price, value, value_date, total_quantity, available_quantity, actual_price, actual_value

Insurance accounts extra fields

  • premium_frequencystring
    Frequency of premium payments
  • policy_statusstring
    Current policy status
  • life_assured_namestring
    Name of the person who is assured
  • premium_amountnumber
    Amount of premium to be paid
  • single_premium_amountnumber
    Amount of single premium to be paid
  • financial_consultantstring
    Name of the financial consultant
  • total_reversionary_bonusnumber
    Accumulated amount of reversionary bonus
  • gross_surrendernumber
    Current gross surrender value
  • guaranteed_gross_surrendernumber
    Guaranteed gross surrender value
  • reversionary_bonus_cash_valuenumber
    Cash value of reversionary bonus
  • owned_policy_amountnumber
    Amount currently owned on policy
  • policy_loan_limitnumber
    Maximum amount of additional Policy Loan
  • policy_converted_to_paid_upnumber
    New assured sum if the Policy is converted to a paid-up
  • paid_up_conversion_reversionary_bonusnumber
    Reversionary bonus amount after policy-to-paid-up conversion
  • policy_componentsobject
    Policy components with own values such as status, amount_assured, amount_premium, start_date, expiry_date, premium_expiry_date, assured_name

Transactions

A movement of funds is represented by a transaction. Various types of transactions, including monetary transfers, withdrawals, and income or expense interchanges, can be represented by any transaction. Transactions are stored in the Accounts of a Connection and are imported from one of the Providers.

Category

The automatic categorization of transactions is facilitated by an algorithm used by the Account Information API. Consequently, upon importing a Connection, all transactions corresponding to the Connection will be assigned to one of the categories. Additionally, an API route is exposed for the Client’s applications to enhance the categorization process based on the behavior of the Users.

Duplicate

While most of the data is imported from the Providers with a thorough check for duplicates, changes in the format of some data by the Providers may result in the return of transactions that have different data but are duplicates for the Users. The duplicate action can be used to inform about duplicates, allowing to take immediate actions.

Attributes

  • idstring
    The id of the transaction
  • account_idstring
    The id of the Account the transaction belongs to
  • duplicatedboolean
    Whether the transaction is a duplicate or not
  • modestring
    Possible values: normal, fee, transfer
  • statusstring
    Possible values: posted, pending
  • made_onstring (date)
    The date when the transaction was made
  • amountnumber
    Transaction’s amount
  • currency_codestring
    Transaction’s currency code
  • descriptionstring
    Transaction’s description
  • categorystring
    Transaction’s category
  • extra
    Extra data associated with the transaction
  • created_atstring (date-time)
    Time and date when the transaction was imported
  • updated_atstring (date-time)
    The last time the transaction’s attributes were changed by the Client

Extra

The following represents the object that is received in the extra field of the transaction object.

Note

The Provider may or may not opt to send the parameters listed below, based on data availability.

  • account_balance_snapshotnumber (float)
    The balance of the Account at the moment when the transaction was imported
  • account_numberstring
    The number of the Account to which the transaction belongs
  • additionalstring
    Additional information is recommended for use in concatenation with the original description, if available
  • asset_amountnumber (float)
    The original transaction amount in asset units
  • asset_codestring
    Asset commonly used abbreviation (Ex.: BTC - Bitcoin, XAU - Gold & Silver index, etc.)
  • categorization_confidencenumber (float)
    A value from 0 to 1 represents the probability that the current category is the correct one
  • check_numberstring
    The payee's transaction check number
  • closing_balancenumber (float)
    The Account balance after the transaction has been imported
  • constant_codestring
    Payment reference for cashless domestic Payments (transfers)
  • convertboolean
    Whether the transaction amount was converted using exchange rates or not
  • customer_category_codestring
    The category that was categorized by the rules created by the Customer
  • customer_category_namestring
    The category that was categorized by the rules created by the Customer
  • exchange_rateobject
    The exchange rate that was applied to the converted transaction
  • idstring
    The transaction's identifier on the Provider’s end (not to be confused with the Salt Edge transaction id)
  • end_to_end_idstring
    A unique identifier set by the merchant, typically used for reconciliation purposes
  • informationstring
    Information regarding the transaction
  • mccstring
    The transaction’s Merchant Category Code
  • merchant_idstring
    The merchant's identifier
  • opening_balancenumber
    The Account balance before the transaction is imported
  • installment_debt_amountnumber
    The amount of installment transactions in the group
  • original_amountnumber
    The native amount of the transaction in the transaction's currency (provided with the original_currency_code)
  • original_categorystring
    The original category of the transaction
  • original_currency_codestring
    The native currency of the transaction (provided with original_amount)
  • original_subcategorystring
    The original subcategory of the transaction
  • payeestring
    The IBAN or Account nr. to whom the money was paid
  • payee_informationstring
    Additional payee information as company/ name/ vendor etc.
  • payerstring
    The IBAN or Account nr. of who paid the money
  • payer_informationstring
    Additional payer information as company/ name/ vendor etc.
  • possible_duplicateboolean
    It is set to true if the current transaction duplicates the amount, made_on, and currency_code of any transaction parsed in a previous attempt
  • posted_by_aspspboolean
    Indicates that the transaction is marked as posted (or booked) by the Provider but has the pending status assigned by Salt Edge due to custom_pendings_period logic.
    A posted transaction is a fully processed and confirmed financial transaction that has been officially recorded in the Account, reflecting the updated balance.
  • posting_datestring (date)
    Date when the transaction appears in the statement
  • posting_timestring
    Time in HH:MM:SS format, representing the time when the transaction appears in the statement
  • record_numberstring
    Bank record number
  • specific_codestring
    Additional identification information for cashless domestic payments (transfers)
  • tagsarray of strings
    User-defined information in the Provider or e-wallet interface, assigned to a transaction record is provided (not category)
  • timestring (time)
    The time when the transaction was made
  • transfer_account_namestring
    The name of the linked Account
  • typestring
    The transaction type
  • unit_pricenumber (float)
    Price per unit (used with units, available for investment accounts nature only)
  • unitsnumber (float)
    Amount of units owned (used with unit_price, available for investment accounts nature only)
  • variable_codestring
    Identifies the tax subject to the Tax Office, used for domestic payments (transfers)

ListGET

The non-duplicated posted transactions of an Account are imported.

To retrieve all the data, information about the next_id field in the Pagination section of the reference should be consulted.

Query Parameters

  • connection_idintegermandatory
    The id of the Connection
  • account_idinteger
    The id of the Account to which transactions belong
  • pendingboolean
    Filters transactions by pending status.
    Possible values: true, false.
    Returns a list of posted transactions if pending: false or parameter not sent.
    Returns a list of pending transactions if pending: true.
    A pending transaction is an action initiated on an Account that has been authorized but not yet fully processed or confirmed by the Provider.
  • duplicatedboolean
    Filters transactions by duplicated value
    Possible values: true, false
  • from_idinteger
    The id of the transaction the list starts with
  • per_pageinteger
    The nr. of transactions to be listed per page
Note

Pending transactions for an Account, although structured similarly to regular transactions, exhibit different behavior. Attributes of pending transactions may be deleted and modified by the Provider. Consequently, upon Connection, Refresh, or Reconnection, existing pending transactions will be removed. Subsequently, a pending transaction may be re-added with a different ID, transitioned to a posted status, or not reappear (e.g., if unconfirmed by the Provider).

It is advised that the app does not depend on pending transactions having a consistent ID, as they may be replaced with similar transactions bearing different IDs. Additionally, it is recommended the app to remove pending transactions for the Account every time transactions are fetched.

Possible errors:

Error ClassHTTP codeDescription
ConnectionNotFound404The requested connection_id does not match any existing Connections
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

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

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/v6/transactions?connection_id=111111111111111111&account_id=222222222222222&duplicated=true&pending=false&from_id=111111111111111111&per_page=250
Sample response
{
  "data": [
    {
      "id": "1111111111111111111",
      "account_id": "2222222222222222222",
      "duplicated": false,
      "mode": "normal",
      "status": "posted",
      "made_on": "2024-01-03",
      "amount": 100,
      "currency_code": "EUR",
      "description": "Sample EUR for transaction on 2024-01-03",
      "category": "uncategorized",
      "extra": {
        "payee": "Sample payee",
        "payer": "Sample payer",
        "payee_information": "Sample payee information",
        "payer_information": "Sample payer information",
        "account_balance_snapshot": 1000,
        "categorization_confidence": null
      },
      "created_at": "2024-01-03T14:40:14Z",
      "updated_at": "2024-01-03T14:40:14Z"
    },
    {
      "id": "2222222222222222222",
      "account_id": "2222222222222222222",
      "duplicated": false,
      "mode": "normal",
      "status": "posted",
      "made_on": "2024-01-03",
      "amount": 100,
      "currency_code": "EUR",
      "description": "Sample EUR for transaction on 2024-01-03",
      "category": "uncategorized",
      "extra": {
        "payee": "Sample payee",
        "payer": "Sample payer",
        "payee_information": "Sample payee information",
        "payer_information": "Sample payer information",
        "account_balance_snapshot": 1000,
        "categorization_confidence": null
      },
      "created_at": "2024-01-03T14:40:14Z",
      "updated_at": "2024-01-03T14:40:14Z"
    }
  ]
}

UpdatePUT

Request Body Parameters

  • connection_idstringmandatory
    id of the Connection to which transactions belong
  • transaction_idsarray of stringsmandatory
    The array of transactions ids for which the update should be made
  • duplicatebooleanmandatory
    Marks the provided transactions as duplicated
    Possible values: true

Possible errors:

Error ClassHTTP codeDescription
ConnectionNotFound404The requested connection_id does not match any existing Connections
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

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

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 \
         -d "{ \ 
               \"data\": { \
                 \"connection_id\": \"1111111111111\", \
                 \"transaction_ids\": [ \
                   \"transaction_id_1\", \
                   \"2222222222222222\", \
                   \"3333333333333333\" \
                 ], \
                 \"duplicate\": true \
               } \
             }" \
         https://www.saltedge.com/api/v6/transactions
Sample response
{
  "data": {
    "duplicated": true,
    "transaction_ids": [
      "transaction_id_1",
      "2222222222222222",
      "3333333333333333"
    ]
  }
}

Currencies

The currency is represented simply as a string, using ISO 4217 currency codes. Thus, all currency codes will have exactly three uppercase letters. If certain currencies are no longer existing, it will still be supported for the transactions held in those currencies and both versions are supported.

For example:

  • Zambian Kwacha ZMK (old currency code)
  • Zambian Kwacha ZMW (new currency code)

Rates

A rate is an index of any currency value in relation to the USD currency. Daily updates are applied to all rates.

Attributes

  • currency_codestring
    The currency code in ISO 4217 three-letter format
  • ratenumber (decimal)
    The currency's ratio compared to the USD currency
  • failboolean
    The field indicates whether the currency rate is up-to-date.
    If true, it means that the rate has been retrieved from the previous available date

ListGET

Returns the list of all supported currency rates that can be obtained.

Query Parameters:

  • datestring (date)
    The currency rate for a specific date is returned
    Possible values: any date in the YYYY-MM-DD format Default_value: current date

Possible errors:

Error ClassHTTP codeDescription
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/rates

Method

GET

Sample request
curl -v -H "Accept: application/json" \
         -H "Content-type: application/json" \
         -H "App-id: $APP_ID" \
         -H "Secret: $SECRET" \
         -X GET \
         https://www.saltedge.com/api/v6/rates?date=2022-01-01
Sample response
{
  "data": [
    {
      "currency_code": "AED",
      "rate": 0.2722652206,
      "fail": false
    },
    {
      "currency_code": "AFN",
      "rate": 0.0135567167,
      "fail": false
    }
  ]
}

Data Enrichment Platform

Salt Edge has developed the Data Enrichment Platform to assist Clients in delivering better products through advanced financial analysis, thereby enhancing User Experience, reducing operational costs, and expanding the Client base. The Data Enrichment Platform comprises the following components:

1. Transaction Categorization & Merchant Identification API:
this component assigns categories and identifies merchants for both personal and business transactions.

2. Financial Insights:
this feature generates reports based on Providers' data using sophisticated algorithms, offering institutions insights into the financial behavior profiles of their potential Customers.

Callbacks

When Standalone Categorization is finished, the Client should receive a callback with the following response:

  {
    "data": {
      "bucket_id": "some_bucket_identifier",
      "status": "completed",
    },
    "meta": {
      "version": "6"
    }
  }

Create BucketPOST

Request Body Parameters

  • customer_idstringmandatory
    id of the User for whom the categorization is performed.
  • bucket_idstringmandatory
    Free-form external reference of the bucket.

Possible errors:

Error ClassHTTP codeDescription
ActionNotAllowed400The Client has no access to the required route
DuplicatedRecord403A duplicate Account or transaction was uploaded to the bucket
InvalidParams400The JSON request contains invalid parameters
InvalidRequestFormatError400The JSON request is incorrectly formed
MissingParams400Missing required parameters for categorization
MissingRequiredFields400Missing required fields for categorization
StandaloneCategorizationError406An error occurred during the categorization
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/categorization/buckets

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\": { \
                 \"bucket_id\": \"some string identifier\", \
                 \"customer_id\": \"existing customer id\" \
               } \
             }" \
         https://www.saltedge.com/api/v6/categorization/buckets
Sample response
{
  "data": {
    "bucket_id": "some string identifier",
    "customer_id": "180",
    "status": "pending"
  }
}

Import AccountsPOST

Request Body Parameters

  • bucket_idstringmandatory
    Free-form external reference of the bucket.
  • accountsarray of objectsmandatory
    Hide child attributes
    • idstringmandatory
      Free-form id of the Account on the Client side.
    • country_codestringmandatory
      ISO country code.
      Possible values: any supported country code.
    • currency_codestringmandatory
      ISO currency code.
      Possible values: any supported currency code
    • naturestring
      Account natures.
      Possible values: account, bonus, card, checking, credit, credit_card, debit_card, ewallet, insurance, investment, loan, mortgage, savings
    • provider_codestring
      The code assigned by Salt Edge for a particular Provider includes the country code for easier differentiation. I.e.: all Spanish providers' codes end with _es.
    • holder_namestring
      Free-form name of the Account holder.
    • extraobject
      Some extra information.

Possible errors:

Error ClassHTTP codeDescription
ActionNotAllowed400The Client has no access to the required route
InvalidParams400The JSON request contains invalid parameters
InvalidRequestFormatError400The JSON request is incorrectly formed
MissingParams400Missing required parameters for categorization
MissingRequiredFields400Missing required fields for categorization
StandaloneCategorizationError406An error occurred during the categorization
TooManyImportObjectsError403The total nr. of accounts/ transactions per bucket has reached the limit
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/categorization/accounts

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\": { \
                 \"bucket_id\": \"some_identifier\", \
                 \"accounts\": [ \
                   { \
                     \"id\": \"some_account_identifier\", \
                     \"country_code\": \"GB\", \
                     \"currency_code\": \"EUR\", \
                     \"nature\": \"account\", \
                     \"provider_code\": \"some_provider_code\", \
                     \"holder_name\": \"Holder Name\", \
                     \"extra\": { \
                       \"some_key\": \"some_value\" \
                     } \
                   }, \
                   { \
                     \"id\": \"some_account_identifier\", \
                     \"country_code\": \"AU\", \
                     \"currency_code\": \"USD\", \
                     \"nature\": \"account\", \
                     \"provider_code\": \"some_provider_code\", \
                     \"holder_name\": \"Holder Name\", \
                     \"extra\": { \
                       \"some_key\": \"some_value\" \
                     } \
                   } \
                 ] \
               } \
             }" \
         https://www.saltedge.com/api/v6/categorization/accounts
Sample response
{
  "data": {
    "imported": 2,
    "failed": [
      {
        "error_messages": [
          "Country code can't be blank",
          "Currency code can't be blank"
        ],
        "account_id": "1234"
      }
    ],
    "duplicates_ignored": 1
  }
}

Import TransactionsPOST

Request Body Parameters

  • bucket_idstringmandatory
    Free-form external reference of the bucket.
  • account_idstringmandatory
    Free-form id of the Account on the Client side.
  • transactionsarray of objectsmandatory
    Hide child attributes
    • idstringmandatory
      Free-form ID of the transaction on the Client side.
    • descriptionstringmandatory
      Description of the transaction.
    • amountfloatmandatory
      Transaction’s amount.
    • mccstringmandatory
      The transaction’s Merchant Category Code.
    • payeestring
      The IBAN or Account nr. to whom the money was paid.
    • payee_informationstring
      Additional payee information as company/ name/ vendor etc.
    • payerstring
      The IBAN or Account nr. who paid the money.
    • payer_informationstring
      Additional payer information as company/ name/ vendor etc.
    • typestring
      Transaction type.
    • actionstring
      The action that should be applied for imported transaction.
      Possible values: learn, categorization
    • categorystring
      Transaction’s category.
    • made_onstring (date)
      The date when the transaction was made in YYYY-MM-DD format.
Note

The category of the transaction must be provided if the action is learn.

Possible errors:

Error ClassHTTP codeDescription
ActionNotAllowed400The Client has no access to the required route
InvalidParams400The JSON request contains invalid parameters
InvalidRequestFormatError400The JSON request is incorrectly formed
MissingParams400Missing required parameters for categorization
MissingRequiredFields400Missing required fields for categorization
StandaloneCategorizationError406An error occurred during the categorization
TooManyImportObjectsError403The total nr. of accounts/ transactions per bucket has reached the limit
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/categorization/transactions

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\": { \
                 \"bucket_id\": \"some_identifier\", \
                 \"account_id\": \"some_account_identifier\", \
                 \"transactions\": [ \
                   { \
                     \"id\": \"some_transaction_identifier\", \
                     \"description\": \"Some transaction description\", \
                     \"amount\": 10.5 \
                   }, \
                   { \
                     \"id\": \"some_transaction_identifier\", \
                     \"description\": \"Some transaction description\", \
                     \"amount\": 10.5, \
                     \"mcc\": \"12495-AS\", \
                     \"payee\": \"some_iban\", \
                     \"payee_information\": \"some name\", \
                     \"payer\": \"some_iban\", \
                     \"payer_information\": \"some name\", \
                     \"type\": \"PMNT-CTFD-10\", \
                     \"action\": \"learn\", \
                     \"category\": \"new_learn_category\", \
                     \"made_on\": \"2022-05-24\" \
                   } \
                 ] \
               } \
             }" \
         https://www.saltedge.com/api/v6/categorization/transactions
Sample response
{
  "data": {
    "imported": 2,
    "failed": [
      {
        "error_messages": [
          "Description can't be blank"
        ],
        "transaction_id": "e3c8805e-8eff-40d4-8ea7-ec923f859894"
      }
    ],
    "duplicates_ignored": 1
  }
}

Start CategorizationPOST

Query Parameters

  • bucket_idstringmandatory
    Free-form external reference of the bucket, unique for each bucket

Request Body Parameters

  • categorization_typestringmandatory
    Type of categorization.
    Possible values: personal, business
  • categorization_vendorstringmandatory
    Vendor for categorization.
    Possible values: saltedge, fino

Possible errors:

Error ClassHTTP codeDescription
ActionNotAllowed400The Client has no access to the required route
EnrichmentError500An error occurred during the categorization
InvalidParams400The JSON request contains invalid parameters
InvalidRequestFormatError400The JSON request is incorrectly formed
MissingParams400Missing required parameters for categorization
MissingRequiredFields400Missing required fields for categorization
StandaloneCategorizationError406An error occurred during the categorization
TooManyImportObjectsError403The total nr. of accounts/ transactions per bucket has reached the limit
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/categorization/buckets/{bucket_id}/categorize

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\": { \
                 \"categorization_type\": \"personal\", \
                 \"categorization_vendor\": \"saltedge\" \
               } \
             }" \
         https://www.saltedge.com/api/v6/categorization/buckets/11111111111111/categorize
Sample response
{
  "data": {
    "status": "processing",
    "customer_id": 180
  }
}

Categorized TransactionsGET

Query Parameters

  • bucket_idstringmandatory
    Free-form external reference of the bucket, unique for each bucket
  • customer_idintegermandatory
    id of customer
  • uniqueboolean
    Returns only unique accounts (latest entries) or all entries from
    Default value: false
  • account_idstring
    The id of the Account
  • from_idinteger
    The id of the Account the list starts with
  • per_pageinteger
    The nr. of Accounts to be listed per page

Possible errors:

Error ClassHTTP codeDescription
ActionNotAllowed400The Client has no access to the required route
InvalidParams400The JSON request contains invalid parameters
InvalidRequestFormatError400The JSON request is incorrectly formed
MissingParams400Missing required parameters for categorization
MissingRequiredFields400Missing required fields for categorization
StandaloneCategorizationError406An error occurred during the categorization
TooManyImportObjectsError403The total nr. of accounts/ transactions per bucket has reached the limit
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/categorization/transactions

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/v6/categorization/transactions?bucket_id=1111111111111111&customer_id=180
Sample response
{
  "data": [
    {
      "transaction_id": "aef5f584-a7f0-40b4-97f0-77606a4b23f3",
      "description": "lorem ipsum",
      "amount": 12.09,
      "mcc": "12495-AS",
      "payee": "some iban",
      "payee_information": "some name",
      "payer": "some iban",
      "payer_information": "some name",
      "type": "PMNT-CTRG-12",
      "category": "custom_category",
      "made_on": "2022-05-24"
    },
    {
      "transaction_id": "6925f584-41f0-40b4-81de-77606a4b23f3",
      "amount": -120,
      "mcc": "12725-AS",
      "description": "lorem ipsum",
      "payee": "some iban",
      "payee_information": "some name",
      "payer": "some iban",
      "payer_information": "some name",
      "type": "PMNT-CTFD-10",
      "made_on": "2022-05-24"
    }
  ],
  "meta": {
    "next_id": "6925f584-41f0-40b4-81de-77606a4b23f4",
    "next_page": "api/v6/categorization/transactions?per_page=1000from_id=6925f584-41f0-40b4-81de-77606a4b23f4"
  }
}

Identification

A merchant is represented as a company that sells goods or provides services to a Customer.

​​Merchant identification is an option that enables the identification of merchant names and other pertinent information based on transaction data. This option is country-based and is currently available for the following countries:

Europe

  • Austria
  • Belgium
  • Croatia
  • Czech Republic
  • Estonia
  • France
  • Germany
  • Hungary
  • Italy
  • Latvia
  • Lithuania
  • Luxembourg
  • Netherlands
  • Poland
  • Portugal
  • Republic of Ireland
  • Romania
  • Russia
  • SlovakiaNew
  • Slovenia
  • Spain
  • United Kingdom

Middle East

  • BahrainNew
  • Israel
  • Turkey
  • Saudi Arabia
  • United Arab Emirates

Africa

  • South AfricaNew

Asia

  • Hong Kong
  • India
  • Indonesia
  • Malaysia
  • Philippines
  • Singapore

Australia/ Oceania

  • Australia
  • New Zealand

North America

  • Mexico

South America

  • Brazil

Attributes

  • idstring
    The id of the merchant
  • namesarray of objects
    Merchant names are utilized to identify a company, corporation, brand, franchise name, or any other entity involved in the User’s transaction
    Hide child attributes
    • modestring
      Possible values: name, transliterated_name, alternative_name, brand, operator
    • valuestring
      It will contain values according to the mode. For example: if the mode is name, then the value will contain the name of the merchant.
  • addressobject
    The following location parameters may be included in the merchant's address:
    city, transliterated_city, state, street, transliterated_street, country_code, post_code, coordinates, and extra data associated with the address, such as building_name, shop_number, etc."
  • contactarray of objects
    Contact information through which the merchant can be accessed, such as via website, phone, or social media
    Hide child attributes
    • modestring
      Possible values: email, viber, phone, fax, website, facebook, twitter, google_plus, linkedin, instagram, skype, vk, flickr, youtube
    • valuestring
      It will contain values according to the mode. For example: if the mode is email, then the value will include the email of the merchant.

ShowPOST

To retrieve the name and additional information available for identified merchants, the required merchant_ids should be passed in an array to the route https://www.saltedge.com/api/v6/merchants.

It should be noted that the primary objective of this feature is to identify the merchant name, which is why arrays with the name and transliterated_name are always provided.

Sometimes, additional information about the merchant, such as shop_number or the address of the sale point with city, post_code, and street_number can be found in the transaction's descriptional fields. In such cases, it is possible to pinpoint the exact location where the User’s transaction occurred.

If a corresponding Point of Sale for the transaction is available in our database, more detailed information including contact and address details, along with geo-coordinates, can be returned.

Note

The API accepts batches of at most 100 objects.

Request Body Parameters

  • merchant_idsarray of stringsmandatory
    An array of merchants' UUIDs.

Possible errors:

Error ClassHTTP codeDescription
ActionNotAllowed400The Client has no access to the required route
InvalidParams400The JSON request contains invalid parameters
InvalidRequestFormatError400The JSON request is incorrectly formed
MissingParams400Missing required parameters for categorization
MissingRequiredFields400Missing required fields for categorization
RecordNotFound404An entity with the sent id could not be found
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/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\": { \
                 \"merchant_ids\": [ \
                   \"A_64_characters_string\", \
                   \"fqtrwtqerqeycbc7cce2f4571b632bb096f6663b2895b3177339797dcc0ba8d3\", \
                   \"f6dabf8bb3e1cbc7ccq8736265452gb096f6663b2895b3177339797dcc0ba8d3\" \
                 ] \
               } \
             }" \
         https://www.saltedge.com/api/v6/merchants
Sample response
{
  "data": [
    {
      "id": "392aca001402afbdc23cee3d2f09152d190b05df41f0e75249b8b0126e6c1333",
      "names": [
        {
          "mode": "name",
          "value": "Apple"
        },
        {
          "mode": "transliterated_name",
          "value": "apple"
        }
      ],
      "contact": [
        {
          "mode": "website",
          "value": "http://www.applepharmacy.co.uk/"
        }
      ],
      "address": {
        "country_code": "GB"
      }
    },
    {
      "id": "f6dabf8bb3e1cbc7cce2f4571b632bb096f6663b2895b3177339797dcc0ba8d3",
      "names": [
        {
          "mode": "name",
          "value": "Amazon"
        },
        {
          "mode": "transliterated_name",
          "value": "amazon"
        }
      ],
      "contact": [
        {
          "mode": "website",
          "value": "www.amazon.com"
        },
        {
          "mode": "website",
          "value": "www.amazon.co.uk"
        },
        {
          "mode": "website",
          "value": "www.amazon.uk.com"
        }
      ],
      "address": {
        "country_code": "GB"
      }
    }
  ]
}

Customer RulesGET

Query Parameters

  • customer_idintegermandatory
    id of the customer for which the categorization is done

Possible errors:

Error ClassHTTP codeDescription
ActionNotAllowed400The Client has no access to the required route
InvalidParams400The JSON request contains invalid parameters
InvalidRequestFormatError400The JSON request is incorrectly formed
MissingParams400Missing required parameters for categorization
MissingRequiredFields400Missing required fields for categorization
RecordNotFound404An entity with the sent id could not be found
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/categorization/customer_rules

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/v6/categorization/customer_rules?customer_id=111111111111111
Sample response
{
  "data": [
    {
      "rule": "some test description",
      "category_name": "pet supplies"
    },
    {
      "rule": "some other test description",
      "category_name": "allowance"
    }
  ],
  "meta": {
    "next_id": null,
    "next_page": null
  }
}

Show BucketGET

Query Parameters

  • bucket_idstringmandatory
    Free-form external reference of the bucket, unique for each one

Possible errors:

Error ClassHTTP codeDescription
ActionNotAllowed400The Client has no access to the required route
InvalidParams400The JSON request contains invalid parameters
InvalidRequestFormatError400The JSON request is incorrectly formed
MissingParams400Missing required parameters for categorization
RecordNotFound404An entity with the sent id could not be found
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/categorization/buckets/{bucket_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/v6/categorization/buckets/bcd9b2a4-4e19-4385-985f-e3ff86c1eaa8
Sample response
{
  "data": {
    "bucket_id": "808be4c9-a4e6-41f0-81de-fd183b7347cc",
    "status": "processing",
    "customer_id": 180,
    "mode": "test"
  }
}

Remove BucketDEL

Query Parameters

  • bucket_idstringmandatory
    Free-form external reference of the bucket, unique for each one

Possible errors:

Error ClassHTTP codeDescription
ActionNotAllowed400The Client has no access to the required route
InvalidParams400The JSON request contains invalid parameters
InvalidRequestFormatError400The JSON request is incorrectly formed
MissingParams400Missing required parameters for categorization
RecordNotFound404An entity with the sent id could not be found
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/categorization/buckets/{bucket_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/v6/categorization/buckets/bcd9b2a4-4e19-4385-985f-e3ff86c1eaa8
Sample response
{
  "data": {
    "bucket_id": "bcd9b2a4-4e19-4385-985f-e3ff86c1eaa8",
    "deleted": "true"
  }
}

List AccountsGET

Query Parameters

  • bucket_idstringmandatory
    Free-form external reference of the bucket, unique for each bucket
  • customer_idintegermandatory
    id of the customer for which the categorization is done
  • from_idinteger
    The id of the Account the list starts with
  • per_pageinteger
    The nr. of Accounts to be listed per page
Note

Although customer_id and bucket_id are both optional, one of them is required to be sent in the request.

Possible errors:

Error ClassHTTP codeDescription
ActionNotAllowed400The Client has no access to the required route
InvalidParams400The JSON request contains invalid parameters
InvalidRequestFormatError400The JSON request is incorrectly formed
MissingParams400Missing required parameters for categorization
MissingRequiredFields400Missing required fields for categorization
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/categorization/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/v6/categorization/accounts?bucket_id=714143be-b24d-4771-8a85-3819df97205e&customer_id=1170415646270294289&per_page=100&from_id=6925f584-41f0-40b4-81de-77606a4b23f4
Sample response
{
  "data": [
    {
      "bucket_id": "714143be-b24d-4771-8a85-3819df97205e",
      "account_id": "029d224e-f629-48c4-bd45-46e1a6a1e59a",
      "customer_id": 1170415646270294300,
      "country_code": "GB",
      "currency_code": "EUR",
      "nature": "account",
      "provider_code": "some_provider_code",
      "holder_name": "Holder Name",
      "external_id": null,
      "extra": {
        "some_key": "some_value"
      }
    },
    {
      "bucket_id": "714143be-b24d-4771-8a85-3819df97205e",
      "account_id": "28f304b2-a47e-424d-8152-9fee87964bc5",
      "customer_id": 1170415646270294300,
      "country_code": "GB",
      "currency_code": "EUR",
      "nature": "account",
      "provider_code": "some_provider_code",
      "holder_name": "Holder Name",
      "external_id": null,
      "extra": {
        "some_key": "some_value"
      }
    },
    {
      "bucket_id": "714143be-b24d-4771-8a85-3819df97205e",
      "account_id": "6596bb4e-3708-478a-b1f5-b917d1680016",
      "customer_id": 1170415646270294300,
      "country_code": "GB",
      "currency_code": "EUR",
      "nature": "account",
      "provider_code": "some_provider_code",
      "holder_name": "Holder Name",
      "external_id": null,
      "extra": {
        "some_key": "some_value"
      }
    }
  ],
  "meta": {
    "next_id": "6925f584-41f0-40b4-81de-77606a4b23f4",
    "next_page": "api/v6/categorization/accounts?per_page=1000&from_id=6925f584-41f0-40b4-81de-77606a4b23f4&customer_id=1170415646270294289"
  }
}

Remove AccountDEL

Query Parameters

  • account_idstringmandatory
    The id of the Account.
  • bucket_idstring
    Free-form external reference of the bucket, unique for each bucket
  • customer_idintegermandatory
    id of the customer for which the categorization is done

Possible errors:

Error ClassHTTP codeDescription
ActionNotAllowed400The Client has no access to the required route
InvalidParams400The JSON request contains invalid parameters
InvalidRequestFormatError400The JSON request is incorrectly formed
MissingParams400Missing required parameters for categorization
MissingRequiredFields400Missing required fields for categorization
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/categorization/accounts/{{account_id}}?bucket_id=a{{bucket_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/v6/categorization/accounts/6596bb4e-3708-478a-b1f5-b917d1680016?bucket_id=14143be-b24d-4771-8a85-3819df97205e
Sample response
{
  "data": {
    "bucket_id": "14143be-b24d-4771-8a85-3819df97205e",
    "deleted": "true"
  }
}

ListGET

The list of all supported categories can be obtained.

Multiple categories can be returned by the API for any operation, each with its own meaning.

There are two types of categories:

  • Personal category
  • Business category

Possible errors

No specific errors

URL

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

List by typeGET

Query Parameters

  • categorystringmandatory
    Categories type
    Possible values: personal, business

Possible errors

No specific errors

URL

https://www.saltedge.com/api/v6/categories{category}

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/v6/categories/personal
Sample response
{
  "data": {
    "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": []
    }
  }
}

LearnPOST

If the category of the transaction has changed, the Learn endpoint provides the possibility to update the category and improve the categorization accuracy.

If the category is changed to an already existing one from the categories list, in this case, the new category will be located in the transaction's extras as customer_category_code. If the category is changed to a new custom one, it will be applied only to the User’s new transactions with similar descriptions. The custom category will be located in the transaction's extras as customer_category_name.

Personal Categories

Personal categories include:

  • auto_and_transport
    Used for transactions, related to cars and other modes of transport
    Hide child attributes
    • car_rental
      Carsharing, car rentals, bicycle rentals
    • gas_and_fuel
      Filling stations, gas, fuels, lubricants
    • parking
      Parking spaces; parking apps
    • public_transportation
      Public transportation of passengers; bus lines, train, metro
    • service_and_parts
      Automotive parts and accessories; car wash, car repairs; vulcanizations
    • taxi
      Taxicabs; limousines; taxi apps
  • bills_and_utilities
    Refers to the set of utility services
    Hide child attributes
    • internet
      Internet bills; services of internet providers
    • phone
      Cell phone, landline phone bills
    • television
      Cable, satellite and other television services
    • utilities
      Water, electricity, natural gas, heating, garbage disposal
  • business_services
    Implies miscellaneous services for business, as accounting, consulting, marketing, legal, design
    Hide child attributes
    • advertising
      Outdoor adverstising; digital ads; social media marketing
    • office_supplies
      Stationery, office supplies, printing paper
    • shipping
      Logistics and delivery; courier services
  • education
    Applied for transactions with colleges, universities, schools, learning centers
    Hide child attributes
    • books_and_supplies
      Books, periodicals, eBook apps, e-readers
    • student_loan
      Student loans
    • tuition
      Tuition grants and scholarships; tuition fees
  • entertainment
    Includes entertainment activities, as visits of aquariums, dolphinariums, zoos, museums, theaters
    Hide child attributes
    • amusement
      Amusement parks
    • arts
      Art dealers, art galleries
    • games
      Video games, gambling, betting, casinos, lotteries
    • movies_and_music
      Movie streaming services, audio streaming platforms, radio, cinemas and music festivals
    • newspapers_and_magazines
      Newspapers, magazines and their distributors
  • fees_and_charges
    Covers fees and charges
    Hide child attributes
    • loans
      Money lending
    • provider_fee
      Banking fees
    • service_fee
      Photo studio services; laundry; repairs and restoration
    • taxes
      Different types of taxes, as income taxes, property taxes
  • food_and_dining
    Applied for transactions related to food and beverage products, dining, catering
    Hide child attributes
    • alcohol_and_bars
      Alcohol sellers, bars, pubs, nightclubs
    • cafes_and_restaurants
      Cafes, restaurants, pizzerias, canteens, steakhouses, gelaterias, trattorias
    • groceries
      Grocery stores, supermarkets
  • gifts_and_donations
    Refers to gifts and donations
    Hide child attributes
    • charity
      Donations, charitable services
    • gifts
      Greetings cards, gift and souvenir shops
  • health_and_fitness
    Covers goods and services for the maintenance or improvement of health and well-being
    Hide child attributes
    • doctor
      Hospitals; dental clinics; medical services
    • personal_care
      Personal hygiene and beautification
    • pharmacy
      Drugstores products, medicaments
    • sports
      Sportclubs, gyms, fitness centers, swimming pools
    • wellness
      Beauty spas; hair services; nail salons; massage parlors
  • home
    Applied for household goods, services for building or maintenance of houses
    Hide child attributes
    • home_improvement
      Furniture, interior design services, improvements to outdoor structures
    • home_services
      Home maintenance and repair, cleaning, laundry, ironing
    • home_supplies
      Building materials, household hardware, cookware, domestic appliances
    • mortgage
      Real estate purchases, estate sale, mortgage loans
    • rent
      Property rentals
  • income
    Covers different types of earnings
    Hide child attributes
    • bonus
      Bonuses, rewards, cashback
    • investment_income
      Capital gains, dividends, interest
    • paycheck
      Salaries, wages
  • insurance
    Implies deals with insurance companies
    Hide child attributes
    • car_insurance
      Insurance for cars, trucks, motorcycles, and other road vehicles
    • health_insurance
      Health insurance medical plans
    • life_insurance
      Life insurance
    • property_insurance
      Fire, theft and some weather damage property insurance
  • kids
    Includes various child care activities
    Hide child attributes
    • allowance
      Child allowance
    • babysitter_and_daycare
      Babysitting, kids daycare services
    • baby_supplies
      Baby products, baby food
    • child_support
      Child support
    • kids_activities
      Amusement parks for kids, theme parks for kids
    • toys
      Different types of toys
  • pets
    Refers to pet stores, animal care
    Hide child attributes
    • pet_food_and_supplies
      Products and food for pets
    • pet_grooming
      Pet grooming services
    • veterinary
      Pet health care including veterinary clinics, pharmacies
  • shopping
    Covers shopping malls, e-commerce marketplaces, retail of particular goods
    Hide child attributes
    • clothing
      Clothing, shoes, jewelry, sunglasses
    • electronics_and_software
      Electronics, software, hardware, computers
    • sporting_goods
      Equipment that completes the sport, as gym clothing, motorcycle gear
  • transfer
    Includes money transfers; ATM cash withdrawals
  • travel
    Covers travelling, travel agencies, tourism, excursions
    Hide child attributes
    • hotel
      Accommodation, hotels, motels, resorts
    • transportation
      Air transportation, yachts
    • vacation
      Holiday companies, specific trips or journies
  • uncategorized
    The category of the transaction could not be identified

Business Categories

Business categories include:

  • equipment_and_materials
    Refers to equipment and materials, used by a company
    Hide child attributes
    • consumer_goods
      Various consumer goods
    • electronics
      Electronics intended for use in offices
    • raw_materials
      Raw materials, as wood, textil, glass, plastic
    • software
      Any software or set of computer programs
    • supplies_and_furniture
      Office supplies, stationery, office furniture
  • financials
    Covers company's financial operations
    Hide child attributes
    • dividends
      Sums of money paid by companies to their shareholders
    • donations
      Gifts made to a nonprofit organization, charity, private foundation
    • fees
      Financial institutions fees
    • fines
      Local council fines, traffic offences, other offences
    • interest
      Interests paid or received
    • loans
      Money lending
  • human_resources
    Used for transactions, linked to human resources issues
    Hide child attributes
    • bonus
      Bonuses, rewards added to wages for good performance
    • education_and_trainings
      Training providers, educational institutions, learning centers, learning apps
    • employee_benefits
      Various types of non-wage compensation provided to employees
    • entertainment
      Team buildings, corporate events
    • meals
      Catering, drinking water, dining
    • staff_outsourcing
      Outsourcing of specialists from different domains: manufacturing, HR, accounting, developers; project-based outsourcing
    • travel
      Air tickets, hotels
    • wages
      Paychecks, wages
  • income
    Covers different types of income
    Hide child attributes
    • investments
      Money investments to investment funds, saving deposits, mutual funds
    • prepayments
      Advance payments
    • returns
      Sales returns, online orders returns
    • sales
      Sales income
  • insurance
    Implies deals with insurance companies
    Hide child attributes
    • business_insurance
      Business insurance; business interruption insurance
    • equipment_insurance
      Inventory insurance, furniture insurance, tools insurance
    • health_insurance
      Health insurance medical plans
    • liability_insurance
      Liability insurance
    • professional_insurance
      Professional liability insurance policies, civil liability insurance
    • vehicle_insurance
      Insurance for cars, trucks, motorcycles, and other road vehicles
  • real_estate
    Covers deals with real estate, as sales or rental of property
    Hide child attributes
    • construction_and_repair
      Construction; repair of facilities, reconstruction, restoration
    • mortgage
      Mortgage loans
    • office_rent
      Rental of a property used for business purposes
  • services
    Implies miscellaneous services for business
    Hide child attributes
    • accounting_and_auditing
      Accounting, auditing, bookkeeping services
    • cleaning
      Cleaning, maintenance, sanitation services
    • consulting
      Consulting services
    • contractors
      Services delivered by contractors
    • it_services
      Services in IT domain, web design, app development
    • marketing_and_media
      Marketing and media services; advertising
    • online_subscriptions
      Online subscriptions, web hosting, data storage
    • storage
      Warehousing services; goods storage
  • taxes
    Covers different types of taxes
    Hide child attributes
    • duty_taxes
      Duty taxes; taxes on imported goods
    • federal_taxes
      Federal taxes; estate tax, gift tax
    • income_taxes
      Income taxes
    • payroll_taxes
      Social Security tax; taxes for medicare
    • property_taxes
      Property taxes; land property tax
    • tax_return
      Tax return
    • vat
      Value added tax
  • transport
    Used for transactions, related to cars and other modes of transport
    Hide child attributes
    • gas_and_fuel
      Filling stations, gas, fuels, lubricants
    • leasing
      Operational or financial leasing of transport
    • service_and_parts
      Automotive parts and accessories; car wash, car repairs; vulcanizations
    • shipping
      Motor freight carriers; logistics; delivery; courier services
    • taxi
      Taxicabs; limousines; taxi apps
  • uncategorized
    The category of the transaction could not be identified
  • utilities
    Refers to the set of utility services and includes subcategories:
    Hide child attributes
    • electricity
      Electricity, energy supplies
    • gas
      Natural Gas supplies
    • internet
      Internet bills; services of internet providers
    • phone
      Cell phone, landline phone bills
    • water
      Water supplies

Request Body Parameters

  • customer_idstringmandatory
    The User’s id for which the new category is to be applied
  • transactionsobjectmandatory
    Hide child attributes
    • idintegermandatory
      The transaction id for which to apply the new category
    • category_codestringmandatory
      The new category code of the transaction
    • immediateboolean
      If set to false, the learning threshold of the Salt Edge categorizer will be applied. The categorizer will store information about the User's custom category for the transaction with this description.
      If the categorizer identifies that the category has been updated 3 times for the transaction with this description, further transactions with this description will be automatically categorized for this User under this category.
      If set to true, the learning threshold of the categorizer will be ignored, and further transactions with the same description will be classified under the category chosen by the User.
      Possible values: true, false
      Default value: false

Possible errors:

Error ClassHTTP codeDescription
CustomerLocked406The User was locked manually in the Dashboard and may be unlocked
CustomerNotFound404The User with the provided customer_id does not exist
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/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\": \"11111111111111111\", \
                 \"transactions\": [ \
                   { \
                     \"id\": \"11111111111111111\", \
                     \"category_code\": \"paycheck\", \
                     \"immediate\": true \
                   }, \
                   { \
                     \"id\": \"22222222222222222\", \
                     \"category_code\": \"car_rental\", \
                     \"immediate\": false \
                   } \
                 ] \
               } \
             }" \
         https://www.saltedge.com/api/v6/categories/learn
Sample response
{
  "data": {
    "learned": true
  }
}

Financial Insights

A report based on all the activities of a single Customer is represented by Financial Insights. It analyzes all the unique accounts of the Customer's Connections to the Providers for a selected period.

The Financial Insights report is provided as an additional service. Please reach out to the Sales team to discuss the use case and receive a quote.

Financial Insights reports are stored in the Client Dashboard and can be accessed for 1 week.

Callbacks

Whenever the Financial Insights Report is successfully generated, a callback will be received by the Client’s application.

Insights

Here’s an example of Successful report callback sent to the Financial Insights route of the Client’s app:

  {
    "data": {
      "report_id": "12345",
      "status": "success",
      "customer_id": "222222222222222222"
    },
    "meta": {
      "version": "6",
      "time": "2022-06-27T10:09:26.141Z"
    }
  }

Attributes

  • idstring
    The id of the general report generated based on the User’s data
  • customer_idstring
    The id of the User for whom the report has been requested
  • customer_identifierstring
    The unique identifier for the User for whom the report has been requested
  • statusstring
    Current report’s status
    Possible values: initialized, calculating, success, failed
  • connection_idsarray of integers
    List of Connections for which to generate the report
    Default value: all existing Connections for the given User
  • include_account_naturesarray of strings
    Accounts with specified Account natures are included in the report
    Possible values: account, bonus, card, checking, credit, credit_card, debit_card, ewallet, insurance, investment, loan, mortgage, savings
  • currency_codestring
    The main currency code used for the generation of the report and conversion of values
  • from_datestring (date)
    The date from which the data included in the report starts
  • to_datestring (date)
    The date to which the data included in the report extends
  • report_typesarray of strings
    Types of reports
    Possible values: balance, expense, income, savings, expense_categories, income_categories, inbound_transfers, outbound_transfers
  • dataobject
    Contains a Report Object
  • created_atstring (date-time)
    The date when the report was created
  • updated_atstring (date-time)
    The date when the report was last updated

CreatePOST

Allows Clients to generate a report for a User within a specific date range.

Note

The report might take some time to complete; this can be tracked by the status attribute.

Request Body Parameters

  • customer_idintegermandatory
    The id of the User for whom the report has been requested
  • report_typesarray of stringsmandatory
    Types of reports that can be generated
    Possible values: balance, expense, income, savings, expense_categories, income_categories, inbound_transfers, outbound_transfers
  • currency_codestringmandatory
    The currency to which the data should be converted
    Possible values: ISO 4217 currency codes
  • from_datestring (date)mandatory
    The starting date for the report's date range
  • to_datestring (date)mandatory
    The end date for the report's date range
  • include_account_naturesarray of strings
    Accounts with specified Account natures are included in the report
    Possible values: account, bonus, card, checking, credit, credit_card, debit_card, ewallet, insurance, investment, loan, mortgage, savings
  • connection_idsarray of integers
    List of Connections for which the report is to be generated
    Default value: all existing Connections for the given User

Possible errors:

Error ClassHTTP codeDescription
ActionNotAllowed400The Client has no access to the required route
WrongReportType400We have received a wrong report type
URL

https://www.saltedge.com/api/v6/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\": \"111111111111111\", \
                 \"report_types\": [ \
                   \"balance\", \
                   \"expense\" \
                 ], \
                 \"currency_code\": \"EUR\", \
                 \"from_date\": \"2023-03-01\", \
                 \"to_date\": \"2023-04-01\", \
                 \"include_account_natures\": [ \
                   \"account\", \
                   \"bonus\" \
                 ], \
                 \"connection_ids\": [ \
                   \"111111111111111\", \
                   \"222222222222222\", \
                   \"333333333333333\" \
                 ] \
               } \
             }" \
         https://www.saltedge.com/api/v6/reports
Sample response
{
  "data": {
    "id": "111111111111111",
    "customer_id": "222222222222222",
    "customer_identifier": "some_customer_identifier",
    "connection_ids": [
      "3333333333333333",
      "4444444444444444444"
    ],
    "status": "initialized",
    "currency_code": "EUR",
    "from_date": "2024-01-01",
    "to_date": "2024-01-31",
    "report_types": [
      "balance",
      "expense",
      "income"
    ],
    "include_account_natures": [
      "account",
      "bonus",
      "card"
    ],
    "created_at": "2024-01-01",
    "updated_at": "2024-01-01",
    "data": {}
  }
}

ListGET

Returns all the currently available general reports for a User.

Query Parameters

  • customer_idintegermandatory
    The id of the User for whom the report has been requested
  • from_idinteger
    The id of the report with which the list starts
  • per_pageinteger
    The number of reports to be displayed per page, in the response

Possible errors:

Error ClassHTTP codeDescription
ActionNotAllowed400The Client has no access to the required route
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/reports

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/v6/reports?customer_id=1111111111&from_id=11111111111&per_page=250
Sample response
{
  "data": [
    {
      "id": "111111111111111",
      "customer_id": "222222222222222",
      "customer_identifier": "some_customer_identifier",
      "connection_ids": [
        "3333333333333333",
        "4444444444444444444"
      ],
      "status": "initialized",
      "currency_code": "EUR",
      "from_date": "2024-01-01",
      "to_date": "2024-01-31",
      "report_types": [
        "balance",
        "expense",
        "income"
      ],
      "include_account_natures": [
        "account",
        "bonus",
        "card"
      ],
      "created_at": "2024-01-01",
      "updated_at": "2024-01-01",
      "data": {}
    }
  ],
  "meta": {
    "next_id": null,
    "next_page": null
  }
}

ShowGET

Displays the generated report with all the related details.

Note

The report can also be downloaded in PDF format via the API by setting the Accept header to application/pdf.

Query Parameters

  • report_idintegermandatory
    The id of the general report generated based on the User's data
  • customer_idintegermandatory
    The id of the User for whom the report has been requested

Possible errors:

Error ClassHTTP codeDescription
ActionNotAllowed400The Client has no access to the required route
ReportExpired406The report's storage time ended, and it was deleted
ReportFetchError406The report could not be retrieved
ReportNotFound404A report with the provided report_id could not be found
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/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/v6/reports/111111111111?customer_id=111111111111111
Sample response
{
  "data": {
    "id": "111111111111111",
    "customer_id": "222222222222222",
    "customer_identifier": "some_customer_identifier",
    "connection_ids": [
      "3333333333333333",
      "4444444444444444444"
    ],
    "status": "initialized",
    "currency_code": "EUR",
    "from_date": "2024-01-01",
    "to_date": "2024-01-31",
    "report_types": [
      "balance",
      "expense",
      "income"
    ],
    "include_account_natures": [
      "account",
      "bonus",
      "card"
    ],
    "created_at": "2024-01-01",
    "updated_at": "2024-01-01",
    "data": {}
  }
}

RemoveDEL

Removes a report.

Parameters

  • report_idstringmandatory
    The id of the general report

Possible errors:

Error ClassHTTP codeDescription
ClientDisabled406The Client’s Account has been disabled
ClientNotFound404The API key used in the request does not correspond to a registered Client
ReportNotFound404A report with the provided report_id could not be found
WrongRequestFormat400Some parameters or the entire JSON request are in the wrong format
URL

https://www.saltedge.com/api/v6/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/v6/reports/111111111111
Sample response
{
  "data": {
    "id": "509574324735183486",
    "deleted": true
  }
}

Report Object

  • resultobject
    Report result
    Hide child attributes
  • customer_idstring
    The id of the customer
  • connection_idsarray 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.
  • connectionsarray of objects
    Information related to connections included in report
    Hide child attributes
    • idstring
      The id of the connection
    • customer_idstring
      The id of the customer
    • provider_codestring
      The code assigned by Salt Edge for a particular Provider includes the country code for easier differentiation. I.e.: all Spanish providers' codes end with _es.
    • provider_namestring
      The name of the Provider the connection belongs to
    • accountsarray of objects
      Information related to accounts, which belong to this connection
      Hide child attributes
      • idstring
        The id of the Account
      • namestring
        The unique name of the Account
      • naturestring
        The type of the Account
        Possible values: account, bonus, card, checking, credit, credit_card, debit_card, ewallet, insurance, investment, loan, mortgage, savings
      • balancenumber
        The Account's current balance in currency used for report's generation
      • original_balancenumber
        The Account's current balance in Account's original currency
      • original_currency_codestring
        The Account's original currency code
      • transactionsobject
        Transactions related information
        Hide child attributes
        • start_datestring (date)
          The date of the first transaction
        • end_datestring (date)
          The date of the last transaction
        • first_idstring
          The id of the first transaction
        • last_idstring
          The id of the last transaction
        • countinteger
          Total number of transactions
    • holder_infoobject
      Essential information about the Account holder fetched from the connected Provider
    • client_namestring
      Name of the Salt Edge Client, who requested the Financial Insights report
  • currency_codestring
    Main currency code used for report's generation and value conversion
  • exchange_ratesobject
    A list of exchange rates at the time of report creation
  • report_idinteger
    The id of the generated report
  • report_typesarray of strings
    Types of generated reports
  • statusstring
    Current report's status
    Possible values: initialized, calculating, success, failed
  • from_datestring (date)
    The date from which the data in the report are included
  • to_datestring (date)
    The date to which the data in the report are 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": {}
    }
  }
}

Balance Report Object

  • start_date_amountnumber
    Opening balance. The balance before the first transaction was imported
  • end_date_amountnumber
    Closing balance. The balance after the last transaction was imported
  • minimumnumber
    The minimum balance registered for the report's date range
  • maximumnumber
    The maximum balance registered for the report's date range
  • averageobject
    Average balance
    Hide child attributes
    • dailyobject
      Daily average balance
      Hide child attributes
      • amountnumber
        Average balance amount
      • start_datestring (date)
        The date of the first transaction within the date range used for daily average balance calculation
      • end_datestring (date)
        The date of the last transaction within the date range used for daily average balance calculation
    • daily_per_monthobject
      Daily average balance calculated per each month
      Hide child attributes
      • amountnumber
        Average balance amount
      • is_whole_monthboolean (date)
        Will be true if the whole month is covered by the report
      • yearinteger
        Year that the calculation was made for
      • monthinteger
        Month that the calculation was made for
    • monthlyobject
      Monthly average balance
      Hide child attributes
      • amountnumber
        Average balance amount
      • start_datestring (date)
        The date of the first transaction within the date range used for monthly average balance calculation
      • end_datestring (date)
        The date of the last transaction within the date range used for monthly average balance calculation
    • minimum_monthlyobject
      Minimum monthly average balance
      Hide child attributes
      • amountnumber
        Average balance amount
      • start_datestring (date)
        The date of the first transaction within the date range used for monthly average balance calculation
      • end_datestring (date)
        The date of the last transaction within the date range used for monthly average balance calculation
    • maximum_monthlyobject
      Maximum monthly average balance
      Hide child attributes
      • amountnumber
        Average balance amount
      • start_datestring (date)
        The date of the first transaction within the date range used for monthly average balance calculation
      • end_datestring (date)
        The date of the last transaction within the date range used for monthly average balance calculation
    • quarterlyobject
      Quarterly average balance
      Hide child attributes
      • amountnumber
        Average balance amount
      • start_datestring (date)
        The date of the first transaction within the date range used for quarterly average balance calculation
      • end_datestring (date)
        The date of the last transaction within the date range used for quarterly average balance calculation
    • annualobject
      Annual average balance
      Hide child attributes
      • amountnumber
        Average balance amount
      • start_datestring (date)
        The date of the first transaction within the date range used for annual average balance calculation
      • end_datestring (date)
        The date of the last transaction within the date range used for annual average balance calculation
  • forecasted_averageobject
    Forecasted average balance
    Hide child attributes
    • next_monthnumber
      Forecasted average balance for the next calendar month
    • next_quarternumber
      Forecasted average balance for the next 3 calendar months
    • next_yearnumber
      Forecasted average balance for the next 12 calendar months
Sample object
{
  "start_date_amount": 1150,
  "end_date_amount": 6412,
  "minimum": 1000,
  "maximum": 9341,
  "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

  • start_datestring (date)
    The date of the first income/expense transaction
  • end_datestring (date)
    The date of the last income/expense transaction
  • transactions_countinteger
    Number of income/expense transactions
  • last_year_amountnumber
    Total amount of income/expense for the last fully covered 12 months
  • totalnumber
    Total amount of income/expense per the calculated period
  • total_per_montharray of objects
    Total amount of income/expense per each month
    Hide child attributes
    • yearinteger
      Year that the calculation was made for
    • monthinteger
      Month that the calculation was made for
    • is_whole_monthboolean
      Will be true if the whole month is covered by the report
    • amountnumber
      Amount of income/expense per specified month and year
    • countinteger
      Number of income/expense transactions per a specified month and year
  • averageobject
    Average amount of income/expense
    Hide child attributes
    • monthlynumber
      Monthly average amount of income/expense
    • quarterlynumber
      Quarterly average amount of income/expense
    • annualnumber
      Annual average amount of income/expense
  • forecasted_averageobject
    Forecasted average amount of income/expense
    Hide child attributes
    • next_monthnumber
      Forecasted average amount of income/expense for the next calendar month
    • next_quarternumber
      Forecasted average amount of income/expense for the next 3 calendar months
    • next_yearnumber
      Forecasted average amount of income/expense for the next 12 calendar months
  • streamsobject
    Information on income/expense a customer receives/spends on a regular/irregular basis
    Hide child attributes
    • regular_amountnumber
      The total amount of regular income/expense
    • irregular_amountnumber
      The total amount of irregular income/expense
    • countobject
      Number of income/expense streams
      Hide child attributes
      • regularinteger
        Number of regular income/expense streams
      • irregularinteger
        Number of irregular income/expense streams
        Note
        The number always equals to 1, because the irregular stream contains all the irregular transactions, which have not become a part of any regular stream, as they are not consistent, regular and periodic.
      • maximum_overlappinginteger
        Maximum number of regular overlapping streams at the same time
    • regulararray of objects
      Regular income/expense stream
      Hide child attributes
      • transactions_countinteger
        Number of transactions, which belong to the stream
      • transaction_idsarray of strings
        ids of transactions, which belong to the stream
      • start_datestring (date)
        The date of the first transaction from the stream
      • end_datestring (date)
        The date of the last transaction from the stream
      • amountobject
        Information related to the amounts of regular income/expense, which belong to the stream
        Hide child attributes
        • totalnumber
          Total stream income/expense
        • averagenumber
          Average stream income/expense
        • mediannumber
          Median stream income/expense
        • stdevnumber
          Standard deviation of the stream income/expense
      • frequencystring
        Average period of time between two transactions in the stream
        Possible values: daily, 3_times_a_week, twice_a_week, weekly, 3_times_a_month, every_2_weeks, monthly, every_2_months, quarterly, 3_times_a_year, 2_times_a_year, annual, few_years
      • days_countinteger
        Average number of days between two transactions in the stream
      • category_codestring
        Category of transactions which belong to the stream
      • descriptionstring
        Transaction's description common for the stream
      • merchantobject
        Merchant common for the stream
        Hide child attributes
        • namestring
          Merchant's name
        • emailstring
          Merchant's email address
        • phonestring
          Merchant's phone
        • addressstring
          Merchant's address
        • websitestring
          Merchant's website
    • irregularobject
      Irregular income/expense stream
      Hide child attributes
      • transactions_countinteger
        Number of transactions, which belong to the stream
      • transaction_idsarray of strings
        ids of transactions, which belong to the stream
      • start_datestring (date)
        The date of the first transaction from the stream
      • end_datestring (date)
        The date of the last transaction from the stream
Sample object
{
  "start_date": "2021-01-02",
  "end_date": "2021-04-03",
  "transactions_count": 9,
  "last_year_amount": null,
  "total": 17100,
  "total_per_month": [
    {
      "year": 2021,
      "month": 1,
      "is_whole_month": true,
      "amount": 4100,
      "count": 3
    },
    {
      "year": 2021,
      "month": 2,
      "is_whole_month": true,
      "amount": 4300,
      "count": 3
    },
    {
      "year": 2021,
      "month": 3,
      "is_whole_month": true,
      "amount": 4350,
      "count": 2
    },
    {
      "year": 2021,
      "month": 4,
      "is_whole_month": false,
      "amount": 4350,
      "count": 1
    }
  ],
  "average": {
    "monthly": 4250,
    "quarterly": null,
    "annual": null
  },
  "forecasted_average": {
    "next_month": 4500,
    "next_quarter": null,
    "next_year": null
  },
  "streams": {
    "regular_amount": 16800,
    "irregular_amount": 300,
    "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,
          "average": 4125,
          "median": 4125,
          "stdev": 182
        },
        "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,
          "average": 100,
          "median": 100,
          "stdev": 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

  • totalnumber
    Total amount of savings per the calculated period
  • per_montharray of objects
    Information related to net savings per each month
    Hide child attributes
    • yearinteger
      Year that the calculation was made for
    • monthinteger
      Month that the calculation was made for
    • is_whole_monthboolean
      Will be true if the whole month is covered by the report
    • amountnumber
      Amount of net savings per specified month and year
  • averageobject
    Average savings
    Hide child attributes
    • monthlynumber
      Monthly average savings
    • quarterlynumber
      Quarterly average savings
    • annualnumber
      Annual average savings
  • forecasted_averageobject
    Forecasted average savings
    Hide child attributes
    • next_monthnumber
      Forecasted average savings for the next calendar month
    • next_quarternumber
      Forecasted average savings for the next 3 calendar months
    • next_yearnumber
      Forecasted average savings for the next 12 calendar months
  • runwaynumber
    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_ratenumber
    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_runwaynumber
    Provides an estimate (number of months) on how long the current balance will be sufficient to cover the customer's regular expenses in case income unexpectedly stops.
    Note
    This indicator is calculated for all cases, except the one, when the customer has no expenses.
  • income_stabilitynumber
    Average weighted stability of income from all the sources
    Note
    It is close to 1, if customer has stable income.
  • income_regularitynumber
    Average weighted regularity of income from all the sources
    Note
    It is close to 1, if customer has regular income.
  • income_to_expense_ratenumber
    Ratio of average monthly income to average monthly expense
Sample object
{
  "total": 5262,
  "per_month": [
    {
      "year": 2021,
      "month": 1,
      "is_whole_month": true,
      "amount": 430
    },
    {
      "year": 2021,
      "month": 2,
      "is_whole_month": true,
      "amount": 1955
    },
    {
      "year": 2021,
      "month": 3,
      "is_whole_month": true,
      "amount": 1730
    },
    {
      "year": 2021,
      "month": 4,
      "is_whole_month": false,
      "amount": 1147
    }
  ],
  "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

  • categoriesarray of objects
    Information on expense categories a customer spends money on
    Note
    Outbound transfers are not considered.
    Hide child attributes
    • categorystring
      The category of expense
    • amountnumber
      Total amount of the expense per specified category per the calculated period
    • averagenumber
      Average amount of the expense per specified category per the calculated period
    • amounts_per_montharray of objects
      Amount of the expense per specified category calculated per each month
      Hide child attributes
      • monthstring
        Month and year that the calculation was made for
      • amountnumber
        Amount of the expense per specified category per month
Sample object
{
  "categories": [
    {
      "category": "Education",
      "amount": -3000,
      "average": -1000,
      "amounts_per_month": [
        {
          "month": "2021-01",
          "amount": -1000
        },
        {
          "month": "2021-02",
          "amount": -1000
        },
        {
          "month": "2021-03",
          "amount": -1000
        },
        {
          "month": "2021-04",
          "amount": 0
        }
      ]
    },
    {
      "category": "Utilities",
      "amount": -1980,
      "average": -493.33,
      "amounts_per_month": [
        {
          "month": "2021-01",
          "amount": -500
        },
        {
          "month": "2021-02",
          "amount": -550
        },
        {
          "month": "2021-03",
          "amount": -430
        },
        {
          "month": "2021-04",
          "amount": -500
        }
      ]
    },
    {
      "category": "Shopping",
      "amount": -1915,
      "average": -155,
      "amounts_per_month": [
        {
          "month": "2021-01",
          "amount": -200
        },
        {
          "month": "2021-02",
          "amount": -165
        },
        {
          "month": "2021-03",
          "amount": -100
        },
        {
          "month": "2021-04",
          "amount": -1450
        }
      ]
    },
    {
      "category": "Home improvement",
      "amount": -1206,
      "average": -300,
      "amounts_per_month": [
        {
          "month": "2021-01",
          "amount": -300
        },
        {
          "month": "2021-02",
          "amount": -300
        },
        {
          "month": "2021-03",
          "amount": -300
        },
        {
          "month": "2021-04",
          "amount": -306
        }
      ]
    },
    {
      "category": "Service and parts",
      "amount": -1100,
      "average": -200,
      "amounts_per_month": [
        {
          "month": "2021-01",
          "amount": -600
        },
        {
          "month": "2021-02",
          "amount": 0
        },
        {
          "month": "2021-03",
          "amount": 0
        },
        {
          "month": "2021-04",
          "amount": -500
        }
      ]
    },
    {
      "category": "Other categories",
      "amount": -2585,
      "average": -730,
      "amounts_per_month": [
        {
          "month": "2021-01",
          "amount": -1070
        },
        {
          "month": "2021-02",
          "amount": -330
        },
        {
          "month": "2021-03",
          "amount": -790
        },
        {
          "month": "2021-04",
          "amount": -395
        }
      ]
    }
  ]
}

Income Categories Report Object

  • streamsarray 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.
    Hide child attributes
    • regular_amountnumber
      The total amount of regular income
    • irregular_amountnumber
      The total amount of irregular income
    • countobject
      Number of income streams
      Hide child attributes
      • regularinteger
        Number of regular income streams
      • irregularinteger
        Number of irregular income streams
        Note
        The number always equals to 1, because the irregular stream contains all the irregular transactions, which have not become a part of any regular stream, as they are not consistent, regular and periodic.
    • regulararray of objects
      Regular income stream
      Hide child attributes
      • transaction_countinteger
        Number of transactions, which belong to the stream
      • transaction_idsarray of strings
        Ids of transactions, which belong to the stream
      • start_datestring (date)
        The date of the first transaction from the stream
      • end_datestring (date)
        The date of the last transaction from the stream
      • amountobject
        Information related to the amounts of regular income, which belong to the stream
        Hide child attributes
        • totalnumber
          Total stream income
        • averagenumber
          Average stream income
        • mediannumber
          Median stream income
        • stdevnumber
          Standard deviation of the stream income
      • amounts_per_montharray of objects
        Information on what amount of stream income has been received each month
        Hide child attributes
        • yearinteger
          Year that the calculation was made for
        • monthinteger
          Month that the calculation was made for
        • amountnumber
          Amount of the stream income per the specified month and year
      • frequencystring
        Average period of time between two transactions in the stream
        Possible values: daily, 3_times_a_week, twice_a_week, weekly, 3_times_a_month, every_2_weeks, monthly, every_2_months, quarterly, 3_times_a_year, 2_times_a_year, annual, few_years
      • days_countinteger
        Average number of days between two transactions in the stream
      • category_codestring
        Category of transactions which belong to the stream
      • descriptionstring
        Transaction’s description common for the stream
      • merchantobject
        Merchant common for the stream
        Hide child attributes
        • namestring
          Merchant’s name
        • emailstring
          Merchant’s email address
        • phonestring
          Merchant’s phone
        • addressstring
          Merchant’s address
        • websitestring
          Merchant’s website
    • irregularobject
      Irregular income stream
      Hide child attributes
      • transaction_countinteger
        Number of transactions, which belong to the stream
      • transaction_idsarray of strings
        Ids of transactions, which belong to the stream
      • start_datestring (date)
        The date of the first transaction from the stream
      • end_datestring (date)
        The date of the last transaction from the stream
      • amounts_per_montharray of objects
        Amount of irregular income per month
        Hide child attributes
        • yearinteger
          Year that the calculation was made for
        • monthinteger
          Month that the calculation was made for
        • amountnumber
          Amount of irregular income per the specified month and year
      • averagenumber
        Average amount of irregular income
Sample object
{
  "streams": {
    "regular_amount": 16500,
    "irregular_amount": 300,
    "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,
          "average": 4125,
          "median": 4125,
          "stdev": 182
        },
        "amounts_per_month": [
          {
            "year": 2021,
            "month": 1,
            "amount": 3900
          },
          {
            "year": 2021,
            "month": 2,
            "amount": 4000
          },
          {
            "year": 2021,
            "month": 3,
            "amount": 4250
          },
          {
            "year": 2021,
            "month": 4,
            "amount": 4350
          }
        ],
        "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
        },
        {
          "year": 2021,
          "month": 2,
          "amount": 200
        },
        {
          "year": 2021,
          "month": 3,
          "amount": 0
        },
        {
          "year": 2021,
          "month": 4,
          "amount": 0
        }
      ],
      "average": 100
    }
  }
}

Inbound Transfers Report Object

  • streamsarray of objects
    Information on the transfers a customer receives on a regular/irregular basis
    Note
    All transfers incoming from one Account to another are considered as inbound transfers, no matter if those accounts belong to the same customer or different.
    Hide child attributes
    • regular_amountnumber
      The total amount of regular transfers
    • irregular_amountnumber
      The total amount of irregular transfers
    • countobject
      Number of inbound transfers streams
      Hide child attributes
      • regularinteger
        Number of regular streams
      • irregularinteger
        Number of irregular streams
        Note
        The number always equals to 1, because the irregular stream contains all the irregular transactions, which have not become a part of any regular stream, as they are not consistent, regular and periodic.
    • regulararray of objects
      Regular inbound transfers stream
      Hide child attributes
      • transaction_countinteger
        Number of transactions, which belong to the stream
      • transaction_idsarray of strings
        Ids of transactions, which belong to the stream
      • start_datestring (date)
        The date of the first transaction from the stream
      • end_datestring (date)
        The date of the last transaction from the stream
      • amountobject
        Information related to the amounts of regular transfers, which belong to the stream
        Hide child attributes
        • totalnumber
          Total stream amount
        • averagenumber
          Average stream amount
        • mediannumber
          Median stream amount
        • stdevnumber
          Standard deviation of the stream amount
      • amounts_per_montharray of objects
        Information on what amount of stream related transfers has been received each month
        Hide child attributes
        • yearinteger
          Year that the calculation was made for
        • monthinteger
          Month that the calculation was made for
        • amountnumber
          Amount of stream related transfers per specified month and year
      • frequencystring
        Average period of time between two transactions in the stream
        Possible values: daily, 3_times_a_week, twice_a_week, weekly, 3_times_a_month, every_2_weeks, monthly, every_2_months, quarterly, 3_times_a_year, 2_times_a_year, annual, few_years
      • days_countinteger
        Average number of days between two transactions in the stream
      • category_codestring
        Category of transactions which belong to the stream
      • descriptionstring
        Transaction’s description common for the stream
      • merchantobject
        Merchant common for the stream
        Hide child attributes
        • namestring
          Merchant’s name
        • emailstring
          Merchant’s email address
        • phonestring
          Merchant’s phone
        • addressstring
          Merchant’s address
        • websitestring
          Merchant’s website
    • irregularobject
      Irregular transfers stream
      Hide child attributes
      • transaction_countinteger
        Number of transactions, which belong to the stream
      • transaction_idsarray of strings
        Ids of transactions, which belong to the stream
      • start_datestring (date)
        The date of the first transaction from the stream
      • end_datestring (date)
        The date of the last transaction from the stream
      • amounts_per_montharray of objects
        Information on amount of irregular transfers per month
        Hide child attributes
        • yearinteger
          Year that the calculation was made for
        • monthinteger
          Month that the calculation was made for
        • amountnumber
          Amount of irregular transfers per specified month and year
      • averagenumber
        Average amount of irregular transfers
Sample object
{
  "streams": {
    "regular_amount": 300,
    "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,
          "average": 100,
          "median": 100,
          "stdev": 0
        },
        "amounts_per_month": [
          {
            "year": 2021,
            "month": 1,
            "amount": 100
          },
          {
            "year": 2021,
            "month": 2,
            "amount": 100
          },
          {
            "year": 2021,
            "month": 3,
            "amount": 100
          },
          {
            "year": 2021,
            "month": 4,
            "amount": 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

  • streamsarray of objects
    Information on transfers a customer sends on a regular/irregular basis
    Note
    All transfers outgoing from one Account to another are considered as outbound transfers, no matter if those accounts belong to the same customer or different.
    Hide child attributes
    • regular_amountnumber
      The total amount of regular transfers
    • irregular_amountnumber
      The total amount of irregular transfers
    • countobject
      Number of outbound transfers streams
      Hide child attributes
      • regularinteger
        Number of regular streams
      • irregularinteger
        Number of irregular streams
        Note
        The number always equals to 1, because the irregular stream contains all the irregular transactions, which have not become a part of any regular stream, as they are not consistent, regular and periodic.
    • regulararray of objects
      Regular outbound transfers stream
      Hide child attributes
      • transaction_countinteger
        Number of transactions, which belong to the stream
      • transaction_idsarray of strings
        Ids of transactions, which belong to the stream
      • start_datestring (date)
        The date of the first transaction from the stream
      • end_datestring (date)
        The date of the last transaction from the stream
      • amountobject
        Information related to the amounts of regular transfers, which belong to the stream
        Hide child attributes
        • totalnumber
          Total stream amount
        • averagenumber
          Average stream amount
        • mediannumber
          Median stream amount
        • stdevnumber
          Standard deviation of the stream amount
      • amounts_per_montharray of objects
        Information on what amount of stream related transfers has been sent each month
        Hide child attributes
        • yearinteger
          Year that the calculation was made for
        • monthinteger
          Month that the calculation was made for
        • amountnumber
          Amount of stream related transfers per specified month and year
      • frequencystring
        Average period of time between two transactions in the stream
        Possible values: daily, 3_times_a_week, twice_a_week, weekly, 3_times_a_month, every_2_weeks, monthly, every_2_months, quarterly, 3_times_a_year, 2_times_a_year, annual, few_years
      • days_countinteger
        Average number of days between two transactions in the stream
      • category_codestring
        Category of transactions which belong to the stream
      • descriptionstring
        Transaction’s description common for the stream
      • merchantobject
        Merchant common for the stream
        Hide child attributes
        • namestring
          Merchant’s name
        • emailstring
          Merchant’s email address
        • phonestring
          Merchant’s phone
        • addressstring
          Merchant’s address
        • websitestring
          Merchant’s website
    • irregularobject
      Irregular transfers stream
      Hide child attributes
      • transaction_countinteger
        Number of transactions, which belong to the stream
      • transaction_idsarray of strings
        Ids of transactions, which belong to the stream
      • start_datestring (date)
        The date of the first transaction from the stream
      • end_datestring (date)
        The date of the last transaction from the stream
      • amounts_per_montharray of objects
        Information on amount of irregular transfers per month
        Hide child attributes
        • yearinteger
          Year that the calculation was made for
        • monthinteger
          Month that the calculation was made for
        • amountnumber
          Amount of irregular income per the specified month and year
      • averagenumber
        Average amount of irregular transfers
Sample object
{
  "streams": {
    "regular_amount": 0,
    "irregular_amount": -52,
    "count": {
      "regular": 0,
      "irregular": 1
    },
    "regular": [],
    "irregular": {
      "transactions_count": 1,
      "transaction_ids": [
        "499953322376038900"
      ],
      "start_date": "2021-04-21",
      "end_date": "2021-04-21",
      "amounts_per_month": [
        {
          "year": 2021,
          "month": 1,
          "amount": 0
        },
        {
          "year": 2021,
          "month": 2,
          "amount": 0
        },
        {
          "year": 2021,
          "month": 3,
          "amount": 0
        },
        {
          "year": 2021,
          "month": 4,
          "amount": -52
        }
      ],
      "average": 0
    }
  }
}

NEW Release: AIS & Data Enrichment API V6 is now available! Payments API is coming soon. Check the Changelog for more details.