Developer news

News KYC API v2: Upcoming changes to orderOptions and sourceId fields

KYC API v2: Upcoming changes to orderOptions and sourceId fields

Posted 2025-03-14

Summary

We would like to announce some minor changes in the KYC API v2 response, scheduled for release on April 2, 2025. These enhancements are designed to improve the clarity and consistency of the fields in our API response.

The changes will affect the following fields:

orderOptions in the [GET] product/search and in [POST, GET and GET with orderId] product/order endpoints.

sourceId under sources in the [GET] system/coverage endpoint.

Changes to orderOptions

In the [GET] product/search endpoint the field orderOptions will be serialised as null if productType has no productOptions, instead of an empty array. Below are examples of current situation (as-is) and the future scenario (to-be) after the change is deployed to production.

Request

curl --location 'https://api.kompany.com/api/v2/product/search/1D62D6B910435F8CE12EAF571B378D74' \
--header 'user_key: ••••••'

Response now (as-is)

[
    {
        "productType": "REPOFHFAT",
        "productCategory": "Document government fee",
        "productName": "Register Report",
        "productDescription": "Official register extract retrieved in real time from the primary source",
        "countryCode": "AT",
        "requiresOption": false,
        "estimatedDeliverySeconds": 1,
        "orderOptions": [],
        "availability": true,
        "availabilityCheckStatus": "SUCCESS"
    }
]

Response after changes (to-be)

[
    {
        "productType": "REPOFHFAT",
        "productCategory": "Document government fee",
        "productName": "Register Report",
        "productDescription": "Official register extract retrieved in real time from the primary source",
        "countryCode": "AT",
        "requiresOption": false,
        "estimatedDeliverySeconds": 1,
        "orderOptions": null",
        "availability": true,
        "availabilityCheckStatus": "SUCCESS"
    }
]

Moreover, in the [POST, GET and GET with orderId] product/order endpoints the field orderOptions will change type from array to object. Below are examples of current situation (as-is) and the future scenario (to-be) after the change is deployed to production.

Request

curl --location 'https://api.kompany.com/api/v2/product/order' \
--header 'Content-Type: application/json' \
--header 'user_key: ••••••' \
--data '{
    "kompanyId": "1D62D6B910435F8CE12EAF571B378D74",
    "productType":"DOCOFFBAT",
    "productOptionId": "c2f7f663b2e74cef11bb0f5845a07007c9a24621"
}'

Response now (as-is)

{
    "orderId": "495241D1378AD1712FAF2B827DC6AF25",
    "kompanyId": "1D62D6B910435F8CE12EAF571B378D74",
    "productType": "DOCOFFBAT",
    "orderOptions": [
        {
            "productOption": {
                "productOptionId": "c2f7f663b2e74cef11bb0f5845a07007c9a24621"
            }
        }
    ],
    "status": "PROCESSING",
    "info": "DOCOFFBAT",
    "requestTime": "2025-03-14T08:26:14+00:00",
    "responseTime": "2025-03-14T08:26:17+00:00",
    "orderDeliveryTime": null,
    "estimatedDeliverySeconds": 1,
    "mimeTypes": [
        "application/pdf"
    ]
}

Response after changes (to-be)

{
    "orderId": "495241D1378AD1712FAF2B827DC6AF25",
    "kompanyId": "1D62D6B910435F8CE12EAF571B378D74",
    "productType": "DOCOFFBAT",
    "orderOptions": {
            "productOption": {
                "productOptionId": "c2f7f663b2e74cef11bb0f5845a07007c9a24621"
            }
    },
    "status": "PROCESSING",
    "info": "DOCOFFBAT",
    "requestTime": "2025-03-14T08:26:14+00:00",
    "responseTime": "2025-03-14T08:26:17+00:00",
    "orderDeliveryTime": null,
    "estimatedDeliverySeconds": 1,
    "mimeTypes": [
        "application/pdf"
    ]
}

Changes to sourceId

In the [GET] system/coverage endpoint in the sources element, the field sourceId will be renamed to sourceIds and it will be an array instead of a string. While under the other elements (datasets, searches, products, otherServices, conciergeProducts) sourceId will not have any changes and will remain a string. Below are examples of current situation (as-is) and the future scenario (to-be) after the change is deployed to production.

Request

curl --location 'https://api.kompany.com/api/v2/system/coverage?countryCode=ID' \
--header 'user_key: ••••••'

Response now (as-is)

[
    {
        "countryCode": "ID",
        "countryName": "Indonesia",
        "state": null,
        "continent": "Asia and Middle East",
        "countryConnectionType": "LIVE",
        "updateFrequency": null,
        "status": "LIVE",
        "sources": [
            {
                "sourceName": "Directorate General of General Law Administration",
                "sourceNameLong": "Directorate General of General Law Administration (Ditjen Administrasi Hukum Umum)",
                "isPrimarySource": true,
                "sourceStatus": "STABILITY ISSUES",
                "sourceConnectionType": "LIVE",
                "sourceId": "ce5140df15d046a66883807d18d0264b"
            },
            {
                "sourceName": "Directorate General of General Law Administration",
                "sourceNameLong": "Directorate General of General Law Administration (Ditjen Administrasi Hukum Umum)",
                "isPrimarySource": false,
                "sourceStatus": "STABILITY ISSUES",
                "sourceConnectionType": "LIVE",
                "sourceId": "698d51a19d8a121ce581499d7b701668"
            },
            {
                "sourceName": "Directorate General of General Law Administration (Ditjen Administrasi Hukum Umum)",
                "sourceNameLong": "Directorate General of General Law Administration (Ditjen Administrasi Hukum Umum)",
                "isPrimarySource": false,
                "sourceStatus": "BUSINESS CONCIERGE",
                "sourceConnectionType": "BUSINESS CONCIERGE",
                "sourceId": "d2ddea18f00665ce8623e36bd4e3c7c5"
            }
        ],
        "datasets": [
            {
                "productName": "Refresh Dataset ID",
                "productType": "REFRESHED_DATA_ID",
                "productCategory": "Dataset government fee",
                "productDescription": "Refresh dataset in Indonesia",
                "countryCode": "ID",
                "estimatedDeliverySeconds": 96123,
                "price": 15,
                "priceTier": "F",
                "priceCurrency": "EUR",
                "relatedProductType": [],
                "sourceId": "ce5140df15d046a66883807d18d0264b"
            }
        ],
        "searches": [...],
        "products": [...],
        "otherServices": [...],
        "conciergeProducts": [...]
    }
]

Response after changes (to-be)

[
    {
        "countryCode": "ID",
        "countryName": "Indonesia",
        "state": null,
        "continent": "Asia and Middle East",
        "countryConnectionType": "LIVE",
        "updateFrequency": null,
        "status": "LIVE",
        "sources": [
            {
                "sourceName": "Directorate General of General Law Administration",
                "sourceNameLong": "Directorate General of General Law Administration (Ditjen Administrasi Hukum Umum)",
                "isPrimarySource": true,
                "sourceStatus": "STABILITY ISSUES",
                "sourceConnectionType": "LIVE",
                "sourceIds": ["ce5140df15d046a66883807d18d0264b", "698d51a19d8a121ce581499d7b701668"]
            },
            {
                "sourceName": "Directorate General of General Law Administration (Ditjen Administrasi Hukum Umum)",
                "sourceNameLong": "Directorate General of General Law Administration (Ditjen Administrasi Hukum Umum)",
                "isPrimarySource": false,
                "sourceStatus": "BUSINESS CONCIERGE",
                "sourceConnectionType": "BUSINESS CONCIERGE",
                "sourceIds": ["d2ddea18f00665ce8623e36bd4e3c7c5"]
            }
        ],
        "datasets": [
            {
                "productName": "Refresh Dataset ID",
                "productType": "REFRESHED_DATA_ID",
                "productCategory": "Dataset government fee",
                "productDescription": "Refresh dataset in Indonesia",
                "countryCode": "ID",
                "estimatedDeliverySeconds": 96123,
                "price": 15,
                "priceTier": "F",
                "priceCurrency": "EUR",
                "relatedProductType": [],
                "sourceId": "ce5140df15d046a66883807d18d0264b"
            }
        ],
        "searches": [...],
        "products": [...],
        "otherServices": [...],
        "conciergeProducts": [...]
    }
]

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

Back Next