API

Performing enrichment workflows via the API is a two-step process.

  1. Identifying the right business profile
  2. Retrieving attributes from that profile

As a result, Enigma’s API has two endpoints, each serving those functions respectively.

  1. The Match Endpoint enables a user to identify which of Enigma’s business profile(s) corresponds to a business of interest. A user submits identifying information about a business and is returned a potential list of matching profiles with confidence levels. The result of using this endpoint is identifying an Enigma ID(s) that a user may want to query in the ID Endpoint.
  2. The ID Endpoint enables a user to retrieve specific attributes for a given business profile.

For technical guidance around either of these endpoints, see the API Reference section.

Enigma recommends using the API for enrichment workflows if you are building a full integration and if:

  1. Your application’s concurrent request need is small (up to 50 RPS for matching and 200 RPS for ID lookups).
  2. Your application needs to make very frequent enrichment requests.
  3. You need to programmatically enrich your records.

Match Endpoint

Overview

The match endpoint is used to identify which of Enigma’s profiles correspond to a business that is of interest to a user. In order to use the match endpoint, a user must have identifying information about a business like its name, address, website, etc. Importantly, a user can specify whether they want a business match or a business location match - for more information on these entities see the section on Enigma’s data structure.

Making a request to businesses/match

Header
To make a businesses 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
Business entity type: Set business_entity_type to either business or business_location. If not configured, the default entity type returned is business_location.

Match Threshold: By setting match_threshold to the desired value between 0 and 1. This will serve as a threshold by which to filter results based on the match_confidence (see more on match confidence below) determined by the Enigma match model. If not configured the default value is 0.5.

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.

Show Non-Matches: In the event that no result has a match confidence higher than the provided match_threshold, setting show_non_matches to 1 will result in the API returning as many matches as possible up to top_n.

Inputs
The match endpoint supports POST requests. The minimum payload required will depend on whether you are performing a business or business location match.

Enigma currently allows for matching based on the following inputs:

Business LocationBusinesses
Business NameYesYes
Business AddressYesYes
Associated PersonYesYes
WebsiteNoYes

Associated person represents a potential owner of the business.

Enigma does not currently allow for phone numbers or EINs to be used as inputs for business matching, butt plans to do so in the future.

Business Match
The request body for requesting a business match will have the following fields:

{
"name": "",
"person": {
   "first_name": "",
   "last_name": ""
 },
  "address": {
      "street_address1": "",
      "street_address2": "",
      "city": "",
      "state": "",
      "postal_code": ""
  },
  "website": ""
}

If at least one match is found, the response to this POST request will contain an Enigma ID corresponding to each matched business entity. The Enigma ID is the unique identifier for each profile in Enigma’s dataset. Additionally, the response object will contain a list titled business_location_enigma_ids. This is a list of Enigma IDs corresponding to the business locations associated with that business. For a full description of fields included in the response refer to the API Reference section.

Enigma allows for the following combination of inputs for business matching:

  • Website URL (with or without any other information)
  • Name + Address + Person
  • Name + Address
  • Name + Person
  • Person + Address

If providing a website URL in the request body, a business match is first attempted using only the URL. If a match on URL is successful, the other fields provided in the request body are ignored.

If a match on URL is unsuccessful or a URL was not provided, then the endpoint will look to using the other fields (business name, address and/or person) to attempt a match on a corresponding business location and return the Business entity that the location is associated with.

Business Location Match
The request body for making a business location match will have the following fields:

{
"name": "",
"person": {
   "first_name": "",
   "last_name": ""
 },
  "address": {
      "street_address1": "",
      "street_address2": "",
      "city": "",
      "state": "",
      "postal_code": ""
  },
}

As with business matching, if at least one match is found, the response to this POST request will contain an Enigma ID corresponding to each matched business location entity. For a full description of fields included in the response refer to the API Reference section.

Enigma allows for the following combination of inputs for business location matching:

  • Name + Address + Person
  • Name + Address
  • Name + Person
  • Person + Address

Website URL is an invalid parameter for performing a business location match. This is because there are often multiple locations associated with a business’s website.

We recommend storing the Enigma ID in order to make subsequent calls to the ID Endpoint, where you’ll be able to call the same entity based on its ID, and - most importantly - pull Enigma’s attributes for that entity.

The Enigma ID can also be used for entity resolution across your internal data set.

Matched Fields

Alongside each potential match, Enigma provides an attribute called matched_fields. This attribute shows the business name, address, person and/or website in Enigma’s data asset that was found to be similar to the query inputs.

Match Confidence

Along with each potential match, Enigma provides a confidence score called match_confidence.

This attribute - the output of our match model - is a quantitative representation of the proximity between the information provided in the request input and the business profile. The score ranges from 0 to 1, where 1 indicates an exact match.

How should the match confidence score be interpreted?

The score does not translate to a percent probability of a match. The score is a measure of a combination of string and semantic similarity between the user provided match inputs and the Enigma business or business location entity.

  • A score of 0.75 does not mean it is a 75% probability of a match
  • A score of 0.25 does not mean it is a 25% probability of a match
  • Enigma considers anything with a match score of >0.5 to be a match with estimated precision of 95% or higher. That is to say, Enigma expects there to be <5% false positives for matches with a score of 0.5 or above.

ID Endpoint##

Overview

Enigma's ID Endpoint enables a user to retrieve specific attributes for a given business profile. The user inputs the Enigma ID they want to retrieve information from, and selects which attributes they want returned.

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

Making a request to businesses/{ID}

To make a businesses ID 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

Attrs: Enter the desired set of attributes using this parameter. More than one attribute can be passed by using a comma (,) separated list. By default a number of basic attributes will be returned.

Lookback Months: If requesting a time series attribute (currently only the Merchant Transaction Signals attributes fall into this category), historical data going back to Jan 2017 (where applicable) is available. Set the lookback_months parameter to an integer greater than 0 to request the corresponding number of months of data. If not configured, the most recently available 1 month of data will be returned. To request the maximum number of months available set this parameter to *.

Inputs

The ID endpoint requires GET requests. Use the Enigma ID obtained from the match response as a path parameter in the request.

Below is an example of a GET request to pull data on Enigma using its unique Enigma ID:

curl -X GET 'https://api.enigma.com/businesses/B00233ee1f5e?attributes=industries
-H 'x-api-key: YOUR-API-KEY' | python -m json.tool

Below is an example response for the above request:

{
   "enigma_id": "B00233ee1f5e",
   "websites": [
       "enigma.com"
   ],
   "names": [
       {
           "name": "ENIGMA TECHNOLOGIES INC"
       }
   ],
   "addresses": [
       {
           "street_address1": "245 5TH AVE",
           "street_address2": "FL 17",
           "city": "NEW YORK",
           "state": "NY",
           "postal_code": "10016"
       }
   ],
   "business_location_enigma_ids": [
       "E0013165d200004146",
       "E000b32fc000002615",
       "E000f971c20000020c"
   ],
   "data_sources": [
       "Public Web Directories",
       "Third-Party Active Business",
       "UCC Loans",
       "Corporate Registrations",
       "H1B Visa Applications",
       "Card Transactions"
   ]
"industries": [
       {
           "classification_code": "541511",
           "classification_description": "Custom Computer Programming Services",
           "classification_type": "NAICS_2017"
       }
   ]
}

Try out our API in our Quick Start tool or by hitting the API directly.

Note: Enigma IDs are not persistent over time. While you may find that the Enigma IDs for many businesses and business locations do not change often, we do not guarantee that they will not change.