LeadGen Occupant:Request Parameters

← LeadGen Cloud API

Standard Components

Parameter	Definition
Domain
Version	Web Service version.
Web Service	Occupant
Protocol	REST. The protocol used by the Web Service.
Action	"get" or "buy"
Geographic type	ZIP, city, county, radius. See Geographic Types for more info.
Customer ID	The requester’s Customer ID or email address.
Options	Geographic Options Occupant Options General Options Other Purchase Options

Actions

The following actions are supported by the web service:

Action	Service Description
Get	Get count of addresses that fit in the given criteria.
Buy	Buy a list of addresses’ info that fit the given criteria.

Authentication

Each Customer’s ID or email address is passed in as id in the URL. It is checked against the list of registered customers.

Required

URL Parameter	Description
id	Required. User ID or Email Address. You must be subscribed to the Occupant Web Service.

Geographic Types

Each request must specify a geographic types.

Don't forget! The call URL format: Occupant Call Format.

URL Parameter	Geographic Type	Description
zip?	Zip	Format: 5-digit ZIP or 9-digit ZIP+4 Multiple ZIP or ZIP+4 can be requested, comma separated with no space. Ex. zip=92688,85023,129265917
city?	City	Format: 2-digit state;city name Multiple cities be requested, comma separated with no space. Ex. city=TX;Dallas,TX;Houston,TX;Austin
county?	County	Format: 2-digit state;county name Multiple counties be requested, comma separated with no space. Ex. county=CA;Lake,AZ;Mohave,AZ;Maricopa
RadiusByMiles?	RadiusByMiles	Miles of radius from a given address, and/or the closes so many records to a given address EX. to request the closest 100 addresses within 5 mile to the address 23412 Avenida Empresa, 92688: addr=23412+avenida+empresa&zip=92688&mile=5&records=100
RadiusByRecords?	RadiusByRecords	Returns the nearest records to the selected address, up to 100,000 files (65,535 when requesting Excel files).
States?	States	Returns a complete list of Sates within the United States of America.
CountiesByState?	CountiesByState	Returns a complete list of counties within the specified U.S. State.
CitiesByState?	CitiesByState	Returns a complete list of cities within the specified U.S. State.
ZipsByCity?	ZipsByCity	Returns a complete list of ZIP Codes within the specified City. State is separated from city with a “;” semi-colon. Multiple entries are delimited with a “,” comma.
CrtsByZip?	CrtsByZip	Returns a complete list of Carrier Routes within the specified ZIP Codes. Multiple entries are delimited with a “,” comma.

Options

Each request takes a set of geographic input. Occupant address types and other input are optional with default values, as well as purchase options. See Columns in File for the format of all columns appended to file.

Geographic Options

URL Parameter	Geographic Type	Description
zip	Required: zip Optional: RadiusByMiles, RadiusByRecords, city, county	Comma-delimited list of five-digit ZIP Codes. Can also include partial ZIP codes with a wild card. Ex: “92688, 90210” or “926*”
crrt	Optional: zip, city, RadiusByMiles	Comma-delimited list of carrier routes within the selected ZIP Codes. Format is “crrt-zip”. Ex: “C001-92688, R002-90210”
mile	Required: RadiusByMiles	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.
count	Required: RadiusByRecords	Number of records around the submitted address to search. Maximum is 100,000 (65,535 when buying an Excel file).
address	Required: RadiusByMiles, RadiusByRecords	Street address that will be the center of the search area.
state	Required: city, county Optional: RadiusByMiles, RadiusByRecords, CitiesByState, CountiesByState	Two-character abbreviation for the desired state. Ex: “state=ca”.
city	Required: city Optional: RadiusByMiles, RadiusByRecords	Must be the name of an existing city within the selected state.
county	Required: county	Must be the name of an existing county within the selected state.

Occupant Options

URL Parameter	Description	Default Value	Optional Output Parameter
cityres	Includes residential addresses not located on rural routes, if any exist in the selected area.	cityres=1	To exclude: cityres=0
cityapt	Includes apartment addresses not located on rural routes, if any exist in the selected area.	cityapt=1	To exclude: cityapt=0 or do not include.
citybiz	Includes business and commercial addresses not located on rural routes.	citybiz=1	To exclude: citybiz=0 or do not include.
pores	Includes PO Boxes rented by residential customers.	pores=1	To exclude: pores=0 or do not include.
pobiz	Includes PO Boxes rented by commercial customers.	pobiz=1	To exclude: pobiz=0 or do not include.
ruralres	Includes residential addresses located on rural routes, if any exist in the selected area.	ruralres=1	To exclude: ruralres=0 or do not include.
ruralapt	Includes apartment addresses located on rural routes, if any exist in the selected area.	ruralapt=1	To exclude: ruralapt=0 or do not include.
ruralbiz	Includes business and commercial addresses located on rural routes, if any exist in the selected area.	ruralbiz=1	To exclude: ruralbiz=0 or do not include.

Purchase Options

The following options are for buy requestes only.

URL Parameter	Description	Default Value	Optional Output Parameter
multi	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.	multi=1	multi=(1 through 5)
file	Buy Requests Only. Defines the desired file format of a purchased list.	file= (none)	Value File Format 2 Zipped .txt 3 Zipped .csv 5 Zipped .xls (Excel) 7 .txt 8 (Default) .csv 10 .xls (Excel)
po	Buy Requests Only. Defines the customer’s purchase order number.	N/A	To specify: po=xxxx

General Options

URL Parameter	Description	Default Value	Optional Output Parameter
name	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.	name=0	To include: name=1
dbug	Parameter check. If a parameter in the url is spelled wrong or not suited for the given call, the request will be rejected.	dbug=0	To check: dbug=1