Quickstart Guide

LeadGen - Consumer

Introduction

LeadGen Occupant can be used to:

  • Select, Get Counts, and Purchase Targeted Consumer Mailing Lists
  • Do any of the above in real-time, anytime
  • You can custom-design a website to meet your own needs, as well as those of your customers.

Basic Order of Operations

Real Time

  • Set up the request: license key, options, ect.
  • Send the count request: This call returns an XML/JSON 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/Consumer/rest/Service.svc/get/city?id=[your Melissa license key]&city=CA;orange&&ownRent-d=1&dwell=2&cAge-d=3-4-5&phone=1"

REST - Purchase

Use the REST request to purchase the list.

curl -X GET "http://list.melissadata.net/v1/Consumer/rest/Service.svc/buy/city?id=[your Melissa license key]&city=CA;orange&&ownRent-d=1&dwell=2&cAge-d=3-4-5&phone=1&file="

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

Geometry Request Parameters

Parameter Type Description
Zip (5 digits) or
zip+4 (9 digits)		 Required: zip
Optional: radius, street		 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 (mile)
Optional: radius
(One of the two should be given, not required together.)		 Mile is used to find out the latitude and longitude of a parameter so many miles away from the given point or address.
For circle, it must be within 0.25 and 25 miles.
Records Number of records that are the closest to the given address.
Str Required: street
Optional: radius		 A street name within the given zip.
For radius type, the street name needs to be exact.
For street type, if not exact street name is found, similar street name (as a substring) is searched.
Strzip Optional: radius Zip for a specific street that is within the given radius (combination with a given address).
Points Required: polygon Each set of points for polygon is validate, and reoriented in the sequence of drawing.
Pt Required: circle A longitude;latititude point

Demographic Request Parameters

Parameter Description Values
hInc Append household income info to file. Default: hInc =0
To append: hInc =1
hInc-d Various ranges of household incomes.
Code Definition
1 $0 - 14,999
2 $15,000 - 19,999
3 $20,000 - 29,999
4 $30,000 - 39,999
5 $40,000 - 49,999
6 $50,000 - 74,999
7 $75,000 - 99,999
8 $100,000 - 124,999
9 $125,000 - 149,999
10 $150,000 - 174,999
11 $175,000 - 199,999
12 $200,000 - 249,999
13 $250,000+
Default: all inclusive
Otherwise specify the index; use ‘-‘ dash to specify multiple ranges, i.e.
hInc-d =2-3-5
cAge Append contact age group info to file if exists (frequency: 84.2%) Default: cAge=0
To append: cAge=1
cAge-d Various contact age groups.
Code Definition
1 18-20
2 21-25
3 26-30
4 31-35
5 36-40
6 41-45
7 46-50
8 51-55
9 56-60
10 61-65
11 66-70
12 71-75
13 76+
Default: all inclusive
Otherwise specify the index; use ‘-‘ dash to specify multiple ranges, i.e.
cAge-d =2-3-5
ownRent Append home owner/renter info to file if exists (frequency: 98.5%) Default: ownRent=0
To append: ownRent=1
ownRent-d Home owner or renter
Code Definition
1 Home Owner
2 Renter
Default: all inclusive
Otherwise specify the index, i.e.
ownRent-d =1
marital Append marital status to file Default: marital =0
To append: marital=1
marital-d Various marital statuses
Code Definition
1 Unknown
2 Household contain at least 1 married person
3 Household contain at least 1 single person
4 Household contain both married & single persons
Default: all inclusive
Otherwise specify the index; use ‘-‘ dash to specify multiple ranges, i.e.
marital–d=2-3-4
resLen Append length of residency to file Default: resLen=0
To append: resLen=1
resLen-d Various lengths of residency
Code Definition
1 0 - 6 months
2 7 - 12 months
3 1 - 2 years
4 3 - 5 years
5 6 - 10 years
6 11 - 15 years
7 16 - 20 years
8 20 or more years
Default: all inclusive
Otherwise specify the index; use ‘-‘ dash to specify multiple ranges, i.e.
resLen-d=2-3-4
hAge Append household age code to file Default: hAge=0
To append: hAge=1
hAge-d Various household age codes
Code Definition
1 18 - 24
2 25 - 34
3 35 - 44
4 45 - 54
5 55 - 64
6 65 - 74
7 75+
Default: all inclusive
Otherwise specify the index; use ‘-‘ dash to specify multiple ranges, i.e.
hAge–d=2-3-4
people Append number of people in household to file Default: people =0
To append: people=1
people-d Various numbers of people in household
Code Definition
1 1 person
2 2 persons
3 3 persons
4 4 persons
5 5 persons
6 6 persons
7 7 persons
8 8 persons
9 9+
Default: all inclusive
Otherwise specify the index; use ‘-‘ dash to specify multiple ranges, i.e.
people-d=2-3-4
adults Append numbers of adults in household to file Default: adults=0
To append: adults=1
adults-d Various numbers of adults in household
Code Definition
1 1 adult
2 2 adults
3 3 adults
4 4 adults
5 5 adults or more
Default: all inclusive
Otherwise specify the index; use ‘-‘ dash to specify multiple ranges, i.e.
adults –d=2-3-4
kids Append numbers of children in household to file if exists (frequency: 25.5%) Default: kids=0
To append: kids=1
kids-d Various numbers of children in household
Code Definition
1 0 child
2 1 child
3 2 children
4 3 children
5 4 children
6 5 children
7 6 children
8 7 children
9 8 children
10 9 children or more
All inclusive
Otherwise specify the index; use ‘-‘ dash to specify multiple ranges, i.e.
kids-d=2-3-9
cCard Append household credit card info to file Default: cCard=0
To append: cCard=1
cCard-d Various household credit cards
Code Definition
1 Miscellaneous Credit Card
2 Standard Retail Card
3 Standard Specialty Card
4 Upscale Retail Card
5 Upscale Specific Retail Card
6 Bank Card
7 Oil-Gas Card
8 Finance Company Card
9 Travel/Entertainment Card
Default: all inclusive
Otherwise specify the index; use ‘-‘ dash to specify multiple ranges, i.e.
cCard –d=2-3-4
mail Append mail responsive info to file if exists (frequency: 66.5%) Default: mail=0
To append: mail=1
mail-d Various mail responsive info
Code Definition
1 Mail Buyer Indicator
2 Mail Donor Indicator
Default: all inclusive
Otherwise specify the index; use ‘-‘ dash to specify multiple ranges, i.e.
mail-d=2
worth Append net worth to file if exists (frequency: 69.5%) Default: worth=0
To append: worth=1
worth-d Various net worth ranges
Code Definition
1 Less than $25K
2 $25,000-$49,999
3 $50,000-$74,999
4 $75,000-$99,000
5 $100,000-$149,999
6 $150,000-$249,999
7 $250,000-$499,999
8 $500,000-$749,999
9 $750,00-$999,999
10 $1,000,000 or More
Default: all inclusive
Otherwise specify the index; use ‘-‘ dash to specify multiple ranges, i.e.
Worth-d=2-3-5
home Append target home valuation mode in 1,000s to file if exists (frequency: 76.2%) Default: home=0
To append: home=1
Home-d Various ranges of target home valuation mode in 1,000s
Code Definition
1 $1 - 49,999
2 $50,000 - 99,999
3 $100,000 - 149,999
4 $150,000 - 199,999
5 $200,000 - 249,999
6 $250,000 - 299,999
7 $300,000 - 349,999
8 $350,000 - 399,999
9 $400,000 - 449,999
10 $450,000 - 499,999
11 $500,000 - 574,999
12 $575,000 - 649,999
13 $650,000 - 724,999
14 $725,000 - 799,999
15 $800,000 - 899,999
16 $900,000 - 999,999
17 $1,000,000 - 1,999,999
18 $2,000,000+
Default: all inclusive
Otherwise specify the index; use ‘-‘ dash to specify multiple ranges, i.e.
home–d=2-3-5

Input Best Practices

While text encoding is a rare issue with LeadGen Consumer 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.

<Consumer>
  <Geography>
    <City>CA;orange</City>
  </Geography>
  <Options>
    <ContactPersonInfo>
      <ContactPersonInfo>One per Address</ContactPersonInfo>
    </ContactPersonInfo>
    <BuildingType>
      <Details>Single Family Only</Details>
    </BuildingType>
    <HouseholdIncome>
      <IncludeAll>True</IncludeAll>
      <AppendToFile>False</AppendToFile>
    </HouseholdIncome>
    <ContactAgeGroup>
      <Details>26-30;31-35;36-40</Details>
      <AppendToFile>False</AppendToFile>
    </ContactAgeGroup>
    <HomeOwnerRenter>
      <Details>Home Owner</Details>
      <AppendToFile>False</AppendToFile>
    </HomeOwnerRenter>
    <MaritalStatus>
      <IncludeAll>True</IncludeAll>
      <AppendToFile>False</AppendToFile>
    </MaritalStatus>
    <LengthOfResidentCode>
      <IncludeAll>True</IncludeAll>
      <AppendToFile>False</AppendToFile>
    </LengthOfResidentCode>
    <HouseholdAgeCode>
      <IncludeAll>True</IncludeAll>
      <AppendToFile>False</AppendToFile>
    </HouseholdAgeCode>
    <NumPersonsInHousehold>
      <IncludeAll>True</IncludeAll>
      <AppendToFile>False</AppendToFile>
    </NumPersonsInHousehold>
    <NumAdultsInHousehold>
      <IncludeAll>True</IncludeAll>
      <AppendToFile>False</AppendToFile>
    </NumAdultsInHousehold>
    <NumChildrenInHousehold>
      <IncludeAll>True</IncludeAll>
      <AppendToFile>False</AppendToFile>
    </NumChildrenInHousehold>
    <HouseholdCreditCardInfo>
      <IncludeAll>True</IncludeAll>
      <AppendToFile>False</AppendToFile>
    </HouseholdCreditCardInfo>
    <MailResponsiveInfo>
      <IncludeAll>True</IncludeAll>
      <AppendToFile>False</AppendToFile>
    </MailResponsiveInfo>
    <TargetNetWorth>
      <IncludeAll>True</IncludeAll>
      <AppendToFile>False</AppendToFile>
    </TargetNetWorth>
    <TargetHomeMarketValue>
      <IncludeAll>True</IncludeAll>
      <AppendToFile>False</AppendToFile>
    </TargetHomeMarketValue>
    <AdditionalAppend>
      <PhoneNumber>True</PhoneNumber>
    </AdditionalAppend>
  </Options>
  <CountDetails>
    <StreetRange>
      <Street>
        <StartNumber/>
        <EndNumber/>
        <Geography>Orange, CA</Geography>
        <Zip/>
        <Count>16192</Count>
      </Street>
    </StreetRange>
    <TotalCount>
      <Count>16192</Count>
    </TotalCount>
    <Order>
      <Id>123456</Id>
      <Usage>1</Usage>
      <DownloadURL>https://list.melissadata.com/ListOrderFiles/123456_678910.csv</DownloadURL>
      <DeliveredQty>16192</DeliveredQty>
    </Order>
    <Result>
      <StatusCode>Approved</StatusCode>
    </Result>
  </CountDetails>
</Consumer>

Output Fields

Field Name Description
<Consumer> Tag encapsulating the whole XML document.
<Geography> Geo request
<Address> Tags returned depend on Geo type.
<City>
<County>
<State>
<ZIP>
<Polygons>
<Circle>
<Records> Returned if Radius is called with &records specification.
<Miles> Returned if radius is called with &mile specification.
<Options> Demographic Selects Request
<ContactPersonInfo>
<ContactPersonInfo>
  • One Per Address
  • All Contacts
<Gender> Returned if &gender is specified in url request. Output per request.
<OnlyAddressesWithZipPlus4> Returned if &zip4=1 is requested. Output: True.
<USPSPreferredCityNames> True or False
<BuildingType>
<Details>
  • Single and Multi-Family
  • Single Family Only
  • Multi-Family Only
<HouseholdIncome>
<IncludeAll> OR <Details> Default output is <IncludeAll>True</IncludeAll>, unless detailed options are specified in request. For example, <Details>$15,000 - 19,999;$20,000 - 29,999;$40,000 - 49,999</Details> would be shown with all chosen options separated by semi colon.
<AppendToFile> True or False
<ContactAgeGroup>
<IncludeAll> OR <Details> Default output is <IncludeAll>True</IncludeAll>, unless detailed options are specified in request. For example, <Details>21-25;26-30;36-40</Details> would be shown with all chosen options separated by semi colon.
<AppendToFile> True or False
<HomeOwnerRenter>
<IncludeAll> OR <Details> Default output is <IncludeAll>True</IncludeAll>, unless detailed option is specified in request. For example, <Details>Home Owner</Details> would be shown.
<AppendToFile> True or False
<MaritalStatus>
<IncludeAll> OR <Details> Default output is <IncludeAll>True</IncludeAll>, unless detailed options are specified in request. For example, <Details>Household contain at least 1 married person;Household contain at least 1 single person;Household contain both married & single persons</Details> would be shown with all chosen options separated by semi colon.
<AppendToFile> True or False
<LengthOfResidentCode>
<IncludeAll> OR <Details> Default output is <IncludeAll>True</IncludeAll>, unless detailed options are specified in request. For example, <Details>07 - 12 months;01 - 02 years;03 - 05 years</Details> would be shown with all chosen options separated by semi colon.
<AppendToFile> True or False
<HouseholdAgeCode>
<IncludeAll> OR <Details> Default output is <IncludeAll>True</IncludeAll>, unless detailed options are specified in request. For example, <Details>25 - 34;35 - 44;45 - 54</Details> would be shown with all chosen options separated by semi colon.
<AppendToFile> True or False
<NumPersonsInHousehold>
<IncludeAll> OR <Details> Default output is <IncludeAll>True</IncludeAll>, unless detailed options are specified in request. For example, <Details>2 persons;3 persons;4 persons</Details> would be shown with all chosen options separated by semi colon.
<AppendToFile> True or False
<NumAdultsInHousehold>
<IncludeAll> OR <Details> Default output is <IncludeAll>True</IncludeAll>, unless detailed options are specified in request. For example, <Details>2 adults;3 adults;4 adults</Details>, would be shown with all chosen options separated by semi colon.
<AppendToFile> True or False
<NumChildrenInHousehold>
<IncludeAll> OR <Details> Default output is <IncludeAll>True</IncludeAll>, unless detailed options are specified in request. For example, <Details>2 children;3 children;9+</Details> would be shown with all chosen options separated by semi colon.
<AppendToFile> True or False
<HouseholdCreditCardInfo>
<IncludeAll> OR <Details> Default output is <IncludeAll>True</IncludeAll>, unless detailed options are specified in request. For example, <Details>Standard Retail Card;Standard Specialty Card;Upscale Retail Card</Details> would be shown with all chosen options separated by semi colon.
<AppendToFile> True or False
<MailResponsiveInfo>
<IncludeAll> OR <Details> Default output is <IncludeAll>True</IncludeAll>, unless detailed options are specified in request. For example, <Details>Mail Donor Indicator</Details> would be shown with all chosen options separated by semi colon.
<AppendToFile> True or False
<TargetNetWorth>
<IncludeAll> OR <Details> Default output is <IncludeAll>True</IncludeAll>, unless detailed options are specified in request. For example, <Details>$25,000-$49,999;$50,000-$74,999;$100,000-$149,999</Details> would be shown with all chosen options separated by semi colon.
<AppendToFile> True or False
<TargetHomeMarketValue>
<IncludeAll> OR <Details> Default output is <IncludeAll>True</IncludeAll>, unless detailed options are specified in request. For example, <Details>$50,000 - 99,999;$100,000 - 149,999;$200,000 - 249,999</Details> would be shown with all chosen options separated by semi colon.
<AppendToFile> True or False
<AdditionalAppend>
<PhoneNumber> True or False
<StructureYear> True or False
<FamilyRelationship> True or False
<BirthDate> True or False
<CountDetails> Contains a breakdown of the total count.
<StreetRange> Contains a breakdown of the street range.
<Street> Individual streets.
<StartNumber> For Geo types radius and street. 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.
  • Street type returns street, city, state.
  • Radius type returns street, city, state.
  • Polygon type returns sets of polygon points with longitude and latitude.
<Zip> For radius and street types only.
<Count> Number of records that <StartNumber>, <EndNumber>, <Geography>, and <Zip> apply to.
<Addresses>
  • Returned with geo type Street.
  • Only returned with Radius when strzip is specified.
  • Contains a breakdown of the addresses returned.
<Address> Individual addresses.
<TotalCount> Total number of records returned with the selected options.
<Order> Buy Requests Only. Order details for a Buy request.
<Id> Order Id.
<Usage>
<DownloadURL> The URL to download the purchased file.
<PONumber> Returned if po is specified.
<DeliveredQty>
<RequestedQty> Returned if &qty is specified.
<Result> Returns the status code.
<StatusCode> Indicates the status of a request. Returns Declined, Approved, or Err.
<Errors> If <StatusCode> returns Err.
<Error>
<ErrorCode>
<ErrorDescription>

Download File

Column Name Max Length URL Parameter Description
Address 75 Mailing street address
City 28 Mailing city name
State 2 Mailing state
Zip 5 Mailing zip
Plus4 4 Maling zip4
CRRT 4 Mailing carrier route
DPB 3 Mailing Delivery Point
namePrefixCode 1
Code Definition
1 Mr
2 Mrs with male name
3 Miss or Ms
4 Mrs
5 Dr
6 Rev
Blank Blank
firstName 14
lastName 20
nameSuffix 2
Code
3D
Blank
II
IV
JR
SR
HouseIncome 1 hInc=1
Code Definition
1 Less than $15,000
2 $ 15,000 - $ 19,999
3 $ 20,000 - $ 29,999
4 $ 30,000 - $ 39,999
5 $ 40,000 - $ 49,999
6 $ 50,000 - $ 74,999
7 $ 75,000 - $ 99,999
8 $ 100,000 - $124,999
9 $ 125,000 - $149,999
A $ 150,000 - $174,999
B $ 175,000 - $199,999
C $ 200,000 - $249,999
D $ 250,000 or more
Age1 3 cAge=1 Data is presented in 2-year bands. So, for example, 18 means 18 or 19 and 34 means 34 or 35
OwnerRenter 1 ownRent=1
Code Definition
0 No Information
1 Definite Renter
2 Probable Renter
3 Probable owner
4 Definite owner
MaritalStatus 1 marital=1
Code Definition
0 Not Available
1 Household contains at least 1 Married person
2 Household contains at least 1 Single person
3 Household contains both married and single persons
LengthResidence 1 resLen=1
Code Definition
A 00–06 months
B 07-12 months
C 13-18 months
D 19-24 months
E In the 3rd year
F In the 4th year
G In the 5th year
H In the 6th year
I In the 7th year
J In the 8th year
K In the 9th year
L In the 10th year
M In the 11th year
N In the 12th year
O In the 13th year
P In the 14th year
Q In the 15th year
R In the 16th year
S In the 17th year
T In the 18th year
U In the 19th year
V 20 or more years
AgeHouseholdCode 1 hAge=1
Code Definition
1 18-24 years old
2 25-34 years old
3 35-44 years old
4 45-54 years old
5 55-64 years old
6 65-74 years old
7 75+ years old
NumPersons 1 people=1
Code Definition
1 One person
2 Two persons
3 Three persons
4 Four persons
5 Five persons
6 Six persons
7 Seven persons
8 Eight persons
9 Nine or more persons
Blank Not Available
NumAdults adults=1
Code Definition
1 One adult
2 Two adults
3 Three adults
4 Four adults
5 Five adults
Blank Unknown number of adults
NumChildren kids=1
Code Definition
1 No child
2 One child
3 Two children
4 Three children
5 Four children
6 Five children
7 Six children
8 Seven children
9 Eight children
10 Nine or more children
Blank Unknown number of children
CCMisc 1 cCard=1 Represents a category of Credit card used by someone within the household.
CCStdRetail
CCStdSpecialty
CCUpRetail
CCUpSpecialty
CCBank
CCOil
CCFinance
CCTravel
MailBuyer 1 mail=1
Code Definition
0 No mail buyer information available
1 Single mail buyer
2 Multiple mail buyer
MailDonor
Code Definition
0 No mail buyer information available
1 Single mail buyer
2 Multiple mail buyer
TargetNetWorth 1 worth=1
Code Definition
0 Less than $25k
1 $25,000 - $49,999
2 $50,000 - $74,999
3 $75,000 - $99,999
4 $100,000 - $149,999
5 $150,000 - $249,999
6 $250,000 - $499,999
7 $500,000 - $749,999
8 $750,000 - $999,999
9 $1,000,000 or More
Blank Blank
TargetHomeMarketValue 10 Home=1 Home Market Value in Thousands
Phone 10 phone=1
BirthYear1 4 birth=1 Format: YYYY
BirthMonth1 2
Code Definition
1 January
2 February
3 March
4 April
5 May
6 June
7 July
8 August
9 September
10 October
11 November
12 December
Blank Blank
MemberCode 1 fam=1
Code Definition
1 Head of Household
Blank Not Available
StructureAgeYear 4 struct=1 Construction year of the home
Format: YYYY

Interpreting Results

All Melissa products use result codes. LeadGen - Consumer 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 - Consumer.

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 Excel and comma limited files cannot have more than 65,535 records.
125 Request exceeds 10 miles maximum radius.
126 Invalid polygon(s).
127 The square mileage requested exceeds the limit 10 square miles.
128 The number of polygons requested exceeds the limit 10 polygons.
129 Miles of radius for the circle must be within 0.25 and 25 miles.
130 You have exceeded your order limit.
131 You're approaching your order limit.
132 Your subscription will expire soon.
133 Your subscription expired.
134 Invalid latitude/longitude.