Quick Start

Before we proceed, make sure that you have a Spectre Client account (you can register at https://www.saltedge.com/client_users/sign_up).

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

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

$ export APP_ID=YOUR_APP_ID
$ export SECRET=YOUR_APP_SECRET

1. Create customer

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

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"identifier\": \"test1\" \
              } \
            }" \
        https://www.saltedge.com/api/v4/customers/

This request returns a response of the following structure:

{
  "data": {
    "id":         "111",
    "identifier": "test1",
    "secret":     "SECRET"
  }
}

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

$ export CUSTOMER_ID=111

See customers reference for Customer related API endpoints.

2. Create Connect token

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

There are 2 ways to create connections in Spectre API:

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

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

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"customer_id\": \"$CUSTOMER_ID\", \
                \"fetch_scopes\": [ \
                  \"accounts\", \
                  \"transactions\" \
                ] \
              } \
            }" \
        https://www.saltedge.com/api/v4/tokens/create

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

{
  "data": {
    "token": "GENERATED_TOKEN",
    "expires_at": "2018-08-16T13:37:09Z",
    "connect_url": "https://www.saltedge.com/connect?token=GENERATED_TOKEN"
  }
}

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

3. Visit connect_url

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

Once selected, we will be presented with a form for user credential input, from this provider. Input “username” and “secret” as per the on-screen instructions and press “Connect”.

After that we will have to wait for the connection process to finish and then we can proceed to retrieve all its data via the API.

4. Fetch logins

In Spectre API, a distinct bank connection is called a Login. Each Spectre Customer can have multiple Logins. When we visited Salt Edge Connect and connected “Fake Bank Simple” we effectively created a Login for our Customer in the system. So to retrieve all data for this Login we first need to retrieve the Login itself.

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v4/logins?customer_id=$CUSTOMER_ID

The response contains an array of entries, each representing a connection to a financial institution.

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

In our case we will have only one entry. We need to save the id (in our case 1227) to retrieve its accounts.

$ export LOGIN_ID=1227

See logins reference for more information on Login endpoints.

5. Fetch accounts for Login

Having the Login id, we can retrieve all its accounts.

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v4/accounts?login_id=$LOGIN_ID

The response contains an array of entries, each representing an account from a financial institution.

{
  "data": [
    {
      "id": "142",
      "name": "Fake account 1",
      "nature": "card",
      "balance": 2007.2,
      "currency_code": "EUR",
      "login_id": "1227",
      "created_at": "2018-08-16T09:37:09Z",
      "updated_at": "2018-08-16T09:37:09Z",
      "extra": {
        "client_name": "Fake name"
      },
      ...
    }
  ]
}

We need to save the id (in our case 142) to retrieve all transactions for this account.

$ export ACCOUNT_ID=142

See accounts reference for more information on Account endpoints.

6. Fetch transactions for an account

Having the Account id we can retrieve its transactions.

curl -v -H "Accept: application/json" \
        -H "Content-type: application/json" \
        -H "App-id: $APP_ID" \
        -H "Secret: $SECRET" \
        -X GET \
        https://www.saltedge.com/api/v4/transactions?account_id=$ACCOUNT_ID

The response contains an array of entries, each representing a transaction from a financial institution.

{
  "data": [
    {
      "id": "987",
      "duplicated": false,
      "mode": "normal",
      "status": "posted",
      "made_on": "2013-05-03",
      "amount": -200.0,
      "currency_code": "USD",
      "description": "test transaction",
      "category": "advertising",
      "account_id": "100",
      "created_at": "2018-08-14T12:37:09Z",
      "updated_at": "2018-08-15T12:37:09Z",
      "extra": {
        "posting_date": "2013-05-07",
        "time": "23:56:12",
        "original_amount": -3974.60,
        "original_currency_code": "CZK"
      },
      ...
    }
  ]
}

See transactions reference for more information on Transaction endpoints.

Next steps

  • In this guide, we visited Connect manually. You might want to do that programmatically. For more information see about embedding Salt Edge Connect in your application.
  • Since new Spectre API clients are in test mode and have access only to fake providers, the request signature is not required. However, you will need to implement request signing before you are going live. For more information see our signature guide.
  • All responses with arrays (like accounts or transactions) are paginated by default, see how to implement it on our pagination guide.
  • The recommended way of syncronizing data with Spectre API is via callbacks. That way you won’t have to poll the servers to see whether there is new data available. See our callbacks guide for more information.
  • We have a “before going live” checklist with all the things necessary for enabling access to real providers.