Enigma's KYB endpoint is built to perform a Know Your Business (KYB) check on a business. It queries our dataset of legal entities, which are based on official state records, as well as our businesses dataset.

The API returns the data you need to automatically verify your customers, including registration and industry information. It also has the optional capability to do TIN checks and sanctions screening.

Making a request

You can try the KYB endpoint with your API key by making a POST request to https://api.enigma.com/v1/kyb/:

curl  --request POST 'https://api.enigma.com/v1/kyb/' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR-API-KEY' \
--data-raw '{
    "name": "Enigma Technologies",
    "address": {
        "state": "NY"
    }'

Or get started by making queries from our API documentation page .

Request schema

To make a request, include your API key by adding the following to the request header:

x-api-key: YOUR-API-KEY

Inputs

The request body can follow the same schema as our other endpoints, with the addition of optional persons_to_screen and tin fields:

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

Your query 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 a city, state, or postal_code.

Watchlist screening and TIN verification are sold as separate add-on services:

If you are doing EIN/TIN verification, pass a 9-digit string in the tin 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.

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, and 1 person. To maximize match rates, Enigma looks at all combinations of names and addresses.

Query Parameters

package: The package parameter specifies the set of attributes you want returned with your matches. Package values can be "identify" or "verify" (the default). Read more about packages on the KYB-Specific Attributes and Objects page.

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 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. The default value is 0.5.

top_n: The 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

curl --request POST 'https://api.enigma.com/v1/kyb/?package=identify&attrs=watchlist,tin_verification&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"
            }
        ],
        "tins": [
            "000000000"
        ],
        "persons_to_screen": [
            {
                "first_name": "Example",
                "last_name": "Name",
                "date_of_birth": "1990-01-01"
            }
        ]
    }
}'

Request object reference

address object input schema

{
  "street_address1": string,
  "street_address2": string,
  "city": string,
  "state": string,
  "postal_code": string
}

person object input schema

{
  "first_name": string,
  "last_name": string
}

person_to_screen object schema

{
  "first_name": string,
  "last_name": string,
  "date_of_birth": string, // YYYYMMDD or YYYY-MM-DD
  "address": object
}

// Date of birth and address are optional.

Example (minimum detail request)

{
  "data": {
    "names": ["Enigma Technologies"],
    "addresses": [{
      "state": "NY"
    }]
  }
}

Example (maximum detail request)

{
  "data": {
    "names": ["Enigma Technologies", "Enigma"],
    "addresses": [{
      "street_address1": "245 5th Avenue",
      "street_address2": "Fl 17",
      "city": "New York",
      "state": "NY",
      "postal_code": "10016"
		},
    {
      "street_address1": "251 LITTLE FALLS DR",
      "street_address2": "",
      "city": "Wilmington",
      "state": "DE",
      "postal_code": "19808"
    }
    ],
    "persons": [{
      "first_name": "Hicham",
      "last_name": "Oudghiri"
    }],
    "websites": ["enigma.com"],
    "tins": ["123456789"], 
    "persons_to_screen": [{
      "first_name": "Jane",
      "last_name": "Doe",
      "date_of_birth": "1951-12-31",
      "address": {
        "street_address1": "2600 Elm Street",
        "street_address2": "Apt 42",
        "city": "Cloudcroft",
        "state": "NM",
        "postal_code": "88317"
       }
      },
     {
       "first_name": "John",
       "last_name": "Doe",
       "date_of_birth": "1984-01-30",
       "address": {
         "street_address1": "4800 Maple Avenue",
         "street_address2": "Suite 110",
         "city": "Austin",
         "state": "TX",
         "postal_code": "73301"
       }
     }
    ]
  }
}

Response object reference

Unlike Enigma's other endpoints, the KYB API will return your matches and their attributes in response to your call — there is no need to hit another endpoint to collect more data.

Top level response object

{
  "response_id": string,
  "risk_summary": {
    "overall_risk_rating": string, // ("high", "low")
    "legal_existence_risk_rating": string, // ("high", "low")
    "activity_risk_rating": string, // ("high", "low")
    "watchlist_risk_rating": string, // ("high", "low")
    "tasks": [
      {
        "task_name": string, 
        "status": string, 
        "result": string, 
        "reason": string
      }
  },
  "data": {
    "best_match": object,
    "legal_entities": array[object],
    "brands": array[object],
    "watchlists": array[object]
  }
}

Second and third level response objects

best_match object

This object shows the overall match confidence and matched fields. Matched fields are the Enigma fields that the input parameters matched to.

{
	"match_confidence": number,
	"matched_fields": object // {"field": "value"} for fields that were matched on
}

legal_entity object

This object is a view into the Secretary of State registrations for a given business. Our dataset of legal entities contains all registration filings which Enigma has access to.

{
	"enigma_id": string,
	"data_sources": array[string],
	"match_confidence": number,
	"matched_fields": object, // {"field": "value"} for fields that were matched on
	"registrations": array[object]
}

registration object

This object, contained within the legal entity object, is a replica of the information on the Secretary of State filing.


{
  "issue_date": string, // YYYY-MM-DD
  "registration_state": string, // Two-letter abbrevation
  "file_number": string,
  "registered_name": string,
  "jurisdiction_type": string, // ("domestic", "foreign")
  "home_jurisdiction_state": string, // Two-letter abbrevation
  "standardized_status": string, // ("active", "inactive")
  "registration_status": string,
  "persons": [
    {
      "full_name": string,
      "titles": array[string]
    }
  ], 
  "addresses": [
    {
      "type": string,
      "street_address1": string,
      "street_address2": string,
      "city": string,
      "state": string, // Two-letter abbrevation
      "postal_code": string,
      "country": string
    }
  ]
}

brand object

This object is a viewpoint into the operating names and addresses of a business, though it may also include legal entity name and addresses.

This object supplements the legal entity object with additional firmographic data. It is derived from our business ID endpoint. (See our Identity and Firmographics Attributes documentation for more details on these attributes.)

{
  "enigma_id": string,
  "data_sources": array[string],
  "match_confidence": number,
  "matched_fields": object, // {"field": "value"} for fields that were matched on
  "activities": {
    "compliance_risk_level": string,
    "activity_types": [{"activity_type": string}]
  },
  "names": array[string],
  "addresses": array[object],
  "industries": array[object],
  "websites": array[string]
}

watchlist object

In addition to the business and any persons in your query, Enigma looks at company aliases and associated people on the registration filing to surface any related people or business names that may appear on the OFAC sanctions watchlists.

{
  "enigma_id": string,
  "match_confidence": number,
  "matched_fields": object, // {"field": "value"} for fields that were matched on
  "watchlist_entity": {
    "watchlist_name": string,
    "entity_type": string, // ('organization', 'person')
    "full_name": string, // None if entity_type is 'organization'
    "organization_name": string, // None if entity_type is 'person'
    "dob": string, // YYYY-MM-DD; None if entity_type is 'organization' or unavailable for person record
    "full_address": string // 
  }
}

Example full response

{
  "response_id": "aweradf972d-2ksf-8h85-097s-fasd54h3fhg8",
  "risk_summary": {
    "legal_existence_risk_rating": "low",
    "activity_risk_rating": "low",
    "watchlist_risk_rating": "high",
    "overall_risk_rating": "high",
    "tasks": [
            {
                "task_name": "address_verification",
                "status": "success",
                "reason": "An input address and an address we identified match exactly"
            },
            {
                "task_name": "sos_address_verification",
                "status": "success",
                "result": "address_approximate_match",
                "reason": "An input address and an address on an SoS record match approximately"
            },
			      {
                "task_name": "name_verification",
                "status": "success",
                "reason": "An input name and a name we identified match exactly"
            },
            {
                "task_name": "sos_name_verification",
                "status": "success",
                "result": "name_exact_match",
                "reason": "An input name and a name on an SoS record match exactly"
            },
      			{
                "task_name": "tin_verification",
                "status": "success",
                "result": "tin_verified",
                "reason": "TIN and Name combination matches IRS records"
            },
     			  {
                "task_name": "watchlist",
                "status": "failure",
                "result": "watchlist_hits",
                "reason": "1 hit(s) identified on the consolidated sanctions list (including OFAC)"
            }
        ]
  },
  "data": {
    "best_match": {
      "match_confidence": 1.0,
      "matched_fields": {
        "name": "Example Company",
        "street_address1": "720 Main Blvd",
        "street_address2": "",
        "city": "Alamogordo",
        "state": "NM",
        "postal_code": "88310"
      }
    },
    "legal_entities": [{
      "enigma_id": "L1238700000",
      "data_sources": ["Corporate Registrations"],
      "match_confidence": 1.0,
      "matched_fields": {
        "name": "Example Company",
        "street_address1": "720 Main Blvd",
        "street_address2": "",
        "city": "Alamogordo",
        "state": "NM",
        "postal_code": "88310"
     },
     "registrations": [{
       "issue_date": "2010-10-20",
       "registration_state": "NM",
       "file_number": "0931830",
       "registered_name": "Example Company LLC",
       "jurisdiction_type": "domestic",
       "home_jurisdiction_state": "NM",
       "standardized_status": "active",
       "registration_status": "in existence",
       "persons": [{
          "name": "Joe Smith",
          "titles": ["member"]
       },
       {
          "name": "UNITED STATES CORPORATION AGENTS, INC",
          "titles": ["registered agent"]
       }
       ],
       "addresses": [{
          "type": "headquarters",
          "street_address1": "720 MAIN BLVD",
          "street_adress2": "#100",
          "city": "CLOUDCROFT",
          "state": "NM",
          "postal_code": "88317",
          "country": "US"
       },
       {
         "type": "registered_agent",
         "street_address1": "4801 LANG AVE NE STE 110",
         "street_address2": null,
         "city": "ALBUQUERQUE",
         "state": "NM",
         "postal_code": "87109",
         "country": "US"
       }
      ]
     }]
    }],
    "brands": [{
      "enigma_id": "B002528db000016900",
      "data_sources": ["Corporate Registrations"],
      "match_confidence": 0.99,
      "matched_fields": {
        "name": "Example Company LLC",
        "street_address1": "720 MAIN BLVD",
        "city": "Cloudcroft",
        "state": "NM",
        "postal_code": "88317"
     },
     "activities": {
       "compliance_risk_level": "high",
       "activity_types": [
         {
           "activity_type": "Gambling and Sports Betting"
         }
       ]
     },
      "names": [{
        "name": "Example Company LLC"
      }],
      "addresses": [{
        "street_address1": "720 MAIN BLVD",
        "street_adress2": null,
        "city": "CLOUDCROFT",
        "state": "NM",
        "postal_code": "88317",
        "country": "US",
        "type": null
      }],
      "industries": [{
        "classification_description": "gambling house",
        "classification_type": "enigma_description"
      },
      {
        "classification_code": "713290",
        "classification_description": "Other Gambling Industries",
        "classification_type": "NAICS_2017"
      }],
      "websites": ["examplecompanyurl.site"]
    }],
    "watchlists": [{
      "enigma_id": "11161737",
      "match_confidence": 1.0,
      "matched_fields": {
        "person.first_name": "John",
        "person.last_name": "Doe"
      },
      "watchlist_entity": {
        "watchlist_name": "djw/SIP",
        "entity_type": "person",
        "full_name": "John Doe",
        "organization_name": null,
        "dob": null,
        "full_address": null
      }
    }]
  }
}