Quickstart Guide| LeadGen - Business

Introduction

LeadGen Business can be used to:

Select, Get Counts, and Purchase Targeted Business Mailing Lists
Do any of the above in real-time, anytime

Basic Order of Operations

Real Time

Set up the request: license key, options, ect.
Send the count request: This call returns an XML document showing the record counts for a specific request, allowing you to see how many records are available for the selected parameters.
Send the buy request: This call initiates the purchase of the list detailed by the request. This call is similar to the Get call, but has additional information returned. This information is the order ID, number of usage, and download URL. If the purchase of the list was successful, you will receive a link to the list file in the format you selected in the options.
Download/Retrieve list: download the list from HTTPS link in the buy call response.

Input Request

Simply replace [your Melissa license key] with your license key to test these requests. It will also work in any browser.

REST - Count

Use a REST request to get the count.

curl -X GET "http://list.melissadata.net/v1/Business/rest/Service.svc/get/zip?id=[your Melissa license key]&zip=92688&sale-d=2"

REST - Purchase

Use the REST request to purchase the list.

curl -X GET "http://list.melissadata.net/v1/Business/rest/Service.svc/get/zip?id=[your Melissa license key]&zip=92688&sale-d=2&file=7"

HTTPS - Download

Use the HTTPS link to download the purchased list.

curl -u user:password "https://list.melissadata.com/ListOrderFiles/123456_678910.csv"

Input Fields

Geography Request Parameters

Parameter	Type	Description
`Zip` (5 digits) or `zip+4` (9 digits)	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 validated
`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 records must be given.)	Mile is used to find out the latitude and longitude of a parameter so many miles away from the give 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 records must be given.)	Number of records that are the closest to the 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;latititude point

Business Request Parameters

Parameter Description 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

Code	Definition
1	1 - 4
2	5 - 9
3	10 - 19
4	20 - 49
5	50 - 99
6	100 - 249
7	250 - 499
8	500 - 999
9	1,000 - 4,999
10	5,000 - 9,999
11	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 selection/filter

Code	Definition
1	$1,000-$499,999
2	$500,000-$999,999
3	$1,000,000-$2,499,999
4	$2,500,000-$4,999,999
5	$5,000,000-$9,999,999
6	$10,000,000-$19,999,999
7	$20,000,000-$49,999,999
8	$50,000,000-$99,999,999
9	$100,000,000-$499,999,999
10	$500,000,000-$999,999,999
11	Over $1 billion

all inclusive

Otherwise specify the index; use ‘-‘ dash to specify multiple sales volume codes, i.e.
sale-d =6-8-10

Input Best Practices

While text encoding is a rare issue with LeadGen Business Web Service, note that the API will not support any wrongly-encoded special characters or non-Latin characters. In general, text encoding is an important part of any data enterprise.

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.

Output Response

XML Response

Here is a sample response.

<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>https://list.melissadata.com/ListOrderFiles/123456.csv</DownloadURL>
    <DeliveredQty>63</DeliveredQty>
  </Order>
  <Result>
    <StatusCode>Approved</StatusCode>
  </Result>  
</Business>

Output Fields

Field Name	Description
`<Business>`	Tag encapsulating the whole XML document.
`<Geography>`	Geo request
`<Address>`	Requests within Geo Selects. Tags returned depend on Geo type.
`<City>`
`<County>`
`<State>`
`<ZIP>`
`<Records>`
`<Circle>`
`<Miles>`
`<Options>`
`<ContactPersonInfo>`
`<ContactPersonInfo>`	One per business All contacts
`<NumberOfEmployees>`
`<IncludeAll> OR <Details>`	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.
`<AppendToFile>`	True or False
`<SalesVolumes>`	Various ranges of annual sales volumes
`<IncludeAll> OR <Details>`	Default output is `<IncludeAll>True</IncludeAll>`, unless details options are specified in request. For example, `<Details>$10,000,000-$19,999,999;$50,000,000-$99,999,999;$500,000,000-$999,999,999</Details>` would be shown with all chosen options separated by semi colon.
`<AppendToFile>`	True or False
`<SICCodes>`	6-digit SIC code
`<IncludeAll> OR <Details>`	Default output is `<IncludeAll>True</IncludeAll>`, unless details options are specified in request. For example, `<Details>CONSTRUCTION-SPECIAL TRADE CONTRACTORS;NONCLASSIFIED ESTABLISHMENTS;CREDIT & DEBT COUNSELING SERVICES</Details>` would be shown with all chosen options separated by semi colon.
`<AppendToFile>`	True or False
`<AdditionalAppend>`
`<ContactName>`	True or False.
`<CountDetails>`
`<StreetRange>`	Contains a breakdown of the street range.
`<Street>`	Individual streets.
`<StartNumber>`	For Geo types radius. Shows the starting street number and ending street number in the count.
`<EndNumber>`
`<Geography>`	Location of count detail. The location varies by the request type: ZIP type returns Zip plus 4. City type returns city, state. County type returns county, state. State type returns state. Radius type returns street, city, state
`<Zip>`	For radius type only.
`<Count>`	Location of count detail. The location varies by the request type: ZIP type returns Zip plus 4. City type returns city, state. County type returns county, state. State type returns state. Radius type returns street.
`<Addresses>`	Only returned with Radius when strzip is specified. Contains a breakdown of the addresses returned.
`<Address>`	Individual addresses.
`<Count>`	Location of count detail. The location varies by the request type: ZIP type returns Zip plus 4. City type returns city, state. County type returns county, state. State type returns state.
`<TotalCount>`	Total number of records returned with the selected options.
`<Order>`	Buy Requests Only. Order details for a Buy request.
`<Id>`	Order Id.
`<Usage>`	One or multi usage specified in buy call.
`<DownloadURL>`	The URL to download the purchased file.
`<PONumber>`	Returned if po is specified.
`<DeliveredQty>`	Number of records returned
`<RequestedQty>`	Returned if &qty is specified.
`<Result>`	Indicates the status of a request. Returns Declined, Approved, or Err.
`<StatusCode>`
`<Errors>`	If <StatusCode> returns Err.
`<Error>`
`<ErrorCode>`
`<ErrorDescription>`

Download File

Column Name

Max Length

Description

Business

Business name

Contact

Name of contact person

Gender

M or F

Address

Mailing address

City

Mailing City

State

Mailing State

Zip

Mailing Zip

Plus4

Mailing Zip4

CART

Mailing Carrier Route

DPB

Mailing Delivery Point

SIC

This field contains the 6-digit SIC code for the business's primary activity (line of business). Approximately 79% of the records in the US business database have only 1 SIC Code.

SIC2

This field contains the 6-digit SIC code for the business's secondary activity (line of business). Approximately 23% of the records in the US business database have 2 SIC Codes.

SIC3

This field contains the 6-digit SIC code for the business's secondary activity (line of business). Approximately 8% of the records in the US business database have 3 SIC Codes.

SIC4

This field contains the 6-digit SIC code for the business's secondary activity (line of business). Approximately 3% of the records in the US business database have 4 SIC Codes.

EmpSize

This field contains an alpha code for the number of employees that work at this particular location.

Code	Number of Employees	Percentage of Employees
A	1 - 4	37.35%
B	5 - 9	25.76%
C	10 - 19	16.36%
D	20 - 49	7.19%
E	50 - 99	5.30%
F	100 - 249	3.50%
G	250 - 499	2.72%
H	500 - 999	1.03%
I	1,000 - 4,999	0.66%
J	5,000 - 9,999	0.07%
K	10,000 +	0.05%
blank	Unknown	24.80%

SlsVol

This field contains an alpha code corresponding to the estimated sales of the business in thousands of dollars. Sales are based on this particular business location only.

Code	Sales in Thousands of Dollars	Percentage of Sales
A	1 - 499	29.93%
B	500 - 999	20.64%
C	1,000 - 2,499	13.11%
D	2,500 - 4,999	5.76%
E	5,000 - 9,999	4.25%
F	10,000 - 19,999	2.80%
G	20,000 - 49,999	2.18%
H	50,000 - 99,999	0.82%
I	100,000 - 499,999	0.53%
J	500,000 - 999,999	0.06%
K	1,000,000 +	0.04%
Blank	Unknown	19.87%

Interpreting Results

All Melissa products use result codes. LeadGen - Business Result codes are numeric codes, e.g. 101. Result codes are returned as a comma-delimited string with no whitespace, e.g. 100,101.

The following table shows the most common result codes seen while using LeadGen - Business.

Code	Description
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 have no permission to 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.