Skip to content
/Consumer Service

LeadGen - Consumer

Overview

LeadGen Consumer Cloud API offers a real-time REST-based solution, enabling users to select, retrieve counts, and purchase customized consumer mailing lists.

The LeadGen Cloud APIs are at the disposal of mailers, whether for private in-house use or as a customer-facing portal for list selection.

Documentation

Useful Resources

Product Page

https://www.melissa.com/direct/mailing-lists-sales-leads/leadgen-api

Support Center

https://www.melissa.com/company/product-support

Download OpenAPI description
leadgen-consumer.json
leadgen-consumer.yaml
Languages
Servers
Consumer Service Server
https://list.melissadata.net/v1/Consumer/rest/Service.svc/

Consumer Service

Use this endpoint to call various consumer service actions.

Operations

Perform action for a single business

Request

Uses HTTP GET to accept one input record and returns the response in JSON format.

Path
actionstringrequired

There are two available actions: get and buy. get: Get count of addresses that fit in the given criteria. buy: Buy a list of addresses' info that fit the given criteria.

Enum"get""buy"
Example: get
geographicTypestringrequired

The included Geographic Types are zip, city, county, state, radius, circle, and polygon.

Enum"zip""city""county""state""radius""circle""polygon"
Example: city
Query
idstringrequired

Customer ID, License Key, or Email Address. This is checked against the list of registered customers.

Example: id=REPLACE-WITH-YOUR-LICENSE-KEY
zipstring

Geographic Type

  • Required: zip
  • Optional: radius

Handling: Each five-digit ZIP is validated.

zip+4string

Geographic Type

  • Required: zip
  • Optional: radius

Handling: Plus4 is a filter in data selection.

citystringrequired

Geographic Type

  • Required: city
  • Optional: radius

Handling: Each city and state combination is valid

Example: city=CA;orange
countystring

Geographic Type

  • Required: county

Handling: Each county and state combination is validated. FIPS is retrieved if valid.

statestring

Geographic Type

  • Required: state
  • Optional: radius

Handling: Two-digit state code is validated.

addrstring

Geographic Type

  • Required: radius

Handling: Exact street number and street name are used in data selection. No validation. Latitude and longitude are retrieved if the address exists.

milestring

Geographic Type

  • Required: circle
  • Optional: radius (Mile or record must be given.)

Handling: 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

recordsstring

Geographic Type

  • Optional: radius (Mile or record must be given.)

Handling: Number of records that are closest to the given address

strstring

Geographic Type

  • Optional: radius

Handling: A street name within the given zip. (The street name needs to be exact.)

strzipstring

Geographic Type

  • Optional: radius

Handling: Zip for a specific street that is within the given radius (combination with a given address.)

ptstring

Geographic Type

  • Required: circle

Handling: A longitude;latitude point

pointsstring

Geographic Type

  • Required: polygon

Handling: Each set of points for a polygon is validated and reoriented in the sequence of drawing.

hIncstring

Meaning: Append household income info to file

Default: hInc=0

To append: hInc

hInc-dstring

Default: all inclusive. Otherwise specify the index; use '-' dash to specify multiple ranges, i.e.: hInc-d=2-3-5

Various ranges of household incomes:

  • 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+
cAgestring

Meaning: Append contact age group info to file if exists (frequency 84.2%)

Default: cAge=0

To append: cAge=1

cAge-dstringrequired

Default: all inclusive. Otherwise specify the index; use '-' dash to specify multiple ranges, i.e.: cAge-d=2-3-5

Various contact age groups:

  • 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+
Example: cAge-d=3-4-5
ownRentstring

Meaning: Append home owner/renter info to file if exists (frequency 98.5%)

Default: ownRent=0

To append: ownRent=1

ownRent-dstringrequired

Default: all inclusive. Otherwise specify the index i.e.: ownRent-d=1

Home owner or renter:

  • 1 - Home Owner
  • 2 - Renter
Example: ownRent-d=1
maritalstring

Meaning: Append marital status to file

Default: marital=0

To append: marital=1

marital-dstring

Default: all inclusive. Otherwise specify the index; use '-' dash to specify multiple ranges, i.e.: marital-d=2-3-4

Various marital statuses:

  • 1 - Unknown
  • 2 - Household contain at least 1 married person
  • 3 - Household contain at least 1 single person
  • 4 - Household contains both married & single NumPersonsInHousehold
resLenstring

Meaning: Append length of residency to file

Default resLen=0

To append: resLen=1

resLen-dstring

Default: all inclusive. Otherwise specify the index; use '-' dash to specify multiple ranges, i.e.: resLen-d=2-3-4

Various lengths of residency:

  • 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
hAgestring

Meaning: Append household age code to file

Default: hAge=0

To append: hAge=1

hAge-dstring

Default: all inclusive. Otherwise specify the index; use '-' dash to specify multiple ranges, i.e.: hAge-d=2-3-4

Various household age codes:

  • 1 - 18 - 24
  • 2 - 25 - 34
  • 3 - 35 - 44
  • 4 - 45 - 54
  • 5 - 55 - 64
  • 6 - 65 - 74
  • 7 - 75+
peoplestring

Meaning: Append number of people in household to file

Default: people=0

To append: people=1

people-dstring

Default: all inclusive. Otherwise specify the index; use '-' to specify multiple ranges, i.e.:people-d=2-3-4

Various numbers of people in the household:

  • 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+
adultsstring

Meaning: Append number of adults in household to file

Default: adults=0

To append: adults=1

adults-dstring

Default: all inclusive. Otherwise specify the index; use '-' dash to specify multiple ranges, i.e.: adults-d=2-3-4

Various numbers of adults in household:

  • 1 - 1 adult
  • 2 - 2 adults
  • 3 - 3 adults
  • 4 - 4 adults
  • 5 - 5 adults
kidsstring

Meaning: Append numbers of children in household to file if exists (frequency 25.5%)

Default: kids=0

To append: kids=1

kids-dstring

Default: All inclusive. Otherwise specify the index; use '-' dash to specify multiple ranges, i.e.: kids-d=2-3-9

Various numbers of children in household:

  • 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
cCardstring

Meaning: Append household credit card info to file

Default: cCard=0

To append: cCard=1

cCard-dstring

Default: all inclusive. Otherwise specify the index; use '-' dash to specify multiple ranges, i.e.: cCard-d=2-3-4

Various household credit cards:

  • 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
mailstring

Meaning: Append mail responsive info to file if exists (frequency 66.5%)

Default: mail=0

To append: mail=1

mail-dstring

Default: all inclusive.Otherwise specify the index; use '-' dash to specify multiple ranges, i.e.: mail-d=2

Various mail responsive info:

  • 1 - Mail Buyer Indicator
  • 2 - Mail Donor Indicator
worthstring

Meaning: Append net worth to file if exists (frequency: 69.5%)

Default: worth=0

To append: worth=1

worth-dstring

Default: all inclusive Otherwise specify the index; use '-' dash to specify multiple ranges, i.e. worth-d=2-3-5

Various net worth ranges:

  • 1 - Less than $25,000
  • 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
homestring

Meaning: Append target home valuation mode in 1,000s to file if exists (frequency: 76.2%)

Default: home=0

To append: home=1

home-dstring

Default: all inclusive. Otherwise specify the index; use '-' dash to multiple ranges, i.e.: home-d=2-3-5

Various ranges of target home valuation mode in 1,000s:

  • 1 - $1 - 49,999
  • 2 - $50,000 - 149,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+
dwellstringrequired

Default: all inclusive. Otherwise specify the index, i.e.: dwell=2

Dwelling type:

  • 1 - Single and Multi-Family
  • 2 - Single Family Only
  • 3 - Multi-Family Only
Example: dwell=2
onestring

Meaning: One contact per address

Default: one=1

Otherwise one=0

return all contacts

genderstring

Meaning: Primary gender

Default: all inclusive

Otherwise M or F

zip4string

Meaning: Records with ZIP+4 info only

Default: zip4=0

Otherwise zip4=1

returns only addresses with zip4 info

uspsstring

Meaning: Using USPS preferred city names

Default: usps=1

Otherwise usps=0

returns whatever city name (official name or vanity name or abbreviated) consumers entered

latlonstring

Meaning: Show latitude/longitude for each address in street count's response

Default: latlon=0

Otherwise latlon=1

returns latitude and longitude

dbugstring

Meaning: Parameter check. If a parameter is spelt wrong or not suited for the given call, the request will be rejected

Default: dbug=0

Otherwise dbug=1 to check

poboxstring

Meaning: Include or exclude PO box. Default is to include

Default: pobox=1

Otherwise pobox=0

phonestringrequired

Meaning: Append phone number to file if exists (frequency: 41.1%)

0 (To append, set value to 1)

Example: phone=1
birthstring

Meaning: Append birth date to file if exists (frequency 84.2%)

0 (To append, set value to 1)

famstring

Meaning: Append family relationship to file if exists (frequency 99.9%)

0 (To append, set value to 1)

structstring

Meaning: Append structure year to file if exists (frequency: 52.8%)

0 (To append, set value to 1)

postring

Meaning: Customer's purchase order number

Values: n/a

qtystring

Meaning: Number of records requested and to charge for billing

Values: n/a

multistring

Meaning: Multiple usage of the list (1 - 5 times)

Values: 1

sorderstring

Meaning: Up to five orders in recent six months for suppression, comma separated with no space

Values: n/a

emailsstring

Meaning:

  • 0 - records with no email
  • 1 - records with email
  • 2 - all records

Values: 2

femailsstring

Meaning: Append Email to order file

Values: 0 (To append, set value to 1)

eduhhstring

Meaning: Append the highest known education of the primary householder

Default: eduhh=0

To append: eduhh=1

eduhh-dstring

Default: all inclusive. Otherwise specify the index; use '-' dash to specify multiple ranges, i.e.: eduhh-d=1-2

Meaning:

  • 1 - Completed High School
  • 2 - Completed College
  • 3 - Completed Graduate School
  • 4 - Attended Vocational/Technical
edulndvstring

Meaning: Append the highest known education in the household.

Default: eduIndv =0

To append: eduIndv=1

eduIndv-dstring

Default: all inclusive. Otherwise specify the index; use '-' dash to specify multiple ranges, i.e.: eduIndv-d=1-2

Meaning:

  • 1 - Completed High School
  • 2 - Completed College
  • 3 - Completed Graduate School
  • 4 - Attended Vocational/Technical
curl -i -X GET \
  'https://list.melissadata.net/v1/Consumer/rest/Service.svc/get/city?id=REPLACE-WITH-YOUR-LICENSE-KEY&city=CA%3Borange&cAge-d=3-4-5&ownRent-d=1&dwell=2&phone=1'

Responses

Successful response

Bodyapplication/xml
Response
application/xml
<Consumer>
  <Geography>
    <City>CA;orange</City>
  </Geography>
  <Options>
    <ContactPersonInfo>
      <ContactPersonInfo>One per Address</ContactPersonInfo>
      <USPSPreferredCityNames>True</USPSPreferredCityNames>
    </ContactPersonInfo>
    <AdvantageDwellingType>
      <Details>Single Family Only</Details>
    </AdvantageDwellingType>
    <Emails>
      <Details>All Records</Details>
    </Emails>
    <ContactAgeGroup>
      <Details>26-30; 31-35; 36-40</Details>
    </ContactAgeGroup>
    <HomeOwnerRenter>
      <Details>Home Owner</Details>
    </HomeOwnerRenter>
  </Options>
  <CountDetails>
    <StreetRange>
      <Street>
        <StartNumber />
        <EndNumber />
        <Geography>Orange, CA</Geography>
        <Zip />
        <Count>3172</Count>
      </Street>
    </StreetRange>
  </CountDetails>
  <TotalCount>
    <Count>3172</Count>
  </TotalCount>
  <Result>
    <StatusCode>Approved</StatusCode>
  </Result>
</Consumer>