Reference Guide

Introduction

Welcome to the LeadGen Property service by Melissa. The Property Web Service is a REST based Web service that can be used to get counts, and purchase targeted property owner mailing lists, in real-time, anytime. It is available to mailers for private, in-house use, or as a portal for your customers to use to make their list selections. You can custom-design a website to meet your own needs, as well as those of your customers.

It has two method calls, which use an HTTP query string to pass a request with selected options. An HTTPS query works just the same as an HTTP query.

Base URL

https://list.melissadata.net/v2/Property

Licensing

Customer ID, License Key, or Email Address is passed in as id in the URL. You will receive your Customer ID, License Key, or Email Address from your Melissa representative. If you don’t have a Customer ID, License Key, or Email Address, contact the Melissa sales team at sales@melissa.com or 800-MELISSA ext. 3 (800-635-4772 ext. 3). Without a valid Customer ID, License Key, or Email Address, LeadGen Occupant will not function.

Endpoints

/v2/Property

Introduction

There are multile endpoints you can access for LeadGen: Property. These endpoints are all formatted like:

http://list.melissadata.net/v2/Property/{{action}}_{{geographicType}}

Where action is either count or buy and geographicType is one geographic type selected from one of these supported types: Geographic Types

Try It Now

Note

Make sure to replace customer@domain.com with your user email or user ident number!

• GET JSON
• GET XML
• BUY JSON
• BUY XML

curl -X GET "http://list.melissadata.net/v2/Property/count_zip\
?id=customer@domain.com&zip=92688&propertype=10-11-22&bedrooms=2-4&occu=3&xml=false" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

curl -X GET "http://list.melissadata.net/v2/Property/count_zip\
?id=customer@domain.com&zip=92688&propertype=10-11-22&bedrooms=2-4&occu=3&xml=true" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml"

curl -X GET "http://list.melissadata.net/v2/Property/buy_zip\
?id=customer@domain.com&zip=92688&propertype=10-11-22&bedrooms=2-4&occu=3&xml=false" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

curl -X GET "http://list.melissadata.net/v2/Property/buy_zip\
?id=customer@domain.com&zip=92688&propertype=10-11-22&bedrooms=2-4&occu=3&xml=true" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml"

Sending a Request

Every request has two parts. The Action and the Geographic Type

Authentication

Customer ID, License Key, or Email Address is passed in as id in the URL. This is checked against the list of registered customers.

REST Protocol

The Occupant Web Service uses the REST protocol, which uses an HTTP query string to pass a request with selected options. An HTTPS query works just the same as an HTTP query.

Using the REST service may require that you encode certain characters using the proper URL entities before adding them to a URL. Characters like spaces, slashes, ampersands, and others must be replaced by special codes, which usually consist of a percent sign followed by a two-digit hexadecimal number.

The following table shows the replacements for the most common characters:

Character	Encoding
[Space]	%20 or +
*	%2A
#	%23
&	%26
%	%25
$	%28
`[Backtick]	%60
:	%3A
<	%3C
>	%3E
[	%5B
]	%5D
{	%7B
}	%7D
“	%22
+	%2B
(	%28
)	%29
.	%2E
!	%21
@	%40
/	%2F
;	%3B
=	%3D
?	%3F
\	%5C
^	%5E
|	%7C
~	%7E
‘	%27
,	%2C
-	%2D
_	%5F

Actions

There are two avaliable actions: count and buy

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

Geographic Types

Each request must specify a single geographic type. Here are the avalaible Geographic Types:

Geographic Type	Sub Types	Description
Zip	Zips	5-digit ZIPs. Multiple ZIP can be requested, comma separated with no space or period.
	ZIP in Radius	5-digit ZIP. Miles of radius from any given ZIP (mile in decimal).
	ZIP(s) in City	5-digit ZIP, City, and 2-digit State.
Address		Address, City and State or ZIP. Miles of radius from a given address. (mile in decimal)
Street		Street name and ZIP or city and state, with street number range being optional
City		Format: 2-digit state;city name, i.e. TX;Dallas. Multiple cities be requested, comma separated with no space, or period
Town		Multiple town or place be requested, comma separated with no space, or period. Format: 2-digit state;town name, i.e. CA:Adelanto. Town name and State
County	by FIPS	Format: 2-digit state;county name, or FIPS
	by County, State	Multiple counties be requested, comma separated with no space or period, i.e. CA:Lake, 06029.
State		2-digit state name.
Circle		Miles of radius from a point defined as “latitude;longitude” with a semi colon delimiter, i.e.“-117.597760116333;33.63565170564778”. 0.25 miles radius min., 25 miles radius max.
Polygon		A set of points (latitude /longitude)within 0.25 miles square and 25 miles square. Each point is defined as “latitude;longitude” with a semi colon delimiter, use comma delimiter between each set of latitude;longitude. For example, 33.649656850987895;-117.59544268774414, 33.636509228993326;-117.6109780423584, 33.63222152688031;-117.59518519567871”.
Rectangle		Southwest and northeast points (latitude /longitude). Each point is defined as “latitude;longitude” with a semi colon delimiter, use comma delimiter between each set of latitude;longitude. For example, “33.63565170564778;-117.597760116333, 33.649513952846554;-117.58685961889648”. 0.25 miles square min., 25 miles square max.

Options

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

Geographic Options

URL Parameter	Geographic Type	Description
zip	Required: Zip Optional: address, street, circle, rectangle	Each five-digit ZIP is validated.
addr	Required: Address	No validation.
ctyst	Required: City	Format: state;city
city	Optional: address, street, zip	If ZIP is given, city is not necessary.
town	Required: Town	Not validated.
cntyst	Required: County	The value could be a variety of state;county and/or FIPS.
state	Required: State Optional: Address, county, street, zip	For state type, 2-digit state is required. For other types, if ZIP or FIPS is given, state is not necessary.
mile	Required: Address, street, circle Optional: zip	Radius of miles from a given street, address or ZIP.
street	Required: Street	Exact street name is required. No validation.
num1	Optional: Street	Start and end of the range of street numbers. Either end can be left unspecified.
num2
pt	Required: Cirlce, rectangle, polygon	Each point is defined as “latitude;longitude” with a semi colon delimiter. For multiple points, use comma delimiter between each set of latitude;longitude. For example, “33.63565170564778;-117.597760116333, 33.649513952846554;-117.58685961889648”. Rectangle takes 2 points: 1) southwest, 2) northeast. Polygon takes at least 3 points, counter clockwise.

Property Options

URL Parameter	Geographic Type	Description
propertype	Property codes & types: Value Definition 00 Miscellaneous 000 Not Available/None 10 Single Family Residence 11 Condominium(Residential) 20 Commercial 21 Duplex, Triplex, Quadplex 22 Apartment 23 Hotel, Motel 24 Condominium(Commercial) 25 Retail 26 Service(general public) 27 Office Building 28 Warehouse 29 Financial Institution 30 Hospital(medical complex, clinic) 31 Parking 32 Amusement-Recreation 33 Mobile Home 50 Industrial 51 Industrial Light 52 Industrial Heavy 53 Transport 54 Utility 70 Agricultural 80 Vacant Lot (Land) 90 Exempt	Default: all. Otherwise specify the index; use ‘-‘ dash to specify multiple choices, e.g. propertype =10-11 means Single Family Residence and Condominium(Residential)
bedrooms	Number of bedrooms	Default: all. Otherwise specify the index; use ‘-‘ dash to specify multiple choices, e.g. propertype =10-11 means Single Family Residence and Condominium(Residential)
bathrooms	Number of bathrooms
units	Unit number
yearbuilt	Year built. Format. YYYY.
pval	Property value ($)
equity	Equity ($)
lvratio	Loan to value ratio (%).
sqft	Square footage
bsqft	Basement square footage
lot	Lot size. It can be a range. The unit can be: a for acre f for ft. Format: unit; size.	Default: no filter. Unit: default is sq. ft (f). Size: To specify a range, use min-max. 2-4 means 2-4 acres. Use 0 if either end has no preference. For instance, f;2000-0 means at least 2000 sq. ft.
samt	Range of sale amounts in thousands ($).	Default: no filter. To specify a range, use min-max, i.e. 2-4. Use 0 if either end has no preference. For instance, 2-0 means at least $2,000.
sdt	Range of sale dates	Default: no filter. To specify a period, use MYYYY-MYYYY. The start month starts on the 1st; the end month ends on the last day, i.e. sdt=32010-122014, this covers 3/1/2010 to 12/31/2014.
pool	Has pool or not.	1 means using it as a filter while 0 means no preference. For example, pool=1. If not specified, it means no preference.
heat	Has heater or not.
ac	Has A/C or not.
fireplace	Has fireplace or not.

Mortgage Options

URL Parameter	Description	Values
mtgAmt	(Range of) amount in thousands ($). Combined amount for 1st and 2nd mortgages	Default: no filter. To specify a range of amounts, use min-max. Use 0 if either end has no preference. For instance, 2-0 means at least $2000, 5-10 means between$5000 and $10000.It’s an OR relationship when more than one of the three parameters have values.
mtgAmt1	1st Mortgage Amount
mtgAmt2	2nd Mortgage Amount
mtgRt	Rate (range)Rate for either 1st or 2nd mortgage	Default: no filter. To specify a range of rates, use min-max. Use 0 if either end has no preference. For instance, 2.5-0 means 2.5% at least, 3-5.5 means between 3% and 5.5%.It’s an OR relationship when more than one of the three parameters have values.
mtgRt1	1st Mortgage Rate
mtgRt2	2nd Mortgage Rate
mtgRtTp	Interest rate type for 1st or 2nd mortgage. Types are: Value Definition 2 Fixed Rate 1 Adjustable Rate 0 Unknown	Default: no filter. To include a variety of types, use -. For instance, 2-1 means to include fixed and adjustable rate. It’s an OR relationship when more than one of the three parameters have values.
mtgRtTp1
mtgRtTp2
mtgTm	Term (years)	Default: no filter. To specify a range of terms, use min-max. Use 0 if either end has no preference. For instance, 5-0 means at least 5-year term, 15-30 means between 15-year to 30-year term It’s an OR relationship when more than one of the three parameters have values.
mtgTm1 mtgTm1	1st mortgage term 1st mortgage term
mtgTm2	2nd mortgage term
mtgLender	Mortgage lender(s). Exact names are needed. Use – as the delimiter for multiple lenders.	Default: no filter. Example: America Bank-America Bank and Trust
mtgRecDt	Recording date (range)	Default: no filter. To specify a period, use MYYYY-MYYYY. The start month starts on the 1st; the end month ends on the last day. For instance, 12015-112018 means between 1/1/2015 and 11/30/2018. It’s an OR relationship when more than one of the three parameters have values.
mtgRecDt1	1st Mortgage Recording Date
mtgRecDt2	2nd Mortgage Recording Date
mtgTp	Interest rate type for 1st or 2nd mortgage. Types are: Value Definition 0 Unknown 3 Building or Construction 5 Conventional 6 Line of Credit 8 FHA 10 Conventional 16 Veterans Administration Loan 101 USDA - US Department of Agriculture Loan 102 Regional Government Programs 103 Commercial 104 Regional Government Programs 105 Reverse Mortgage 120 Private Party Loan	Default: no filter. For instance, 5-8 means conventional or FHA It’s an OR relationship when more than one of the three parameters have values.
mtgTp1	1st Mortgage type
mtgTp2	2nd Mortgage type
mtgScb	Seller Carry Back (Is the seller is also the lender?)	Default: no filter. Including or excluding – true or false. It’s an OR relationship when more than one of the three parameters have values.
mtgScb1	1st Mortgage Seller Carry back
mtgScb2	2nd Mortgage Seller Carry back

Occupant/Owner Options

Column Name	Description	Values
occu	Occupant types Value Definition 1 Owner occupied 2 Absentee owner (all types) 3 Absentee Owner - In County 4 Absentee Owner – In State 5 Absentee Owner - Out of Country 6 Absentee Owner – Out of State	Default: no preference. For instance, 5-8 means conventional or FHA For multiple absentee owner types, use – as the delimiter. It’s an OR relationship between the selected types. For instance, 3-6 means in county or out of state.
owntrs	Trustee owner	Default: no preference. Including or excluding – true or false.
owncorp	Corporate owner
vacant	Vacant property

Demographic Options

Column Name	Description	Values
hhage	Household age: Value Definition 1 18 - 24 Years 2 25 - 34 Years 3 35 - 44 Years 4 45 - 54 Years 5 55 - 64 Years 6 65 - 74 Years 7 75+ Years	Default: all. Otherwise specify the index; use ‘-‘ dash to specify multiple choices, i.e. 1-2 means 18-34 years old
gender	Gender: Value Definition f female m male u unisex	Default: all. Otherwise specify the index; use ‘-‘ dash to specify multiple genders, i.e. f-m mean female and male
hhinc	Household income: Value Definition 1 Under $10,000 2 $10,000 - $14,999 3 $15,000 - $19,999 4 $20,000 - $24,999 5 $25,000 - $29,999 6 $30,000 - $34,999 7 $35,000 - $39,999 8 $40,000 - $44,999 9 $45,000 - $49,999 A $50,000 - $54,999 B $55,000 - $59,999 C $60,000 - $64,999 D $65,000 - $69,999 E $70,000 - $99,999 F $100,000 - $149,999 G $150,000 - $174,999 H $175,000 - $199,999 I $200,000 - $249,999 J $250,000+	Default: all. Otherwise specify the index; use ‘-‘ dash to specify multiple choices, i.e. 1-2 means $14,999 or less
marital	Marital Status : Value Definition a inferred married b inferred single m married s single	Default: all. Otherwise specify the index; use ‘-‘ dash to specify multiple choices, i.e. b-s means inferred single or single
lores	Length of Residence: Value Definition 0 Less than 1 year 1 1 Years 2 2 Years 3 3 Years 4 4 Years 5 5 Years 6 6 Years 7 7 Years 8 8 Years 9 9 Years 10 10 Years 11 11 Years 12 12 Years 13 13 Years 14 14 Years 15 Over 14 Years	Default: all. Otherwise specify the index; use ‘-‘ dash to specify multiple choices, i.e. 0-1-2 means 2 years or under
people	Persons in household (number of people in household): Value Definition 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+ Persons	Default: all. Otherwise specify the index; use ‘-‘ dash to specify multiple choices, i.e. 1-2 means 2 or less
adults	Adults in household Value Definition 1 1 Adult 2 2 Adults 3 3 Adults 4 4 Adults 5 5 Adults 6 6+ Adults
kids	Children in household Value Definition 1 1 Child 2 2 Children 3 3 Children 4 4 Children 5 5 Children 6 6 Children 7 7 Children 8 8+ Children

Number of Records in File

Each purchase allows 100,000 records at most.

URL Parameter	Description	Values
qty	Number of records to buy	Default: no preference.

File Format

URL Parameter	Values
file	Value Definition 1 Zipped .dbf 3 Zipped .csv 5 Zipped .xls 6 .dbf 8 .csv (default) 10 .xls

Other Options

URL Parameter	Description	Values
email	0: records with no email 1: records with email 2: all records	Default: 2
femails	Append Email to order file	Default: 0 (To append, set value to 1)
one	Value Definition false all properties owned by owner true One property per owner	Default: true
xml	Value Definition true response in xml false response in json	Default: false

Headers

• GET JSON
• GET XML
• BUY JSON
• BUY XML

 Content-Type: application/json
 Accept: application/json

 Content-Type: application/xml
 Accept: application/xml

 Content-Type: application/json
 Accept: application/json

 Content-Type: application/xml
 Accept: application/xml

Response

• GET JSON
• GET XML
• BUY JSON
• BUY XML

{
  "options": {
    "propertyOptions": [
      "Property Type: Single Family Residence;Condominium(Residential);Apartment;",
      "Bedrooms: between 2 and 4"
    ],
    "mortgageOptions": [],
    "occupantOptions": [
      "Absentee/Owner Occupied: AbsenteeOwner_InCounty"
    ],
    "demographicOptions": [],
    "foreclosureOptions": [],
    "listOptions": [
      "One property per owner."
    ]
  },
  "areas": [
    {
      "geo": "92688",
      "count": 1336,
      "message": ""
    }
  ],
  "summary": {
    "geoType": "Zip",
    "totalCount": 1336,
    "orderId": 0,
    "fileUrl": null,
    "status": [
      {
        "statusCode": 1,
        "statusDetail": "Approved."
      }
    ]
  }
}

<Response_Property>
  <areas>
    <CountByArea>
      <Geo>92688</Geo>
      <Count>1336</Count>
      <Message />
    </CountByArea>
  </areas>
  <summary>
    <GeoType>Zip</GeoType>
    <TotalCount>1336</TotalCount>
    <OrderId>0</OrderId>
    <Status>
      <Status>
        <StatusCode>1</StatusCode>
        <StatusDetail>Approved.</StatusDetail>
      </Status>
    </Status>
  </summary>
  <Options>
    <ListOptions>
      <string>One property per owner.</string>
    </ListOptions>
    <PropertyOptions>
      <string>Property Type: Single Family Residence;Condominium(Residential);Apartment;</string>
      <string>Bedrooms: between 2 and 4</string>
    </PropertyOptions>
    <MortgageOptions />
    <OccupantOptions>
      <string>Absentee/Owner Occupied: AbsenteeOwner_InCounty</string>
    </OccupantOptions>
    <DemographicOptions />
    <ForeclosureOptions />
  </Options>
</Response_Property>

{
  "options": {
    "propertyOptions": [
      "Property Type: Single Family Residence;Condominium(Residential);Apartment;",
      "Bedrooms: between 2 and 4"
    ],
    "mortgageOptions": [],
    "occupantOptions": [
      "Absentee/Owner Occupied: AbsenteeOwner_InCounty"
    ],
    "demographicOptions": [],
    "foreclosureOptions": [],
    "listOptions": [
      "One property per owner."
    ]
  },
  "areas": [
    {
      "geo": "92688",
      "count": 1336,
      "message": ""
    }
  ],
  "summary": {
    "geoType": "Zip",
    "totalCount": 1336,
    "orderId": 6853167,
    "fileUrl": "https://list.melissadata.com/ListOrderFiles/123456.csv",
    "status": [
      {
        "statusCode": 1,
        "statusDetail": "Approved."
      }
    ]
  }
}

<Response_Property>
  <areas>
    <CountByArea>
      <Geo>92688</Geo>
      <Count>1336</Count>
      <Message />
    </CountByArea>
  </areas>
  <summary>
    <GeoType>Zip</GeoType>
    <TotalCount>1336</TotalCount>
    <OrderId>6853173</OrderId>
    <FileUrl>https://list.melissadata.com/ListOrderFiles/123456.csv</FileUrl>
    <Status>
      <Status>
        <StatusCode>1</StatusCode>
        <StatusDetail>Approved.</StatusDetail>
      </Status>
    </Status>
  </summary>
  <Options>
    <ListOptions>
      <string>One property per owner.</string>
    </ListOptions>
    <PropertyOptions>
      <string>Property Type: Single Family Residence;Condominium(Residential);Apartment;</string>
      <string>Bedrooms: between 2 and 4</string>
    </PropertyOptions>
    <MortgageOptions />
    <OccupantOptions>
      <string>Absentee/Owner Occupied: AbsenteeOwner_InCounty</string>
    </OccupantOptions>
    <DemographicOptions />
    <ForeclosureOptions />
  </Options>
</Response_Property>

Response Fields

Owner names, mailing address and property address are included in the list by default.

Additional fields can be added by setting each of the URL parameters’ value to “true.”

Column Name	Max Length	URL Value to Append	Description
ID
ContactMak
FullName1	150		party owner 1 full name
FirstName1	50		party owner 1 first name
MiddleName1	20		party owner 1 middle name
LastName1	50		party owner 1 last name
Suffix1	20		party owner 1 name suffix
FullName2	150		party owner 2 full name
FirstName2	50		party owner 2 first name
MiddleName2	20		party owner 2 middle name
LastName2	50		party owner 2 last name
Suffix2	20		party owner 2 name suffix
MailAddr	100		mailing address
MailCity	100		mailing city
MailState	15		mailing state
MailZip	10		mailing ZIP
MailPlus4	4		mailing ZIP 4
MailCRRT	4		mailing carrier route
MailDPB	2		mailing delivery point
MailFIPS	5		mailing FIPS
SiteAddr	50		property address
SiteCity	35		property city
SiteState	15		property state
SiteZip	10		property ZIP
SitePlus4	4		property ZIP 4
SiteCRRT	4		property carrier route
SiteDPB	2		property delivery point
SiteFIPS	5		property FIPS
SiteMak
PropertyType	250	fpropertype
BedroomsCount	10	fbedrooms
BathCount	10	fbathrooms
AreaSqft	10	fsqft
LotSqft	10	flot
LotAcre	15
Units	5	funits
YearBuilt	4	fyearbuilt
EstimatedPropertyValue	15	fpval
EquityAmount	15	fequity
LoanToValueRatio	15	flvratio
LastSaleDate	10	fsdt
LastSaleAmount	15	fsamt
BasementAreaSqft	10	fbsqft
Pool	3	fpool
Heater	3	fheat
AC	3	fac
Fireplace	3	ffireplace
Mortgage1Amount	15	fmtgAmt
Mortgage2Amount	15
Mortgage1InterestRate	10	fmtgRt
Mortgage2InterestRate	10
Mortgage1InterestRateType	15	fmtgRtTp
Mortgage2InterestRateType	15
Mortgage1Term	10	fmtgTm
Mortgage2Term	10
Mortgage1LenderName	250	fmtgLender
Mortgage2LenderName	250
Mortgage1RecordingDate	10	fmtgRecDt
Mortgage2RecordingDate	10
Mortgage1Type	250	fmtgTp
Mortgage2Type	250
Mortgage1SellerCarryBack	3	fmtgScb
Mortgage2SellerCarryBack	3
PrimaryAbsenteeOwner	13	foccu
TrusteeOwner	3	fowntrs
CorporateOwner	3	fowncorp
HouseholdAge	11	fhhage
IncomeEstimatedHousehold	250	fgender
MaritalStatus	250	fhhinc
HomeLengthofResidence	250	fmartial
HouseholdSize	250	flores
NumberOfAdults	250	fpeople
NumberOfChildren	250	fadults

Status Codes

For details of all status codes please visit here

All Melissa products use result codes. LeadGen - Property Status codes are numeric codes, e.g. 101. Status codes are returned as a comma-delimited string with no whitespace, e.g. 100,101.

The following table shows the most common status codes seen while using LeadGen - Property.

Code	Long Description
1	Approved.
100	Unrecognized ZIP Code.
101	Unrecognized city or state.
102	Unrecognized county or state.
103	Unrecognized address.
106	Invalid user information.
107	Invalid number of records requested.
108	Order failed, please try later.
109	Insufficient geographic input.
111	Request exceeds 100,000 record maximum.
112	Unrecognized state.
113	Error, please try again.
116	Sorry, you don’t have permission to access this service.
117	ZIP Code is not a valid input for the requested geography type.
123	Invalid option.
124	Order count exceeds 65,535 record maximum for comma limited files.
134	Invalid geographic input.
135	Conflict between ZIPs in city and ZIP in radius.
136	ZIP in radius cannot have multiple ZIPs.
137	Unrecognized town.
138	Miles must be between 0.25 and 10.
139	Invalid latitude/longitude.
140	Miles must be between 0.25 and 10.
141	Area must be between 0.25 and 10 sq. miles.
142	Invalid file type.