Skip to main content

KYB API Quickstart

Enigma's /kyb endpoint verifies identifying information about a business. It's designed to integrate into new business onboarding and Know Your Business (KYB) compliance checks.

The API queries Enigma's business data, which includes authoritative business data sets, especially official Secretary of State records. Optionally, it can also do Tax Identification Number (TIN) checks and sanctions screening.

To use the KYB API, you'll need to:

  1. Get your API key from the Enigma Console
  2. Make a POST request to https://api.enigma.com/v2/kyb/. Be sure to include your API key by adding the following to the request header as shown:
curl  --request POST 'https://api.enigma.com/v2/kyb/' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR-API-KEY' \
--data-raw '{
    "name": "Enigma Technologies",
    "address": {
        "state": "NY"
    }
}'

Single Query Format​

Your request must include at least two of the business name, business address, or person objects. If you include an address object, it must contain at least one of city, state, or postal_code.

{
  "name": string,
  "website": string,
  "address": {
    "street_address1": string,
    "street_address2": string,
    "city": string,
    "state": string,
    "postal_code": string
  },
  "tin": string,
  "person": {
    "first_name": string,
    "last_name": string,
    "ssn": string
  },
  "persons_to_screen": array[object] // accepts 4 inputs maximum
}

Optionally, you can include the persons_to_screen, tin, and ssn fields:

  • If you are doing EIN/TIN verification, pass a 9-digit string in the tin field.
  • If you are doing SSN verification, pass a 9-digit string in the ssn field.
  • If you need to screen more than one person against government watchlists, you can include up to 4 person_to_screen objects in the persons_to_screen array. These will only be used for watchlist screening, not for matching on business or legal entity records.

Note that watchlist screening and TIN verification are sold as separate add-on services.

Multiple Query Format​

If you have multiple values for the business you are verifying — for instance, a legal name and a DBA — you may increase match rates by submitting them together in the request body:

{
  "data": {
    "names": array[string], // accepts 2 inputs maximum
    "addresses": array[object], // accepts 2 inputs maximum
    "persons": array[object], // accepts 1 input maximum
    "websites": array[string], // accepts 1 input maximum
    "tins": array[string], // accepts 1 input maximum
    "persons_to_screen": array[object] // accepts 4 inputs maximum
  }
}

You can include up to 2 names, 2 addresses, 1 website, 1 person, 1 TIN, and 4 persons to screen. To maximize match rates, the API attempts to match all combinations of names and addresses.

Advanced Query Parameters​

The KYB API defaults to the recommended configuration for most business verification needs. For unusual needs, you can use these parameters to override the default behavior.

  • package: The package parameter specifies the set of attributes you want returned with your matches. Package values can be "identify" or "verify" (the default).
  • attrs: If you want additional attributes not in the "identify" or "verify" packages, you can request them by passing a comma-delimited string to the attrs query parameter. Supported add-on attributes from the KYB endpoint include TIN Verification, SSN Verification, and OFAC Watchlist Screens. If you are interested in using these add-on attributes, please contact our sales team to have them added to your account.
  • match_threshold: The minimum match confidence, from 0 to 1, for us to return a candidate match.
  • top_n: The maximum number of matches to return. Each returned match will have a match confidence at least as high as the provided match_threshold. If not configured, the default value is 1.

Example Request​

curl --request POST 'https://api.enigma.com/v2/kyb/?package=identify&attrs=watchlist&top_n=1&match_confidence=0.5' \
--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"
            }
        ],
        "persons": [
            {
                "first_name": "Hicham",
                "last_name": "Oudghiri",
                "ssn": "111111111"
            }
        ],
        "tins": [
            "000000000"
        ],
        "persons_to_screen": [
            {
                "first_name": "Example",
                "last_name": "Name",
                "date_of_birth": "1990-01-01"
            }
        ]
    }
}'
Last updated on