KYB endpoint
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 thepersons_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
}
}]
}
}
Updated 3 months ago