Quickstart Guide

LeadGen - Occupant

Introduction

LeadGen Occupant can be used to:

  • Select, Get Counts, and Purchase Targeted Occupant Mailing Lists
  • Do any of the above in real-time, anytime

Basic Order of Operations

Real Time

  • Set up the request: license key, options, ect.
  • Send the count request: This call returns an XML document showing the record counts for a specific request, allowing you to see how many records are available for the selected parameters.
  • Send the buy request: This call initiates the purchase of the list detailed by the request. This call is similar to the Get call, but has additional information returned. This information is the order ID, number of usage, and download URL. If the purchase of the list was successful, you will receive a link to the list file in the format you selected in the options.
  • Download/ retrieve list: download the list from HTTPS link in the buy call response.

Input Request

Simply replace [your Melissa license key] with your license key to test these requests. It will also work in any browser.

REST - Count

Use a REST request to get the count.

curl -X GET "http://list.melissadata.net/V1/occupant/rest/Service.svc/get/zip?id=[your Melissa license key]&zip=90602,92688&crrt=c061-90602,c062-90602,b007-92688&name=1"

REST - Purchase

Use the REST request to purchase the list.

curl -X GET "http://list.melissadata.net/V1/occupant/rest/Service.svc/buy/zip?id=[your Melissa license key]&zip=90602,92688&crrt=c061-90602,c062-90602,b007-92688&name=1&file=8"

HTTPS - Download

Use the HTTPS link to download the purchased list.

curl -u user:password "https://list.melissadata.com/ListOrderFiles/123456_678910.csv"

Input Fields

Geometry Request Parameters

Parameter Type Description
Zip (5 digits) Required: zip
Optional: radius by miles, radius by records, city, county		 Each five-digit ZIP is validated
For radius by miles and radius by records types, either ZIP or the city and state combination needs to be entered.
For city and county types, request can be narrowed down by specifying ZIP(s) within the city/county.
Crrt Optional: zip, city, radius by miles Format validation: carrierRoute-ZIP (dash between carrier route and zip)
The ZIP part must be consistent with the zip parameter above. Carrier route is used as filter in selection. If no occupant is within the requested carrier route(s), nothing will be returned.
Multiple carrierRoute-ZIP’s can be entered as comma separated with no space.
For radius by miles type, request can be narrowed down by specifying carrier route(s) within the mileage of the given address.
City Required: city
Optional: radius by miles, radius by records		 Each city and state combination is validated.
For radius by miles and radius by records types, either ZIP or the city and state combination needs to be entered.
County Required: county Each county and state combination is validated.
FIPS is retrieved if valid.
State Required: county, city
Optional: radius		 Two-digit state code is validated in combination with city or county depends on the geo type.
For radius by miles and radius by records types, either ZIP or the city and state combination needs to be entered.
Address Required: radius by miles, radius by records Exact street number and street name are used in data selection
No validation.
Latitude and longitude are retrieved if the address exists.
mile Required: radius by miles Mile is used to find out the latitude and longitude of a parameter so many miles away from the given address.
count Required: radius by records Number of records that are the closest to the given address (within 10 mile radius).

Occupant Request Parameters

Parameter Description Values
cityres To include city deliveries – residential addresses Default: cityres =1
To exclude: cityres=0
cityapt To include city deliveries – apartments Default: cityapt =1
To exclude: cityapt =0
citybiz To include city deliveries – business addresses Default: citybiz=1
To exclude: citybiz =0
pores To include PO boxes - residential addresses Default: pores =1
To exclude: pores=0
pobiz To include PO boxes – business addresses Default: pobiz =1
To exclude: pobiz=0
ruralres To include rural routes – residential addresses Default: ruralres=1
To exclude: ruralres=0
ruralapt To include rural routes - apartments Default: ruralapt =1
To exclude: ruralapt=0
ruralbiz To include rural routes – business addresses Default: ruralbiz=1
To exclude: ruralbiz=0

Input Best Practices

While text encoding is a rare issue with LeadGen Occupant Web Service, note that the API will not support any wrongly-encoded special characters or non-Latin characters. In general, text encoding is an important part of any data enterprise.

This service can deal with multiple languages and scripts. It expects UTF-8 encoding. Be on the lookout for question marks (?), squares (▖) or other unwanted characters like �. They may be an indication of encoding issues and may result in data loss. Bad encoding or character loss is not something our service can correct for you.

Output Response

XML Response

Here is a sample response.

<Occupant>
  <Geography>
    <Zip>90602,92688</Zip>
    <CarrierRoute>c061-90602,c062-90602,b007-92688</CarrierRoute>
  </Geography>
  <Options>
    <CityDeliveries_ResidentialAddresses>True</CityDeliveries_ResidentialAddresses>
    <CityDeliveries_Apartments>True</CityDeliveries_Apartments>
    <CityDeliveries_BusinessAddresses>True</CityDeliveries_BusinessAddresses>
    <POBoxes_ResidentialAddresses>True</POBoxes_ResidentialAddresses>
    <POBoxes_BusinessAddresses>True</POBoxes_BusinessAddresses>
    <RuralRoutes_ResidentialAddresses>True</RuralRoutes_ResidentialAddresses>
    <RuralRoutes_Apartments>True</RuralRoutes_Apartments>
    <RuralRoutes_BusinessAddresses>True</RuralRoutes_BusinessAddresses>
    <IncludeNamesWhereAvailable>True</IncludeNamesWhereAvailable>
  </Options>
  <TotalCount>
    <Count>1737</Count>
    <NameCount>1003</NameCount>
  </TotalCount>
  <CarrierRoutes>
    <CarrierRoute>
      <Zip>90602</Zip>
      <Route>C061</Route>
      <Count>769</Count>
    </CarrierRoute>
    <CarrierRoute>
      <Zip>90602</Zip>
      <Route>C062</Route>
      <Count>872</Count>
    </CarrierRoute>
    <CarrierRoute>
      <Zip>92688</Zip>
      <Route>B007</Route>
      <Count>96</Count>
    </CarrierRoute>
  </CarrierRoutes>
  <Result>
    <StatusCode>Approved</StatusCode>
  </Result>
</Occupant>

Output Fields

Field Name Description
<Occupant> Tag encapsulating the whole XML document.
<Geography> Geo request
<RadiusByRecordCount> Returned if Radius by records is called.
<RadiusByMiles> Returned if radius by miles is called.
<Address> Returned if radius by records or miles is called.
<City> Returned if city, radius by records, or radius by miles is called.
<County> Returned if county is called.
<State> Returned if city, county, radius by records, or radius by miles is called.
<Zip> Returned if zip, radius by records, radius by miles is called.
City and county calls are option only when zip is given by user.
<CarrierRoute> Returned if user requested for zip, city, radius by miles geo types.
<Options> Occupant options requested
<CityDeliveries_ResidentialAddresses> True or False
<CityDeliveries_Apartments>
<CityDeliveries_BusinessAddresses>
<POBoxes_ResidentialAddresses>
<POBoxes_BusinessAddresses>
<RuralRoutes_ResidentialAddresses>
<RuralRoutes_Apartments>
<RuralRoutes_BusinessAddresses>
<IncludeNamesWhereAvailable>
<TotalCount>
<Count> Total number of records returned.
<NameCount> Total number of records with name returned
<CarrierRoutes> Breakdown by carrier routes – for ZIP, city, radius by miles types.
<CarrierRoute> Detailed info of each carrier route
<Zip> 5 digit ZIP
<Route> 4 digit carrier route
<Count> Number of occupants within this carrier route
<ZipCodes> Breakdown by ZIP – for city, county types.
<Zip> Detailed info of each ZIP
<ZipCode> 5 digit ZIP
<Count> Number of occupants within this ZIP
<Streets> Breakdown by street – for radius by miles, radius by records type.
<Street> Detailed info of each street
Format: street name, city, state ZIP
<StartNumber> Start number of the street with the requested criteria
<EndNumber> End number of the street with the requested criteria
<Count> Number of occupants within this carrier route
<Zip>
<Order> Buy Requests Only. Order details for a Buy request.
<Id> Order Id.
<DownloadURL> The URL to download the purchased file.
<PONumber> Returned if po is specified.
<Result> Returns the status code.
<StatusCode> Indicates the status of a request. Returns Declined, Approved, or Err.
<Errors> If <StatusCode> returns Err.
<Error>
<ErrorCode>
<ErrorDescription>

Download File

Column Name Max Length URL Parameter Description
RBDI 20 Residential/Business Indicator
Title 20 Mail to Line 1
Address 64 Mailing street address
City 28 Mailing city name
State 2 Mailing state
Zip 5 Mailing zip
Plus4 4 Maling zip4
Walkseq 9 Walk Sequence Number
Crrt 4 Mailing carrier route
Endose 30 Postal Endorsement
City_rural 1 Carrie Route Type
dpb 2 2-digit Delivery Point
dpbc 20 Delivery Point Check Digit
PreName 10 name=1 Primary Pre Name
FirstName 20 Primary First Name
Initial 1 Primary Middle Initital
LastName 20 Primary Last Name
PostName 5 Primary Name Suffix
updateD 10 Last update date of Carrier Route

Interpreting Results

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

The following table shows the most common result codes seen while using LeadGen - Occupant.

Code Description
100 Unrecognized ZIP Code.
101 Unrecognized city or state.
102 Unrecognized county or state.
103 Unrecognized address.
104 User ID or password not recognized.
106 Invalid user information.
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.
115 For the Radius geography type, please enter a number of records.
116 Sorry, you have no permission to this service.
117 ZIP Code is not a valid input for the requested geography type.
121 The list cannot be used more than 5 times.
122 Order count exceeds the 65,535 record maximum for Excel files.
123 Invalid option.
124 Excel and comma limited files cannot have more than 65,535 records.
125 Request exceeds 10 miles maximum radius.
130 You have exceeded your order limit.
131 You're approaching your order limit.
132 Your subscription will expire soon.
133 Your subscription expired.