# Perform action for a single consumer

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

Endpoint: GET /{action}/{geographicType}

## Path parameters:

  - `action` (string, required)
    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.

  - `geographicType` (string, required)
    The included [Geographic Types](https://docs.melissa.com/reference-data/leadgen-business/leadgen-business-reference-guide.html#geographic-types) are zip, city, county, state, radius, circle, and polygon.

## Query parameters:

  - `id` (string, required)
    Customer ID, [License Key](https://docs.melissa.com/melissa/license/license-information.html), or Email Address. This is checked against the list of registered customers.

  - `zip` (string)
    Geographic Type
* Required: zip
* Optional: radius

Handling: Each five-digit ZIP is validated.

  - `zip+4` (string)
    Geographic Type
* Required: zip
* Optional: radius

Handling: Plus4 is a filter in data selection.

  - `city` (string, required)
    Geographic Type
* Required: city
* Optional: radius

Handling: Each city and state combination is valid

  - `county` (string)
    Geographic Type
* Required: county

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

  - `state` (string)
    Geographic Type
* Required: state
* Optional: radius

Handling: Two-digit state code is validated.

  - `addr` (string)
    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.

  - `mile` (string)
    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

  - `records` (string)
    Geographic Type
* Optional: radius
(Mile or record must be given.)

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

  - `str` (string)
    Geographic Type
* Optional: radius

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

  - `strzip` (string)
    Geographic Type
* Optional: radius

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

  - `pt` (string)
    Geographic Type
* Required: circle

Handling: A longitude;latitude point

  - `points` (string)
    Geographic Type
* Required: polygon

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

  - `hInc` (string)
    Meaning: Append household income info to file

Default: hInc=0

To append: hInc

  - `hInc-d` (string)
    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+

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

Default: cAge=0

To append: cAge=1

  - `cAge-d` (string, required)
    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+

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

Default: ownRent=0

To append: ownRent=1

  - `ownRent-d` (string, required)
    Default: all inclusive. Otherwise specify the index i.e.: ownRent-d=1

Home owner or renter:
- `1` - Home Owner
- `2` - Renter

  - `marital` (string)
    Meaning: Append marital status to file

Default: marital=0

To append: marital=1

  - `marital-d` (string)
    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

  - `resLen` (string)
    Meaning: Append length of residency to file

Default resLen=0

To append: resLen=1

  - `resLen-d` (string)
    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

  - `hAge` (string)
    Meaning: Append household age code to file

Default: hAge=0

To append: hAge=1

  - `hAge-d` (string)
    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+

  - `people` (string)
    Meaning: Append number of people in household to file

Default: people=0

To append: people=1

  - `people-d` (string)
    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+

  - `adults` (string)
    Meaning: Append number of adults in household to file

Default: adults=0

To append: adults=1

  - `adults-d` (string)
    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

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

Default: kids=0

To append: kids=1

  - `kids-d` (string)
    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

  - `cCard` (string)
    Meaning: Append household credit card info to file

Default: cCard=0

To append: cCard=1

  - `cCard-d` (string)
    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

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

Default: mail=0

To append: mail=1

  - `mail-d` (string)
    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

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

Default: worth=0

To append: worth=1

  - `worth-d` (string)
    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

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

Default: home=0

To append: home=1

  - `home-d` (string)
    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+

  - `dwell` (string, required)
    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

  - `one` (string)
    Meaning: One contact per address

Default: one=1

Otherwise one=0

return all contacts

  - `gender` (string)
    Meaning: Primary gender

Default: all inclusive

Otherwise M or F

  - `zip4` (string)
    Meaning: Records with ZIP+4 info only

Default: zip4=0

Otherwise zip4=1

returns only addresses with zip4 info

  - `usps` (string)
    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

  - `latlon` (string)
    Meaning: Show latitude/longitude for each address in street count's response

Default: latlon=0

Otherwise latlon=1

returns latitude and longitude

  - `dbug` (string)
    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

  - `pobox` (string)
    Meaning: Include or exclude PO box. Default is to include

Default: pobox=1

Otherwise pobox=0

  - `phone` (string, required)
    Meaning: Append phone number to file if exists (frequency: 41.1%)

0 (To append, set value to 1)

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

0 (To append, set value to 1)

  - `fam` (string)
    Meaning: Append family relationship to file if exists (frequency 99.9%)

0 (To append, set value to 1)

  - `struct` (string)
    Meaning: Append structure year to file if exists (frequency: 52.8%)

0 (To append, set value to 1)

  - `file` (string)
    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)

  - `po` (string)
    Meaning: Customer's purchase order number

Values: n/a

  - `qty` (string)
    Meaning: Number of records requested and to charge for billing

Values: n/a

  - `multi` (string)
    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)

  - `sorder` (string)
    Meaning: Up to five orders in recent six months for suppression, comma separated with no space

Values: n/a

  - `emails` (string)
    Meaning:
- `0` - records with no email
- `1` - records with email
- `2` - all records

Values: 2

  - `femails` (string)
    Meaning: Append Email to order file

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

  - `eduhh` (string)
    Meaning: Append the highest known education of the primary householder

Default: eduhh=0

To append: eduhh=1

  - `eduhh-d` (string)
    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

  - `edulndv` (string)
    Meaning: Append the highest known education in the household.

Default: eduIndv =0

To append: eduIndv=1

  - `eduIndv-d` (string)
    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

## Header parameters:

  - `Accept` (string, required)
    Format of the response.

  - `Content-Type` (string, required)
    Format of the request.

## Response 200:

  - `200` (unknown)
    Successful response

## Response 400:

  - `400` (unknown)
    Bad Request

## Response 400 fields (application/json):

  - `type` (string)
    The type of error that occurred.

  - `title` (string)
    A short summary of the error.

  - `status` (string)
    The HTTP status code for the error.

  - `errors` (object)

  - `errors.$.<PropertyName>` (array)
    A detailed message about the error.

  - `traceId` (string)
    A unique identifier for the request, useful for debugging.