Skip to content
/Occupant Service

LeadGen - Occupant

Overview

Welcome to the LeadGen Occupant by Melissa. The Occupant Cloud API is a REST based Cloud API 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, 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 Cloud API requires a License Key that has been activated for the Occupant Cloud API.

Documentation

Useful Resources

Product Page

https://www.melissa.com/direct/mailing-lists-sales-leads/leadgen-api

Support Center

https://www.melissa.com/company/product-support

Download OpenAPI description
leadgen-occupant.json
leadgen-occupant.yaml
Languages
Servers
Occupant Service Server
http://list.melissadata.net/V1/occupant/rest/Service.svc/

Occupant Service

Use this endpoint to call various occupant service actions.

Operations

Perform action for a single occupant

Request

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

Path
actionstringrequired

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"
Example: get
formatstringrequired

Format is json or xml.

Enum"json""xml"
Example: json
geographicTypestringrequired

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"
Example: zip
Query
idstringrequired

Customer ID, License Key, or Email Address. This is checked against the list of registered customers.

Example: id=REPLACE-WITH-YOUR-LICENSE-KEY
zipstringrequired

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: zip=92688
crrtstringrequired

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: crrt=b007-92688
milestring

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
countstring

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

Geographic Type

  • Required: RadiusByRecords
addressstring

Street address that will be the center of the search area.

Geographic Type

  • Required: RadiusByMiles, RadiusByRecords
statestring

Two-character abbreviation for the desired state. Ex: “state=ca”.

Geographic Type

  • Required: city, county
  • Optional: RadiusByMiles, RadiusByRecords, CitiesByState, CountiesByState
citystring

Must be the name of an existing city within the selected state.

Geographic Type

  • Required: city
  • Optional: RadiusByMiles, RadiusByRecords
countystring

Must be the name of an existing county within the selected state.

Geographic Type

  • Required: county
cityresstring

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.

cityaptstring

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.

citybizstring

Includes business and commercial addresses not located on rural routes.

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

poresstring

Includes PO Boxes rented by residential customers.

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

pobizstring

Includes PO Boxes rented by commercial customers.

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

ruralresstring

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.

ruralaptstring

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.

ruralbizstring

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.

multistring

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)

filestring

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)
postring

Buy Requests Only. Defines the customer's purchase order number.

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

namestring

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

dbugstring

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

curl -i -X GET \
  'http://list.melissadata.net/V1/occupant/rest/Service.svc/get/json/zip?id=REPLACE-WITH-YOUR-LICENSE-KEY&zip=92688&crrt=b007-92688'

Responses

Successful response

Body
Occupantobject

Tag encapsulating the whole XML document

Response
{
  "Occupant": {
    "Geography": { … },
    "Options": { … },
    "CarrierRoutes": { … },
    "Streets": "",
    "TotalCount": { … },
    "Result": { … }
  }
}