Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

Migrate from KYB v1 to the backwards compatible KYB v2 API

We recommend upgrading to the new v2 KYB API, which offers a simpler, clearer interface that's more consistent with Enigma's improved data model. That data model, and the resolution technology that powers it, improves name verification rates, industry classification coverage, website coverage, and more.

If you can't upgrade yet, you can still benefit from improved v2 data by migrating to the backwards compatible KYB v2 API. It's a drop-in replacement for the v1 KYB API that returns more accurate results based on the same v2 data. Most users can implement, test, and deploy the necessary changes in a few minutes.

Update Your Request Endpoint​

To make a request to the backwards compatible KYB v2 API, set the version to v2 and use the kyb-legacy endpoint in the URL:

curl --request POST 'https://api.enigma.com/v2/kyb-legacy/' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR-API-KEY' \
--data-raw '{
    "data": {
        "names": [
            "Enigma Technologies",
            "Enigma"
        ],
        "addresses": [
            {
                "street_address1": "245 5th Ave",
                "city": "New York",
                "state": "NY",
                "postal_code": "10016"
            }
        ]
    }
}'

That's it! You'll receive a response that's nearly identical to what you received from v1/kyb.

Specify Your Package

To ensure consistent behavior, specify your package via the package parameter when making your request.

Re-evalutate Your Match Threshold

While the backwards compatible v2 API supports a configurable match_threshold with the same range of values as v1, the same value may result in different behavior between v1 and v2. If you set a custom match_threshold, we recommend re-evaluating it by testing with a sample of representative requests before migrating.

API Keys and Usage Tracking

You can use the same API key for v1 and v2, but if you intend to use both versions concurrently, consider creating a new API key for v2 so that you can track usage separately.

Response Changes​

The v2/kyb-legacy response is syntactically backwards-compatible with the v1/kyb response, but there are important differences to be aware of in the returned values.

Added Fields​

Two additions add more context to the response and the relationships between the objects returned:

  • Added sources to task objects, indicating the data sources used to verify the task result
  • Added brand_ids to legal entity objects and legal_entity_ids to brand objects
Retrieving the Best Match

While the backwards compatible response structure is identical to the v1 response structure in every other respect, it does not include the best_match object. Instead, the first object in the array of legal_entities is the best match for the request. If no legal entities are returned, then the first object (if any) in the brands array is the best match.

Field Value Changes​

Note that while the structure and key names in the response are backwards compatible, some returned values have changed:

  • Task reason values are different and more descriptive
  • All IDs, including response_id enigma_id, legal_entity_ids, and brand_ids are UUIDs instead of strings
  • NAICS codes and descriptions conform to 2022 standards instead of 2017 standards
  • Websites are returned as full URLs instead of just the domain

FAQ​

Does the v2 KYB API still support add-ons?​

Yes, the v2 KYB API offers all of the same add-on attributes as the v1 KYB API and more. See available add-on attributes for more information.

Have the underlying data sources changed?​

Registration data is sourced from each US Secretary of State (SoS), just as before, but Enigma has augmented these authoritative sources with additional information. Enigma is constantly expanding and improving the data sources that power our data asset.

Last updated on