Skip to main content

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​

Authentication​

To make a businesses API request, ensure you first enter your API key in the request header:

x-api-key: YOUR-API-KEY

Query Parameters​

ParameterTypeDefaultDescription
business_entity_typestringbusiness_locationSet to either business or business_location
match_thresholdfloat0.5Value between 0 and 1 to filter results based on match confidence
top_ninteger1Number of matches to return
show_non_matchesinteger0Set to 1 to return matches below threshold if no results above threshold
prioritizationstring-Set to MTX to prioritize profiles with revenue data
Revenue Data

Business revenue will always be greater than business location revenue and be returned at the brand level. For example, McDonald's revenue will be returned across all businesses, not just a single location - please be sure to stipulate business_location if you are looking for the revenue of an individual location.

Supported Input Fields​

FieldBusiness LocationBusiness
Business Name✅✅
Business Address✅✅
Associated Person✅✅
Website❌✅
Input Limitations

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

Request Examples​

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

Valid input combinations:

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

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

Understanding Results​

Matched Fields​

Alongside each potential match, Enigma provides an attribute called matched_fields. This 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 score ranges from 0 to 1, where 1 indicates an exact match.

Confidence Score Interpretation

The score does not translate to a percent probability of a match:

  • 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

Match Models​

Why is matching important?​

Matching means that you don't need to have perfect information about a business in order to find the correct business profile. The models are highly optimized around the relevancy of the data returned. This means that when you see a match, you can be very confident that it's the right business. It also means that when there are no relevant results, no match will be returned.

How the matching system works​

  1. For business matches, first check for exact URL match (confidence = 1)
  2. If no URL match (or business location request):
    • Generate potential matches based on provided fields
    • Compare using machine learning model considering:
      • String distance between company names
      • Semantic similarities between names
      • String distances between addresses
      • Shared tokens between names and addresses
  3. Neural network generates final confidence score

The 0.5 Threshold​

The default 0.5 threshold provides optimal precision-recall tradeoff:

  • Accuracy: Share of observations classified correctly
  • Precision: Share of predicted matches that are true matches
  • Recall: Share of true matches classified correctly
Threshold Configuration

If making a match request without complete address and without complete person name, use a lower threshold (0.2-0.35 recommended).

Prioritizing MTX Transaction Data​

Use prioritization=MTX when:

  • Multiple profiles cross the 0.5 threshold
  • You want to prioritize profiles with financial/revenue data
  • Different profiles represent facets of the same business

For more details on how profiles relate, see Entity Resolution.

Last updated on