This API reference will explain how to integrate the new version of Algoan's Score and Credit Insights products. All APIs are returning a JSON-encoded response and are organized around REST. It uses standard HTTP response codes.

This section will describe Algoan concepts related to the data model and some basic information on the APIs. Below are some definitions:

Customer: represents a user able to connect/aggregate their bank accounts. It is unique for your organization, your project and your "custom identifier" (represents your internal reference). Each Customer has:

• zero, one or many Analysis. One Analysis contains a score and a creditInsights results.
• zero, one or many Account. Each Account has zero, one or many Transaction.

API methods that are returning more than one document share the same structure:

• resources: contains the list (or a subset) of requested documents
• pagination:
  • first: contains the first page URL
  • last: contains the last page URL
  • next: contains the next page URL
  • previous: contains the previous page URL
  • totalPages: represents the total number of pages
  • totalResources: represents the total number of resources

Our APIs use a page-based pagination system and accept two query parameters:

• limit: maximum number of resources returned. The default value is set to 200
• page: number of the page

  {
    "resources": [{ ... }],
    "pagination": {
      "next": "/v2/customers?page=3&limit=20",
      "previous": "/v2/customers?page=1&limit=20",
      "first": "/v2/customers?page=1&limit=20",
      "last": "/v2/customers?page=11&limit=20",
      "totalPages": 11,
      "totalResources": 206
    }
  }

NOTE: If the total number of pages is equal to one or if the total number of resources is empty, then first, last, next and previous parameters will be set to null:

  {
    "resources": [],
    "pagination": {
      "next": null,
      "previous": null,
      "first": null,
      "last": null,
      "totalPages": 1,
      "totalResources": 0
    }
  }

The list below describes all possible errors. It is always returned as a JSON:

• code: a machine readable code.
• message: a human readable error message.
• status: the HTTP status code.

Example:

  {
    "code": "MISSING_PARAM",
    "message": "Transaction 'id_1' has no amount",
    "status": 400
  }

The following section will guide you through the integration of Score and Credit Insights products, depending on your integration mode:

• "without a connector": you are already able to retrieve banking data by yourself and directly use Algoan's APIs.
• "with a connector": you don't want to implement the aggregator's API. In this case, you can use one of our open-source connectors described here.

If you are already able to fetch banking data, read the following process:

1. Generate a new access token with your credentials
2. Create a new customer. You must provide at least a custom identifier, which can be your internal reference
3. You can then create a new analysis with the banking information. It will automatically launch the Score and/or Credit Insights computation.
4. Proceed to a short polling, until the analysis status is set to COMPLETED.

💡 You can also subscribe to the analysis_completed event using our webhook system to be notified instead of proceeding to a polling.

Aggregator raw data

It is possible to upload bank accounts and transactions with different format. Today, we support:

• Budget Insight
• Oxlin Direct Account API

If you have already implemented these aggregators, you can create analyses with the raw data. Algoan handles the translation. If you don't support these format, refer to the Algoan open banking data format.

Fetching Open Banking is a prerequisite to use Algoan APIs. This process changes from an aggregator to another. In order to help its customers, Algoan develops and maintains a set of open-source connectors. They are designed to retrieve open banking data and send it directly to Algoan.

• The Budget Insight connector: retrieves banking information from Budget Insight and triggers an analysis.
• The Bridge connector: retrieves banking information from Bridge and triggers an analysis.

Contact your Customer Success Manager to see which one fits with your Customer Journey.

If you use one of our open-source connectors, then read the following process:

1. Generate a new access token with your credentials
2. Create a new customer. You must provide at least a custom identifier, which can be your internal reference. It will automatically trigger a aggregator_link_required event.
3. Process to a short polling by requesting the customer, until the redirectUrl is defined.
4. Redirect the user to the aggregator's link (redirectUrl)
5. Once the user has finished connecting their bank accounts, you can then create a new empty analysis. It will automatically launch the bank_details_required event and trigger the aggregator connector.
6. Proceed to a short polling, until the analysis status is set to COMPLETED.

💡 You can also subscribe to the analysis_completed event using our webhook system to be notified instead of proceeding to a polling.

Algoan can send events using webhooks to notify your system about an event during the Open Banking process and the end of the calculation of Score and Credit Insights.

After exposing an endpoint on your server, create a subscription using the POST /v1/subscriptions API. You need to be authenticated with credentials that Algoan provided to you.

An event sent by Algoan is a POST request. Here is an overview of the payload:

{
  "subscription": {
    "id": "2118ac3d2e202f98759489f2",
    "target": "https://your-end-point.com/webhok/",
    "eventName": "bank_details_required",
  },
  "payload": {
    "customerId": "...",
    "analysisId": "..."
  },
  "time": 1458692752478,
  "index": 1
}

It contains:

• subscription: The subscription called.
• payload: The payload including only model identifiers related to the event.
• time: The time when the event has been emitted (number of milliseconds since the Unix epoch in UTC).
• index: Event's index in the list of all events emitted for this webhook and this application.

You can subscribe to the below list of events:

The HTTP post request will contain an X-Hub-Signature header with the SHA256 signature of the payload. The signature is calculated using the keyed-hash message authentication code (HMAC) where the key is your webhook secret. The signature is then prefixed with sha256=. Your webhook endpoint can verify this signature to validate the integrity and origin of the payload. Please note that the calculation is made on the raw escaped Unicode version of the payload, with lower case hex digits. For example, the string äöå will be escaped to \u00e4\u00f6\u00e5. The calculation also escapes / to /, < to \u003C, % to \u0025 and @ to \u0040. If you just calculate against the decoded bytes, you will end up with a different signature.

Algoan provides JSON Web Tokens based on the OAuth2 protocol to authenticate your organization. When you create a new project, you will need to use the service account shared by Algoan containing a client_id and a client_secret.

NOTE: this is the only API where request's parameters are formatted as snake case.

represents a user able to connect/aggregate their bank accounts. It is unique per organization, project and custom identifier.

An analysis is a snapshot of a customer's financial situation based on the connected bank accounts. It contains results from both products Score and Credit Insights.

NOTE: To get Credit Insights results or a Score, the analysis need to contain at least one CHECKING Account with a minimum of 20 transactions.