Reference Guide#

Introduction #

The Business Web Service is a dynamic REST-based web service, tailored for selecting, retrieving counts, and acquiring precision-targeted business mailing lists instantly, round the clock. It serves as a versatile resource, accessible to mailers for exclusive in-house utilization or as a convenient portal for your customers, facilitating their list selection process. You have the flexibility to craft a customized website to align with your unique requirements, as well as cater to the preferences of your valued clientele

Base URL #

https://list.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, LeadGen Consumer will not function.

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

Endpoints #

/v1/Business #

Introduction #

There are multile endpoints you can access for LeadGen: Business. These endpoints are all formatted like:

https://list.melissadata.net/v1/Business/{{action}}_{{geographicType}}

Where action is either get or buy and geographicType is one geographic type selected from one of these supported types: Geographic Types

Try it Now #

GET XML
BUY XML

curl -X GET "http://list.melissadata.net/v1/Business/rest/Service.svc/get/zip?\
&id={{customer@domain.com}}\
&zip=92688\
&sale-d=2"

curl -X GET "https://list.melissadata.net/v1/Business/rest/Service.svc/get/zip?\
&id={{customer@domain.com}}\
&zip=92688\
&sale-d=2\
&file=7"

Request Parameters #

GET XML

Code

Description

Version

Version of the web service.

Web Service

Business.

Protocol

REST.

Action

Get count or buy list.

Geographic Type

Requester’s customer ID or email Address

opt

Actions #

There are two avaliable actions: get and buy

Action	Service Description
Get	Get count of addresses that fit in the given criteria.
Buy	Buy a list of addresses’ info that fit the given criteria.

Options #

Geographic Options #

URL Paramters	Geographic Type	Handling
Zip (5digits) zip+4 (9digits)	Required: zip Optional: radius	Each five-digit ZIP is validated. Plus4 is a filter in data selection.
City	Required: city Optional: radius	Each city and state combination is valid
County	Required: county	Each county and state combination is validated. FIPS is retrieved if valid.
State	Required: state Optional: radius	Two-digit state code is validated.
Addr	Required: radius	Exact street number and street name are used in data selection. No validation. Latitude and longitude are retrieved if the address exists.
Mile	Required: circle Optional: radius (Mile or record must be given.)	Mile is used to find out the latitude and longitude of a parameter for many miles away from the given address. For radius type, maximum is 50 miles. For circle type, the radius must be between .025 and 25 miles
Records	Optional: radius (Mile or record must be given.)	Number of records that are closest to thte given address
Str	Optional: radius	A street name within the given zip. (The street name needs to be exact.)
Strzip	Optional: radius	Zip for a specific street that is within the given radius (combination with a given address.)
Pt	Required: circle	A longitude;latitude point
Points	Required: polygon	Each set of points for a polygon is validated and reoriented in the sequence of drawing.

Business Options #

URL Parameters	Meanings	Default	To Append
sic	Append 6- digit SIC code to file if exists	sic=0	sic=1
sic-d	Various SIC codes as selection/filter	all inclusive	Otherwise specify the SIC’s (2 to 6 digits), use ‘-’ dash to specify multiple SIC codes, i.e. sic-d=17-9999-729924
staff	Append number of employees to file	staff=0	staff=1
staff-d	Various sizes of staff as selection/filter 1 - 4 5 - 9 10 - 19 20 - 49 50 - 99 100 - 249 250 - 499 500 - 999 1,000 - 4,999 5,000 - 9,999 10,000	all inclusive	Otherwise specify the index; use ‘-’ dash to specify multiple staff codes, i.e. staff-d=6-8-10
sale	Append annual sales volume to file	sale=0	sale=1
sale-d	Various ranges of annual sales volumes as selction/filter $1,000-$499,999 $500,000-$999,999 $1,000,000-$2,499,999 $2,500,000-$4,999,999 $5,000,000-$9,999,999 $10,000,000-$19,999,999 $20,000,000-$49,999,999 $50,000,000-$99,999,999 $100,000,000-$499,999,999 $500,000,000-$999,999,999 Over $1 billion	all inclusive	Otherwise specify the index; use ‘-’ dash to specify multiple sales volume codes, i.e. sale-d=6-8-10
emails	0: records with no email 1: records with email 2: all records	emails=2
femails	Append emails to order file	femails=0	To append: femails=1

General Options #

URL Parameters	Description	Default Value	Optional Output Parameter
one	One contact per business	one=1	one=0 returns all contacts
dbug	Parameter check. If a parameter is spelt wrong or not suited for the given call, the request will be rejected.	dbug=0	dbug=1 to check

Other Purchase Options #

URL Parameters	Description	Default Value	Optional Output Parameter
name	Append contact name and gender to file if exists	name=0	To append: name=1
po	Customer’s purchase order number	none	To specify: po=xxxx
qty	Number of records requested	all records	To specify: qty=xxx
multi	Multiple usage of the list (1 - 5 times)	multi=1	Multi=(1through5)
file	Specify file format	file=8(csv)
email	0: records with no email 1: records with email 2: all records	email=2
email	Show emails in file?	femail=0	To append: femail=1

Response #

GET XML
BUY XML

  <Business>
      <Geography>
          <Zip/>
      </Geography>
      <Options>
          <ContactPersonInfo>
              <ContactPersonInfo>One per Business</ContactPersonInfo>
          </ContactPersonInfo>
          <NumberOfEmployees>
              <IncludeAll>True</IncludeAll>
              <AppendToFile>False</AppendToFile>
          </NumberOfEmployees>
          <AnnualSalesVolume>
              <IncludeAll>True</IncludeAll>
              <AppendToFile>False</AppendToFile>
          </AnnualSalesVolume>
          <SIC>
              <IncludeAll>True</IncludeAll>
              <AppendToFile>False</AppendToFile>
          </SIC>
          <Email>
              <Details>Records with No Email</Details>
              <AppendToFile>False</AppendToFile>
          </Email>
      </Options>
      <CountDetails>
          <StreetRange>
              <Street>
                  <StartNumber>0</StartNumber>
                  <EndNumber>0</EndNumber>
              </Street>
          </StreetRange>
      </CountDetails>
      <TotalCount>
          <Count>0</Count>
      </TotalCount>
      <Result>
          <StatusCode>Declined</StatusCode>
      </Result>
  </Business>

  <Business>
    <Geography>
      <ZIP>92688</ZIP>
    </Geography>
    <Options>
      <ContactPersonInfo>
        <ContactPersonInfo>One per Address</ContactPersonInfo>
      </ContactPersonInfo>
      <NumberOfEmployees>
        <IncludeAll>True</IncludeAll>
        <AppendToFile>False</AppendToFile>
      </NumberOfEmployees >
      <SalesVolumes>
        <Details>$5,000,000-$9,999,999</Details>
        <AppendToFile>False</AppendToFile>
      </SalesVolumes >
      <SICCodes>
        <IncludeAll>True</IncludeAll>
        <AppendToFile>False</AppendToFile>
      </SICCodes>
      <AdditionalAppend></AdditionalAppend>
    </Options>
    <TotalCount>
      <Count>63<Count>
    </TotalCount>
    <Order>
      <Id>123456</Id>
      <Usage>1</Usage>
      <DownloadURL>ftp://w10.melissadata.com/ListOrderFiles/123456.csv</DownloadURL>
      <DeliveredQty>63</DeliveredQty>
    </Order>
    <Result>
      <StatusCode>Approved</StatusCode>
    </Result>
  </Business>

Service Level Response Fields #

Output Name	Description
Version	The current service version number.
TransmissionReference	Optional. Serves as a unique request identifier.
TransmissionResults	Lists error codes from any errors caused by the most recent request as a whole.
TotalRecords	Total number of records.

Record Level Response Fields #

GET XML

Business	Tag encapsulating the whole XML document.
LB-Geography	Geo request.
LB-Address	Requests within Geo Selects. Tags returned depend on Geo type.
Zip	For radius type only.
Options	Requests within Geo Selects. Tags returned depend on Geo type.
Contact Person Info	One per business / All contacts
Number of Employees	Number of employees of the business
Include All	Default output is <IncludeAll>True</IncludeAll>, unless details options are specified in request. For example, <Details>100 – 249;500 – 999;5,000 - 9,999</Details> would be shown with all chosen options separated by semi colon
Apend to File	True or False
Annual Sales Volume	Various ranges of annual sales volumes
SICCodes	6-digit SIC code
Street Range	Contains a breakdown of the street range.
Street	Individual streets.
Start Number	For Geo types radius. Shows the starting street number in the count.
End Number	For Geo types radius. Shows the starting ending number in the count.
Total Count	Total number of records returned with the selected options.
Count	Location of count detail. The location varies by the request type
Result	Indicates the status of a request. Returns Declined, Approved, or Err.
Status Code	Indicates the status

Status Codes #

For details of all status codes please visit here

LeadGen - Business Status codes are numeric codes, e.g. 101. Status codes are returned as a comma-delimited string with no whitespace, e.g. 100,101.

Record Level Status Codes #

Code	Long Description
Consumer List
100	Unrecognized ZIP Code.
101	Unrecognized city or state.
102	Unrecognized county or state.
103	Unrecognized address.
104	User ID or password not recognized.
106	Invalid user information.
108	Order failed, please try later.
109	Insufficient geographic input.
111	Request exceeds 100,000 record maximum.
112	Unrecognized state.
113	Error, please try again.
115	For the Radius geography type, please enter a number of records.
116	Sorry, you don’t have permission to access this service.
117	ZIP Code is not a valid input for the requested geography type.
121	The list cannot be used more than 5 times.
122	Order count exceeds 65,535 record maximum for Excel files.
123	Invalid option.
124	Order count exceeds 65,535 record maximum for comma limited files.

Reference Guide

Contents

Reference Guide#