Skip to main content

KYB Tasks & Matched Data​

The KYB API response is a JSON object with three top-level fields:

FieldDescription
response_idA UUID that uniquely identifies this API response. Include this value when contacting Enigma support or filing a bug report — it allows Enigma to look up the exact request and response. Log it in your system alongside the verification outcome.
risk_summaryComposed of task results.
dataComposed of attributes describing the entities that best match the information provided in the request.

Risk Summary (Task Results)​

The risk summary section includes all the information you need to automate the decisioning logic of a business onboarding or review workflow. It is composed of tasks, which are discrete verification steps that are typically conducted in a business onboarding or review process. Tasks help you understand whether the submitted business is valid and meets your KYB requirements, or if additional investigation is needed. Tasks results are the output of these steps. You can incorporate task results into the decisioning logic implemented in your workflows.

Each task compares a value you provided in your KYB API request to the corresponding value in either the Enigma data set or the records of the authoritative Secretary of State (SoS).

All standard tasks included in your package are always present in the response. If you did not submit a value for a task to compare against (e.g. no person submitted), that task will return a failure result rather than being omitted. Add-on tasks (watchlist, tin_verification, ssn_verification) only appear when explicitly requested via the attrs parameter.

TaskDescription
Address VerificationCompares all input addresses to the addresses of matching records of any kind
SoS Address VerificationCompares all input addresses specifically to the addresses of matching SoS registrations
Name VerificationCompares all input business names to the names of any matching records of any kind
SoS Name VerificationCompares all input names specifically to the names of matching SoS registrations
Person VerificationCompares all input person names to the officer names listed on matching SoS registrations
SSN VerificationCompares all input SSN and person last name combinations to current IRS records
TIN VerificationCompares input TIN and business name combinations to current IRS records
Domestic RegistrationIndicates whether a domestic registration was found for the business
WatchlistIndicates whether the business appears on any U.S. government sanctions lists

Matched Data​

The data object returned in the KYB API response is a structured compilation of attributes describing entities in Enigma’s data model that best match the information provided in the request. The response is structured as lists of:

Together, these attributes offer a holistic perspective of a business and its relationship to people and places. They are the basis on which tasks verify the information you provide about a business.

Making Decisions with Task Results​

Each task returns a status of "success" or "failure". Your decisioning logic should combine these results to route applications to one of three outcomes: approve, decline, or manual review.

The right thresholds depend on your risk tolerance and regulatory requirements. The patterns below reflect common practice — adjust them to your specific program.

Approve automatically​

Route to automatic approval when key tasks pass and no hard blockers are present:

  • name_verification is success, and
  • At least one of address_verification or sos_address_verification is success, and
  • watchlist is success (if enabled), and
  • domestic_registration is domestic_active or domestic_unknown (if using the verify package)

Decline automatically​

Route to automatic decline for hard failures that indicate an unacceptable risk:

  • data.registered_entities is empty — no matching business was found at all
  • watchlist is watchlist_hits — the business or a person appears on a sanctions list
  • tin_verification is tin_not_verified — the submitted EIN does not match the business name in IRS records
  • domestic_registration is domestic_inactive — the business's registration has lapsed (required for payment processing, lending, and banking use cases)

Route to manual review​

Route to manual review when there is a partial match or ambiguous result:

  • name_verification is success but sos_name_verification is failure — the name matches brand records but not SoS filings
  • address_verification is failure — the submitted address does not appear in any Enigma records
  • person_verification is failure — the submitted officer name does not appear on any SoS filing
  • domestic_registration is domestic_not_found — no domestic registration exists (common for sole proprietors; see below)
  • ssn_verification or tin_verification is not_completed — the IRS was unavailable; retry or request documents

Sole proprietors and domestic_not_found​

Sole proprietors are not required to register with the Secretary of State in most states, so domestic_registration returning domestic_not_found is expected for them — it does not necessarily indicate fraud. If your program serves sole proprietors, check registered_entity_type in the response: if the value is Sole Proprietorship, treat domestic_not_found as a manual review signal rather than a decline.

Example Response​

The following is a representative response for a verify package request. Registrations and operating locations are trimmed for brevity.

Example response
{
  "response_id": "2a1b3c4d-5e6f-7890-abcd-ef1234567890",
  "risk_summary": {
    "tasks": [
      {
        "task_name": "address_verification",
        "status": "failure",
        "result": "address_not_verified",
        "reason": "No input address matches any address in any of Enigma's records",
        "sources": []
      },
      {
        "task_name": "sos_address_verification",
        "status": "failure",
        "result": "address_not_verified",
        "reason": "No input address matches any address on a matching SoS registration",
        "sources": []
      },
      {
        "task_name": "name_verification",
        "status": "success",
        "result": "name_exact_match",
        "reason": "An input business name exactly matches a business name in any of Enigma's records",
        "sources": [
          {
            "name": "ENIGMA TECHNOLOGIES",
            "match_entity_type": "brand"
          }
        ]
      },
      {
        "task_name": "sos_name_verification",
        "status": "success",
        "result": "name_match",
        "reason": "An input business name matches a business name on a matching SoS registration",
        "sources": [
          {
            "name": "Enigma Technologies, Inc.",
            "match_entity_type": "registered_entity"
          }
        ]
      },
      {
        "task_name": "domestic_registration",
        "status": "success",
        "result": "domestic_unknown",
        "reason": "A domestic registration was found but no status was provided by the SoS",
        "sources": []
      },
      {
        "task_name": "person_verification",
        "status": "failure",
        "result": "person_not_verified",
        "reason": "The person name does not match any person names on a matching SoS registration",
        "sources": []
      }
    ]
  },
  "data": {
    "registered_entities": [
      {
        "id": "4dccd7a5-790c-c4d1-0000-108000000000",
        "formation_date": "2011-04-26",
        "registered_entity_type": "Corporation",
        "names": [
          { "name": "ENIGMA TECHNOLOGIES, INC." }
        ],
        "brand_ids": [
          "7be0ec97-0ac8-40e9-a9ee-9a1348fb7950"
        ],
        "registrations": [
          {
            "registration_state": "DE",
            "jurisdiction_type": "domestic",
            "home_jurisdiction_state": null,
            "registered_name": "ENIGMA TECHNOLOGIES, INC.",
            "file_number": "4973743",
            "issue_date": "2011-04-26",
            "status": "unknown",
            "sub_status": null,
            "status_detail": null,
            "persons": [
              {
                "name": "CORPORATION SERVICE COMPANY",
                "titles": ["registered agent"]
              }
            ],
            "addresses": [
              {
                "street_address1": "251 LITTLE FALLS DR",
                "street_address2": null,
                "city": "WILMINGTON",
                "state": "DE",
                "postal_code": "19808",
                "type": "registered_agent",
                "deliverable": "deliverable",
                "virtual": "not_virtual",
                "delivery_type": "street",
                "rdi": "commercial"
              }
            ]
          },
          {
            "registration_state": "NY",
            "jurisdiction_type": "foreign",
            "home_jurisdiction_state": "DE",
            "registered_name": "ENIGMA TECHNOLOGIES, INC.",
            "file_number": "5012345",
            "issue_date": "2014-06-15",
            "status": "active",
            "sub_status": "good_standing",
            "status_detail": "Active",
            "persons": [
              {
                "name": "HICHAM OUDGHIRI",
                "titles": ["chief executive officer"]
              }
            ],
            "addresses": [
              {
                "street_address1": "245 5TH AVE",
                "street_address2": "FL 17",
                "city": "NEW YORK",
                "state": "NY",
                "postal_code": "10016",
                "type": "headquarters",
                "deliverable": "deliverable",
                "virtual": "not_virtual",
                "delivery_type": "multi-tenant building",
                "rdi": "commercial"
              }
            ]
          }
        ]
      }
    ],
    "brands": [
      {
        "id": "5f53e079-c66a-487e-8a9d-08efc39652ee",
        "registered_entity_ids": [
          "4dccd7a5-790c-c4d1-0000-108000000000"
        ],
        "names": [
          { "name": "ENIGMA TECHNOLOGIES" }
        ],
        "activities": {
          "activities": []
        },
        "websites": ["https://enigma.com"],
        "industries": [
          {
            "classification_description": "Software Publishers",
            "classification_type": "naics_2022_code",
            "classification_code": "513210"
          }
        ],
        "operating_locations": [
          {
            "id": "20e8d448-f6c7-4854-9855-f8367b97b097",
            "names": [
              { "name": "ENIGMA TECHNOLOGIES" }
            ],
            "addresses": [
              {
                "street_address1": "245 5TH AVE",
                "street_address2": "FL 17",
                "city": "NEW YORK",
                "state": "NY",
                "postal_code": "10016",
                "deliverable": "deliverable",
                "virtual": "not_virtual",
                "delivery_type": "multi-tenant building",
                "rdi": "commercial"
              }
            ]
          }
        ]
      }
    ]
  }
}
Last updated on