Method: GET /beneficialOwners/vip_level

OpenAPI/Swagger: https://ar-rest.rik.ee/docs#/beneficialOwners/vip_level_beneficialOwners_vip_level_get

The service allows a service provider to assess whether it may show beneficial owners data to a specific customer. By default, beneficial owners data must not be shown to the customer; displaying the data is allowed when the service response contains isVIP with the value true.

The service does not return beneficial owners data. It returns a technical indication of whether the service provider may show beneficial owners data to a specific customer. The actual beneficial owners data is requested and displayed through a separate beneficial owners query and depends on the user's access basis.

Access bases and visible data

Access basis	Short description	Visible data
Competent authorities	The broadest access for competent authorities that are entitled to see beneficial owners data for the performance of their duties.	Name, personal code, country of personal code, date of birth, method of control, start date, end date. Hidden beneficial owners data is shown only if a separate permission exists.
Obliged entities	Access for obliged entities that need to use the data to fulfil obligations arising from anti-money laundering and counter-terrorist financing legislation. The reason for viewing the data must be provided before the data is shown.	Name, personal code, country of personal code, date of birth, method of control, start date and end date.
Legitimate interest	Limited access for a user with an identified legitimate interest. A contractual user must provide a reason for viewing the data; where necessary, the connection to the queried juridical entity must also be provided. There may be an exception for journalism/media and NGO/research categories when specifying the connection.	Name, date of birth, method of control, start date and end date.

Using the service

The service is used before displaying beneficial owners data to a customer when a service provider needs to assess whether displaying the data is allowed. By default, the query is handled as a physical person query (personType=P). For a juridical entity, use personType=J.

Query parameters

Parameter	Type	Required	Description
personType	PersonType	Optional	Entity type. Allowed values: P – physical person, J – juridical entity. Default: P.
entityCode	string	Required	Personal code of a physical person or registry code of a juridical entity for which the request right is checked in the context of acting as a service provider for a specific customer.
entityCodeCountry	string	Required	Country of the personal or registry code in ISO 3166-1 alpha-3 format, for example EST.

Header parameters

Parameter	Type	Required	Description
apiVersion	ApiVersions	Optional	API version header. Allowed value: V1. Default: V1.
acceptLanguage	AcceptLanguage	Optional	Language for classifier translations. Allowed values: est – Estonian, eng – English. Default: est.

Request URLs

The service is available in the OpenAPI/Swagger documentation and at the REST API path /beneficialOwners/vip_level. Query parameters are provided in the URL. The example request can be opened directly in a browser; the API returns the response in JSON format.

Example	URL
Physical person	https://ar-rest.rik.ee/beneficialOwners/vip_level?personType=P&entityCode=39001010000&entityCodeCountry=EST
Juridical entity	https://ar-rest.rik.ee/beneficialOwners/vip_level?personType=J&entityCode=10000000&entityCodeCountry=EST

Response schema

BOVipLevelResponse

Field	Type	Description
level	string or null	Required. Additional technical value. The level is returned only if the requester has a separate permission to see it. If there is no permission to show the level or no additional value is returned, the value is null.
isVIP	boolean	Required. Indicates whether the service provider may show beneficial owners data to the specific customer. If the value is true, displaying the data to the customer is allowed; if the value is false, displaying the data is not allowed.

Responses

200 OK

Successful request. The response returns a technical indication of the right to request beneficial owners data.

{
 "level": null,
 "isVIP": false
}

200 OK – access-rights check is positive

If the value of isVIP in the response is true, the service provider may show beneficial owners data to the specific customer. The specifying level is returned only if the requester has a separate permission to see it.

{
 "level": null,
 "isVIP": true
}

Use based on legitimate interest

For users accessing data on the basis of legitimate interest, the result of this service does not grant the right to show additional data to the customer. In the case of legitimate interest, beneficial owners data is displayed according to the scope of the legitimate-interest access basis.

404 Not Found

No match was found for the request, or the physical/juridical entity related to the input data was not found. The response uses the CustomValidationError schema.

{
 "message": "Entity was not found",
 "code": 4043,
 "id": "ENTITY_NOT_FOUND",
 "timestamp": "2026-07-16T12:00:00+03:00"
}

422 Validation Error

Invalid request – a required parameter is missing or a parameter value does not match the allowed values. The response uses the HTTPValidationError schema.

{
 "detail": [
 {
 "loc": ["query", "entityCode"],
 "msg": "Field required",
 "type": "missing"
 }
 ]
}