Reference Guide

Introduction

Global Business Coder provides in-depth firmographic information for over 25 million U.S. enterprises. This data encompasses standardized company names, job titles, contact details (including names, addresses, phone numbers, and email addresses), SIC/NAICS codes, workforce sizes, stock ticker symbols, revenue figures, and more.

This API offers a wealth of valuable insights into businesses, serving a wide range of purposes such as market analysis, lead generation, and customer profiling.

Base URL

https://businesscoder.melissadata.net

Licensing

The License Key is a software key required to use the web service. You will receive your license key from your Melissa representative. If you don’t have a license key, contact the Melissa sales team at sales@melissa.com or 800-MELISSA ext. 3 (800-635-4772 ext. 3). Without a license key this service will not function.

To set the license key, use the id/LicenseKey property in your requests.

Endpoints

/WEB/BusinessCoder/doBusinessCoder

Use this endpoint to validate IP numbers

Try It Now

Note

Make sure to replace {{customerId}} with your license key.

Get it here!

• GET JSON
• POST JSON

curl -X GET "https://businesscoder.melissadata.net/WEB/BusinessCoder/doBusinessCoderUS?\
&cols=\
&id={{customerId}}\
&opt=\
&t=Test\
&a1=22382%20Avenida%20Empresa\
&a2=\
&city=Rancho%20Santa%20Margarita\
&comp=\
&ctry=\
&ff=\
&mak=\
&mek=\
&phone=\
&postal=92688\
&rec=\
&state=California\
&stock=\
&suite=\
&web=" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

curl -X POST "https://businesscoder.melissadata.net/WEB/BusinessCoder/doBusinessCoderUS" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
       "cols": "",
       "id": "{{customerId}}",
       "opt": "",
       "Records":
       [{
          "a1": "22382 Avenida Empresa",
          "a2": "",
          "city": "Rancho Santa Margarita",
          "comp": "",
          "ctry": "",
          "freeform": "",
          "mak": "",
          "mek": "",
          "phone": "",
          "postal": "92688",
          "rec": "",
          "state": "California",
          "stock": "",
          "suite": "",
          "web": ""
       }],
       "t": "Test"
    }'

Request Parameters

Note

For details on territories using different ISO2 codes, see the FAQs.

• GET JSON
• POST JSON

Code	Description
Request Level Parameters
cols	This string value specifies which column(s) to be output as a comma delimited string.
id	The License Key issued by Melissa.
opt	Set Options CentricHint MaxContacts ReturnDominantBusiness SICNAICSConfidence
t	This is a string value that serves as a unique identifier for this set of records. It is returned as sent.
Record Level Parameters
a1	The first address line of the business.
a2	The second address line (suite) of the business.
city	City, Municipality, Locality. The most common population center data element.
comp	The name of the business.
ctry	The country.
ff	This is a string value which can contain one of the possible minimum input requirements.
mak	Melissa Address Key (MAK). A propietary unique key identifier for an address. This is derived from Address Checking.
mek	Melissa Enterprise Key (MEK). The unique identifier given by Business Coder.
phone	The phone number of the business.
postal	ZIP, Postal Code. The complete postal code for a particular delivery point.
rec	This is a string value containing a unique identifier for the current record. Use this to match the record submitted with the record returned. It will return what is inputted.
state	State, Province, Administrative Area. The most common geographic data element.
stock	A unique abbreviation/symbol assigned by the stock exchange for listed companies.
suite	Suite, Sub Premises. The alphanumeric code identifying an individual location.
web	The web address/domain for a company.

Code	Description
Request Level Parameters
cols	This string value specifies which column(s) to be output as a comma delimited string.
id	The License Key issued by Melissa.
opt	Set Options CentricHint MaxContacts ReturnDominantBusiness SICNAICSConfidence
t	This is a string value that serves as a unique identifier for this set of records. It is returned as sent.
Record Level Parameters
a1	The first address line of the business.
a2	The second address line (suite) of the business.
city	City, Municipality, Locality. The most common population center data element.
comp	The name of the business.
ctry	The country.
freeform	This is a string value which can contain one of the possible minimum input requirements.
mak	Melissa Address Key (MAK). A propietary unique key identifier for an address. This is derived from Address Checking.
mek	Melissa Enterprise Key (MEK). The unique identifier given by Business Coder.
phone	The phone number of the business.
postal	ZIP, Postal Code. The complete postal code for a particular delivery point.
rec	This is a string value containing a unique identifier for the current record. Use this to match the record submitted with the record returned. It will return what is inputted.
state	State, Province, Administrative Area. The most common geographic data element.
stock	A unique abbreviation/symbol assigned by the stock exchange for listed companies.
suite	Suite, Sub Premises. The alphanumeric code identifying an individual location.
web	The web address/domain for a company.

Columns

Entering the column name will return the column. Specifying a group name will return all columns in the group.

Delimit multiple columns with a ,.

Group Name	Included Fields
[DEFAULT] These columns are returned by default.	AddressLine1 City CompanyName CurrentCompanyName MelissaEnterpriseKey PostalCode RecordID Records State Suite TotalContacts TransmissionReference TransmissionResults
[NO GROUP] These columns must be requested individually.	Contacts EmployeesEstimate LocationType Phone SalesEstimate StockTicker WebAddress
GrpAddressDetails	CountryCode CountryName DeliveryIndicator MelissaAddressKey MelissaAddressKeyBase Plus4
GrpBusinessCodes	EIN NAICSCode1 NAICSCode2 NAICSCode3 SICCode1 SICCode2 SICCode3
GrpBusinessDescription	NAICSDescription1 NAICSDescription2 NAICSDescription3 SICDescription1 SICDescription2 SICDescription3
GrpGeoCode	Latitude Longitude
GrpCensus	CensusBlock CensusTract CountyFIPS CountyName PlaceCode PlaceName

Options

List options in the following format, with multiple options delimited with a ,.

OptionName:Parameter,OptionName:Parameter

CentricHint

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

Parameter	Description
company	Use Company as the primary pivot.
address	Use Address as a primary pivot.
phone	Use Phone as a primary pivot.

MaxContacts

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

Parameter	Description
{{Integer}}	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.

Parameter	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

This option handles how SIC Codes are returned, depending on our SIC Code confidence level.

Parameter	Description
loose	Default. Returns any associated SIC Codes.
strict	Only returns very confident or correct SIC Codes. Returns null if none pass the requirement.

Headers

• GET JSON
• POST JSON

Content-Type: application/json
Accept: application/json

Content-Type: application/json
Accept: application/json

Response

• GET JSON
• POST JSON

{
   "TransmissionResults": "",
   "TransmissionReference": "Test",
   "Version": "7.0.1.1071",
   "TotalRecords": "1",
   "Records":
   [{
      "AddressLine1": "22382 Avenida Empresa",
      "City": "Rancho Santa Margarita",
      "CompanyName": "Melissa Data",
      "CurrentCompanyName": "Melissa Data",
      "MelissaEnterpriseKey": "323318841",
      "PostalCode": "92688-2112",
      "RecordID": "1",
      "Results": "AS01,DA00,DA20,DA30,DA40,DA50,FS01,FS08",
      "State": "CA",
      "Suite": "",
      "TotalContacts": "8"
   }]
}

{
   "TransmissionResults": "",
   "TransmissionReference": "Test",
   "Version": "7.0.1.1071",
   "TotalRecords": "1",
   "Records":
   [{
      "AddressLine1": "22382 Avenida Empresa",
      "City": "Rancho Santa Margarita",
      "CompanyName": "Melissa Data",
      "CurrentCompanyName": "Melissa Data",
      "MelissaEnterpriseKey": "323318841",
      "PostalCode": "92688-2112",
      "RecordID": "1",
      "Results": "AS01,DA20,DA30,DA40,DA50,FS01,FS04,GS05",
      "State": "CA",
      "Suite": "",
      "TotalContacts": "8"
   }]
}

Service Level Response Fields

Output Name	Description
Records	The returned array of records.
TotalRecords	Total number of records returned in the records array.
TransmissionReference	A pass-through of the input Transmission Reference.
TransmissionResults	Returns the generic web service level result/error codes. For more information, see Result Codes.
Version	The current service version number.

Record Level Response Fields

[DEFAULT]

In addition to the Service Level Response Fields, these fields are returned by default.

Output Name	Description
AddressLine1	The first address line of the business.
City	City, Municipality, Locality. The most common population center data element.
CompanyName	The name of the business.
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.
MelissaEnterpriseKey	The Unique Key assigned to a business for that location.
PostalCode	ZIP, Postal Code. The complete postal code for a particular delivery point.
RecordID	A string value containing a unique identifier for the current record. Use this to match the record submitted with the record returned. It will return what is inputted.
Results	Comma delimited status, error codes, and change codes for the request.
State	State, Province, Administrative Area. The most common geographic data element.
Suite	Suite, Sub Premises. The alphanumeric code identifying an individual location.
TotalContacts	Total number of records.

[NO GROUP]

These columns must be requested individually.

Output Name	Description
Contacts	Returns JSON Array: NameFirst, NameLast, Gender, Title, and Email of one or more contacts. "Contacts": [{ "NameFirst": "string", "NameLast": "string", "Gender": "string", "Title": "string", "ContactPhone": "string", "Email": "string" }]
EmployeesEstimate	The estimated number of employees who work at this business location.
LocationType	A code denoting the business location type. Code Description 1 Headquarters 2 Branches 3 Subsidiary Headquarters 4 Single Location
Phone	A 10-digit phone number.
SalesEstimate	The sales volume and/or assets of the business.
StockTicker	The assigned stock exchange abbreviation/symbol for the business.
WebAddress	The web address/domain for the business.

GrpAddressDetails

Output Name	Description
CountryCode	The 2 letter ISO 3166 country code value. For example: US for United States or CA for Canada.
CountryName	The standardized contents of the CountryName element.
DeliveryIndicator	Residential Business Delivery Indicator (RBDI). The delivery type status based on the address.
MelissaAddressKey	This is a globally unique and persistent key for the location, even if parts of the address change. When an address is fully validated this field returns a 10-digit proprietary key for the address.
MelissaAddressKeyBase	Every full address has its own Melissa Address Key (MAK). If that address is a suites or apartment, we will also return a Melissa Address Key Base (BaseMAK) that corresponds to the overall building. This provides a link between all the individual MAK addresses that belong to the same building.
Plus4	The 4-digit extension for the ZIP code.

GrpBusinessCodes

Output Name	Description
EIN	Employer Identification Number (EIN). A unique 9-digit business identification number assigned by the IRS.
NAICSCode1	North American Industry Classification System (NAICS). A 2-6 digit code that classifies businesses by production. This is defined by NAICSDescription1 and related to SICCode1.
NAICSCode2	This is defined by NAICSDescription2 and related to SICCode2.
NAICSCode3	This is defined by NAICSDescription3 and related to SICCode3.
SICCode1	Standard Industrial Classification (SIC). A 2-4 digit code that classifies businesses by production or market. This is defined by SICDescription1 and related to NAICSCode1.
SICCode2	This is defined by SICDescription2 and related to NAICSCode2.
SICCode3	This is defined by SICDescription3 and related to NAICSCode3.

GrpBusinessDescription

Output Name	Description
NAICSDescription1	North American Industry Classification System (NAICS). A description of NAICSCode1.
NAICSDescription2	A description of NAICSCode2.
NAICSDescription3	A description of NAICSCode3.
SICDescription1	Standard Industrial Classification (SIC). A description of SICCode1.
SICDescription2	A description of SICCode2.
SICDescription3	A description of SICCode3.

GrpGeoCode

Output Name	Description
Latitude	The parsed geographic coordinate for a particular delivery point.
Longitude	The parsed geographic coordinate for a particular delivery point.

GrpCensus

Output Name	Description
CensusBlock	US Only. The Census block number from the most recent yearly census.
CensusTract	US Only. The Census tract number from the most recent yearly census.
CountyFIPS	US Only. The Census FIPS number from the most recent yearly census.
CountyName	US Only. The county name that corresponds to the county FIPS code.
PlaceCode	US Only. The FIPS Place code as defined by the Census.
PlaceName	US Only. The FIPS Place name as defined by the Census.

Input Best Practices

This service can deal with multiple languages and scripts. It expects UTF-8 encoding. Be on the lookout for question marks (?), squares (▖) or other unwanted 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.

Result Codes

Result codes yield more granular information about a given business. They are returned as a comma-delimited string of 4-character alpha-numeric codes, e.g. AS01,FS01.

SE## and GE## Codes

The SE## and GE## codes (Transmission Service Error and General Transmission Error) are used to signify more general errors, and are returned under the key TransmissionResults in the outermost level of our responses.

Service Level Result Codes

Note

The Service Level result codes apply to the service as a whole.

Code	Short Description	Long Description
SE - Transmission Service Error
SE01	Cloud Service Internal Error	The cloud service experienced an internal error.
GE - General Transmission Error
GE04	Empty License Key	The License Key is empty.
GE05	Invalid License Key	The License Key is invalid.
GE06	Disabled License Key	The License Key is disabled.
GE09	Customer Does Not Exist	The Customer ID is not in our system.
GE10	Customer License Disabled	The encrypted license is on the ban list.
GE11	Customer Disabled	The Customer ID is disabled.
GE12	IP Blacklisted	The IP Address is on the global ban list.
GE13	IP Not Whitelisted	The IP Address is not on the customer’s whitelist.
GE14	Out of Credits	The account has ran out of credits. Add more credits to continue using the service.
GE25	No License For Business Demographic	The License Key is not subscribed/licensed for the requested business demographic(s).
GW - General Transmission Warning
GW01	Expiring License	Your License Key is expiring soon. Please contact your sales representative for a new License Key.

Record Level Result Codes

Note

The Record Level result codes apply to the individual request records.

Tip

For example input that returns specific codes, see the FAQs

Code	Short Description	Long Description
AE - Address Error
AE01	General Error	The address could not be verified. This is likely due to a missing or invalid locality or postal code.
AE02	Unknown Street	Could not match the input street to a unique street name. Either no matches or too many matches found.
AE03	Component Mismatch Error	The combination of directionals (N, E, SW, etc) and the suffix (AVE, ST, BLVD) is not correct and produced multiple possible matches.
AE05	Multiple Match	The address was matched to multiple records. There is not enough information available in the address to break the tie between multiple records.
AE08	Sub Premise Number Invalid	The thoroughfare (street address) was found but the sub premise (suite) was not valid.
AE09	Sub Premise Number Missing	The thoroughfare (street address) was found but the sub premise (suite) was missing.
AE10	Premise Number Invalid	The premise (house or building) number for the address is not valid.
AE11	Premise Number Missing	The premise (house or building) number for the address is missing.
AE12	Box Number Invalid	The PO (Post Office Box), RR (Rural Route), or HC (Highway Contract) Box number is invalid.
AE13	Box Number Missing	The PO (Post Office Box), RR (Rural Route), or HC (Highway Contract) Box number is missing.
AE14	PMB Number Missing	US Only. The address is a Commercial Mail Receiving Agency (CMRA) and the Private Mail Box (PMB or #) number is missing.
AE17	Sub Premise Not Required (Deprecated - See AS23)	A sub premise (suite) number was entered but the address does not have secondaries. (Deprecated - See AS23)
AS - Address Status
AS01	Address Fully Verified	The address is valid and deliverable according to official postal agencies.
AS02	Valid Building Address	The building address was verified but the suite/apartment number is missing or invalid.
AS03	Non USPS Address Match	US Only. This US address is not serviced by the USPS but does exist and may receive mail through third party carriers like UPS.
AS04	Proprietary Address Format	The address uses a proprietary addressing scheme where only the format could be validated.
AS09	Foreign Address	The address is in a non-supported country.
AS10	CMRA Address	US Only. The address is a Commercial Mail Receiving Agency (CMRA) like a Mailboxes Etc. These addresses include a Private Mail Box (PMB or #) number.
AS11	PBSA Address	A PO Box formatted as a street address for package and mail delivery.
AS12	Record Move	The record moved to a new address.
AS13	Address Updated By LACS	US Only. The address has been converted by LACSLink® from a rural-style address to a city-style address.
AS14	Suite Appended	US Only. A suite was appended by SuiteLink™ using the address and company name.
AS15	Apartment Appended	An apartment number was appended by AddressPlus using the address and last name.
AS16	Vacant Address	US Only. The address has been unoccupied for more than 90 days.
AS17	No USPS Mail Delivery	This address is classified as not receiving mail by the USPS via their No-Stat flag. Delivery might still be possible by third party carriers but that cannot be counted on.
AS18	DPV Locked Out	US Only. DPV processing was terminated due to the detection of what is determined to be an artificially created address.
AS20	Deliverable only by USPS	US Only. This address can only receive mail delivered through the USPS (i.e. PO Box or a military address).
AS23	Extraneous Suite Information	Extraneous information not used in verifying the address was found. This information was returned in the suite field.
AS24	USPS Door Not Accessible	Address identified by the USPS where carriers cannot physically access a building or door for mail delivery.
AS25	Unique ZIP code	The address contains a USPS unique ZIP code which means any address may be marked as deliverable.
AS26	Unknown Data Moved to ParsedGarbage	The input contains data that could not be identified. That data is returned in the ParsedGarbage/AddressExtras field
AS27	Phantom Route address	Addresses that are assigned to a phantom route of R777 or R779.
DA - Append Results
DA00	Address Appended	An address was changed or appended.
DA20	Company Appended	A company name was changed or appended.
DA30	Phone Appended	A phone number was changed or appended.
DA40	Email Appended	An email address was changed or appended.
DA50	Web Address Appended	The web address was changed or appended.
DA60	Stock Ticker Appended	A stock ticker was changed or appended.
FE - Business/Firm Error
FE01	No Match	No match was found.
FE02	Minimum Input Not Met	The minimum input requirements were not met. These requirements are: Address and City/State or ZIP, Melissa Address Key, Phone, Stock Ticker and Web Address.
FE03	Multiple Matches	Multiple matches were found.
FS - Business/Firm Status
FS01	Data Match	A match was found in the data.
FS02	Company Match	A match was found for the company.
FS03	MAK Match	A match was found for the input MAK (Melissa Address Key).
FS04	Address Match	A match was found for the input address.
FS05	Phone Match	A match was found for the input phone.
FS06	Stock Ticker Match	A match was found for the input stock ticker.
FS07	Web Address Match	A match was found for the input web address.
FS08	MEK Match	A match was found for the input MEK (Melissa Enterprise Key).
GE - Geocode Error
GE01	Regional Geocode Not Found	Geocode could not be appended for the input locality or postal code.
GE02	No Geocode for Input Address	The input address did not provide enough valid information to append a geocode.
GS - Geocode Status
GS01	Geocoded to Street Level	The record was coded to the street level (Zip+4 for US, full postal code for CA).
GS02	Geocoded to the Neighborhood Level	The record was geocoded down to neighborhood level (Zip+2 for US).
GS03	Geocoded to Community Level	The record was coded to the community level (ZIP centroid for US, 3-digit postal code for CA).
GS05	Geocoded to Rooftop Level	The record was geocoded down to the rooftop level, meaning the point is within the property boundaries, usually the center.
GS06	Geocoded to Interpolated Rooftop Level	The record was geocoded down to the rooftop level using interpolation (educated estimations using street coordinates). The point may be in or close to the property boundaries.
PE - Phone Error
PE01	Invalid Phone	The area code/phone number does not exist in our database or contains non-numbers.
PE02	Blank Phone	The phone number is blank.
PE03	Bad Phone	The phone number has too many or too few digits.
PE04	Multiple Match	Two or more possible area codes are available as a fix and their distance is too close to choose one over the other.
PE05	Bad Prefix/Prefix +1	The phone prefix or first 7-digits do not exist in our database.
PS - Phone Status
PS01	Valid Phone	The phone number has been verified as valid.
PS02	7-Digit Match	The first 7-digits of the phone number have been verified, but activity cannot be confirmed.
PS03	Corrected Area Code	NewAreaCode contains corrected area code that was changed according to the postal code it falls into.
PS06	Updated Area Code	The area code was changed due to an area code split. The updated code is located within NewAreaCode.
PS07	Cellular Line	On activation, the exchange type of the phone number was designated as a cellular number, but current status cannot be confirmed.
PS08	Land Line	On activation, the exchange type of the phone number was designated as a land line, but current status cannot be confirmed.
PS09	VOIP Line	On activation, the exchange type of the phone number was designated as a VOIP line, but current status cannot be confirmed.
PS10	Residential Number	The phone number belongs to a residence.
PS11	Business Number	The phone number belongs to a business.
PS12	SOHO Number	The phone number belongs to a small office or home office.