Salt Edge Inc. proudly announces the release of Spectre V3 – the third version of its innovative financial data aggregation service. The main focus in the new version was put on simplifying the workflow, improving the authentication system, and adding new possibilities for clients for a better maintenance and analysis of their connections. One of the most prominent feature that defines Spectre V3 is the implementation of a new entity Attempts, which represent a detailed description of a particular connection attempt. They are meant to provide clients with more information about the established connections for further use in technical and statistical purposes. Another major change has to do with authentication procedure that now uses the field secret instead of customer_id for identifying a customer within the system. The procedure varies depending on the mode it was designed for, be it for a service or an app, and is required for all types of requests related to existing logins. To get an overview of what has been changed and make the transition to V3 easier, the aspects that got modified or have been newly implemented are structured by the type of the application they affect. Some may be valid for all applications, others – just for mobile or web applications.

Changes for all types of applications

• GET /api/v3/attempts returns paginated attempts of a login:

{
  "data": [
    {
      "api_version": "3",
      "automatic_fetch": true,
      "categorize": true,
      "created_at": "2015-12-25T12:12:36Z",
      "custom_fields": {},
      "device_type": "desktop",
      "exclude_accounts": [],
      "fail_at": null,
      "fail_error_class": null,
      "fail_message": null,
      "fetch_type": "recent",
      "finished": true,
      "finished_recent": true,
      "from_date": null,
      "id": 337518,
      "interactive": false,
      "partial": false,
      "store_credentials": true,
      "success_at": "2015-12-25T12:13:39Z",
      "to_date": null,
      "updated_at": "2015-12-25T12:13:39Z",
      "last_stage": {
        "created_at": "2015-12-25T12:13:39Z",
        "id": 2094640,
        "interactive_fields_names": null,
        "interactive_html": null,
        "name": "finish",
        "updated_at": "2015-12-25T12:13:39Z"
      }
    }
  ],
  "meta": {
    "next_id": 36154,
    "next_page": "/api/v3/attempts?from_id=36154&login_id=47872"
  }
}

• A more definite picture of a specific attempt can be viewed on GET /api/v3/attempts/:id:

{
  "data": {
    "api_version": "3",
    "automatic_fetch": true,
    "categorize": true,
    "created_at": "2016-01-28T13:40:16Z",
    "custom_fields": {},
    "device_type": "desktop",
    "exclude_accounts": [],
    "fail_at": null,
    "fail_error_class": null,
    "fail_message": null,
    "fetch_type": "recent",
    "finished": true,
    "finished_recent": true,
    "from_date": null,
    "id": 3355,
    "interactive": false,
    "partial": false,
    "stages": [
        {
          "created_at": "2016-01-28T13:40:16Z",
          "id": 17676,
          "interactive_fields_names": null,
          "interactive_html": null,
          "name": "start",
          "updated_at": "2016-01-28T13:40:16Z"
        },
        {
          "created_at": "2016-01-28T13:40:16Z",
          "id": 17677,
          "interactive_fields_names": null,
          "interactive_html": null,
          "name": "connect",
          "updated_at": "2016-01-28T13:40:16Z"
        },
        {
          "created_at": "2016-01-28T13:40:26Z",
          "id": 17681,
          "interactive_fields_names": null,
          "interactive_html": null,
          "name": "finish",
          "updated_at": "2016-01-28T13:40:26Z"
        }
    ],
    "store_credentials": true,
    "success_at": "2016-01-28T13:40:26Z",
    "to_date": null,
    "updated_at": "2016-01-28T13:40:26Z"
  }
}

• Customer’s customer_id field has been renamed to secret. Given that there is a Customer with following attributes:

{
  "id": 12345,
  "secret": "generatedcustomersecret"
}

• in order to create a login, a Service client will have to execute the following request with customer_idpresent in request body:

curl -v -H "Accept:         application/json" \
        -H "Content-type:   application/json" \
        -H "Client-id:      CLIENT_ID" \
        -H "Service-secret: SERVICE_SECRET" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"customer_id\": 12345, \
                \"country_code\": \"XF\", \
                \"provider_code\": \"fakebank_simple_xf\", \
                \"credentials\": { \
                  \"login\": \"username\", \
                  \"password\": \"secret\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v3/logins

• whilst an App client will execute the following request with Customer-secret present in request headers:

curl -v -H "Accept:          application/json" \
        -H "Content-type:    application/json" \
        -H "Client-id:       CLIENT_ID" \
        -H "App-secret:      APP_SECRET" \
        -H "Customer-secret: generatedcustomersecret" \
        -X POST \
        -d "{ \
              \"data\": { \
                \"country_code\": \"XF\", \
                \"provider_code\": \"fakebank_simple_xf\", \
                \"credentials\": { \
                  \"login\": \"username\", \
                  \"password\": \"secret\" \
                } \
              } \
            }" \
        https://www.saltedge.com/api/v3/login

Note for Apps: The Customer-secret and Login-secret fields will have to be present in all further requests related to existing logins. As an example, for refreshing a login an App client will need to execute the following request:

curl -v -H "Accept:          application/json" \
        -H "Content-type:    application/json" \
        -H "Client-id:       CLIENT_ID" \
        -H "App-secret:      APP_SECRET" \
        -H "Customer-secret: generatedcustomersecret" \
        -H "Login-secret:    generatedloginsecret" \
        -X PUT \
        https://www.saltedge.com/api/v3/login/refresh

• Now a file mode provider can be connected without uploading the file directly. It can be done on /api/v3/logins/create by sending a URL of the uploaded file inside the params:

{
  "data": {
    "customer_id": 905,
    "country_code": "XO",
    "provider_code": "mint_csv_xo",
    "fetch_type": "recent",
    "file_url": "http://spatialkeydocs.s3.amazonaws.com/FL_insurance_sample.csv"
  }
}

• A new token attribute custom_fields has been added. It will allow to send and receive any custom values on all callbacks, except delete one.
• The message field from API error response has been renamed to error_message:

{
    "error_class":   "LoginNotFound",
    "error_message": "Login with id: '1234' was not found.",
    "request":       {}
}

• The maximal value of the header Expires-At has been changed to 1 hour from when the request was made. When this condition is not respected, ExpiresAtInvalid error is returned.
• On Login refresh, if the login can be refreshed at the moment – Login object is returned, otherwise LoginCannotBeRefreshed error is returned.

{
    "error_class": "LoginCannotBeRefreshed",
    "message": "Login cannot be refreshed.",
    "next_refresh_possible_at": "2016-01-29T09:38:07Z",
    "request": {
        "data": {
            "api_version": "3"
        },
        "id": "997675202"
    }
}

• GET /api/v3/countries now returns name and code of the countries:

{
  "data": [
    {
      "name": "Canada",
      "code": "CA"
    }
  ]
}

• GET /api/v3/currencies now returns name and code of the currencies:

{
  "data": [
    {
      "name": "United Arab Emirates dirham",
      "code": "AED"
    },
    {
      "name": "Afghan afghani",
      "code": "AFN"
    },
    ...
  ]
}

• api/v3/oauth_providers/* now returns such a response:

{
  "data":
    {
      "token": "generatedtoken",
      "expires_at": "2013-06-05T07:06:00Z",
      "redirect_url": "http://saltedge.com/api/v3/oauth_providers/redirect?token=generatedtoken"
    }
}

• The response to POST /api/v3/customers request now returns the following data:

{
  "data": {
    "id":         1234,
    "identifier": "test@mail.com",
    "secret":     "generatedsecret"
  }
}

• The response from api/v3/tokens/* now looks like this:

{
  "data":
    {
      "token": "generatedtoken",
      "expires_at": "2013-06-05T07:06:00Z",
      "connect_url": "http://saltedge.com/connect?token=generatedtoken"
    }
}

New errors:

• LoginCannotBeRefreshed – Login cannot be refreshed at the moment;
• AttemptNotFound – The attempt with the requested attempt_id was not found;
• CustomFieldsSizeTooBig – The size of custom_fields does not fit in admissible range;
• CustomFieldsFormatInvalid – The format of custom_fields is invalid;
• InvalidInteractiveCredentials – User has introduced wrong credentials on the interactive step;
• ActionNotAllowed – Client has not been allowed to perform an action.

Changes for web applications

• On a GET /api/v3/customers request, the API now returns the following response:

{
  "data": [
    {
      "id":         1234,
      "identifier": "test@mail.com",
      "secret":     "generatedsecret"
    },
    {
      "id":         1235,
      "identifier": "tes2t@mail.com",
      "secret":     "generatedsecret2"
    },
  ]
}

• In order to identify the customer, the request DELETE api/v3/customers/:id now receives customer_id.
• /api/v3/login/* (except /api/v3/login/destroy) now returns login object:

{
  "data": {
    "country_code": "GB",
    "created_at": "2014-10-24T20:09:02Z",
    "customer_id": 905,
    "id": 1227,
    "last_attempt": {
        "api_version": "3",
        "automatic_fetch": true,
        "categorize": true,
        "created_at": "2016-02-02T16:14:53Z",
        "custom_fields": {},
        "device_type": "desktop",
        "exclude_accounts": [],
        "fail_at": null,
        "fail_error_class": null,
        "fail_message": null,
        "fetch_type": "recent",
        "finished": true,
        "finished_recent": true,
        "from_date": null,
        "id": 425036,
        "interactive": false,
        "partial": false,
        "store_credentials": true,
        "success_at": "2016-02-02T16:16:19Z",
        "to_date": null,
        "updated_at": "2016-02-02T16:16:19Z",
        "last_stage": {
          "created_at": "2016-02-02T16:16:19Z",
          "id": 2691802,
          "interactive_fields_names": null,
          "interactive_html": null,
          "name": "finish",
          "updated_at": "2016-02-02T16:16:19Z"
        }
    },
    "last_success_at": "2016-02-02T16:16:19Z",
    "next_refresh_possible_at": "2016-02-02T17:16:19Z",
    "provider_code": "barclays_gb",
    "provider_name": "Barclays",
    "status": "active",
    "updated_at": "2016-02-04T09:41:23Z"
  }
}

• The callbacks for web applications have been modified, now they look as follows:

Success

{
  "data": {
    "login_id":      123,
    "customer_id":   3452345,
    "custom_fields": { "key": "value" }
  },
  "meta": {
    "version": "3",
    "time":    "2015-12-31T10:08:11Z"
  }
}

Failure

{
  "data": {
    "login_id":      123,
    "customer_id":   3452345,
    "custom_fields": { "key": "value" },
    "error_class":   "InvalidCredentials",
    "error_message":       "Invalid credentials."
  },
  "meta": {
    "version": "3",
    "time":    "2015-12-31T10:08:11Z"
  }
}

Interactive

{
  "data": {
    "login_id":                 123,
    "customer_id":              3452345,
    "custom_fields":            { "key": "value" },
    "stage":                    "interactive",
    "html":                     "<div id='interactive'>text</div>",
    "session_expires_at":       "2015-12-30T11:08:11Z",
    "interactive_fields_names": ["image"]
  },
  "meta": {
    "version": "3",
    "time":    "2015-12-30T10:08:11Z"
  }
}

Notify

{
  "data": {
    "login_id":      123,
    "customer_id":   3452345,
    "custom_fields": { "key": "value" },
    "stage":         "start"
  },
  "meta": {
    "version": "3",
    "time":    "2015-12-30T10:08:11Z"
  }
}

Destroy

{
  "data": {
    "login_id":    123,
    "customer_id": 3452345
  },
  "meta": {
    "version": "3",
    "time":    "2013-05-17T14:29:35Z"
  }
}

Changes for mobile applications

• The Customer-Secret header is now used for identifying the customer on all routes related to a specific Login.
• The response to /api/v3/login/* (except /api/v3/login/destroy) now returns the following login object:

{
  "data": {
    "country_code": "GB",
    "created_at": "2014-10-24T20:09:02Z",
    "id": 1227,
    "last_attempt": {
        "api_version": "3",
        "automatic_fetch": true,
        "categorize": true,
        "created_at": "2016-02-02T16:14:53Z",
        "custom_fields": {},
        "device_type": "desktop",
        "exclude_accounts": [],
        "fail_at": null,
        "fail_error_class": null,
        "fail_message": null,
        "fetch_type": "recent",
        "finished": true,
        "finished_recent": true,
        "from_date": null,
        "id": 425036,
        "interactive": false,
        "partial": false,
        "store_credentials": true,
        "success_at": "2016-02-02T16:16:19Z",
        "to_date": null,
        "updated_at": "2016-02-02T16:16:19Z",
        "last_stage": {
          "created_at": "2016-02-02T16:16:19Z",
          "id": 2691802,
          "interactive_fields_names": null,
          "interactive_html": null,
          "name": "finish",
          "updated_at": "2016-02-02T16:16:19Z"
        }
    },
    "last_success_at": "2016-02-02T16:16:19Z",
    "next_refresh_possible_at": "2016-02-02T17:16:19Z",
    "provider_code": "barclays_gb",
    "provider_name": "Barclays",
    "secret": "XawjVuAPkwfdcQR8klV3AVLiFjGjLTxgy0anOob19-k",
    "status": "active",
    "updated_at": "2016-02-04T09:41:23Z"
  }
}

Javascript callbacks

• Basic callback:

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

• Duplicated login callback:

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

For more details please check our documentation at https://docs.saltedge.com. Spectre API v2 is officially deprecated and will be supported until December 31st, 2016.