KYB API Quickstart

The Enigma /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 the Enigma 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:

Get your API key from the Enigma Console
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 a business name. The other fields are optional but improve match accuracy — including them reduces false positives and increases confidence in the result. If you include an address object, it must contain at least one of city, state, or postal_code. The website field is particularly useful when the business name is common or ambiguous: it acts as a disambiguation signal to help narrow matches when multiple businesses share the same or similar name.

{
  "name": "Acme Corp",
  "website": "https://acme.com",
  "address": {
    "street_address1": "123 Main St",
    "street_address2": "Suite 100",
    "city": "Austin",
    "state": "TX",
    "postal_code": "78701"
  },
  "tin": "123456789",
  "person": {
    "first_name": "Jane",
    "last_name": "Smith",
    "ssn": "123456789"
  }
}

tin and ssn are only needed for their respective add-on verification tasks:

For TIN (EIN) verification, pass a 9-digit string (no dashes) in the tin field.
For SSN verification, pass a 9-digit string (no dashes) in the ssn field within the person object.

Note that TIN and SSN verification are sold separately as add-on tasks.

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
  }
}

To maximize match rates, the API attempts to match all combinations of names and addresses.

persons and persons_to_screen serve different purposes and are independent of each other:

Field	Purpose	Task it drives
`persons`	A beneficial owner or officer whose name you want to verify against SoS registration records.	`person_verification`
`persons_to_screen`	One or more individuals (e.g. UBOs, directors) to screen against OFAC and other sanctions lists.	`watchlist` (add-on)

You can include both in the same request — for example, to simultaneously verify that a person is listed as an officer on the SoS filing and confirm they do not appear on a sanctions list.

Each object in persons_to_screen supports the following fields:

Field	Required	Description
`first_name`	Yes	The person's first name.
`last_name`	Yes	The person's last name.
`date_of_birth`	No	The person's date of birth in `YYYY-MM-DD` format. Providing this narrows watchlist matches — many OFAC SDN entries include date of birth, so including it reduces false positives when names are common.

The watchlist task returns a single aggregate result covering both the submitted business names and all persons in persons_to_screen.

Error Responses

Non-200 responses use a consistent error envelope:

{
  "error": true,
  "message": "..."
}

HTTP Status	Cause	Example message
`400`	Malformed request — invalid JSON, unrecognized `package` value, or other bad input	`Bad Request: Available packages are "identify" and "verify"`
`429`	Rate limit exceeded	`Too Many Requests`
`500`	Missing or invalid API key	`UNAUTHORIZED: Missing or invalid API key`

note

Authentication failures return HTTP 500, not 401. Check for the UNAUTHORIZED message string in your error handling rather than relying on the status code alone.

A successful request always returns HTTP 200, even when no match is found or all tasks fail. Check data.registered_entities and task status fields to determine the verification outcome — not the HTTP status code.

Rate Limits

The KYB API enforces rate limits based on your plan. See Rate Limits for the limits that apply to your account.

When you exceed a rate limit, the API returns an HTTP 429 error response. Use exponential backoff starting at 1 second and doubling on each subsequent retry (1s → 2s → 4s → 8s …), up to a maximum wait of 60 seconds. See Error Responses for the response format.

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: A comma-delimited list of add-on attributes and tasks to include in the response. Pass as a query parameter, e.g. ?attrs=watchlist,bankruptcies. Add-ons must be enabled for your account — contact us to discuss access.

Add-on tasks

Value	Description	Requires
`watchlist`	Screens submitted business names against OFAC and other U.S. sanctions lists.	—
`tin_verification`	Verifies the submitted EIN matches the business name in IRS records.	`tin` field in request body
`ssn_verification`	Verifies the submitted SSN matches the person's last name in IRS records.	`ssn` field in `person` object

Add-on attributes

Value	Returned in	Description
`bankruptcies`	`registered_entities`	Bankruptcy filing details for the matched legal entity.
`operating_status`	`operating_locations`	Operational state of the brand at each address (`Open`, `Closed`, `Temporarily Closed`, `Unknown`).
`phone_numbers`	`operating_locations`	Phone numbers associated with each operating location.
`person_addresses`	`registered_entities.registrations.persons`	Addresses connected to each person on a registration. When included, person addresses are also used in address verification.
`avg_transaction_size`	`brands.card_transactions`	Average card transaction size in dollars for the latest time period.
`card_transactions_count`	`brands.card_transactions`	Total number of card transactions for the latest time period.
`card_revenue_amount`	`brands.card_transactions`	Sum of all transaction amounts in dollars for the latest time period.
`card_revenue_yoy_growth`	`brands.card_transactions`	Ratio of the latest time period's revenue to the same period one year prior.
`card_revenue_prior_period_growth`	`brands.card_transactions`	Ratio of the latest time period's revenue to the previous period.
`card_customers_average_daily_count`	`brands.card_transactions`	Average number of unique daily customers for the latest time period.
`has_transactions`	`brands.card_transactions`	`1` if the brand had any transactions in the time period, `0` otherwise.
`refunds_amount`	`brands.card_transactions`	Total refund amount in dollars for the time period.

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. If greater than 1, task results will not be returned in the response.

When top_n is greater than 1, the risk_summary field is omitted entirely and data.registered_entities and data.brands each contain one entry per candidate match. To associate a registered entity with its corresponding brand, cross-reference registered_entity.brand_ids with brand.id. Use top_n when you want to present candidate matches to a human reviewer rather than drive automated decisioning.

Example Request

curl --request POST 'https://api.enigma.com/v2/kyb/?package=identify&attrs=watchlist&top_n=1&match_threshold=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"
            }
        ]
    }
}'

Single Query Format​

Multiple Query Format​

Error Responses​

Rate Limits​

Advanced Query Parameters​

Example Request​