Overview

To use the services, end users have to authenticate themselves and grant access to information at a "Provider" (i.e. a financial institution). First, we need to create auth url and redirect user to that url. Then a code from callback should be exchanged for long-live access token. Bisnode will collect data of the user and make some analytics. The type of returned data depends on the requested scope during authentication. Scopes can be changed in a re-authentication process later if needed.

Tink provider

When a user wants to "enroll" for the service, the Tink Link interface must be used. We construct a URL containing our client_id (identifies Bisnode) and the scopes to ask for. There are additional optional parameters that can be used for customisation. One is iframe support. The user selects provider and performs the authentication and grants access. Tink starts to download the data from the provider, the user is shown a waiting page during this time. When the download is complete and the data is available for use at Tink, the user is redirected back (or we get a postMessage in case of iframe) with a short lived authorization code. The code can then be exchanged for an access token using an API endpoint with Bisnodes confidential credentials. The access token can then be used to query the various Tink APIs.

 

 Get started

You'll need 3 things to get started.

  • Bisnode ID (contact api-support@bisnode.com for one if you don't have it yet)
  • Sandbox API Key (you need to be logged in with your Bisnode ID to get it)
  • Subscribe to the API (you need to be logged in with your Bisnode ID to subscribe)
Refer to Docs for more details

Ready to start?

Get API Key

Documentation

How to use the API

This guide is intended to help you get going with your integration against the Bisnode Consumer Intelligence API. It serves as a complement to the  Endpoint Reference  and aims to bring a high level understanding of the key concepts of the platform. 

For questions and support, please contact Bisnode at api-support@bisnode.com

 

Changes and versioning

API version is provided in the base of the requested URL in the form of "v1", "v2" etc. Only major version numbers are used.

API versions are raised only on breaking (i.e. backwards incompatible) changes in the API. Fields may be added but will never be removed during an API version lifecycle. When developing your application, take care to ensure that your application is able to handle additional fields.

 

Authentication 

 

Authentication using OAuth2

Bisnode's newest APIs use OAuth2 for authentication. For all API requests, you need to supply an access token in order to authenticate yourself. To obtain such an access token you need to submit your CLIENT_ID and CLIENT_SECRET to Bisnode's authentication endpoint at https://login.bisnode.com/as/token.oauth2. The access token is then passed along in the Authorization header to all API requests. Follow the instructions below to learn how to do this.

 

Get and Use the Access Token

Step 1. Get the Access Token

To get an access token you need to make a POST request to https://login.bisnode.com/as/token.oauth2 using the following HTTP header: Content-Type: application/x-www-form-urlencoded and the following request body: grant_type=client_credentials&scope=psd2. The request must be authenticated using HTTP Basic authentication and your CLIENT_ID and CLIENT_SECRET.

Example in cURL
curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d 'grant_type=client_credentials&scope=psd2' \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     https://login.bisnode.com/as/token.oauth2
 
Example response
{
  "access_token": "eyJhb....seAtPCCQ",
  "token_type": "Bearer",
  "expires_in": 7199
}
 
Step 2. Use the Access Token

Supply your access token with all requests to the API using the HTTP Authorization header: Authorization: Bearer <your access token here> You should reuse the access token for multiple calls to the API. See the next section on recommended usage.

 
Example in cURL - search for company
curl -X POST \
     -H "Authorization: Bearer eyJhb...seAtPCCQ" \
-H 'Content-Type: application/json' \
-d '{"name": "bisnode", "country": "SE"}' \ https://api.bisnode.com/credit-data-companies/v2/companies


Reusing the Access Token

After you have fetched an access token you should save it and use it for subsequent calls to the API. There is no limit on the number of calls it can be used for, but it will expire after a certain time.

We recommend that you use the expires_in field to determine when to request a new access token. It specifies the number of seconds the token will be valid for. Because of possible delays in network communication as well as delays between checking the timestamp and transmitting the actual API request, it is a good idea to request a new token a few seconds before it is about to expire. This minimizes the risk of accidentally using an expired token.

The following pseudo code illustrates how to use the authentication endpoint together with the API.

function make_authorized_api_request():
    token = get_cached_access_token()
    if token == null or is_soon_to_be_expired(token):
        token = get_new_access_token()
        save_to_cache(token)
    make_api_call(token)


function get_new_access_token():
    token = get_token_from_auth_endpoint()
    token.expiration_timestamp = now().add_seconds(token.expires_in)
    return token


function is_soon_to_be_expired(token):
    # Add time margin to avoid token expiring during call
    if now().add_seconds(60) >= token.expiration_timestamp:
        return true
    return false

 

Income verification flow

Step 1

First, we need to build an authentication URL for redirect or iframe flow to authenticate end user at a "Provider". For this purpose, use /auth-url endpoint to get the authentication URL.

GET /auth-url
Query params

Key Value Description
intention verify-income  Available: verify-income, get-transactions, get-statistics
market SE  
locale en_US  
iframe false Set to true, if you will use auth in iframe
redirectUri https://your.domain.com/callback For test purpose, you can use https://console.tink.com/callback

response:

{
    "authUrl": "https://link.tink.com/1.0/authorize?client_id=77bb493acdb348a3bff3bdf23f81afd5&redirect_uri=https://console.tink.com/callback&scope=accounts:read,statistics:read,transactions:read,categories:read&market=SE&locale=en_US",
    "issuedFor": "verify-income"
}
Step 2

With authUrl from previous response we can navigate end user to "Provider" authentication form, where user has to choose his bank institution and authenticate with his credentials.

Step 3

After successful user authentication, the "Provider" will redirect user to callback URL (provided in auth-url query parameter) containing code. This code needs to be exchanged at /token endpoint.

GET /token
Token query parameters:

Key Value Description
code 4gdfg654edr89tg7e4gh654sdf654 The code from callback
intention verify-income  Available: verify-income, get-transactions, get-statistics

response:

{
    "token": {
        "accessToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjMxOWRjYTQx79MwMGItNDBmZi1hYzY4LTFiNzFjYmEwZjZkMCIsInR5cCI6IkpXVCJ9.e4pleHAiOjE1ODc2MzQzOTEsImlhdCI6MTU4NzYyNzE5MSwiaXNzIjoidGluazovL2F1dGgiLCJqdGkiOiJlNWY2MzdmYy0yZTMxLTQwNTktYWYyZi1jNzk4MDk5OTVhMDUiLCJvcmlnaW4iOiJtYWluIiwic2NvcGVzIjpbImNhdGVnb3JpZXM6cmVhZCIsInN0YXRpc3RpY3M6cmVhZCIsImFjY291bnRzOnJlYWQiLCJ0cmFuc2FjdGlvbnM6cmVhZCJdLCJzdWIiOiJ0aW5rOi8vYXV0aC91c2VyLzZjNGY1YTE2NjBjZDRhMGFhMmMxZWFkY2E1NmQxYzM0IiwidGluazovL2FwcC9pZCI6ImUxMTJiYjQ3YzI3YzRmN2FiMGZjMDg3ZGRlNzM5ZjY5In0.fKhJtCK8cAciV2ajmVbTTzMRJy0snpmsOviJ023MHreFwOagbhpX3ItSuwzGjg7ecaNfK-h5METJrFTG-odg4A",
        "tokenType": "bearer",
        "expiresIn": 7200,
        "refreshToken": "4cf6c2ec3f6641ad855095fda6dbded8",
        "scope": "categories:read,statistics:read,accounts:read,transactions:read"
    },
    "issuedFor": "verify-income"
}
Step 4

With this JWT access token we can fetch data from "Provider" APIs. For income verification flow, we have /account/verify-income endpoint or /account/statistics?category=income-salary. These Endpoints need to specify period, which is multi-value query parameter. Each value represents one period. Period can be year or month. In /account/verify-income response, all periods are grouped by years.

List of transactions can be found in /account/transactions.

GET /account/verify-income
Headers:

Key Value Description
psd2-token eyJhbGciOiJFUzI1NiIsImtpZ... The JWT token from /token endpoint

Query parameters:

Key Value Description
periods 2020-03  
periods 2020-02  
periods 2020-01  
periods 2019  
minMonthlyIncome 2019 PoC, required minimal monthly income for evaluation

response:

{
    "requirementsMet": true,
    "years": {
        "2020": {
            "requirementsMet": true,
            "totalIncome": 42000.0,
            "averageMonthlyIncome": 14000.0,
            "months": 3,
            "periods": [
                {
                    "period": "2020-03",
                    "type": "income-by-category",
                    "value": 10500.0
                },
                {
                    "period": "2020-02",
                    "type": "income-by-category",
                    "value": 10500.0
                },
                {
                    "period": "2020-01",
                    "type": "income-by-category",
                    "value": 21000.0
                }
            ]
        },
        "2019": {
            "requirementsMet": true,
            "totalIncome": 84000.0,
            "averageMonthlyIncome": 12000.0,
            "months": 7,
            "periods": [
                {
                    "period": "2019-11",
                    "type": "income-by-category",
                    "value": 10500.0
                },
                {
                    "period": "2019-10",
                    "type": "income-by-category",
                    "value": 10500.0
                },
                {
                    "period": "2019-09",
                    "type": "income-by-category",
                    "value": 21000.0
                },
                {
                    "period": "2019-07",
                    "type": "income-by-category",
                    "value": 10500.0
                },
                {
                    "period": "2019-06",
                    "type": "income-by-category",
                    "value": 10500.0
                },
                {
                    "period": "2019-05",
                    "type": "income-by-category",
                    "value": 10500.0
                },
                {
                    "period": "2019-04",
                    "type": "income-by-category",
                    "value": 10500.0
                }
            ]
        }
    }
}

For only list of all periods, the /statistics endpoint could be used.

Below you can find all endpoints. Each endpoint is documented and has example in curl. 

 

API Console

Production Endpoints

Production URLs:
https://api.bisnode.com/psd2/v1

Sandbox Endpoints

Sandbox URLs:
https://sandbox-api.bisnode.com/psd2/v1

Get Access

Please find the complete reference of the API below. In future releases it will also be possible to try the API out directly from your browser.