Reference Guide#

Introduction #

Welcome to the LeadGen Occupant service by Melissa. The Occupant Web Service is a REST based Web service that can be used to select, get counts, and purchase targeted consumer mailing lists, in realtime, anytime. The LeadGen services are 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.

Take advantage of your buying power with Melissa Data, and pass the discounted prices, along with an impressive selection of mailing lists and sales leads, onto your customers. They’ll appreciate the convenience, the price, and your service. Please note that the Occupant Web Service requires a License Key that has been activated for the Occupant Web Service.

Base URL #

http://list.melissadata.net/V1/occupant/rest/Service.svc

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 #

/V1/Occupant/rest/Service.svc #

Introduction #

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

http://list.melissadata.net/V1/occupant/rest/Service.svc/{{action}}/{{format}}/{{geographicType}}

Where action is either get or buy, format is json or xml, and geographicType is one geographic type selected from one of these supported types: Geographic Types

Try It Now #

GET JSON
GET XML
BUY JSON
BUY XML

curl -X GET "http://list.melissadata.net/V1/occupant/rest/Service.svc/get/json/zip\
?id=customer@domain.com&crrt=b007-92688&zip=92688" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

curl -X GET "http://list.melissadata.net/V1/occupant/rest/Service.svc/get/zip\
?id=customer@domain.com&crrt=b007-92688&zip=92688" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml"

curl -X GET "http://list.melissadata.net/V1/occupant/rest/Service.svc/buy/json/zip\
?id=customer@domain.com&crrt=b007-92688&zip=92688" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

curl -X GET "http://list.melissadata.net/V1/occupant/rest/Service.svc/buy/xml/zip\
?id=customer@domain.com&crrt=b007-92688&zip=92688" \
-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: get and buy

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.

Geographic Types #

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

Geographic Type	Description
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	Format: 2-digit state;city name. Multiple cities be requested, comma separated with no space. Ex. city=TX;Dallas,TX;Houston,TX;Austin
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	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	Returns the nearest records to the selected address, up to 100,000 files (65,535 when requesting Excel files).
States	Returns a complete list of Sates within the United States of America.
CountiesByState	Returns a complete list of counties within the specified U.S. State.
CitiesByState	Returns a complete list of cities within the specified U.S. State.
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	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 Response Fields for 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*”
zip	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 or do not include.
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)

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

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

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

{
    "Occupant": {
        "Geography": {
            "Zip": "92688",
            "CarrierRoute": "b007-92688"
        },
        "Options": {
            "CityDeliveries_ResidentialAddresses": "True",
            "CityDeliveries_Apartments": "True",
            "CityDeliveries_BusinessAddresses": "True",
            "POBoxes_ResidentialAddresses": "True",
            "POBoxes_BusinessAddresses": "True",
            "RuralRoutes_ResidentialAddresses": "True",
            "RuralRoutes_Apartments": "True",
            "RuralRoutes_BusinessAddresses": "True",
            "IncludeNamesWhereAvailable": "False"
        },
        "CarrierRoutes": {
            "CarrierRoute": {
                "Zip": "92688",
                "Route": "B007",
                "Count": "75"
            }
        },
        "TotalCount": {
            "Count": "75"
        },
        "Result": {
            "StatusCode": "Approved"
        }
    }
}

<Occupant>
    <Geography>
        <Zip>92688</Zip>
        <CarrierRoute>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>False</IncludeNamesWhereAvailable>
    </Options>
    <CarrierRoutes>
        <CarrierRoute>
            <Zip>92688</Zip>
            <Route>B007</Route>
            <Count>75</Count>
        </CarrierRoute>
    </CarrierRoutes>
    <TotalCount>
        <Count>75</Count>
    </TotalCount>
    <Result>
        <StatusCode>Approved</StatusCode>
    </Result>
</Occupant>

{
    "Occupant": {
        "Geography": {
            "Zip": "90602,92688",
            "CarrierRoute": "c061-90602,c062-90602,b007-92688"
        },
        "Options": {
            "CityDeliveries_ResidentialAddresses": "True",
            "CityDeliveries_Apartments": "True",
            "CityDeliveries_BusinessAddresses": "True",
            "POBoxes_ResidentialAddresses": "True",
            "POBoxes_BusinessAddresses": "True",
            "RuralRoutes_ResidentialAddresses": "True",
            "RuralRoutes_Apartments": "True",
            "RuralRoutes_BusinessAddresses": "True",
            "IncludeNamesWhereAvailable": "True"
        },
        "TotalCount": {
            "Count": "2483",
            "NameCount": "1705"
        },
        "Order": {
            "Id": "6819006",
            "Usage": "1",
            "DownloadURL": "https://list.melissadata.com/ListOrderFiles/123456.csv"
        },
        "Result": {
            "StatusCode": "Approved"
        }
    }
}

<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>2483</Count>
        <NameCount>1705</NameCount>
    </TotalCount>
    <Order>
        <Id>6819005</Id>
        <Usage>1</Usage>
        <DownloadURL>https://list.melissadata.com/ListOrderFiles/123456.csv</DownloadURL>
    </Order>
    <Result>
        <StatusCode>Approved</StatusCode>
    </Result>
</Occupant>

Response Fields #

These are the definitions for the xml response elements

Element	Description
<Occupant>	Tag encapsulating the whole XML document.
<Geography>	Geo request
<RadiusByRecordCount>	Returned if radius by records is called.
<RadiusByMiles>	Returned if adius 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
<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
<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.

Status Codes #

For details of all status codes please visit here

LeadGen - Occupant 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 - Occupant.

Code	Long 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 don’t have permission to access 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 65,535 record maximum for Excel files.
123	Invalid option.
124	Order count exceeds 65,535 record maximum for comma limited files.
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.

Reference Guide

Contents

Reference Guide#