Difference between revisions of "Business Coder:Request"

From Melissa Data Wiki
Jump to navigation Jump to search
 
(24 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{ BusinessCoderNav
{{ BusinessCoderNav
|RequestCollapse=
|InputOutputCollapse=
}}
}}


Line 6: Line 6:
{{CustomTOC}}
{{CustomTOC}}


A request consists of a protocol to make a call to the service, detailing desired elements. Your Customer ID is required.
A request consists of a protocol to make a call to the service, detailing desired elements. Your License Key is required.


Business Coder supports the REST protocol to access the service.
Business Coder supports the JSON and REST protocols to access the service.
 
 
==URL==
{{URL-BusinessCoder}}




Line 15: Line 19:


{| class="alternate01 sortable"
{| class="alternate01 sortable"
!Field Name !! Level !! REST Abbreviation
!Field Name !! Level !! REST !! JSON
|-
|Transmission Reference||rowspan="4" valign="center"|Request||t
|-
|License||lic
|-
|Column||cols
|-
|Options||opt
|-
|Company Name||rowspan="11"|Request Record||comp
|-
|Phone Number||phone
|-
|Address1||a1
|-
|Address2||a2
|-
|City||city
|-
|State||state
|-
|-
|Postal||postal
|Transmission Reference||rowspan="4" valign="center"|Request||t||t
|-
|-
|Country||ctry
|License Key||id||id
|-
|-
|Melissa Address Key (MAK)||mkey
|Column||cols||cols
|-
|-
|Stock Ticker||stock
|Options||opt||opt
|-
|Web Address||web
|}
 
{| class="alternate01 sortable"
!Field Name !! Level !! REST Abbreviation
|-
|-
|Transmission Reference||Request||t
|Record ID||rowspan="15"|Record||rec||rec
|-
|-
|License||Request||lic
|Company Name||comp||comp
|-
|-
|Column||Request||cols
|Phone Number||phone||phone
|-
|-
|Options||Request||opt
|Address1||a1||a1
|-
|-
|Company Name||Request Record||comp
|Address2||a2||a2
|-
|-
|Phone Number||Request Record||phone
|Suite||suite||suite
|-
|-
|Address1||Request Record||a1
|City||city||city
|-
|-
|Address2||Request Record||a2
|State||state||state
|-
|-
|City||Request Record||city
|Postal||postal||postal
|-
|-
|State||Request Record||state
|Country||ctry||ctry
|-
|-
|Postal||Request Record||postal
|Melissa Address Key (MAK)||mak||mak
|-
|-
|Country||Request Record||ctry
|Stock Ticker||stock||stock
|-
|-
|Melissa Address Key (MAK)||Request Record||mkey
|Web Address||web||web
|-
|-
|Stock Ticker||Request Record||stock
|Melissa Enterprise Key (MEK)||mek||mek
|-
|-
|Web Address||Request Record||web
|Free Form||ff||freeform
|}
|}


Line 86: Line 64:
The following are the possible minimum input requirements.
The following are the possible minimum input requirements.


#Address and Company
#Company Only
#MAK and Company
#MAK and Company
#Address Only
#Address Only
Line 106: Line 84:
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|REST||?t = {string}
|JSON||<code>"t":"'''''string'''''"</code>
|-
|REST||<code>?t = '''''string'''''</code>
|}
|}




<h3 style="background-color:rgb(240,240,240);">License</h3>
<h3 style="background-color:rgb(240,240,240);">License Key</h3>
:''Required.''
:''Required.''


:This is a string value containing the license string issued to the customer by Melissa Data for the Business Coder.
:This is a string value containing the License Key issued to the customer by Melissa Data for the Business Coder.


:If this element is absent, the Web Service will return an error. To receive a license, please contact your Melissa Data sales representative at 1-800-MELISSA.
:If this element is absent, the Web Service will return an error. To receive a License Key, please contact your Melissa Data sales representative at 1-800-MELISSA.


:{| class="alternate01"
:{| class="alternate01"
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|REST||&lic = {string}
|JSON||<code>"id":"'''''string'''''"</code>
|-
|REST||<code>&id = '''''string'''''</code>
|}
|}


Line 132: Line 114:
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|REST||&cols = {string}
|JSON||<code>"cols":"'''''string'''''"</code>
|-
|REST||<code>&cols = '''''string'''''</code>
|}
 
 
Entering the column name to return the column. Specifying a group name will return all columns in the group.
 
:{| class="alternate01 sortable"
!Field Name !! Group
|-
|TransmissionResults||rowspan="13"|'''[DEFAULT]'''
These columns are returned by default.
|-
|TransmissionReference
|-
|Records
|-
|RecordID
|-
|CompanyName
|-
|CurrentCompanyName
|-
|AddressLine1
|-
|Suite
|-
|City
|-
|State
|-
|PostalCode
|-
|TotalContacts
|-
|MelissaEnterpriseKey
|-
|LocationType||rowspan="7"|'''[NO GROUP]'''
These columns must be requested individually.
|-
|Phone
|-
|EmployeesEstimate
|-
|SalesEstimate
|-
|StockTicker
|-
|WebAddress
|-
|Contacts
|-
|CountryCode||rowspan="6"|'''GrpAddressDetails'''
|-
|CountryName
|-
|DeliveryIndicator
|-
|MelissaAddressKey
|-
|MelissaAddressKeyBase
|-
|Plus4
|-
|EIN||rowspan="7"|'''GrpBusinessCodes'''
|-
|SICCode1
|-
|SICCode2
|-
|SICCode3
|-
|NAICSCode1
|-
|NAICSCode2
|-
|NAICSCode3
|-
|SICDescription1||rowspan="6"|'''GrpBusinessDescription'''
|-
|SICDescription2
|-
|SICDescription3
|-
|NAICSDescription1
|-
|NAICSDescription2
|-
|NAICSDescription3
|-
|Latitude||rowspan="2"|'''GrpGeoCode'''
|-
|Longitude
|-
|CountyName||rowspan="6"|'''GrpCensus'''
|-
|CountyFIPS
|-
|CensusTract
|-
|CensusBlock
|-
|PlaceCode
|-
|PlaceName
|}
 
 
:{| class="alternate01"
!JSON Array returned by Contacts
|-
|Contacts:
|-
|style="padding-left:20px;"|NameFirst
|-
|style="padding-left:20px;"|NameLast
|-
|style="padding-left:20px;"|Gender
|-
|style="padding-left:20px;"|Title
|-
|style="padding-left:20px;"|Email
|}
|}


Line 139: Line 243:
:''Optional.''
:''Optional.''


:This is a string value specifies options, if any.
:This is a string value containing the options set by the user.


:{| class="alternate01"
:{| class="alternate01"
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|REST||&opt = {string}
|JSON||<code>"opt":"'''''string'''''"</code>
|-
|REST||<code>&opt = '''''string'''''</code>
|}
 
 
:List options in the following format.
 
:{| class="alternate01"
!Syntax
|-
|<code>''OptionName'':''Parameter''</code>
|}
 
 
:<h4 style="border-bottom:1px solid black;">CentricHint</h4>
::This option allows you to choose what the service will center the search around.
 
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|rowspan="3"|'''CentricHint'''||<code>company</code>||Will use Company as the primary pivot.
|-
|<code>address</code>||Will us Address as a primary pivot.
|-
|<code>phone</code>||Will use Phone as a primary pivot.
|}
 
 
:<h4 style="border-bottom:1px solid black;">MaxContacts</h4>
::This option changes the upper limit on the number of contacts returned.
 
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|rowspan="2"|'''MaxContacts'''||<code># [0 - #]</code>||'''''Default set to 5.''''' Sets the maximum number of contacts to be returned.
|}
 
 
:<h4 style="border-bottom:1px solid black;">ReturnDominantBusiness</h4>
::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.
 
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|rowspan="2"|'''ReturnDominantBusiness'''||<code>yes</code>||'''''Default.''''' Return the dominant business name when the company information is missing or does not match.
|-
|<code>no</code>||Do not return the dominant business name when the company information is missing or does not match.
|}
 
 
:<h4 style="border-bottom:1px solid black;">SICNAICSConfidence</h4>
::Will only return SIC Codes that we are very confident are correct. If they do not pass our requirements we will return null.
 
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|rowspan="2"|'''SICNAICSConfidence'''||<code>strict</code>||Returns very confident or correct SIC Codes. Returns null if none pass the requirement.
|-
|<code>loose</code>||'''''Default.''''' Returns any associated SIC Codes.
|}
|}


Line 153: Line 316:
{| class="alternate01"
{| class="alternate01"
!Protocol !! Definition
!Protocol !! Definition
|-
|JSON||Each record will be contained within [{}] under the Records element.
|-
|-
|REST||The REST interface only allows a single record per request.
|REST||The REST interface only allows a single record per request.
|}
<h3 style="background-color:rgb(240,240,240);">Record ID</h3>
:''Optional.''
: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.
:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"rec":"'''''string'''''"</code>
|-
|REST||<code>&rec = '''''string'''''</code>
|}
|}


Line 166: Line 345:
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|REST||&comp = {string}
|JSON||<code>"comp":"'''''string'''''"</code>
|-
|REST||<code>&comp = '''''string'''''</code>
|}
|}


|Phone Number|| ||phone


<h3 style="background-color:rgb(240,240,240);">Phone Number</h3>
:''Optional.''
:The phone number of the business.
:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"phone":"'''''string'''''"</code>
|-
|REST||<code>&phone = '''''string'''''</code>
|}




Line 181: Line 373:
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|REST||&a1 = {string}
|JSON||<code>"a1":"'''''string'''''"</code>
|-
|REST||<code>&a1 = '''''string'''''</code>
|}
|}


Line 193: Line 387:
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|REST||&a2 = {string}
|JSON||<code>"a2":"'''''string'''''"</code>
|-
|REST||<code>&a2 = '''''string'''''</code>
|}
 
 
<h3 style="background-color:rgb(240,240,240);">Suite</h3>
:''Optional.''
 
:The suite/apartment number for the business.
 
:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"suite":"'''''string'''''"</code>
|-
|REST||<code>&suite = '''''string'''''</code>
|}
|}


Line 205: Line 415:
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|REST||&city = {string}
|JSON||<code>"city":"'''''string'''''"</code>
|-
|REST||<code>&city = '''''string'''''</code>
|}
|}


Line 217: Line 429:
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|REST||&state = {string}
|JSON||<code>"state":"'''''string'''''"</code>
|-
|REST||<code>&state = '''''string'''''</code>
|}
|}


Line 229: Line 443:
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|REST||&postal = {string}
|JSON||<code>"postal":"'''''string'''''"</code>
|-
|REST||<code>&postal = '''''string'''''</code>
|}
|}


Line 241: Line 457:
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|REST||&ctry = {string}
|JSON||<code>"ctry":"'''''string'''''"</code>
|-
|REST||<code>&ctry = '''''string'''''</code>
|}
|}


Line 253: Line 471:
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|REST||&mkey = {string}
|JSON||<code>"mak":"'''''string'''''"</code>
|-
|REST||<code>&mak = '''''string'''''</code>
|}
|}


Line 265: Line 485:
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|REST||&stock = {string}
|JSON||<code>"stock":"'''''string'''''"</code>
|-
|REST||<code>&stock = '''''string'''''</code>
|}
|}


Line 277: Line 499:
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|REST||&web = {string}
|JSON||<code>"web":"'''''string'''''"</code>
|-
|REST||<code>&web = '''''string'''''</code>
|}
 
 
<h3 style="background-color:rgb(240,240,240);">Melissa Enterprise Key (MEK)</h3>
:''Optional.''
 
:The unique identifier given by Business Coder.
 
:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"mek":"'''''string'''''"</code>
|-
|REST||<code>&mek = '''''string'''''</code>
|}
 
 
<h3 style="background-color:rgb(240,240,240);">Free Form</h3>
:''Optional.''
 
:This is a string value which can contain one of the possible minimum input requirements.
 
:'''NOTE:''' If freeform is populated it will ignore all other input fields.
 
:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"ff":"'''''string'''''"</code>
|-
|REST||<code>&freeform = '''''string'''''</code>
|}
|}



Latest revision as of 00:04, 11 May 2022

← Business Coder

Business Coder Navigation
Introduction
Licensing
Input/Output
Request Fields
Response Fields
Examples
REST JSON
Result Codes
Result Code Use
Business Coder Result Codes
Sample Code



A request consists of a protocol to make a call to the service, detailing desired elements. Your License Key is required.

Business Coder supports the JSON and REST protocols to access the service.


URL

Use URL
Standard http://businesscoder.melissadata.net/WEB/BusinessCoder/doBusinessCoderUS
Secure https://businesscoder.melissadata.net/WEB/BusinessCoder/doBusinessCoderUS


Field Names

This is a list of the request field names and their protocol naming conventions.

Field Name Level REST JSON
Transmission Reference Request t t
License Key id id
Column cols cols
Options opt opt
Record ID Record rec rec
Company Name comp comp
Phone Number phone phone
Address1 a1 a1
Address2 a2 a2
Suite suite suite
City city city
State state state
Postal postal postal
Country ctry ctry
Melissa Address Key (MAK) mak mak
Stock Ticker stock stock
Web Address web web
Melissa Enterprise Key (MEK) mek mek
Free Form ff freeform


Minimum Inputs

The following are the possible minimum input requirements.

  1. Company Only
  2. MAK and Company
  3. Address Only
  4. MAK Only
  5. Phone Number
  6. Stock Ticker
  7. Web Address


Request Elements

The following elements set the basic options for each request. These apply to the entire request, not the individual records.

Transmission Reference

Optional.
This is a string value that serves as a unique identifier for this set of records. It is returned as sent.
Protocol Syntax
JSON "t":"string"
REST ?t = string


License Key

Required.
This is a string value containing the License Key issued to the customer by Melissa Data for the Business Coder.
If this element is absent, the Web Service will return an error. To receive a License Key, please contact your Melissa Data sales representative at 1-800-MELISSA.
Protocol Syntax
JSON "id":"string"
REST &id = string


Column

Optional.
This string value specifies which column(s) to be output as a comma delimited string.
Protocol Syntax
JSON "cols":"string"
REST &cols = string


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

Field Name Group
TransmissionResults [DEFAULT]

These columns are returned by default.

TransmissionReference
Records
RecordID
CompanyName
CurrentCompanyName
AddressLine1
Suite
City
State
PostalCode
TotalContacts
MelissaEnterpriseKey
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


JSON Array returned by Contacts
Contacts:
NameFirst
NameLast
Gender
Title
Email


Options

Optional.
This is a string value containing the options set by the user.
Protocol Syntax
JSON "opt":"string"
REST &opt = string


List options in the following format.
Syntax
OptionName:Parameter


CentricHint

This option allows you to choose what the service will center the search around.
Option Name Parameter Description
CentricHint 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.
Option Name Parameter Description
MaxContacts # [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.
Option Name Parameter Description
ReturnDominantBusiness 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.
Option Name Parameter Description
SICNAICSConfidence strict Returns very confident or correct SIC Codes. Returns null if none pass the requirement.
loose Default. Returns any associated SIC Codes.


Request Record Elements

REST will only contain the Records element.

Protocol Definition
JSON Each record will be contained within [{}] under the Records element.
REST The REST interface only allows a single record per request.


Record ID

Optional.
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.
Protocol Syntax
JSON "rec":"string"
REST &rec = string


Company Name

Optional.
The name of the business.
Protocol Syntax
JSON "comp":"string"
REST &comp = string


Phone Number

Optional.
The phone number of the business.
Protocol Syntax
JSON "phone":"string"
REST &phone = string


Address1

Optional.
The first address line of the business.
Protocol Syntax
JSON "a1":"string"
REST &a1 = string


Address2

Optional.
The second address line (suite) of the business.
Protocol Syntax
JSON "a2":"string"
REST &a2 = string


Suite

Optional.
The suite/apartment number for the business.
Protocol Syntax
JSON "suite":"string"
REST &suite = string


City

Optional.
The city (locality).
Protocol Syntax
JSON "city":"string"
REST &city = string


State

Optional.
The state (Administrative Area).
Protocol Syntax
JSON "state":"string"
REST &state = string


Postal

Optional.
The postal code.
Protocol Syntax
JSON "postal":"string"
REST &postal = string


Country

Optional.
The country.
Protocol Syntax
JSON "ctry":"string"
REST &ctry = string


Melissa Address Key (MAK)

Optional.
A propietary unique key identifier for an address. This is derived from Address Checking.
Protocol Syntax
JSON "mak":"string"
REST &mak = string


Stock Ticker

Optional.
A unique abbreviation/symbol assigned by the stock exchange for listed companies.
Protocol Syntax
JSON "stock":"string"
REST &stock = string


Web Address

Optional.
The web address/domain for a company.
Protocol Syntax
JSON "web":"string"
REST &web = string


Melissa Enterprise Key (MEK)

Optional.
The unique identifier given by Business Coder.
Protocol Syntax
JSON "mek":"string"
REST &mek = string


Free Form

Optional.
This is a string value which can contain one of the possible minimum input requirements.
NOTE: If freeform is populated it will ignore all other input fields.
Protocol Syntax
JSON "ff":"string"
REST &freeform = string