# Perform action for a single occupant

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

Endpoint: GET /{action}/{format}/{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.
    Enum: "get", "buy"

  - `format` (string, required)
    Format is json or xml.
    Enum: "json", "xml"

  - `geographicType` (string, required)
    Each request must specify a single geographic type. Here are the available Geographic Types: zip, city, county, radiusbymiles, radiusbyrecords, states, countiesbystate, citiesbystate, zipsbycity, crtsbyzip.
    Enum: "zip", "city", "county", "RadiusByMiles", "RadiusByRecords", "state", "CountiesByState", "CitiesByState", "ZipsByCity", "CrtsByZip"

## 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, required)
    Comma-delimited list of five-digit ZIP Codes. Can also include partial ZIP codes with a wild card. Ex: “92688, 90210” or “926*”

Geographic Type
* Required: zip
* Optional: RadiusByMiles, RadiusByRecords, city, county
    Example: "92688"

  - `crrt` (string, required)
    Comma-delimited list of carrier routes within the selected ZIP Codes. Format is “crrt-zip”.Ex: “C001-92688, R002-90210”

Geographic Type
* Optional: zip, city, RadiusByMiles
    Example: "b007-92688"

  - `mile` (string)
    Set to 1 to include residential addresses not located on rural routes, if any exist in the selected area. Do not include or set to 0 to exclude these addresses from the counts or purchased list.

Geographic Type
* Required: RadiusByMiles

  - `count` (string)
    Number of records around the submitted address to search. Maximum is 100,000 (65,535 when buying an Excel file).

Geographic Type
* Required: RadiusByRecords

  - `address` (string)
    Street address that will be the center of the search area.

Geographic Type
* Required: RadiusByMiles, RadiusByRecords

  - `state` (string)
    Two-character abbreviation for the desired state. Ex: “state=ca”.

Geographic Type
* Required: city, county
* Optional: RadiusByMiles, RadiusByRecords, CitiesByState, CountiesByState

  - `city` (string)
    Must be the name of an existing city within the selected state.

Geographic Type
* Required: city
* Optional: RadiusByMiles, RadiusByRecords

  - `county` (string)
    Must be the name of an existing county within the selected state.

Geographic Type
* Required: county

  - `cityres` (string)
    Includes residential addresses not located on rural routes, if any exist in the selected area.

Default Value: cityres=1
To exclude: cityres=0 or do not include.

  - `cityapt` (string)
    Includes apartment addresses not located on rural routes, if any exist in the selected area.

Default Value: cityapt=1
To exclude: cityapt=0 or do not include.

  - `citybiz` (string)
    Includes business and commercial addresses not located on rural routes.

Default Value: citybiz=1
To exclude: citybiz=0 or do not include.

  - `pores` (string)
    Includes PO Boxes rented by residential customers.

Default Value: pores=1
To exclude: pores=0 or do not include.

  - `pobiz` (string)
    Includes PO Boxes rented by commercial customers.

Default Value: pobiz=1
To exclude: pobiz=0 or do not include.

  - `ruralres` (string)
    Includes residential addresses located on rural routes, if any exist in the selected area.

Default Value: ruralres=1
To exclude: ruralres=0 or do not include.

  - `ruralapt` (string)
    Includes apartment addresses located on rural routes, if any exist in the selected area.

Default Value: ruralapt=1
To exclude: ruralapt=0 or do not include.

  - `ruralbiz` (string)
    Includes business and commercial addresses located on rural routes, if any exist in the selected area.

Default Value: ruralbiz=1
To exclude: ruralbiz=0 or do not include.

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

Default Value: multi=1
Output Parameter: multi=(1 through 5)

  - `file` (string)
    Buy Requests Only. Defines the desired file format of a purchased list.

Default Value: file=(none)
Output Parameter:
- 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)
    Buy Requests Only. Defines the customer's purchase order number.

Default Value: N/A
To specify: po=xxxx

  - `name` (string)
    For count, a separate count of names will be given.

For purchase, extra columns will be added: pre name, first name, initial, last name, post name.

Set to 1 to include personal names when they are available. Do not include or set to 0 to not include names.

Default Value: name=0
To include: name=1

  - `dbug` (string)
    Parameter check. If a parameter in the url is spelled wrong or not suited for the given call, the request will be rejected.

Default Value: dbug=0
To check: dbug=1

## Response 200 fields (application/json):

  - `Occupant` (object)
    Tag encapsulating the whole XML document

  - `Occupant.Geography` (object)
    Geo request

  - `Occupant.Geography.Address` (string)
    Returned if radius by records or miles is called.

  - `Occupant.Geography.City` (string)
    Returned if city, radius by records, or radius by miles is called.

  - `Occupant.Geography.County` (string)
    Returned if county is called.

  - `Occupant.Geography.State` (string)
    Returned if city, county, radius by records, or radius by miles is called.

  - `Occupant.Geography.Zip` (string)
    Returned if zip, radius by records, radius by miles is called. City and county calls are option only when zip is given by user.

  - `Occupant.Geography.CarrierRoute` (string)
    Returned if user requested for zip, city, radius by miles geo types.

  - `Occupant.Geography.Records` (string)
    Returned if radius by records is called.

  - `Occupant.Geography.Miles` (string)
    Returned if radius by miles is called.

  - `Occupant.Options` (object)
    Occupant options requested

  - `Occupant.Options.CityDeliveries_ResidentialAddresses` (string)

  - `Occupant.Options.CityDeliveries_Apartments` (string)

  - `Occupant.Options.CityDeliveries_BusinessAddresses` (string)

  - `Occupant.Options.POBoxes_ResidentialAddresses` (string)

  - `Occupant.Options.POBoxes_BusinessAddresses` (string)

  - `Occupant.Options.RuralRoutes_ResidentialAddresses` (string)

  - `Occupant.Options.RuralRoutes_Apartments` (string)

  - `Occupant.Options.RuralRoutes_BusinessAddresses` (string)

  - `Occupant.Options.IncludeNamesWhereAvailable` (string)

  - `Occupant.CarrierRoutes` (array)
    Breakdown by carrier routes - for ZIP, city, radius by miles types.

  - `Occupant.CarrierRoutes.CarrierRoute` (object)
    Detailed info of each carrier route

  - `Occupant.CarrierRoutes.CarrierRoute.Zip` (string)
    5 digit ZIP

  - `Occupant.CarrierRoutes.CarrierRoute.Route` (string)
    4 digit carrier route

  - `Occupant.CarrierRoutes.CarrierRoute.Count` (string)
    Number of occupants within this carrier route

  - `Occupant.ZipCodes` (object)
    Breakdown by ZIP - for city, county types.

  - `Occupant.ZipCodes.Zip` (array)
    Detailed info of each ZIP

  - `Occupant.ZipCodes.Zip.ZipCode` (string)
    5 digit ZIP

  - `Occupant.ZipCodes.Zip.Count` (string)
    Number of occupants within this ZIP

  - `Occupant.Streets` (array)
    Breakdown by street - for radius by miles, radius by records type.

  - `Occupant.Streets.Street` (object)

  - `Occupant.Streets.Street.Street` (string)
    Detailed info of each street. Format: street name, city, state ZIP

  - `Occupant.Streets.Street.StartNumber` (string)
    Start number of the street with the requested criteria

  - `Occupant.Streets.Street.EndNumber` (string)
    End number of the street with the requested criteria

  - `Occupant.Streets.Street.Count` (string)
    Number of occupants within this carrier route

  - `Occupant.TotalCount` (object)

  - `Occupant.TotalCount.Count` (string)
    Total number of records returned.

  - `Occupant.TotalCount.NameCount` (string)
    Total number of records with name returned

  - `Occupant.Result` (object)

  - `Occupant.Result.StatusCode` (string)
    Indicates the status of a request. Returns Declined, Approved, or Err.

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