Perform action for a single consumer

Request

Uses HTTP GET to accept one input record and returns the response in XML 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)

filestring

Buy Requests Only. Defines the desired file format of a purchased list.

Values:

2 - File Format: Zipped .txt
3 - File Format: Zipped .csv
5 - File Format: Zipped .xls (Excel)
7 - File Format: .txt
8 - (Default) File Format: .csv
10 - File Format: .xls (Excel)

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: Buy Requests Only. By default, purchased lists may be used once. With this parameter included in the Buy call, you can purchase the right to use a list for multiple mailings. Specify the number of uses like this: multi=4. The maximum number of uses allowed for any purchased list is 5.

Values: multi=(1 through 5)

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

Acceptstringrequired

Format of the response.

Enum:"application/xml""*/*"

Example:application/xml

Content-Typestringrequired

Format of the request.

Enum:"application/xml""application/json"

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' \
  -H 'Accept: application/xml' \
  -H 'Content-Type: application/xml'

Responses

Successful response

Bodyapplication/xml

Response

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