KYC API Technical Interface Documentation - the kompany API
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
KYC API Technical Interface Documentation Version 2021.06 - August 360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/ Bank Details: Erste Bank | IBAN AT04 2011 1820 1240 0500 | BIC/SWIFT GIBAATWWXXX
TABLE of CONTENTS
1 INTRODUCTION .................................................................................................... 5
1.1 Meet the KYC API............................................................................................................ 5
1.2 What is KYC API? ............................................................................................................ 5
1.3 Is KYC API right for you? ................................................................................................. 5
1.4 Data Sources: index search vs. live search.......................................................................... 5
1.5 Explore KYC API ............................................................................................................. 6
2 EXAMPLE USE CASES ............................................................................................ 7
3 API TECH OVERVIEW ........................................................................................... 8
3.1 API Authentication .......................................................................................................... 8
3.2 Regenerating an API Key.................................................................................................. 8
3.3 API Host .......................................................................................................................... 8
3.4 Logical Functional Groups ................................................................................................ 8
3.5 Additional Headers ........................................................................................................... 9
3.6 HTTP Status Codes ........................................................................................................... 9
4 API OBJECTS ........................................................................................................ 10
4.1 Covered Jurisdictions ...................................................................................................... 10
4.2 Company Data Retrieval ................................................................................................. 10
4.2.1 Proper usage of company reg number as Search parameters ........................................................ 10
4.2.2 Overview of company search methods .......................................................................................... 11
4.2.3 Search FOR a company by name .................................................................................................... 11
4.2.4 Search FOR a company by registration number ............................................................................ 12
4.2.5 Live search FOR a company by name ............................................................................................ 12
4.2.6 Live Search FOR a company by registration number ................................................................... 12
4.2.7 Get a dataset for a company ............................................................................................................ 13
4.3 Last Update Timestamp .................................................................................................. 14
4.3.1 Sample response (see bottom of dataset) ....................................................................................... 14
4.4 Company Filings Retrieval .............................................................................................. 16
4.4.1 Search for products and their prices for a specific company ........................................................ 16
4.4.2 Check availability of a product for a specific company................................................................. 16
4.4.3 Order a product for a specific company ......................................................................................... 17
4.4.4 Check the status of an order ........................................................................................................... 17
4.4.5 Retrieve a completed order ............................................................................................................. 17
4.4.6 Get notified when an order is complete ......................................................................................... 18
4.5 Company Filings Retrieval via Business KYC Concierge .................................................. 18
4.5.1 Order a document via Concierge Service ....................................................................................... 18
4.6 UBO Discovery ............................................................................................................... 22
2
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/4.6.1 Automatically crawl a company’s shareholder ownership tree to discover UBOs ...................... 22
4.6.2 Step 1. Identify a company for which to order a discovery report............................................... 23
4.6.3 Step 2. Place an order for a discovery report ................................................................................. 23
4.6.4 Step 3. Update an existing, paused discovery report order ........................................................... 25
4.6.5 Step 4. Retrieve and view an ordered discovery report ................................................................ 26
4.7 Monitoring Overview ..................................................................................................... 29
4.8 Announcements & Alerting ............................................................................................ 29
4.8.1 SUPPORTED COUNTRIES FOR ANNOUNCEMENTS ............................................................... 29
4.8.2 Check for ANNOUNCED changes to a company’s data ............................................................... 29
4.8.3 Get ANNOUNCED changes to a company’s data .......................................................................... 30
4.9 Announcements Notifications......................................................................................... 30
4.9.1 Register a notification for new announcements ............................................................................ 30
4.9.2 UNRegister a notification for new announcements ...................................................................... 31
4.9.3 List registered notifications for a company .................................................................................... 31
4.9.4 List registered notifications by API key ......................................................................................... 31
4.10 Monitoring & Alerting................................................................................................. 32
4.10.1 A sample notification response for a monitored company ........................................................ 32
4.10.2 Register A MONITOR ................................................................................................................. 33
4.10.3 Unregister A MONITOR ............................................................................................................. 34
4.10.4 List registered MONITORS for a company ................................................................................ 34
4.10.5 List ALL registered MONITORS for API KEY ........................................................................... 35
4.10.6 List AVAILABLE MONITORING CATEGORIES (CHANGETYPES) ..................................... 35
4.11 PEP and Sanctions Check ............................................................................................ 35
4.11.1 Improving search quality............................................................................................................. 36
4.12 PEP and Sanctions Monitoring .................................................................................... 36
4.12.1 Monitor a PEP & Sanctions Report............................................................................................. 36
4.12.2 Deactivate monitoring of a pepsanction list ............................................................................... 37
4.12.3 Update monitoring details of a pepsanction list ......................................................................... 37
4.13 Tax ID Verification ...................................................................................................... 37
4.14 VAT lookup................................................................................................................. 38
4.14.1 Request Path Parameters ............................................................................................................. 38
4.14.2 Request Body Parameters ............................................................................................................ 38
4.14.3 Response ....................................................................................................................................... 39
4.14.4 Sample response ........................................................................................................................... 39
4.14.5 Supported countries ..................................................................................................................... 40
4.14.6 Error Codes................................................................................................................................... 40
4.15 EU-VAT Verification................................................................................................... 41
4.15.1 Verify a VAT number - basic check ........................................................................................... 41
4.15.2 Verify a VAT number - comprehensive check .......................................................................... 42
4.15.3 Verify a VAT number - level two check .................................................................................... 43
4.16 PT-NIF Verification..................................................................................................... 45
4.17 TIN Verification .......................................................................................................... 46
4.17.1 TIN lookup ................................................................................................................................... 46
4.17.2 Verify a TIN number – basic check ............................................................................................ 47
4.17.3 Verify a TIN number – comprehensive check ........................................................................... 47
3
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/4.18 EIN Verification .......................................................................................................... 52
4.18.1 Validate an EIN number, and verify if connected company is a legal name or not ................ 52
4.18.2 Validate an EIN number & verify connected company legal name, address ........................... 53
4.18.3 Get the EIN number of a company ............................................................................................. 54
4.19 4.20 IBAN Verification ................................................................................................ 55
4.20 4.21 Stock Exchange Listing Verification ..................................................................... 55
4.20.2 4.21.1 Retrieve all ISINs related to an LEI ................................................................................. 55
4.20.3 View stock exchange listing details related to an ISIN number ............................................... 58
4.21 Health Check .............................................................................................................. 59
4.21.1 Look up the Health Status of European Connections ................................................................ 60
5 Available Products: KYC API SKU list ................................................................... 62
6 Error Codes – Full List ........................................................................................... 66
6.1 General .......................................................................................................................... 66
6.2 Endpoint specific ............................................................................................................ 66
7 UBO Discovery Report example ............................................................................. 76
8 Supporting Documents........................................................................................... 84
9 Version History ..................................................................................................... 85
9.1 Version 2021.V3 - May 2021........................................................................................... 85
9.2 Version 2021.V4 - June 2021 .......................................................................................... 85
9.3 Version 2021.V5 - June 2021 .......................................................................................... 85
9.4 Version 2021.V6 - August 2021....................................................................................... 85
4
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/1 INTRODUCTION
This document has been compiled to provide an informative, concise outline of the kompany KYC API.
You can expect to gain a full understanding of the benefits, as well as insight into what a smooth
integration would entail.
1.1 Meet the KYC API
kompany offers real-time access to company information from over 200 countries and jurisdictions via
a user-friendly webtool. Users can perform instant searches across millions of companies, with the
options of customized and value-adding services. The KYC API allows access to the same data by way
of an integration within a customer’s system, providing simplified and more convenient accessibility.
1.2 What is KYC API?
With KYC API global company information and verified business data can be accessed in real-time and
integrated into internal workflows. As a central gateway, our API provides access to more than 150
million companies across Europe, Asia, North America, and Oceania. While company documentation
differs from jurisdiction to jurisdiction, we aim to cover the essentials for a complete and thorough
Business KYC (‘Know Your Customer’) experience that includes access to:
- Official commercial registers
- Shareholder information
- Company filings
- Annual & financial accounts
- Politically Exposed Person, Sanction and Adverse Media Lists
- Tax and IBAN number verification
- Business KYC Concierge services
- Perpetual monitoring and alerting of company data changes and filings
- Perpetual monitoring and alerting of PEP, Sanction and Adverse Media Lists
1.3 Is KYC API right for you?
Yes, if you are interested in reducing the costs of Business KYC and reducing time spent on other
compliance processes such as AML (“Anti-Money Laundering”) and EDD (“Enhanced Due Diligence”),
or the maintenance of internal CRM or ERP applications. If your company is looking to benefit from
automated processes and real-time data enhancements and verification, contributing to faster
business performance, KYC API can be a game-changing solution for you. The integration can be
tailored to suit the needs and requirements of each customer. Our current clientele ranges from major
European banks, global payment service providers and identity verifiers, to global identifier providers.
1.4 Data Sources: index search vs. live search
KYC API’s core value proposition is to provide you with real-time access to structured, official
commercial register and other authoritative data, including company filings, from primary sources.
This is achieved through KYC API’s connections to each jurisdiction’s government registers, so that you
can always verify your client’s data against the most up-to-date, live, and authoritative sources
available.
This process is known as “live search” or “live verification” and forms the basis of our clients’ company
data verification processes.
Response times for these requests vary according to the respective jurisdiction and are subject to
register availability as well as, in some cases, additional charges. The list of charges applicable for live
searches can be provided by sales@kompany.com.
5
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/Because of this, we strongly recommend our clients search for and identify the entity within our
company index first, before performing a live search/live identification.
Our large company index of time-stamped data allows our clients to accurately identify an entity’s
exact name and registration number, prior to calling a live search and verification endpoint. In this way
you can be confident that you are undertaking any live search or verification with accurate, pre-verified company data,
ensuring efficient costs and an effective experience during any live register calls.
This process is known as “company index search” and is often chosen by our clients for company
search and identification processes, prior to verification.
Please note: COMPANY INDEX RECORDS ARE AVAILABLE FOR COMPANIES FOR WHICH DATA HAVE BEEN PREVIOUSLY
RETRIEVED FROM THE REGISTER AND ARE UPDATED UPON EVERY LIVE SEARCH THEREAFTER . BE SURE TO CHECK THE “LAST
UPDATE TIMESTAMP” OF THE DATA SET FOR THE COMPANY YOU HAVE QUERIED IN ORDER TO ASCERTAIN WHETHER THE
COMPANY INDEX DATA IS SUFFICIENT FOR YOUR USE CASE . FOR FURTHER DETAILS PLEASE REFER TO THE SECTION OF THIS
DOCUMENT TITLED “LAST UPDATE TIMESTAMP”.
1.5 Explore KYC API
Customers are welcome to explore the KYC API capabilities before proceeding with an integration. A
user can create a free test account (‘Sandbox’ account) which gives access to the KYC API endpoints,
enabling a developer to gather first impressions of the services before committing to a subscription
plan. The KYC API Sandbox is limited to a pre-defined number of test companies. For a complete list of
those companies, please refer to the separate document titled “KYC API Sandbox companies”.
Should you need a special test setup so that you can assess the usability of KYC API for your company’s
needs, please reach out to our sales team and they will gladly assist you: sales@kompany.com
6
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/2 EXAMPLE USE CASES
KYC API can help make client onboarding faster and more effective:
a. Pre-population of client data based upon identifying characteristics (registration number, VAT
number (EU))
b. Verification of data filled in by a client
c. Document retrieval for audit-proof businesses
KYC API provides endpoints to help monitoring of CRM, ERP
a. Regular checks of client data against primary sources
b. Active monitoring of PEP & Sanction lists for high-risk clients. Data Cleansing
c. Project based data cleansing for whole client books – one-off projects followed with
monitoring functionalities under customized rules
Enhancing business security on self-reporting platforms / networks
a. Adding a layer of data verification to all self-reported / self-created business profiles
b. EU-VAT verification for invoicing and fraud prevention
c. Look-up of identifiers (LEI, GIIN, EIN, VAT, NIF, IBAN) for extended due diligence
Please note: ALSO REFER TO OUR KYC FLOWCHART DOCUMENT WHICH DOCUMENTS THE KEY USE CASES IN VISUAL
FORM.
7
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/3 API TECH OVERVIEW
3.1 API Authentication
KYC API uses API keys for authentication transferred as a separate header. This is safe because each
API key is securely encrypted by the SSL channel. The easiest way to test the API is to use the online
live documentation at http://www.kycapi.kompany.com/ – this is a web page which allows you to test the
various API methods and handles all the communications for you, whilst showing you the appropriate
URLs. KYC API can provide sample interface code in php, java or command line curl.
3.2 Regenerating an API Key
An API key can be regenerated by clicking on the Regenerate button on your dashboard page after
logging in.
https://apidashboard.kompany.com/login
Note: Only one API key may be active on an application at a time. If you choose to regenerate your API
key, your services will not work until you’ve updated all references to your API key. There is only one
API key per application, though your account can manage multiple applications. Regenerating the key
will regenerate it for all users.
3.3 API Host
Since August 2021 the KYC API host is available at https://api.kompany.com.
The legacy host https://api.brex.io is parallelly available but it is planned to phase out in the
future, besides the exact date of end of life is not yet announced.
3.4 Logical Functional Groups
The API is separated into logical functional groups which follow the general format of
api/version/object/method/parameter_1/.../parameter_n
It is important to note that parameter1 to parameter _n may possibly include reserved URI characters
and must therefore be URL encoded to the current standard (RFC3986). Any components of the URL
preceding the parameter sections will not require encoding but will also be defined in such a way that
encoding them would have no effect.
The version of the API must be specified with every request. This ensures your request will always
behave the same way.
Currently only version v1 is available, so the full valid path to the KYC API v1 API then looks like
https://api.kompany.com/api/v1/
Should updates be released to an endpoint, those will be released on a new version, so that older
integrations will not be affected.
There are several valid “object” and 'method' values. For a full overview please refer to the current
online documentation in your KYC API account listed under “Active Docs” upon login.
The basic functionalities of the API rely strongly on the following methods:
- search used to return a list of 'objects' that match the parameters following
- availability used to check the actual availability of a product for a given company
- buy/order used to order a product or PEP sanction check
8
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/- status get the status of an ordered product
- retrieve used to retrieve a product or PEP sanction check
3.5 Additional Headers
KYC API currently returns results in JSON. Only when retrieving an ordered PEP Sanction Check it can
be returned either in JSON or PDF format, for this case the ACCEPT header is used.
Accept: application/json
Accept: application/pdf
3.6 HTTP Status Codes
Every request includes an HTTP status code with the result. The status code should be examined before
the response. The online documentation provides up to date status code information, however in
general the response codes can be interpreted as:
200 – 299 as success
400 – 499 as client request errors
500 – 599 as server errors
The User Key must be passed in an HTTP header called user_key:
user_key: {your API key}
9
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/4 API OBJECTS
The API method calls are documented in the online system, but the general object structure and
sequence is as described below. Please note that the described below queries are only a subset of the
available search options. For a full overview please refer to the current online documentation in your
KYC API account listed under “Active Docs” upon login.
The structure and setup of the API serves a wide variety of use cases. A small subset will be presented
below. Please contact sales@kompany.com for an extended introduction to the functionalities the KYC
API can support.
4.1 Covered Jurisdictions
The usage of the KYC API requires its customers to use the standard 2-letter country codes. There are
two exceptions to this rule:
- The country code for English, Welsh, Scottish and Northern Irish companies is UK, rather than
the more usual GB. This is to cover the case of Northern Ireland. A customer can be provided
with an API key set to accept and return GB instead of UK on request.
- It is required to provide both the 2-lettter country code for the United States of America as
well as the 2-letter code for the respective US state for any requests focusing on our US
coverage (e.g., US-NY for New York)
It is recommended to always use the upper-case for all country code 2-letter codes.
The full and most up-to-date list of covered jurisdictions can be provided by sales@kompany.com
4.2 Company Data Retrieval
KYC API provides company information in structured format to a differing level of data depth (subject
to availability depending on jurisdiction). A detailed view on the provided information, including list of
covered jurisdictions, can be provided by sales@kompany.com.
KYC API users can decide with each call what level of data depth and of freshness is needed (refer to
“Live verification vs. Index search”).
The current setup of the API allows the user to identify or verify the sought company with the company
search endpoints:
4.2.1 PROPER USAGE OF COMPANY REG NUMBER AS SEARCH PARAMETERS
There are many variants of registration numbers. In some cases, e.g., Germany, a named court or
district is part of the registration number – in others e.g., the US, the state code needs to be part of
the registration number. This is to ensure uniqueness. A list of expected registration number formats
split by jurisdiction can be provided on demand.
The API user must be aware to use the company registration number in the specific format of how the
particular jurisdiction accepts it. In the kompany API there is not implemented any altering (trim,
replace special characters, etc.) method against the given company registration number parameter.
Thus, for the companyIndex search clients need to give the exact proper number as a parameter.
Besides, in some cases the provider itself applies some more advanced possibilities than
simple exact string match, that means in deepsearch can be experienced that we got results in case of
not exact match as well. Some examples are presented here.
In most of the jurisdictions handling the company registration number means no difficulties, since in
most countries the format of company registration number is a simple set of numeric digits.
10
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/Country Search param. Result – companyIndex Result - deepsearch
Belgium 0770.936.501 ok (Kabra) ok (Kabra)
Belgium 0770936501 not found ok (Kabra)
Finland 1863164-4 ok (Toni Lagerstedt) ok (Toni Lagerstedt)
Finland 1863164 ok (Toni Lagerstedt) ok (Toni Lagerstedt)
Finland 18631644 not found not found
Malta C 96331 ok (WINNER LIVE LTD) ok (WINNER LIVE LTD)
Malta C96331 no result no result
Malta X 505 ok (IRISH EMERALD SOCIETY) ok (IRISH EMERALD SOCIETY)
Malta X505 no result no result
Cyprus HE333944 ok (SUOL INNOVATIONS LTD) ok(a) (SUOL INNOVATIONS LTD)
Cyprus XX333944 no result ok(a) (SUOL INNOVATIONS LTD)
resulted different company(a) (FINART
CONSTRUCT LIMITED with reg number
Cyprus 333944 no result HE3944)
Netherlands 10034591-0000 ok (FICHTNER-ORANJEWOUD B.V.) ok (FICHTNER-ORANJEWOUD B.V.)
Netherlands 10034591 ok (FICHTNER-ORANJEWOUD B.V.) ok (FICHTNER-ORANJEWOUD B.V.)
(a)Forqueries in the primary source for Cyprus cut the first two letter from the given parameter
regardless of what they are.
4.2.2 OVERVIEW OF COMPANY SEARCH METHODS
KYC API offers two main ways for company identification:
- One is the companyIndex search (referred to as search, see in 4.2.3 and in 4.2.4). The search
endpoints retrieve the information very quickly (typically 200-400 ms) from our index. The
other advantage of search is that there are no extra costs. The search method is implemented
by the KYC API internal logic.
- The other method is referred to as live search or deep search (see in 4.2.5 and in
4.2.6). In case of these methods the API directly points to the primary source, therefore the
response time vary, (typically 2-4 seconds), and government fees may be added as an extra
cost dependent on jurisdictions. The search method is implemented by the primary source’s
providers and therefore can be different from country to country.
The recommended sequence of usage of the above endpoints is as follows:
- use search for a company by name or by number
- if there is no match, or the result is outdated (see 4.3 for lastUpdate timestamp)
- use live search for a company by name or by number to get the live indormation from the
primary source.
4.2.3 SEARCH FOR A COMPANY BY NAME
This endpoint searches the KYC API company index, allowing for fast search and identification of a
company, using a company name as the input:
11
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/4.2.4 SEARCH FOR A COMPANY BY REGISTRATION NUMBER
This endpoint searches the KYC API company index, allowing for fast search and identification of a
company, using a company registration number as the input:
Both search endpoints strive to respond with the closest available match. Should the request not
deliver the expected result, the user can loosen the search matching algorithm by setting a limit
parameter that is higher than 10. If no search parameter is set, it will default to 10.
Search by name and search by number provide the list of responses from the KYC API company index.
In the unlikely case that the company in question cannot be found with neither endpoint, the user
should perform a live search using the below endpoints.
4.2.5 LIVE SEARCH FOR A COMPANY BY NAME
This endpoint searches a particular jurisdictions official register directly (live search / live
identification), allowing for search, identification, and verification of company data, using company
name as the input:
4.2.6 LIVE SEARCH FOR A COMPANY BY REGISTRATION NUMBER
This endpoint searches a particular jurisdictions official register directly, (live search / live
identification), allowing for search, identification, and verification of company data, using company
registration number as the input:
To be noted: the latter endpoint is available only for a limited number of jurisdictions. A list can be
provided on demand.
Response times for live search by name and number vary according to the respective jurisdiction and
are subject to register availability as well as, in some cases, additional charges. The list of charges
applicable for deepsearch can be provided by sales@kompany.com.
4.2.6.1 Identifying entities, and the KYC API unique identifier
All the endpoints above (both live search and company index data based) provide the user with basic
information that allows identification of an entity.
{
"id": "77A5AD48BBB33E5E3A397FFC920C3885 ",
12
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/"country": "AT",
"registrationNumber": "375714x",
"name": "360kompany AG",
"requestTime": 1627645107,
"lastUpdate": 1627511705
}
After successfully identifying the sought entity, the user should store the provided company id (“id”).
It is a unique identifier within the KYC API and can be stored, eliminating the need of recurring
identification of the same identity.
4.2.7 GET A DATASET FOR A COMPANY
The KYC API offers different levels of data depth and “currentness”. Both have an impact on the pricing
of the relevant request, as have the expected volumes and traffic patterns of a customer.
The returned data consist of id, country, registrationNumber and name on minimum level,
therefore this fields are referred to as mini dataset.
In KYC API the following datasets are available: mini, master, full, refresh and super
dataset.
The master dataset contains all the fields covered by mini dataset and on the top of that the address
information.
{
"id": "77A5AD48BBB33E5E3A397FFC920C3885",
"country": "AT",
"registrationNumber": "375714x",
"name": "360kompany AG",
"status": "LIVE",
"address": [
"Schwindgasse 7/12",
"1040",
"Wien",
"AUT"
],
"formattedAddress": {
"cc": "AT",
"country": "AUT",
"city": "Wien",
"zip": "1040",
"careOf": "",
"street": "Schwindgasse",
"number": "7/12",
"extra": ""
},
"requestTime": 1627645249,
"lastUpdate": 1627511705
}
The structure of full, refresh and super datasets can be various dependent on jurisdiction.
13
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/Mini, master, full, and refresh data sets can be retrieved with the following endpoint:
Details on the expected responses per jurisdiction can be provided by sales@kompany.com
Please note: THE ID IN THE CALL ABOVE IS THE COMPANY _ID RETURNED FROM THE SEARCH – NOT THE REGISTRATION
NUMBER.
Also note that the data sets differ in data depth across the covered jurisdictions. For more information,
please contact sales@kompany.com.
The Super Data Set is a structured representation of data which is usually provided in document form
as the register report or register check. The Super Data Set may include officer and shareholder
information, depending on the jurisdiction, and is denoted by 'S' in the KYC API Endpoint
documentation. The underlying document (register report or register check) can be provided as part
of the endpoint, depending on the requirements of the respective customer and on the availability of
the document. This implies that the pricing for this endpoint varies across the covered jurisdictions.
A detailed overview of the pricing and data fields available in the Super Data Set for the respective
jurisdiction can be provided by sales@kompany.com.
A super data set can be retrieved with the following endpoint:
4.3 Last Update Timestamp
To ascertain whether the company index data is suitable for your use case, the lastUpdate field can be
used. This Unix timestamp shows the time the company index for that entity was updated from the
primary source register. If the timestamp displayed from the company index is fresh enough (=
timestamp is shown) for your needs, then a refresh data call is unnecessary. If the lastUpdate is 0, this
means the company index has not been updated from the source register, or the time of the last
update is undetermined.
4.3.1 SAMPLE RESPONSE
(SEE BOTTOM OF DATASET)
Please note that for reasons of space, some data values have been truncated from the example.
{
"id": "77A5AD48BBB33E5E3A397FFC920C3885",
"country": "AT",
"registrationNumber": "375714x",
"name": "360kompany AG",
"status": "LIVE",
"address": [
"Schwindgasse 7/12",
"1040",
"Wien",
"AUT"
14
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/],
"formattedAddress": {
"cc": "AT",
"country": "AUT",
"city": "Wien",
"zip": "1040",
"careOf": "",
"street": "Schwindgasse",
"number": "7/12",
"extra": ""
},
"managingDirectors": [
"Russell E. Perry",
"Johanna Konrad"
],
"secretaries": [],
"dateOfIncorporation": "2012-02-29",
"legalForm": "Aktiengesellschaft",
"sicNaceCodes": [
"7375 - Informationsabruf von entfernten Datenbanken",
"1450 - Media",
"73759903 - Remote data base information retrieval",
"63120 - Web portals"
],
"extraData": {
"registerCourt": "Handelsgericht Wien",
"oenace": "63120",
"url": "https://www.kompany.com",
"vat": "AT67091005",
"shareCapital": "112883",
"shareCurrency": "EUR",
"lei": "529900ENKWV3BZ5GYL12",
"email": "support@kompany.com",
"twitter": "https://twitter.com/kompany",
"phone": "+43-720-882960",
"linkedin": "https://www.linkedin.com/company/kompany"
},
"requestTime": 1627376796,
"lastUpdate": 1627376793,
"typeOfOwnership": [],
"structuredNaceCodes": [...
],
"signatureRights": [...
],
"people": {...
}
]
},
"officialNumber": [
"375714x"
]
}
15
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/4.4 Company Filings Retrieval
The KYC API allows users to purchase documents and official filings from commercial registers.
To purchase a document, it is required to use the existing sku of as an identified for the specific
document, as well as the company_id. The prices of the documents differ across jurisdictions and can
be provided upon request.
The KYC API gives a user full overview of the available documents as well as full control over the
purchase.
4.4.1 SEARCH FOR PRODUCTS AND THEIR PRICES FOR A SPECIFIC COMPANY
The following endpoint can be used to search for products for a specific company. It will give the user
both the needed sku and the current price for the document:
Please note: THE ENDPOINT ABOVE DOES NOT CHECK THE AVAILABILITY OF THE PRODUCTS IN REAL-TIME.
4.4.2 CHECK AVAILABILITY OF A PRODUCT FOR A SPECIFIC COMPANY
It is recommended to use the endpoint below to check the actual availability for the selected Product.
This will return an updated Product object with availability status and whether there are options
available (e.g., accounts for a specific year)
To check the filing history for a company through the availability endpoint, by entering the sku code
for the required product, and the KYC API company ID.
/api/v1/product/availability/{sku}/{subjectId}
For IE use SKU “DOCOFCRIE”
For UK use SKU “DOCOFCHUK”
If filings are available for a company the response field will hasOptions return a value of “true”,
followed by a collection of options reflecting each of the filings available.
Identify the filing you require via the type and subType fields. You will need the associated docId to
uniquely identify the document to the system in the next step.
Example response:
{
"date": "2014-08-18",
"docId": "MzEwNTcyMjEwMGFkaXF6a2N4",
"description": "incorporation-company",
"type": "NEWINC"
}
16
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/4.4.3 ORDER A PRODUCT FOR A SPECIFIC COMPANY
To place an order for the chosen product, the following endpoints must be used:
Or when there are options available, e.g. a specific year for a document:
To order the document through the product options endpoint, by entering the docId from 4.4.2,
together with the sku and KYC API company ID:
/api/v1/product/order/{sku}/{option}/{subjectId}
A successful document order will result in a response containing status with a value "PROCESSING"
e.g.
{
"identity": "F406C6C9B336E803D71975B837833FE6",
"owner": "1409622006386",
"sku": "ADDASCHUK",
"price": 3,
"subjectValue": "UK/09179938",
"subjectId": "C6A6CBD18DA986ED920F36339A1AF205",
"option": "",
"status": "PROCESSING",
"ordered": "1627540623"
}
You will need the associated identity (=Product Order ID) to retrieve the actual document in the
next step.
4.4.4 CHECK THE STATUS OF AN ORDER
It is important to mention that both endpoints mentioned above will result in the response of a
ProductOrder object (product order id). This object can be used to see when it is ready for
download.
Tip: IT IS RECOMMENDED TO LOOP THIS REQUEST EVERY 60 SECONDS UNTIL COMPLETED (=DOCUMENT IS READY) OR THE
PRODUCT IS MARKED AS FAILED.
4.4.5 RETRIEVE A COMPLETED ORDER
When the request is marked as completed, it can be retrieved using the following endpoint.
17
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/Please note: THIS ENDPOINT WILL RETURN A BYTE STREAM CONTAINING THE PRODUCT IN AN APPROPRIATE FORMAT AS
PER THE RESPONSE CONTENT -TYPE HEADER.
NOTE THE STATUS CHECKING HERE IS DONE VIA POLLING . THERE IS AN ALTERNATIVE METHOD BY USING A PRODUCT
NOTIFIER. THIS ALLOWS THE KYC API TO NOTIFY YOU WHEN A PRODUCT IS READY.
Once processing is complete, retrieve the document itself through the product endpoint, by entering
the identity from 4.4.3
/api/v1/product/{orderId}
The response will contain a link to view and download the document e.g.
{
"productOrderId": "42262D509B027096DC245C3A207AB8C4",
"mimeType": "application/pdf",
"uri": "https://api.kompany.com/api/v1/product/pdf/42262D509B027096DC245C3A207AB8C4"
}
Please note: ALSO REFER TO OUR KYC FLOWCHART DOCUMENT WHICH DOCUMENTS THE KEY USE CASES IN VISUAL
FORM.
4.4.6 GET NOTIFIED WHEN AN ORDER IS COMPLETE
To use a Product Notifier, replace step Check the status of an order with the following: Create a Product
Order Notifier providing a URL which will be called using HTTP GET. Note – the callback URL MUST have
any forward slashes (/) converted to tilde characters (~)
Wait for the callback from KYC API to the URL you supplied. The URL will be called with added
parameters of orderId={product order id} and notifierId={the id of the product order notifier
as created in this step).
The use of a notifier does not preclude the polling method but can be more adequate for you.
4.5 Company Filings Retrieval via Business KYC Concierge
4.5.1 ORDER A DOCUMENT VIA CONCIERGE SERVICE
Our international team of KYC experts is here to assist you when the information (data and documents)
you require cannot be retrieved with our regular KYC API endpoints. Only the most basic company
information is necessary to initiate a Business KYC Concierge request via the KYC API concierge
endpoint. By using this service you’ll get:
18
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/- Highly trained KYC & AML experts at your disposal
- Business KYC data from historically “difficult-to-access” locations
- Request response time of 72 hours with 24-hour express option available
- Guaranteed data integrity to meet even the strictest compliance requirements
Once you place an order, the concierge endpoint will return a product order ID, and our experts will
begin to process your request manually.
4.5.1.1 Service levels
standard Response time: within 72 hours
express Response time: within 24 hours
4.5.1.2 Endpoint
4.5.1.3 Description
Place an order for a concierge product.
4.5.1.4 Request URL
/api/v1/product/order/concierge
4.5.1.5 Request Path & Query Parameters
None
4.5.1.6 Request Body Parameters
Parameter Type Description
subjectId string Required (at least one of…):
subjectId registerNumber companyName
KYC API internal company ID of the company you want to place the
order for
priority string Priority of order: "standard" or "express" are allowed. Express
service must be enabled for your plan, otherwise default is standard
service.
country string Required Two letter ISO code of the country of the company
companyName string 4.5.1.6.1 Required (at least one of…):
subjectId registerNumber companyName
Name of the company for which a document should be ordered.
Tip: To avoid any ambiguity ideally enter both companyName and
registerNumber if available.
registerNumber string 4.5.1.6.2 Required (at least one of…):
subjectId registerNumber companyName
Registration number of the company for which a document should
be ordered.
Tip: To avoid any ambiguity ideally enter both companyName and
registerNumber if available.
19
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/informationRequirements string Required Requirements on what document or information should
be provided. Please be very precise.
registerData boolean If you want register data of the company to be retrieved. Possible
values are “true” or “false”.
fiancialData boolean If you want financial data of the company to be retrieved. Possible
values are “true” or “false”.
historicInformation boolean If you want historical data of the company to be retrieved. Possible
values are “true” or “false”.
localInvestigation boolean If the company’s residency should be investigated. Possible values
are “true” or “false”.
costConfirmation boolean If the concierge cost should require additional confirmation if a
threshold is reached (configured on your plan). When set to true, in
case the concierge service and document would cost more than the
threshold you set, then one of our customer care agents will contact
you on the email or phone you provided in the request in order to
confirm whether to proceed or not. Possible values are “true” or
“false”.
contactEmail string 4.5.1.6.3 Required (at least one of…):
contactEmail contactPhone
Contact E-Mail, will be contacted if concierge costs are exceeding
the threshold configured on your plan
contactPhone string 4.5.1.6.4 Required (at least one of…):
contactEmail contactPhone
Contact phone, will be contacted if concierge costs are exceeding
the threshold configured on your plan
Tip: WHEN PLACING A REQUEST USING COMPANYNAME OR REGISTERNUMBER, IDEALLY PROVIDE BOTH IF AVAILABLE, IN
ORDER TO AVOID ANY AMBIGUITY, IN CASE OF SIMILARLY NAMED COMPANIES .
4.5.1.7 Response
This will return an object with the following (concierge) product order details:
Parameter Type Description
identity string Identity of the order, otherwise known as “orderID” or “productOrderId” which
will be needed to retrieve the product / document when the order is complete
owner string For internal use The application ID of the orderer of the product – a unique client
identifier.
sku string Unique identifier for a specific product / document
price number($float) For internal use Price of product in EUR according to your plan (set to “0” here,
given actual costs for concierge service are calculated manually after request)
subjectValue string "country" e.g. "AT" / "registrationNumber"
subjectId string KYC API unique company ID - 32 character hex value
option string For internal use Any option value passed with the order
status string Status of the order
ordered string($date) Unix Timestamp of when the product was ordered
4.5.1.8 Response example
A successful product order will return a status value of “PROCESSING”, together identity with
the (product order ID) you will need, in order retrieve the order once it’s complete:
{
"identity": "4B5543C654A39D5CCC7197F0EB74F0DF",
20
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/"owner": "1409612205297",
"sku": "CONCIERGE_EXPRESS",
"price": 0,
"subjectValue": null,
"subjectId": null,
"option": "64",
"status": "PROCESSING",
"ordered": "1590492217"
}
4.5.1.9 Error codes
HTTP_STA Fault code Description
500 ERR_PRODUCT_CONCIERGE_SERV An unexpected Error appeared during request execution. Please retry the
ER_ERROR request or get in contact with apisupport@kompany.com if the error
persists.
404 ERR_PRODUCT_CONCIERGE_CC_E Express orders are currently not supported for the given country. Please try
XPRESS_NOT_AVAIL to order with standard priority instead.
404 ERR_PRODUCT_CONCIERGE_CC_N The country you have provided was invalid or is not currently supported in
OT_AVAIL our system. Make sure to use the correct two-letter ISO code.
https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
400 ERR_PRODUCT_CONCIERGE_INVA No company was found with the given subjectId. Make sure you pass a valid
LID_COMP company identifier. The identifier should be a 32-byte hexadecimal string as
returned, for instance, by the searching endpoints.
400 ERR_PRODUCT_CONCIERGE_MISSI Could not execute your request because some required parameters are
NG_DETAILS missing. Check the error message returned for more information.
400 ERR_PRODUCT_CONCIERGE_CONF The provided company is from a different country than the country provided
LICTING_CC_COMPANY in the super data set request! Make sure if you have provided the correct
country code.
403 ERR_PRODUCT_CONCIERGE_MISSI Your KYC API plan is currently not allowed to request concierge orders.
NG_FEATURE Please contact apisupport@kompany.com if you think there is a
misconfiguration. Otherwise, if you would be interested in adding the
concierge feature to your plan, please contact sales@kompany.com.
400 ERR_PRODUCT_CONCIERGE_MISSI If you want to be asked for confirmation if the costs of a concierge request
NG_THRESHOLD_FEATURE exceed a certain threshold, please get in contact with sales@kompany.com.
The available levels are 100€‚¬, 200€‚¬, and 300€‚¬.
400 ERR_PRODUCT_CONCIERGE_CONT Please provide a contact email or contact phone number so our concierge
ACT_REQUIRED team can contact you with potential questions about the order.
4.5.1.10 Next steps…
Once your order is complete, you may retrieve any related data and documents using your product
order ID identity via the regular Product endpoint:
/api/v1/product/{orderId}
Should you wish to be notified about when your product order is ready for retrieval you may
additionally employ a notifier via the regular Product Notifier endpoint:
/api/v1/product/notifier/{orderId}/{type}/{uri}
21
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/4.6 UBO Discovery
4.6.1 AUTOMATICALLY CRAWL A COMPANY’S SHAREHOLDER OWNERSHIP TREE TO DISCOVER UBOS
The UBO discovery endpoints enable the user to analyze shareholders and how much they benefit
either directly (as direct shareholders) or indirectly (via connected companies) from a specific
company’s economic activities.
While the legal definition of UBO or Ultimate Beneficial Owner varies from jurisdiction to jurisdiction,
(and therefore the logic to verify whether a specific natural person is classifiable as the UBO of a
company), the UBO endpoints do provide the flexibility for the user to define the shareholder criteria
they are interested in, and receive cross-border, multi-level ownership details about any connected
companies or individuals that either hold shares directly or indirectly in a specific company, along with
details of how they are connected, in the form of a discovery report (in both PDF and structured JSON
data formats), including optional accompanying official register documents supporting the findings.
The process to order a discovery report is outlined below, followed by details on the endpoints a user
will typically call at each stage in the order process.
4.6.1.1 Discovery Report Order Process
22
360kompany AG | Schwindgasse 7/12, A-1040 Vienna, Austria
Commercial Court: Vienna, FN 375714x | VAT Nr: ATU67091005 | Board of Directors: Russell E. Perry | Johanna Konrad
Call us: +43 720 882 960 | Email us: apisupport@kompany.com | Visit us: https://kycapi.kompany.com/You can also read
