Stateful

This guide shows how to submit retail transaction data that needs to be analyzed, and then retrieve the analytics. An overview of all the endpoints with additional options and details can be found on the Endpoints page.

The difference between the stateless and statefull flow is that when using the stateful flow some information is stored and that subject management is needed. Actions performed through the stateful flow are reflected in the Navigator dashboard.

1. Authenticate

First you need to authenticate, as explained in Authentication. To get a JWT token you can use the command below:

curl -X POST 'https://navigator.riskquest.com/api/v1/auth/token/' \
  -H 'Content-Type: application/json' \
  -d'{"username":"<username>", "password":"<password>"}'

The response contains the access_token, this can be used to authenticate all other requests.

2. Create a Subject

Within the Navigator there are users (clients that use the Navigator) and subjects (the clients of the users). Each analysis is bound to a subject and all subjects are bound to an organisation.

In order to create an analysis you first need to create a subject:

curl -X POST 'https://navigator.riskquest.com/api/v1/subjects/create' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{"name": "foobar","email": "[email protected]"}'

The id that is returned can be used to create an analysis for the created subject and will be referred to as subject_id.

3. Create an Analysis

There are two ways to submit transaction data:

Option 1: File upload

In order to create a new analysis you can upload one or more files (MT940, CSV or JSON) that contains transaction data using the following endpoint:

curl -X POST 'https://navigator.riskquest.com/api/v1/analyses/upload' \
  -H 'Authorization: Bearer <access_token>' \
  -F 'subject_id="<subject_id>"' \
  -F 'analytics_type="retail"' \
  -F 'files=@"<file_path>"'

The id that is returned can be used to retrieve analytics for the created analysis and will be referred to as analysis_id.

The fields that your PSD2 provider needs to create a consent link can differ. To see the required fields you can use the following endpoint:

curl 'https://navigator.riskquest.com/api/v1/api/v1/provider/fields' \
  -H 'Authorization: Bearer <access_token>'

The output will have two types of fields, individual fields and shared fields. In case you want to create multiple consent links for an analysis, the individual_fields can be used to create different consent links (for example: bank name) and the shared_fields will be used for every consent link (for example: number of days of access).

To create a new analysis all the required fields need to be provided. An example with the PSD2 provider Nordigen:

curl -X POST 'https://navigator.riskquest.com/api/v1/analyses/create' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
        "subject_id": <subject_id>,
        "analytics_type": "retail",
        "individual_fields": [
          { "bank_id": "ING_INGBNL2A" },
          { "bank_id": "RABOBANK_RABONL2U" }
        ],
        "shared_fields": {
          "transaction_days": 400
        }
      }'

The output will contain an analysis with consents. Every consent has a consent_link that can be sent to clients with which they can provide their transaction data.