Getting started

Introduction

Enigma’s Businesses product provides automated business intelligence you can integrate into your SMB applications and workflows. This guide helps get you up and running with the Businesses API as quickly and easily as possible.

We’ll start with an overview of the Businesses API and then walk through simple integration examples in Python, Javascript, and cURL.

Platform Overview

Let’s begin with the basics of Enigma’s data platform.

Enigma Console

The Console is your home for integrations with Enigma’s APIs. This is where you can create your Enigma account, obtain an API key, configure account settings and track usage and billing.

API Keys

In the Console home page, the first thing you’ll see is your API Secret Key. You’ll need to pass this key in your request headers in order to successfully make calls.

If you copy your key to another location, make sure that it’s secure in order to prevent someone else from making calls using your account.

Endpoints

The Business API currently consists of the following endpoints:

Match - https://api.enigma.com/businesses/match

  • Use this endpoint when you have precise information about a business, like name, address, and associated people
  • The endpoint runs a match model and returns a match confidence score so you can be confident you’ve identified the right business

Lookup by ID - https://api.enigma.com/businesses/{enigma_id}

  • Retrieve basic profile and premium attributes on a business using its unique Enigma ID

Accessing Business Data

Making a Match Request

The Match endpoint supports POST requests, which require a payload containing Business Name plus one of the two input fields below:

  • Business Address
  • Associated Person (typically an officer or owner)

To view the required format and child attributes for each input, see our API refs.

The request runs a match model against Enigma’s SMB data asset. The model uses a variety of data science techniques to query Enigma’s SMB records and surface the businesses that most closely resemble the inputs provided.

Below is an example of a POST request to look up a business using its name and address. (The API works analogously when the user instead inputs business name and associated person).

Interpreting the Response

If the business name and address specified match one or more of the 30m+ small and medium businesses represented in our datasets, the API returns a JSON response with information about the matching business.

More About Matching

The match_confidence attribute represents the proximity between the information provided for the business and the information contained in our records. The score ranges from 0 to 1, where 1 indicates an exact match.

The API defines a match – and thus returns a data object for that business – as an entity whose match_confidence meets a threshold of 0.5 (this threshold presents the optimal tradeoff between false negatives and false positives, given our match models).

Configuration

The API response can be modified with parameters to return multiple results (more than 1 match) or non-matches (businesses where match_confidence is below 0.5):

  • top_n: N - API returns the top N business results in a list
  • show_non_matches: 1 - API returns non-matched businesses, with the is_match attribute set to false.

Making an ID Request

The ID endpoint supports GET requests, where an Enigma ID is appended to the Businesses API base URL.

Below is an example of a GET request to look up Enigma Technologies using its unique Enigma ID.

By default, the ID endpoint returns the business’ basic profile.

Retrieving Premium Attributes

In addition to the business profile, the ID endpoint allows users to access our premium attributes. The attrs parameter allows users to specify which premium data they want returned. Different attributes have different prices, and each API call is billed according to the attributes requested.

An example of a premium attribute is verification. A user interested in the verification attribute can set attrs=ver. The response will contain the business’ basic profile plus a verification score and its components.

Interpreting the Response

If a valid Enigma ID is provided, the API returns a JSON response with information about the specified business, including requested premium attributes.

Questions & Feedback

If you have any questions or would like to provide feedback, please reach out to support.