Skip to content
Console(opens in a new tab)

KYB quickstart

Learn how Enigma verifies a business, send your first KYB request, and read the result.

The Enigma KYB API verifies a U.S. business in one request. You describe the business, Enigma matches it to its records and runs a set of verification tasks, and the response returns the matched data with the evidence behind each result. This page takes you from an API key to a result you can act on.

Every KYB request follows the same four steps.

  1. Describe the business. Send what you know: its name, address, and website, and optionally a person connected to it.
  2. Enigma finds the match. Enigma resolves your input to the registered entity and brand that most likely describe the business.
  3. Enigma runs the tasks. Each task checks one fact about the business, usually by comparing your input with the matched data, and reports a result with the evidence behind it.
  4. You apply your policy. Your application decides what to store, display, approve, decline, or send for review.

Businesses often trade under a name that differs from their legal name. Instacart, for example, is registered as Maplebear Inc. Enigma links the brand (the name customers know) to the registered entity (the legal entity on the Secretary of State registration), so a request with either name finds the business.

These five terms appear throughout the KYB docs.

Concept What it means
Business input The JSON body you send: a business name, plus any address, website, or person you have.
Match The registered entity and brand that Enigma returns as the closest records to the business you described.
Package The standard tasks and data a request returns: identify, or verify (the default).
Task One verification check, such as whether your business name appears on a Secretary of State registration.
Matched data The records Enigma matched: registered entities with their registrations, and brands with their operating locations.

You need:

  • An Enigma account with API access.
  • An API key. In Enigma Console, go to Settings, then Account, then API keys.
  • A terminal with curl.

The API keys page appears after your organization has selected a plan. If you cannot see the API keys page, contact an Enigma representative to confirm your access.

  1. Store your API key.

    Set the key as an environment variable for the current terminal session.

    Terminal window
    export ENIGMA_API_KEY='replace_with_your_api_key'
  2. Send a request.

    This request describes Enigma Technologies by name, website, and street address.

    Request
    curl --request POST 'https://api.enigma.com/v2/kyb/?package=identify&top_n=1' \
    --header "x-api-key: $ENIGMA_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
    "name": "Enigma Technologies",
    "website": "https://enigma.com",
    "address": {
    "street_address1": "245 5th Ave",
    "city": "New York",
    "state": "NY",
    "postal_code": "10016"
    }
    }'
    • package=identify runs the four name and address tasks, so the first response stays short.
    • top_n=1 asks for the single best match.
    • Only a business name is required. Every identifier you add helps Enigma tell apart businesses with similar names.
    • Include street_address1. The address tasks compare street addresses, and without one they always return address_not_verified.
  3. Read the response.

    Look for three parts:

    • risk_summary.tasks holds the tasks in the package, one object per task.
    • response_id identifies this response.
    • data holds the matched data, in registered_entities and brands.

    The example response below is illustrative and trimmed to the fields this page discusses. A real response includes more fields, and values change as Enigma updates its data.

    Example response
    {
    "risk_summary": {
    "tasks": [
    {
    "task_name": "address_verification",
    "status": "success",
    "result": "address_match",
    "reason": "An input address matches an address in any of Enigma's records",
    "sources": [
    {
    "address": {
    "street_address1": "245 5TH AVE",
    "street_address2": "FL 17",
    "city": "NEW YORK",
    "state": "NY",
    "postal_code": "10016",
    "type": "headquarters"
    },
    "match_entity_type": "registered_entity",
    "match_relationship_type": "registration_address",
    "urls": ["https://example.com/records/ny-5012345"]
    }
    ]
    },
    {
    "task_name": "sos_address_verification",
    "status": "success",
    "result": "address_match",
    "sources": [
    {
    "match_entity_type": "registered_entity",
    "match_relationship_type": "registration_address"
    }
    ]
    },
    {
    "task_name": "name_verification",
    "status": "success",
    "result": "name_exact_match",
    "sources": [
    {
    "name": "ENIGMA TECHNOLOGIES",
    "match_entity_type": "brand",
    "urls": []
    }
    ]
    },
    {
    "task_name": "sos_name_verification",
    "status": "success",
    "result": "name_match",
    "sources": [
    {
    "name": "ENIGMA TECHNOLOGIES, INC.",
    "match_entity_type": "registered_entity"
    }
    ]
    }
    ]
    },
    "response_id": "2a1b3c4d-5e6f-7890-abcd-ef1234567890",
    "data": {
    "registered_entities": [
    {
    "id": "4dccd7a5-790c-c4d1-0000-108000000000",
    "registered_entity_type": "Corporation",
    "names": [{ "name": "ENIGMA TECHNOLOGIES, INC." }],
    "brand_ids": ["5f53e079-c66a-487e-8a9d-08efc39652ee"],
    "registrations": [
    {
    "registration_state": "NY",
    "registered_name": "ENIGMA TECHNOLOGIES, INC.",
    "file_number": "5012345"
    }
    ]
    }
    ],
    "brands": [
    {
    "id": "5f53e079-c66a-487e-8a9d-08efc39652ee",
    "registered_entity_ids": ["4dccd7a5-790c-c4d1-0000-108000000000"],
    "names": [{ "name": "ENIGMA TECHNOLOGIES" }],
    "websites": ["https://enigma.com"]
    }
    ]
    }
    }

    Each task returned its result for a specific reason.

    Task Result Why
    name_verification name_exact_match The name matches the brand exactly.
    sos_name_verification name_match The Secretary of State registration adds INC. to the name.
    address_verification and sos_address_verification address_match The record includes a floor (FL 17) that the request left out.
Part What it tells you
HTTP status Whether Enigma accepted and processed the request.
Matched data data.registered_entities and data.brands hold what Enigma matched.
Task result result is the specific result code of a task, such as name_exact_match or address_not_verified. Branch on this value.
Task status status is a coarse summary, usually success or failure.
Sources sources lists the Enigma records that support a result, when there are any.
Response ID response_id is the identifier to log, and to give Enigma when you investigate a request.

A registered entity lists its brands in brand_ids, and a brand lists its registered entities in registered_entity_ids. Join records by these IDs, not by their position in the arrays. Even with top_n=1, the returned brand is not guaranteed to be linked to the returned registered entity. Check that the brand’s registered_entity_ids contains the registered entity’s id before you treat them as one business.

Request Use it when What it returns
package=identify You need identity matching, enrichment, onboarding prefill, or third-party confirmation. The matched data and four name and address tasks.
package=verify You need a full business verification for compliance, such as onboarding under a KYB program. Everything in identify, plus registration status fields and three tasks: domestic_registration, person_verification, and verification_tier (beta).

Add checks to either package with add-ons in attrs, for example attrs=watchlist for watchlist screening. Each add-on must be enabled for your account. The use cases show a complete request for every job, from onboarding a business to screening an owner or getting negative news.

  • Set package explicitly. A request without it runs verify. See packages.
  • Keep top_n=1 when you need tasks. Tasks run only on a single match. See control the number of matches.
  • Send every identifier you have, in the right field. A full street address, a website, and both the legal name and the brand name, when you have them, all improve the match. See send strong identifiers.
  • Branch on result, never on reason. The reason text is written for people and can change. See the task object.
  • Log response_id for every request. Quote it to Enigma when you investigate a request. See top-level fields.
  • Retry 429 and 5xx responses with exponential backoff. Fix a 400 instead of retrying it. Every retry is a new request. See retries and backoff.
  • Treat add-ons as account features. Confirm with Enigma which add-ons are enabled for your account. See account enablement.