Migrate from KYB v1 to v2 API

We recommend upgrading to the new v2 KYB API, which offers a simpler, clearer interface that's more consistent with the improved Enigma 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. Because the response keeps the v1 shape, most users can implement, test, and deploy the change 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:

• All IDs, including response_id, enigma_id, legal_entity_ids, and brand_ids, are UUIDs instead of strings

The remaining value changes are the same as the full v2 upgrade—more descriptive task reason values, NAICS 2022 codes, and full-URL websites. See Field Value Changes for the complete list.

FAQ

Does the backwards compatible endpoint return brand bankruptcies?

No. The v2/kyb-legacy endpoint preserves the v1 bankruptcy response shape: bankruptcy information is returned as business_bankruptcy, not as brands[].bankruptcies. Use the v2/kyb endpoint with attrs=bankruptcies to return bankruptcy filings on registered_entities. To associate bankruptcies with a brand, join brand.registered_entity_ids to the matching entries in data.registered_entities.

For questions that apply to both v2 endpoints—such as add-on support and whether the underlying data sources have changed—see the KYB v1→v2 upgrade FAQ.