Match Endpoint

Enigma's Match endpoint is built for retrieval of business records from our SMB database.

The Match endpoint is built for retrieval of business records from Enigma’s SMB data. As the name suggests, the purpose of this endpoint is to determine whether Enigma has a business record that corresponds to - or matches - a business that is of interest to you.

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

Overview

For example, suppose an SMB lender receives an application from a business for a loan. The application will contain some basic information about a business - such as the business name, address, and owner.

The match endpoint enables the lender to supply these inputs and instantly find a match.

Importantly, a user can specify whether they want a business match or a business location match - for more information on Enigma's business hierarchy, see the subpage Business Hierarchy: Business vs. Business Location. By default, the API returns business location matches.

Find the right business in Enigma’s records

Learn more information about it from our detailed business attributes - such as registrations, website, and corporate structure.

21932193

📘

Enigma has records for over 30 million businesses - through the match endpoint, you can easily query this data set to uniquely find the right one and obtain its business profile.

Making a request to businesses/match

Header

To make a Businesses API request, first ensure to enter your API key by adding the following request header.

'x-api-key': 'YOUR-API-KEY'

Inputs

Business Location Match
The Match endpoint supports POST requests, which require a payload containing two of the following three input fields:

  • Business Name
  • Business Address
  • Associated person (typically an officer or the business owner)

Business Match
Enigma aggregates Business Locations to the Business level by enriching Business Locations with URLs. If one or more business locations have the same URL, Enigma will assign new Enigma ID prefixed with the letter "B" to the group of business locations. An Enigma Business must contain at least one Business Location.

URL matching: The Business match first looks up a match on a URL if it is included as part of the request body. URLs can include prefixes like "http://" or "www.", as well as subdomains like test.example.com. Platforms that host business websites, like Facebook or Yelp, are filtered out during the enrichment process.

Fallback logic: Then, if there is no exact URL match or if no URL is included, it will fall back to a reverse lookup of business locations using two of the three below.

  • Business Name
  • Business Address
  • Associated person (typically an officer or the business owner)

If one of the returned Business Locations also has a URL and therefore can be linked up to the Business level, then the entire Business is returned.

Sometimes, a Business Location does not have any associated URL and therefore no Business match will return - in that case, we encourage the user to query the default Business Location.

To maximize match rates, we recommend that a user query both the Business and the Business Location.

Request

Below is an example of a POST request to lookup a business location using its name and address. (Note that the API works analogously for any other combination of two inputs).

import requests
import json
url = 'https://api.enigma.com/businesses/match'
 # add "?business_entity_type=business" as part of the query string to look up a business instead
headers = {
  'Content-Type': 'application/json',
  'x-api-key': 'YOUR-API-KEY'
}
params = {   }
body = {
  "name": "Enigma Technologies, Inc.",
  "person": {
    "first_name": "",
    "last_name": ""
  },
  "address": {
    "street_address1": "245 5th Ave",
    "street_address2": "",
    "city": "New York",
    "state": "NY",
    "postal_code": "10016"
  }
}
response = requests.post(
  url, 
  json=body, 
  params=params, 
  headers=headers
).json()
let requesturl = 'https://api.enigma.com/businesses/match';
 // add "?business_entity_type=business" as part of the query string to look up a business instead
let params = {
 "name": "Enigma Technologies, Inc.",
  "person": {
    "first_name": "",
    "last_name": ""
  },
  "address": {
    "street_address1": "245 5th Ave",
    "street_address2": "",
    "city": "New York",
    "state": "NY",
    "postal_code": "10016"
  }
};
// Configure request headers
let headers = new Headers();
headers.append('Content-Type', 'application/json');
headers.append('x-api-key', 'YOUR-API-KEY');
fetch(requesturl, {
  method: 'POST',
  body: JSON.stringify(params),
  headers: headers
})
.then(response => response.json())
.then(function (response) {
  console.log(response);
})
.catch(function (error) {
  console.log(error);
});
curl -X POST 'https://api.enigma.com/businesses/match' \
     -H 'Content-Type: application/json' \
     -H 'x-api-key: YOUR-API-KEY' \
     -d '{ \
  "name": "Enigma Technologies, Inc.", \
  "person": { \
    "first_name": "", \
    "last_name": "" \
  }, \
  "address": { \
    "street_address1": "245 5th Ave", \
    "street_address2": "", \
    "city": "New York", \
    "state": "NY", \
    "postal_code": "10016" \
  } \
} \' | python -m json.tool

The Match Model

Once you send the request, Enigma runs a match model against our SMB data. The model uses precision data science techniques to query Enigma’s SMB records and return the business that most closely resembles the inputs provided.

Interpreting the Response

If the request inputs match one of the SMBs represented in our data, the API returns a JSON response containing the profile of the matching business. The profile is made up of our basic attributes, which helps you learn more about the business and be sure that you’ve identified the correct one.

The response also denotes the fields that were matched to your input, so that you can understand why that specific business result was returned.

Enigma ID

In the response you’ll also find the business’s Enigma ID. This is the unique, persistent ID for the entity in Enigma’s SMB data, assigned as a result of our expert Entity Resolution process.

Response
{
  "businesses": [
    {
      "match_confidence": 0.99,
      "matched_fields": {
        "name": "ENIGMA TECHNOLOGIES INC.",
        "address": {
          "street_address1": "245 5 AVE",
          "street_address2": "FL 17",
          "city": "NEW YORK",
          "state": "NY",
          "postal_code": "10016"
        }
      },
      "is_matched": true,
      "enigma_id": "E000f971c20000020c",
      "data_sources": [
        "Third-Party Active Business",
        "UCC Loans",
        "Corporate Registrations",
        "H1B Visa Applications",
        "Card Transactions"
      ],
      "aliases": [
        "ENIGMA TECHNOLOGIES INC",
        "ENIGMA TECHNOLOGIES INC WA",
        "ENIGMA TECHNOLOGIES"
      ],
      "addresses": [
        {
          "street_address1": "245 5 AVE",
          "street_address2": "FL 17",
          "city": "NEW YORK",
          "state": "NY",
          "postal_code": "10016"
        },
        {
          "street_address1": "245 5 AVE",
          "street_address2": "",
          "city": "NEW YORK",
          "state": "NY",
          "postal_code": "10016"
        },
        {
          "street_address1": "600 WEST MAIN",
          "street_address2": "",
          "city": "JEFFERSON CITY",
          "state": "MO",
          "postal_code": "65101"
        },
        {
          "street_address1": "245 5 AVE",
          "street_address2": "17 FL",
          "city": "NEW YORK",
          "state": "NY",
          "postal_code": "10016"
        },
        {
          "street_address1": "245 5 AVE 17",
          "street_address2": "",
          "city": "NEW YORK",
          "state": "NY",
          "postal_code": "10016"
        },
        {
          "street_address1": "245 5 AVE",
          "street_address2": "FL 17",
          "city": "NEW YORK",
          "state": "NY",
          "postal_code": ""
        },
        {
          "street_address1": "501 LOUISIANA AVE",
          "street_address2": "",
          "city": "BATON ROUGE",
          "state": "LA",
          "postal_code": "70802"
        },
        {
          "street_address1": "",
          "street_address2": "",
          "city": "NEW YORK",
          "state": "NY",
          "postal_code": ""
        }
      ],
      "ein": [],
      "associated_people": [
        {
          "name": "HICHAM OUDGHIRI",
          "titles": [
            "CEO",
            "OFFICER"
          ]
        },
        {
          "name": "OUDGHIRI HICHAM",
          "titles": [
            "OFFICER"
          ]
        }
      ],
      "registered_agents": [
        "ENIGMA TECHNOLOGIES INC",
        "SECRETARY OF STATE",
        "CORPORATION SERVICE COMPANY D B A CSC-LAWYERS INCORPORATING SERVICE COMPANY",
        "CORPORATION SERVICE COMPANY"
      ],
      "phone_numbers": [],
      "websites": [
        "http://www.enigma.com/"
      ],
      "registrations": [
        {
          "state": "NY",
          "issue_date": "2011-11-09",
          "file_number": "4163621"
        },
        {
          "state": "CA",
          "issue_date": "2018-01-17",
          "file_number": "C4106346"
        },
        {
          "state": "WA",
          "issue_date": "2017-08-20",
          "file_number": "604163534"
        },
        {
          "state": "MO",
          "issue_date": "2018-07-28",
          "file_number": "F001330176"
        },
        {
          "state": "DC",
          "issue_date": "2017-08-18",
          "file_number": "EXTUID_4192167"
        },
        {
          "state": "LA",
          "issue_date": "2016-05-10",
          "file_number": "42261937F"
        },
        {
          "state": "TX",
          "issue_date": "2017-10-27",
          "file_number": "0802847446"
        },
        {
          "state": "HI",
          "issue_date": "2019-01-26",
          "file_number": "100516F1"
        },
        {
          "state": "TN",
          "issue_date": "2019-01-26",
          "file_number": "001007445"
        },
        {
          "state": "MA",
          "issue_date": "2020-04-28",
          "file_number": "001435918"
        }
      ],
      "corporate_structure": "CORPORATION",
      "year_incorporated": "2011"
    }
  ]
}

📘

For further information on this topic, read about Entity Resolution in our Methods and Models section

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 business result based on its ID, and - most importantly - pull Enigma’s premium attributes for that entity.

The Enigma ID can also be used for Entity Resolution across your internal data set.

Match Confidence

You’ll notice the response also contains an attribute 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 returned from our records. The score ranges from 0 to 1, where 1 indicates an exact match.

The Businesses API defines a match - and thus returns a business object - as a result whose match_confidence meets a threshold of 0.5. (From our in-depth research and numerous studies, this threshold provides the highest accuracy and while maintaining the best tradeoff between precision and recall).

📘

Our match model has been honed over time to find the best result from over 30m SMB profiles. To learn more, read about our Match Models in our Methods and Models section.

Configuration

Depending on your needs, the API response can be configured using parameters to modify:

  • The match threshold

    By setting match_threshold to the desired value between 0 and 1

  • The number of matches returned

    By setting top_n to the desired number of results

  • Show_non_matches

    In the event that no result meets the match_threshold, set show_non_matches: 1 so that the API still returns the best result it can find

  • The business entity type

    By setting business_entity_type to either "business" and "business_location". If not configured, the default entity type returned is "business_location".