Quickstart Guide

Business Coder

Introduction

Business Coder can be used to:

  • Search for businesses using the phone number, stock ticker, and web address.
  • Discover business SIC codes, sales volumes, employee sizes, phone numbers, etc.

Basic Order of Operations

Real Time

  • Choose JSON or REST service.
  • Create an instance of the request object.
  • Populate the request element License Key with your License Key.
  • Add input business info to the “Records” array with a record.
  • Call the method and pass in the request to the service using the WEB endpoint for JSON requests.
  • Examine and parse the response from the reply object back from the service.
  • Interpret the results

Batch

  • Choose JSON or REST service.
  • Create an instance of the request object.
  • Populate the request element License Key with your License Key.
  • Add input business info to the “Records” array with anywhere from 1 to 100 records. (Make sure each record in the request has a unique Record ID.)
  • Call the method and pass in the request to the service using the WEB endpoint for JSON requests.
  • Examine and parse the response from the reply object back from the service.
  • Interpret the results

Input Request

NOTE: This service deals with multiple languages and scripts. It expects UTF-8 character encoding. Be on the lookout for question marks (?), squares (▖) or other weird characters like �. They may be an indication of encoding issues and may result in data loss. Bad encoding or character loss is not something our service can correct for you.

NOTE: Business Coder will only process requests if any of the minimum input requirements below are satisfied.

Real Time

With a REST request, you can include all the input along with the URL for an easy and quick way of sending a single record.

Using Address as Input

curl -X GET 
https://businesscoder.melissadata.net/WEB/BusinessCoder/doBusinessCoderUS?id={LicenseKey}&cols={Columns}&opt=
{Options}&rec={Record ID}&comp={Company}&a1={Address1}&a2={Address2}&city={City}&state={State}&postal={Postal
Code}&ctry={Country}

Using Melissa Address Key (MAK) as Input

curl -X GET 
https://businesscoder.melissadata.net/WEB/BusinessCoder/doBusinessCoderUS?id={LicenseKey}&cols={Columns}&opt=
{Options}&rec={Record ID}&mak={Melissa Address Key}

Using StockTicker as Input

curl -X GET 
https://businesscoder.melissadata.net/WEB/BusinessCoder/doBusinessCoderUS?id={LicenseKey}&cols={Columns}&opt=
{Options}&rec={Record ID}&stock={Stock Ticker}

Using Web Address as Input

curl -X GET 
https://businesscoder.melissadata.net/WEB/BusinessCoder/doBusinessCoderUS?id={LicenseKey}&cols={Columns}&opt=
{Options}&rec={Record ID}&web={Web Address}

Using Phone as Input

curl -X GET 
https://businesscoder.melissadata.net/WEB/BusinessCoder/doBusinessCoderUS?id={LicenseKey}&cols={Columns}&opt=
{Options}&rec={Record ID}&phone={Phone}

Using FreeForm as Input

curl -X GET 
https://businesscoder.melissadata.net/WEB/BusinessCoder/doBusinessCoderUS?id={LicenseKey}&cols={Columns}&opt={Options}&rec={Record ID}&ff={FreeForm}

You can also put the URL without the "curl -X GET" command directly into your browser.

Batch

Batch requests from 1 to 100 records at a time are sent using HTTP POST. This means you cannot send it in a browser like with HTTP GET.

Header

Accept: application/json

Make sure the header includes this line:

Body

{
  "t":"{Transmission Reference}",
  "id":"{License Key}",
  "cols":"{Columns}",
  "opt":"{Options}",
  "Records":[
  {
    "rec":"{Record ID}",
    "comp":"{Company}",
    "a1":"{Address1}",
    "a2":"{Address2}",
    "city":"{City}",
    "state":"{State}",
    "postal":"{Postal Code}",
    "ctry":"{Country}",
    "phone":"{Phone}",
    "mak":"{Melissa Address Key}",
    "stock":"{Stock Ticker}",
    "web":"{Web Address}"
  },
  {
    "rec":"{Record ID}",
    "comp":"{Company}",
    "a1":"{Address1}",
    "a2":"{Address2}",
    "city":"{City}",
    "state":"{State}",
    "postal":"{Postal Code}",
    "ctry":"{Country}",
    "phone":"{Phone}",
    "mak":"{Melissa Address Key}",
    "stock":"{Stock Ticker}",
    "web":"{Web Address}"
  }]
}

Here, we are sending a batch request with 2 records.

Input Fields

Input Name Description REQUIRED
t Value passed through unchanged to the response for identification or any other purpose No
id The License Key issued by Melissa. Yes
cols The columns to be output as a comma delimited string. Column Groups
Field Name Column Group
LocationType [NO GROUP]
These columns must be requested individually.
Phone
EmployeesEstimate
SalesEstimate
StockTicker
WebAddress
Contacts
CountryCode GrpAddressDetails
CountryName
DeliveryIndicator
MelissaAddressKey
MelissaAddressKeyBase
Plus4
EIN GrpBusinessCodes
SICCode1
SICCode2
SICCode3
NAICSCode1
NAICSCode2
NAICSCode3
SICDescription1 GrpBusinessDescription
SICDescription2
SICDescription3
NAICSDescription1
NAICSDescription2
NAICSDescription3
Latitude GrpGeoCode
Longitude
CountyName GrpCensus
CountyFIPS
CensusTract
CensusBlock
PlaceCode
PlaceName
No
opt CentricHint

This option allows you to choose what the service will center the search around.

Code Description
company Will use Company as the primary pivot.
address Will us Address as a primary pivot.
phone Will use Phone as a primary pivot.
MaxContacts

This option changes the upper limit on the number of contacts returned.

Code Description
# [0 - #] Default set to 5. Sets the maximum number of contacts to be returned.
ReturnDominantBusiness

This option handles the returning of the dominant business name and demographics for a particular site when the company information is missing or does not match.

Code Description
yes (Default) Return the dominant business name when the company information is missing or does not match.
no Do not return the dominant business name when the company information is missing or does not match.
SICNAICSConfidence

Will only return SIC Codes that we are very confident are correct. If they do not pass our requirements we will return null.

Code Description
strict Returns very confident or correct SIC Codes. Returns null if none pass the requirement.
loose (Default) Returns any associated SIC Codes.
rec Unique Record ID. Use it to match the record submitted with the record returned. No
comp The name of the business. No
phone The phone number of the business. No
a1 The first address line of the business. No
a2 The Second address line (suite) of the business. No
city The city (Locality). No
state The state (Administrative Area). No
postal The postal code. No
ctry The country. No
mak (MAK) A propietary unique key identifier for an address. This is derived from Address Checking. No
stock A unique abbreviation/symbol assigned by the stock exchange for listed companies. No
web The web address/domain for the business. No
mek (MEK) A proprietary unique key identifier given by Business Coder. No
ff This is a string value which can contain one of the possible minimum input requirements. No

Input Best Practices

What type of Information can I submit to the Web Service in order to get business firmographics?

The Business Coder Web Service can be queried using any one of the following Input Data:

  1. Address (With or without the company name)
  2. Phone Number
  3. Melissa Address Key (Can be retrieved using any of Melissa Data’s Address Verification Solutions)
  4. Web Address
  5. Stock Ticker

Where does Business Coder Get its Data?

The Business Coder Database is compiled from several sources and industries. The final combined database merges the data to about 15 million records of business information. This data is then exposed through the Business Coder Web Service which allows for appending Firmographics. Since the service revolves heavily around the contents of the data, the exact provider for the sources is not something we can disclose at the moment as we prefer to keep this information private in order to maintain the product’s uniqueness and value in the industry.

Output Response

Single vs. Batch

Melissa cloud services are capable of both single record real-time processing and batch processing. The difference is simply in the number of records sent in each request. Melissa cloud services take an array of records. This array can contain anything from one to one hundred records. For a real-time process like a web form entry or a call center application, send in a request with one record. For a batch processing scenario like a database, send requests of up to 100 records until all the records are processed. Note: Make sure each record in the request has a unique Record ID.

Sample JSON Response

Here is a sample JSON response.

{
  "TransmissionResults": "string",
  "TransmissionReference": "string",
  "Version": "string",
  "TotalRecords": "string",
  "Records": [
    {
       "AddressLine1": "string",
       "AddressType": "string",
       "CensusBlock": "string",
       "CensusTract": "string",
       "City": "string",
       "CompanyName": "string",
       "CurrentCompanyName": "string",
       "CountryCode": "string",
       "CountryName": "string",
       "CountyFIPS": "string",
       "CountyName": "string",
       "DeliveryIndicator": "string",
       "EIN": "string",
       "EmployeesEstimate": "string",
       "Latitude": "string",
       "LocationType": "string",
       "Longitude": "string",
       "MelissaAddressKey": "string",
       "MelissaAddressKeyBase": "string",
       "MelissaEnterpriseKey": "string",
       "NAICSCode1": "string",
       "NAICSCode2": "string",
       "NAICSCode3": "string",
       "NAICSDescription1": "string",
       "NAICSDescription2": "string",
       "NAICSDescription3": "string",
       "Phone": "string",
       "PlaceCode": "string",
       "PlaceName": "string",
       "Plus4": "string",
       "PostalCode": "string",
       "RecordID": "string",
       "Results": "string",
       "SICCode1": "string",
       "SICCode2": "string",
       "SICCode3": "string",
       "SICDescription1": "string",
       "SICDescription2": "string",
       "SICDescription3": "string",
       "SalesEstimate": "string",
       "State": "string",
       "StockTicker": "string",
       "Suite": "string",
       "TotalContacts": "string",
       "WebAddress": "string",
       "Contacts": [
         {
           "NameFirst": "string",
           "NameLast": "string",
           "Gender": "string",
           "Title": "string",
           "ContactPhone": "string",
           "Email": "string"
         },
         {
           "NameFirst": "string",
           "NameLast": "string",
           "Gender": "string",
           "Title": "string",
           "ContactPhone": "string",
           "Email": "string"
         } ]
    } ]
}

Output Fields

Response Level

Output Name Description
TransmissionResults Service Errors (SE Codes) and General Transmission Errors (GE Codes)
TransmissionReference Returned value will be the same as the input TransmissionReference to be used as a unique identifier.
Version The current revision number of the Business Coder web service.
TotalRecords The total number of records returned.
Records The returned array of records.

Record Level

Output Name Description
AddressLine1 Address line 1 of the business
AddressType Returns a code for the address type in the AddressLine field.
CensusBlock Census block number for the address
CensusTract Census tract number for the address
City City of the business
CompanyName The business name.
CurrentCompanyName The company name in our reference data. You can use this to easily compare your input company name against Melissa records for that address.
CountryCode 2-Character Country Code
CountryName Name of the Country based on address
CountyFIPS FIPS code of the county
CountyName County name
DeliveryIndicator RBDI indicator based on the address
EIN The Employer Identification Number for the business.
EmployeesEstimate Number of employees working at this business location
Latitude Geographic coordinate
LocationType Code denoting business location type
Longitude Geographic coordinate
MelissaAddressKey Unique key assigned to an address record
MelissaAddressKeyBase Unique key assigned to the base address of a complex with apartments or suites
MelissaEnterpriseKey Unique Key assigned to a business for that location
NAICSCode1 North American Industry Classification System code, related to SIC Code 1
NAICSCode2 Second NAICS code, related to SIC Code 2
NAICSCode3 Third NAICS code, related to SIC Code 3
NAICSDescription1 First NAICS Code description
NAICSDescription2 Second NAICS Code description
NAICSDescription3 Third NAICS Code description
Phone 10-digit business phone number
PlaceCode Census Bureau place code
PlaceName Census Bureau place name
Plus4 Plus4 of the business address
PostalCode ZIP/Postal Code of the business
RecordID Unique ID if processing multiple records
Results Shows you the result of the business information verification with codes for status, error, and changes. See the Results section below for more details.
SICCode1 6-digit SIC code for the primary line of business
SICCode2 Second SIC code
SICCode3 Third SIC code
SICDescription1 First SIC Code description
SICDescription2 Second SIC Code description
SICDescription3 Third SIC Code description
SalesEstimate Sales volume and/or assets
State State of the business
StockTicker Assigned stock exchange symbol
Suite Business suite
TotalContacts Number of employee contacts we have in our databases
WebAddress Web address/domain of the business
Contacts Contains JSON Array: NameFirst, NameLast, Gender, Title, ContactPhone, and Email

Interpreting Results

The Business Coder API and other Melissa APIs will have a Results Output. Several different Result Codes may be returned by the service in order to give you detailed information about the status of the record submitted.

It is important to understand these result codes in order for you to make a determination of good vs bad data and how you would want to use it.

The following shows you the indicators for the different results:

Code Description Quality Indicator
FS01 A match was found in the data. Good Data
FS02 A match was found for the company. Good Data
FS03 A match was found for the input MAK (Melissa Address Key). Good Data
FS04 A match was found for the input address. Good Data
FS05 A match was found for the input phone. Good Data
FS06 A match was found for the input stock ticker. Good Data
FS07 A match was found for the input web address. Good Data
FS08 A match was found for the input MEK (Melissa Enterprise Key). Good Data
FE01 No match was found. Bad Data
FE02 The minimum input requirements were not met. These requirements are:
  • Address and City/State or ZIP
  • Melissa Address Key
  • Phone
  • Stock Ticker
  • Web Address
 Need More Data
FE03 Multiple matches were found. Multiple Matches

For a list of the common transmission errors, see the General Info - Response Level Errors page.

For the full list of all possible result codes, please visit our Result Wiki page at Business Coder Result Code Details.

While the Business Coder returns firmographics for a single matched Business Location, there is also a Business Search API which allows you to search for businesses at a general location.

So for example you can query for the following:

Input

Company: McDonalds
City/Locality: Los Angeles
State/Administrative Area: CA

Results

Returns all the McDonalds locations in Los Angeles.

For more information on Business Search, go to http://wiki.melissadata.com/index.php?title=Business_Search