KYC API v2: decommission of 4 system endpoints

Posted 2024-10-11 | Updated 2024-10-13

Summary

We have decommissioned the following four endpoints in KYC API v2:

countries: https://api.kompany.com/api/v2/system/countries
priceList: https://api.kompany.com/api/v2/system/priceList
health: https://api.kompany.com/api/v2/system/health
catalog: https://api.kompany.com/api/v2/system/catalog

This decision comes from the introduction of a new endpoint in KYC API v2, known as system/coverage. This new endpoint consolidates the data previously spread across the four mentioned endpoints into a single, more efficiently structured, and user-friendly response. See here for more details on the coverage endpoint.

In short, this is the simplified JSON structure response of the new endpoint.

[
  {
    "countryCode": "string",
    "countryName": "string",
    "continent": "string",
    "countryConnectionType": "string",
    "updateFrequency": "string",
    "status": "string",
    "sources": [...],
    "datasets": [...],
    "searches": [...],
    "products": [...],
    "otherServices": [...],
    "conciergeProducts": [...]
  }
]

For a detailed comparison of the data provided by each of the original endpoints with that of the new system/coverage endpoint please see below for more details. This consolidation is part of our ongoing efforts to enhance data accessibility and streamline our API offering.

Comparison

For simplicity, the responses provided here are limited to data pertaining to Austria (AT).

countries vs coverage

The system/countries endpoint retrieves a list of all currently enabled countries.

Request

curl --location 'https://api.kompany.com/api/v2/system/countries' --header 'user_key: {secret}'

Response

[
    {
        "countryCode": "AT",
        "countryName": "Austria"
    }
]

This country specific information is also present in the system/coverage endpoint, and you may include the optional query parameter countryCode in your request to retrieve all the data for each jurisdiction.

Differences: a distinct feature of the system/coverage endpoint is its inclusion of all countries, regardless of the nature of their connectivity.

Request

curl --location 'https://api.kompany.com/api/v2/system/coverage?countryCode=AT' \
--header 'user_key: {secret}'

Response

[
    {
        "countryCode": "AT",
        "countryName": "Austria",
        "continent": "Europe",
        "countryConnectionType": "LIVE",
        "updateFrequency": null,
        "status": "LIVE",
        "sources": [...],
        "datasets": [...],
        "searches": [...],
        "products": [...],
        "otherServices": [],
        "conciergeProducts": []
    }
]

priceList vs coverage

The system/priceList endpoint retrieves all the price information that you can expect to be charged for the corresponding products.

Request

curl --location 'https://api.kompany.com/api/v2/system/priceList' --header 'user_key: {secret}'

Response

[
    {
        "productName": "Refresh Dataset AT (Tier: C)",
        "productType": "REFRESHED_DATA_AT",
        "productCategory": "Dataset government fee",
        "productDescription": "Refresh dataset in Austria",
        "countryCode": "AT",
        "estimatedDeliverySeconds": 0,
        "price": 1.5,
        "priceCurrency": "EUR",
        "monthlyTierMinimun": 0,
        "monthlyTierMaximun": null,
        "relatedProductType": null
    }
]

In the system/coverage endpoint, the same information is also showed under one of six primary objects included in the response depending on the category of the metric.

Differences: objects (metrics) are now categorised under a specific country and category, rather than being presented as a single comprehensive list. The tier information is now provided in a separate field called priceTier instead of being enclosed in brackets after the name. These 2 fields: monthlyTierMinimun and monthlyTierMaximun have been removed. Additionally, each metric includes a unique sourceId that identifies its origin within the sources object, making it simpler to determine the source of each product or dataset.

Request

curl --location 'https://api.kompany.com/api/v2/system/coverage?countryCode=AT' \
--header 'user_key: {secret}'

Response

[
    {
        "countryCode": "AT",
        "countryName": "Austria",
        "continent": "Europe",
        "countryConnectionType": "LIVE",
        "updateFrequency": null,
        "status": "LIVE",
        "sources": [...],
        "datasets": [
            {
                "productName": "Refresh Dataset AT",
                "productType": "REFRESHED_DATA_AT",
                "productCategory": "Dataset government fee",
                "productDescription": "Refresh dataset in Austria",
                "countryCode": "AT",
                "estimatedDeliverySeconds": 0,
                "price": "1.500",
                "priceTier": "C",
                "priceCurrency": "EUR",
                "relatedProductType": [
                    "REFRESHED_DATA"
                ],
                "sourceId": "35f4a8d465e6e1edc05f3d8ab658c551"
            }
        ],
        "searches": [...],
        "products": [...],
        "otherServices": [],
        "conciergeProducts": []
    }

health vs coverage

The system/health endpoint retrieves the health information for the official sources based on usage.

Request

curl --location 'https://api.kompany.com/api/v2/system/health' --header 'user_key: {secret}'

Response

[
    {
        "countryCode": "AT",
        "status": "GREEN"
    }
]

In the system/coverage endpoint, the status field now provides updated information on the health of a specific connection to a jurisdiction on a source level.

Differences: an important update is the shift from using colour codes such as GREEN and YELLOW to descriptors like LIVE and STABILITY ISSUES to represent connection statuses. So, from these status GREEN, YELLOW, RED we shifted to LIVE, REGULAR UPDATES, STABILITY ISSUES, OFFLINE, BUSINESS CONCIERGE, UNKNOWN. Additionally, statuses are now determined at the source level through the sourceConnectionType field, offering a more granular set of information.

Request

curl --location 'https://api.kompany.com/api/v2/system/coverage?countryCode=AT' \
--header 'user_key: {secret}'

Response

[
    {
        "countryCode": "AT",
        "countryName": "Austria",
        "continent": "Europe",
        "countryConnectionType": "LIVE",
        "updateFrequency": null,
        "status": "LIVE",
        "sources": [...],
        "datasets": [...],
        "searches": [...],
        "products": [...],
        "otherServices": [],
        "conciergeProducts": []
    }
]

catalog vs coverage

The system/catalog takes the countryCode parameter on the request and returns a list of documents with some information.

Request

curl --location 'https://api.kompany.com/api/v2/system/catalog/AT' --header 'user_key: {secret}'

Response

[
    {
        "productName": "Register Report (Tier: E)",
        "productType": "REPOFHFAT",
        "productCategory": "Document government fee",
        "productDescription": "Official register extract retrieved in real time from the primary source",
        "countryCode": "AT",
        "estimatedDeliverySeconds": 53,
        "price": 9,
        "priceCurrency": "EUR",
        "monthlyTierMinimun": 0,
        "monthlyTierMaximun": null,
        "relatedProductType": null
    }
]

In the system/coverage endpoint, the same information is also showed under the products object included in the response.

Differences: same as described above inside the system/priceList.

Request

curl --location 'https://api.kompany.com/api/v2/system/coverage?countryCode=AT' \
--header 'user_key: {secret}'

Response

[
    {
        "countryCode": "AT",
        "countryName": "Austria",
        "continent": "Europe",
        "countryConnectionType": "LIVE",
        "updateFrequency": null,
        "status": "LIVE",
        "sources": [...],
        "datasets": [...],
        "searches": [...],
        "products": [
            {
                "productName": "Register Report",
                "productType": "REPOFHFAT",
                "productCategory": "Document government fee",
                "productDescription": "Official register extract retrieved in real time from the primary source",
                "countryCode": "AT",
                "estimatedDeliverySeconds": 53,
                "price": "9.000",
                "priceTier": "E",
                "priceCurrency": "EUR",
                "relatedProductType": [
                    "PRODMARKU"
                ],
                "sourceId": "35f4a8d465e6e1edc05f3d8ab658c551"
            }
        ],
        "otherServices": [],
        "conciergeProducts": []
    }
]

If you would like to provide us with feedback or you have a question related to this, contact us here: support team.