Occupant Service

Use Occupant Service endpoint to request 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 XML 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

Acceptstringrequired

Format of the response.

Enum:"application/xml""*/*"

Example:application/xml

Content-Typestringrequired

Format of the request.

Enum:"application/xml""application/json"

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' \
  -H 'Accept: application/xml' \
  -H 'Content-Type: application/xml'

Responses

Successful response

Body

Occupantobject

Tag encapsulating the whole XML document

Response

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