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. The single-form fields (name, address, website, person, tin) and the multi-form fields (names, addresses, websites, persons, tins) are mutually exclusive: a request that mixes them returns HTTP 400. When you use the data wrapper shown below, every field must be nested inside it — top-level keys alongside data are also rejected.

{
  "data": {
    "names": ["Acme Corp", "Acme"],
    "addresses": [
      {
        "street_address1": "123 Main St",
        "city": "Austin",
        "state": "TX",
        "postal_code": "78701"
      }
    ],
    "websites": ["https://acme.com"],
    "persons": [{ "first_name": "Jane", "last_name": "Smith" }],
    "tins": ["123456789"]
  }
}

The multi-form fields accept up to 2 names, 2 addresses, 1 website, 1 person, and 1 TIN per request. To maximize match rates, the API matches every combination of names and addresses.

The person (or persons) field accepts one beneficial owner or officer to verify against Secretary of State registration records, and drives the person_verification task. The watchlist add-on screens the submitted business names against U.S. sanctions lists — see Watchlist screening for what the task covers.

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"`
`401`	Missing or invalid API key	`Unauthorized`
`429`	Rate limit exceeded	`Too Many Requests`
`503`	Upstream search service unavailable	`Could not connect to ESS API. The service may be down.`

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: start at 1 second and double the wait on each subsequent retry (1, 2, 4, 8 seconds, and so on), up to a maximum 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, for example ?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 each matched legal entity. To associate bankruptcies with a brand, join `brand.registered_entity_ids` to the entries in `data.registered_entities`.
`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 up to top_n candidates. The two array lengths can differ — a single brand may map to multiple registered entities, and vice versa. 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"
        ]
    }
}'

Single Query Format​

Multiple Query Format​

Error Responses​

Rate Limits​

Advanced Query Parameters​

Example Request​