Overview

Enigma's KYB Endpoint enables a user to retrieve specific attributes across our Businesses and Registration Filings data asset. Unlike the Match and ID endpoints, you can retrieve attributes with just one query, as opposed to hitting a match and an ID endpoint separately.

For technical guidance around this endpoint, see our API Reference section.

Making a request to kyb/{ID}

To make a KYB API request, ensure you first enter your API key by adding the following to the request header:

x-api-key: YOUR-API-KEY

Query Parameters

Package: Call a set of attributes to return by using the package parameter. Package values can be identify or kyb. Read more about packages on the KYB-Specific Attributes and Objects page.

Number of matches returned: By setting top_n to the desired number of matches to be returned. Each match returned will have a match confidence higher than the provided match_threshold. If not configured, the default value is 1.

Example:

POST /v1/kyb/?package=kyb&top_n=1
...

Inputs
The match endpoint supports POST requests. Minimum inputs include two of each of the objects referring to the business address, business name, or persons. The address object must contain at least one field value within city, state, or zip code.

The request body follows the same schema as our other endpoints, with the addition of an optional persons_to_screen field:

# POST /v1/kyb/?package=kyb&top_n=1
# persons_to_screen supports max 4 elements
{
  "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
  },
"persons_to_screen": array[object]
}

Example (minimum detail request)

{
  "name": "Enigma Technologies",
  "address": {
    "state": "NY"
  }
}

Matching methodology

Enigma's KYB match endpoint operates differently depending on the input parameters
- If only a business name and a state are provided, Enigma only matches based on an exact match requirement, i.e. the legal entity name input must match exactly the name in the Enigma data asset.
  - This is to ensure 100% precision matches when only a state is provided.
- Under all other conditions, matching is consistent with the methodology on the Match Endpoint

Combinatorial matching

Enigma's KYB endpoint allows for combinatorial matching, e.g. up to two names and two addresses can be included, and Enigma can attempt to match against four possible total combinations of inputs.

For each individual business query, the maximum number of inputs for each field is:

2 names max
2 addresses max
1 person max
1 website max
4 persons to screen max

Multiple-inputs request schema

// POST /v1/kyb/?package=kyb&top_n=1
// Default for top_n=1 which returns the best match
// Include up to 2 names, 2 addresses, 1 website, and 1 person.
// Enigma will look at all four combinations of names and addresses in the API to maximize fill and match.
// Up to 4 persons_to_screen will be checked against watchlists
{
  "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
    "persons_to_screen": array[object] // accepts 4 inputs maximum
  }
}

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,
  "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"],
    "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

Top level 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, // ("address_verification","name_verification")
        "status": string, // ("success","failure")
        "reason": string
      }
  },
  "data": {
    "best_match": object,
    "legal_entities": array[object],
    "brands": array[object],
    "watchlists": array[object]
  }
}

Second and third level 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]
}

Registrations 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
    }
  ]
}

Businesses object

Also known as Brands, 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 is used to return basic firmographics as part of the Identity package or supplement the legal entity object with additional firmographics and industries. It is derived from the existing Business 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]
}

Watchlists 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"
  },
  "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": null,
          "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
      }
    }]
  }
}