KYB Monitoring API (v2)

Table of Contents

1 Introduction
2 Getting started
- 2.1 Authorization
- 2.2 Environments
- 2.3 Endpoints
3 Calling endpoints
4 Glossary
5 Monitored events
6 Process diagram
7 RC (Registru centras)

Introduction

The KYB monitoring API enables you to track modifications to different events associated with a company, such as its name, status, VAT number, manager, address, shareholders, and beneficial owners. This document offers a comprehensive understanding of the KYB monitoring API and its functionality.

Getting started

This API aims to deliver comprehensive company information, including any monitored changes. Clients can receive events based on the following parameters:

Company name
Type
Address
Contacts
Representatives
Shareholders
Beneficial owners

Authorization

To utilize our KYB monitoring API, it is essential to include an access token in every request.

Learn how to get an access token here: Authentication.

Scopes

When requesting an access token, you can specify one or more authorization scopes to indicate the level of access you require. The available scopes for the KYB monitoring API are:

kybmonitoring_api: Provides the full access to KYB monitoring.

Environments

Environment	Swagger URL	Base URL

Environment	Swagger URL	Base URL
Sandbox	https://sandbox-kybmonitoring.ondato.com/swagger/index.html?urls.primaryName=v2	`https://sandbox-kybmonitoring.ondato.com/`
Prod	https://kybmonitoring.ondato.com/swagger/index.html?urls.primaryName=v2	`https://kybmonitoring.ondato.com/`

Endpoints

This API consists of the following endpoints:

Events

get /v2/events

put /v2/events/{id}

Watchlist

Operations

Calling endpoints

Header

	Parameter	Type	Required	Description

Parameter

Type

Required

Description

1

Access token

string

yes

Described here:

Natural entity data validation | 🛂 Authentication

2

Application-Id

string

yes

Your application Id.

Please contact support@ondato.com if you don’t have one.

Request body

	Name	Type	Description	Mandatory/Optional

	Name	Type	Description	Mandatory/Optional
1	q	string	The user can specify one of the following parameters: Company name Company code to narrow down the total events count and search for a specific company.	optional
2	from	string	Date from which the user wishes to receive events in the following format: yyyy/mm/dd	optional
3	to	string	Date to which the user wishes to receive events in the following format: yyyy/mm/dd	optional
4	changeType	string	You can specify the type of event that has changed and exclude all other events. The available types are: CompanyName CompanyStatus VatNumber Ceo Shareholder Address UltimateBeneficialOwner	optional
5	viewStatus	string	By providing the parameter "viewed," users can look into the events that were already marked as reviewed.	optional
6	page	integer	Allows retrieving a specific page in the response.	optional
7	pageSize	integer	Allows to get a specific page size in the response.	optional

Response data

	Field	Description

	Field	Description
1	page	Page number.
2	pageSize	Total page size.
3	count	Total page count.
4	events	All the events that occurred during the specified time period.
5	eventId	The unique eventId pertains to the specific event that occurred.
6	companyName	Company name for which a specific event happened.
7	companyCode	A unique company code which refers to the specific company
8	changeType	Type of the event which happened in the specific period of time. Available values: CompanyName CompanyStatus VatNumber Ceo Shareholder Address UltimateBeneficialOwner
9	previousValue	The previous value of the parameter.
10	newValue	The updated value of the parameter that caused the event to trigger.
11	changeDate	The date when the value was modified.
12	isReviewed	If this particular event was reviewed or not.
13	country	Country in which the specific event occurred.

Example

{
  "page": 1,
  "pageSize": 20,
  "count": 1,
  "events": [
    {
      "eventId": 1,
      "companyName": "Ondato",
      "companyCode": 98756456,
      "changeType": "CompanyName",
      "previousValue": "Active",
      "newValue": "Inactive",
      "changeDate": "2023-05-09T12:11:54.852Z",
      "isReviewed": true,
      "country": "string"
    }
  ]
}

Header

	Parameter	Type	Required	Description

Parameter

Type

Required

Description

1

id

integer

yes

A unique id for the event that the user wishes to mark as "viewed."

2

Application-id

string

yes

Your application Id.

Please contact support@ondato.com you don’t have one.

Request body

	Name	Description

	Name	Description
1	viewed	By providing this parameter, the user sets the specific event which occurred to "viewed."

Header

	Parameter	Type	Required	Description

Parameter

Type

Required

Description

1

Application-id

string

yes

Your application Id.

Please contact support@ondato.com you don’t have one.

Request body

	Name	Description

	Name	Description
1	companyCode	Unique company code, which is needed to add that company to the watchlist.
2	country	Specific country (ISO2 format). For now, it is applicable only for Lithuania.

Up to 5000 records can be added to the watchlist with a single batch request.
Response will return operationId which can be used to call Operation endpoints to get batch job status and possible issues with individual records processing.

Header

	Parameter	Type	Required	Description

Parameter

Type

Required

Description

1

Application-id

string

yes

Your application Id.

Please contact support@ondato.com you don’t have one.

Request body

	Name	Type	Description	Mandatory/Optional

	Name	Type	Description	Mandatory/Optional
1	q	string	The user can specify one of the following parameters: Company name Company code to narrow down the total events count and search for a specific company.	optional
2	from	string	The date from which the companies were added to the watchlist should be in the following format: yyyy-MM-dd. For example, 2022-06-23.	optional
3	to	string	The date to which the companies were added to the watchlist should be in the following format: yyyy-MM-dd. For example, 2022-06-23.	optional
4	page	integer	Allows retrieving a specific page in the response.	optional
5	pageSize	integer	Allows to get a specific page size in the response.	optional
6	country	string	Allows specifying the country.	optional

Response data

	Field	Description

	Field	Description
1	page	Page number.
2	pageSize	Total page size.
3	count	Total page count.
4	companies	Information regarding all the companies that have been added to the watchlist.
5	Name	Company name which is in the watchlist.
6	Code	A unique company code which refers to the specific company that is currently in the monitored watchlist.
7	added	Indicates the date when the specific company was included in the monitoring.
8	country	A country of the company.

Example

{
  "page": 1,
  "pageSize": 20,
  "count": 1,
  "companies": [
    {
      "code": 9878456456,
      "name": "Ondato",
      "added": "2023-05-15T10:16:04.333Z",
      "country": "Lt"
    }
  ]
}

Header

	Parameter	Type	Required	Description

Parameter

Type

Required

Description

1

Application-id

string

yes

Your application Id.

Please contact support@ondato.com you don’t have one.

Request body

	Name	Type	Mandatory/Optional

	Name	Type	Mandatory/Optional
1	companyCode	integer	mandatory
2	country	string	optional

Response data

	Field	Description

	Field	Description
1	companyCode	A unique company code which refers to the specific company that is currently in the monitored watchlist.
2	addedAt	Date and time when the specific company was added to the monitoring watchlist.
3	removedAt	Date and time when the specific company was removed from the watchlist.
4	country	Country, which refers to the company code.

Example

{
  "companyCode": 9875684564,
  "addedAt": "2023-05-15T10:57:17.037Z",
  "removedAt": "2023-05-15T10:57:17.037Z",
  "country": "Lt"
}

Header

	Parameter	Type	Required	Description

Parameter

Type

Required

Description

1

Application-id

string

yes

Your application Id.

Please contact support@ondato.com if you don’t have one.

Request body

	Name	Type	Mandatory/Optional

	Name	Type	Mandatory/Optional
1	companyCode	integer	mandatory
2	country	string	optional

Up to 5000 records can be deleted from the watchlist with a single batch request.
The response will return operationId which can be used to call Operation endpoints to get batch job status and possible processing issues with individual records.

Use operationId from the response of the post /v2/watchlists/batch or delete /v2/watchlists/batch.
get /v2/operations/{id} - will return the summary of the batch operation including status, create/finish date, number of loaded and processed records.
get /v2/operations/{id}/status - will return only the status of the batch operation.
get /v2/operations/{id}/details - will return individual records of the batch operation with their status and possible errors.

Glossary

Term	Meaning

Term	Meaning
JAR	Stands for Juridinių asmenų registras. A part of RC, which contains general information about company.
JADIS	Stands for Juridinių asmenų dalyvių informacinė sistema. A part of RC, which contains general information about company and its shareholders.
JANGIS	Stands for Juridinių asmenų naudos gavėjų informacinė sistema. A part of RC, which contains general information about company and its beneficial owners.
KYB	Stands for Know Your Business.

Monitored events

The KYB Monitoring API monitors the following events for each company:

Process diagram

The process flow can be illustrated by referring to the following diagram:

RC (Registru centras)

RC refers to external providers utilized for acquiring company information. It serves as a source for updates on changes in shareholders and beneficial owners sourced from JADIS and JANGIS.