# Perform action for a single consumer

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

Endpoint: GET /{action}/{geographicType}

## Header parameters:

  - `Accept` (string, required)
    Format of the response.
    Enum: "application/json", "*/*"

  - `Content-Type` (string, required)
    Format of the request.
    Enum: "application/json", "application/xml"

## 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.
    Enum: "get", "buy"

  - `geographicType` (string, required)
    The included Geographic Types are zip, city, county, state, radius, circle, and polygon.
    Enum: "zip", "city", "county", "state", "radius", "circle", "polygon"

## Query parameters:

  - `id` (string, required)
    Customer ID, License Key, or Email Address. This is checked against the list of registered customers.
    Example: "REPLACE-WITH-YOUR-LICENSE-KEY"

  - `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
    Example: "CA;orange"

  - `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+
    Example: "3-4-5"

  - `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
    Example: "1"

  - `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
    Example: "2"

  - `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)
    Example: "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

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


## Response 200 fields