Monitoring REST API Documentation v1.0.10 ^BETA

Changes

Glossary

• client - user of monitoring service
• event - some change in companies' data or assessment
• monitoring - service for monitoring and reporting on changes in the data and credit assessment of legal entities in the client's portfolio
• portfolio - the group of legal entities (subjects) entered to monitoring service. One client can have several portfolios.
• Portfolio URI - the URI of one specific portfolio that is generated when the portfolio is created.
• resource - data objects (for example portfolio, subject, event) or process (for example adding subject to the portfolio)
• service provider - AS Creditinfo Eesti AS
• subject - legal entities or natural persons the client has added to monitoring service. Legal entity (company) must be registered in Estonia. One company can be represented as subject several times in different portfolios. Only Estonian natural persons are accepted.
• subject id - the unique code. For legal entities the registry code issued by Commercial Register. For natural persons the Estonian person identification code issued by Population Register.
• URI - Uniform Resource Identifier. Every resource has its own unique URI that usually is also a URL where the resource is accessible.

Introduction

This is a technical documentation of a Creditinfo Eesti AS monitoring service API.

Sample use case

Client makes a portfolio:

    POST /mon/portfolios
    Content-Type: application/vnd.ci.mon.v1+json
    Authorization: Bearer xxxxxxxxxxx

    {"name":"My first portfolio"}
    

    POST {portfolioUri}/subjects/subscriptions
    Content-Type: application/vnd.ci.mon.v1+json
    Authorization: Bearer xxxxxxxxxxx

    ["10256137"]
    

    POST {portfolioUri}/subjects/unsubscriptions
    Content-Type: application/vnd.ci.mon.v1+json
    Authorization: Bearer xxxxxxxxxxx

    ["10256137"]
    

    GET {portfolioUri}/events?from=2019-11-24&to=2019-11-24
    Accept: application/vnd.ci.mon.v1+json
    Authorization: Bearer xxxxxxxxxxx
    

Web interface

This API is also accessible by human using browser.

The entry point lists resources where user can start to navigate and discover the services this API provides.

This feature expands the accessibility and usability of the service. The service can be taken into usage without waiting until developers finish integration. Also some features (like creation of portfolio) might not be feasible to integrate into system if they are needed only once. Data analysts has direct access to the data if needed.

Most important, there is always a backup way to access the service in case integrated solution fails.

Development

Prerequisites

1. user must be a registered client
2. service provider must have issued an username and password
3. service provider must have granted access to the interface
4. Optional: service provider must have granted permission to process natural persons' data

Concept

The purpose of this API is to expose resources. Resources are things (like data) and also processes. Processes are asynchronous and will have a URI as a unique identifier that might be used to query the status of a process.

Every resource has a representation. Representation can be in different formats. For example the event can be in JSON, XML or in HTML. There is no default format (representation) in order to provide best backward compatibility. Client must always specify in which format he or she wants the resource (see Accept field in header).

Sandbox

There is a test environment for developers. Test environment URL is https://katseklaas.krediidiinfo.ee/mon.

Service provider will create a sample portfolio with a subject which has events so developers can test the requesting of events. If you request portfolios from test server and you can not see sample portfolio contact with the service provider and ask to add one.

This sample portfolio will be regenerated every night and therefore will have different portfolio URI. One way to get the portfolio URI quickly is by using curl:

$ curl --user USERNAME:PASSWORD  https://katseklaas.krediidiinfo.ee/mon/portfolios -H "Accept: application/vnd.ci.mon.v1+json"

Replace USERNAME and PASSWORD accordingly.

Requirements

Client must be abel to handle HTTP redirects when querying resource.

All posted data must be in UTF-8 encoding.

Authentication

API uses HTTP Basic Authentication. This means that username and password must be joined, base64 encoded and added into HTTP header.

For example if whe have a username 1234 and password secret then we have to merge them using colon as separator: 1234:secret. The new string must be encoded using base64 and the result is MTIzNDpzZWNyZXQ=. The request for these credentials must look like this:

    POST /
    Authorization: Basic MTIzNDpzZWNyZXQ=

Because API is using always HTTPS the header with password is always encrypted and kept secret.

This API uses URI-s as a resource identification and same URI can be accessed using browser. Browser can recognize this authentication schema and can ask to enter username and password.^* The purpose of this approach is to allow to consume service without specific integration. For example for representing data in HTML format as-is, for debugging, or for one time export. Usually for simple use cases it is not reasonable to make an integration.

^*Currently this feature does not work because there is no representation for resources in HTML format. It will will be added if there is a demand for it.

Quick way to check if login credentials are working:

   $ curl --user "USERNAME:PASSWORD" -H "Accept: application/vnd.ci.mon.v1+json" https://services.krediidiinfo.ee/mon/portfolios -I

Replace USERNAME and PASSWORD. In response look for the response code in HTTP response header (this is why -I is important in curl command). This tells if request was success or not.

Error handling

API re-uses HTTP status codes. Most common error codes are:

• 400 - Could not read payload. Usually some syntax error in payload.
• 401 - Could not authenticate the user. Check Authorization field in request header.
• 415 - Could not recognize Media Type. Check Content-Type or Accept in request.

Error handling must be based on HTTP codes. Error handling must not be base on parsing response body. There are a lot of things that might go wrong before the request reaches to the Monitoring API (connection lost, server crashed, etc) and the response might not be generated by API. Using HTTP status code in response for checking the success or failure is more robust way.

When client has detected that the response is not success then next step is to check Content-Type. If it is application/vnd.ci.error.v1+json then the response contains error message in JSON format:

    {
        "message":"lorem ipsum"
    }
    

where message contains the error message.

Near future development plan:

• All error responses generated by API will return error message in format "application/vnd.ci.error.v1+json". Currently some methods have empty payload on error responses and this is very confusing. If you are using curl for debugging then add -I option which forces curl to display response header where status code of resonse can be found.

Resources

Portfolio

Portfolio is a collection of subjects. One client can have zero to many portfolios.

Creation

    POST /mon/portfolios

Creation of private portfolio for authenticated user.

Sample request:

    POST /mon/portfolios
    Content-Type: application/vnd.ci.mon.v1+json
    Authorization: Bearer xxxxxxxxxxx

    {"name":"My first portfolio"}

Sample response:

    HTTP/1.1 201 Created

    Location: https://example.org/mon/portfolios/120

Returned Location is the identification of newly created portfolio. It is called portfolio URI and referred in this documentation as portfolioUri. Store portfolio URI as it is and do not parse it. It can be changed in future.

TIP! Portfolios can be created through web interfaces. Go to the entry point and navigate to portfolios. Usually it is not feasible to create API integration for this because it is one time task.

User's portfolios

    GET /mon/portfolios

Information about current user's portfolios.

Sample request:

    GET /mon/portfolios
    Accept: application/vnd.ci.mon.v1+json
    Authorization: Bearer xxxxxxxxxxx

Sample response:

    {
      "portfolios": [
        {
          "id": "https:\/\/services.creditinfo.ee\/mon\/portfolios\/xf2sdf""
          "name": "This is my first portfoli",
        },
        {
          "id": "https:\/\/services.creditinfo.ee\/mon\/portfolios\/yKD224"
          "name": "This is my second portfoli",
        },
      ]
    }

    POST {portfolioUri}/synchronizations

    POST {portfolioUri}/synchronizations
    Content-Type: application/vnd.ci.mon.v1+json
    Authorization: Bearer xxxxxxxxxxx

    ["10256137", "10000000", "47101010033"]

    POST {portfolioUri}/synchronizations
    Content-Type: application/vnd.ci.mon.v1+text
    Authorization: Bearer xxxxxxxxxxx

    10256137
    10000000
    47101010033

    HTTP/1.1 201 Created

    Location: https://example.org/mon/portfolios/123/synchronizations/456

    GET {processId}
    Accept: application/vnd.ci.process.v1+json
    Authorization: Bearer xxxxxxxxxxx

    HTTP/1.1 200 OK
    Content-Type: application/vnd.ci.process.v1+json

    {"status":"queued"}

    HTTP/1.1 200 OK
    Content-Type: application/vnd.ci.process.v1+json

    {"status":"finished"}

    HTTP/1.1 200 OK
    Content-Type: application/vnd.ci.process.v1+json

    {"status":"failed","message":"Failure reason"}

    POST {portfolioUri}/deletion

    POST {portfolioUri}/deletion
    Authorization: Bearer xxxxxxxxxxx

    HTTP/1.1 201 Created

Subjects in portfolio

    GET {portfolioUri}/subjects

Sample request:

    GET {portfolioUri}/subjects
    Accept: application/vnd.ci.mon.v1+json
    Authorization: Bearer xxxxxxxxxxx

Sample response:

    HTTP/1.1 200 OK
    Content-Type: application/vnd.ci.mon.v1+json

    {
        "subjects": [
            {
                "id": "https://services.creditinfo.ee/mon/subjects/a4xcs",
                "code": "10256137",
                "active": true,
                "subscriptions": [
                     {
                         "begin":"2018-01-01",
                         "end":"2018-06-01"
                     },
                     {
                         "begin": "2019-01-01",
                         "end": null
                     }
                 ]
            },
            {
                "id": "https://services.creditinfo.ee/mon/subjects/yiscs",
                "code": "0000000",
                "active": false,
                "subscriptions": [
                    {
                        "begin": "2019-01-01",
                        "end": "2019-09-01"
                    }
                ]
            }
        ]
    }

The result is a JSON list of subjects.

If active field is true then the subject is currently subscribed and under monitoring.

One subject can be subscribed several times but one subject can have not more than one active subscription at a time. The subscription field holds an array of subscriptions start and end dates ie the periods the subject has been monitored. If end is null then it means the subscription is still active and subject is not unsubscribed yet.

Multiple subscriptions at once

    POST {portfolioUri}/subjects/subscriptions

Add many subject at once into portfolio.

Sample request (subjects as list of JSON):

    POST {portfolioUri}/subjects/subscriptions
    Content-Type: application/vnd.ci.mon.v1+json
    Authorization: Bearer xxxxxxxxxxx

    ["10256137", "10000000", "47101010033"]

Sample request (subjects as text file):

    POST {portfolioUri}/subjects/subscriptions
    Content-Type: application/vnd.ci.mon.v1+text
    Authorization: Bearer xxxxxxxxxxx

    10256137
    10000000
    47101010033

Sample response:

    HTTP/1.1 201 Created

Notes:

• If subject is already subscribed then it is not resubscribed

Multiple unsubscriptions at once

    POST {portfolioUri}/subjects/unsubscriptions

Unsubscribe all subjects listed in request.

All subjects that are already unsubscribed will be skipped. No error message is returned in such case. Also are skipped subject that are not in portfolio at all.

Sample request (subjects as list of JSON):

    POST {portfolioUri}/subjects/unsubscriptions
    Content-Type: application/vnd.ci.mon.v1+json
    Authorization: Bearer xxxxxxxxxxx

    ["10256137", "10000000", "47101010033"]

Sample request (subjects as text file):

    POST {portfolioUri}/subjects/unsubscriptions
    Content-Type: application/vnd.ci.mon.v1+text
    Authorization: Bearer xxxxxxxxxxx

    10256137
    10000000
    47101010033

Sample response:

    HTTP/1.1 201 Created

201 means unsubscription process was created and subjects will be unsubscribed.

Event

Event is some change of subject's data.

Events in portfolio

    GET {portfolioUri}/events

All events registered about subjects in a portfolio. API exposes events registered up to yesterday.

Events can be filtered by using query parameters. Query parameters are optional. Allowed query parameters:

Note that filtering is based on the events registration date in system, not based on an actual date an event occurred.

Sample request:

    GET {portfolioUri}/events
    Accept: application/vnd.ci.mon.v1+json
    Authorization: Bearer xxxxxxxxxxx

Sample response:

    {
      "events": [
        {
          "subjectCode": "10256137",
          "type": "13",
          "typeName": "this is some name",
          "occurredOn": "2019-01-02",
          "registeredAt": "2019-01-03T05:02:00",
          "content": "Aadressi muutus: Kannikese 10-1 Tallinn 1023 -> Aasa 101-3 Tallinn 10111",
        },
        {
          "subjectCode": "10256137",
          "type": "13",
          "typeName": "this is some name",
          "occurredOn": "2019-01-02",
          "registeredAt": "2019-01-03T05:02:00",
          "content": "Aadressi muutus: Kannikese 10-1 Tallinn 1023 -> Aasa 101-3 Tallinn 10111"
        },
      ]
    }

Sample request with query parameter:

    GET {portfolioUri}/events?from=2019-01-02&to=2019-01-03
    Accept: application/vnd.ci.mon.v1+json
    Authorization: Bearer xxxxxxxxxxx

Event types

    GET /mon/events/types

All available event types.

Sample request:

    GET /mon/events/types
    Accept: application/vnd.ci.mon.v1+json

Sample response:

    {
      "eventTypes": [
        {
          "type": "1",
          "name": [
              "et": "Ärinime muutus",
              "en": "Change of business name"
          ],
        },
        {
          "type": "10",
          "name": [
               "et": "Maksehäire tekkimine",
               "en": "Appearance of payment default"
          ]
        }
      ]
    }