Skip to content
Data Retriever/
/
Get a paginated result vi...

Data Retriever

Overview

The Data Retriever Cloud API allows you to generate, download, and access lists of contacts, addresses, businesses, and more.

Data Retriever offers the following capabilities:

  • Retrieve a count of results based on provided filters, including City/State, Radius, Zip code, and polygon Shape.
  • Purchase a complete result set, navigate through the list of contacts and addresses using pagination.

Documentation

Useful Resources

Product Page

https://www.melissa.com/data-retriever-cloud-api

Support Center

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

Download OpenAPI description
data-retriever.json
data-retriever.yaml
Languages
Servers
Data Retriever Server
https://dataretriever.melissadata.net/web/V1/

MAK

Use this endpoint to retrieve lists of addresses.

Operations

NewMovers

Use this endpoint to retrieve lists of new movers.

Operations

NewHomeowners

Use this endpoint to retrieve lists of new homeowners.

Operations

Get total record count of new homeowners

Request

This endpoint gets the total record count returned using the required and optional properties passed in. This endpoint does not count against the package usage.

Bodyapplication/jsonrequired
CustomerIDstring(CustomerID)required

The License Key issued by Melissa.

Includesobject(NewHomeowners_Includes)required

Any parameter you would like to include in the query.

Requires at least one from:

  • Zips
  • Cities
  • Radius
  • ShapeWKTs
Includes.​ZipsArray of objects(Zips)

A list of Zips objects containing Zip codes and optionally Plus4.

Includes.​CitiesArray of objects(Cities)

A list of cities objects each containing City and State.

Includes.​Radiusobject(Radius)

A Radius object containing a Latitude, Longitude, and Distance represented in miles.

Includes.​ShapeWKTsArray of strings(wkt)(ShapeWKTs)

A list of WKT polygon strings

Includes.​MelissaAddressKeyArray of strings(MelissaAddressKey)

A list of Melissa address keys.

Includes.​BaseMelissaAddressKeyArray of strings(BaseMelissaAddressKey)

A list of BaseMelissaAddressKeys.

Includes.​FirstNameArray of strings(FirstName)

A list of FirstNames.

Includes.​LastNameArray of strings(LastName)

A list of LastNames.

Includes.​RBDIArray of strings(RBDI)

An RBDI code.

Includes.​AddressArray of strings(Address)

A list of Addresses.

Includes.​StreetArray of strings(Street)

A list of Streets.

Includes.​StateArray of strings(State)

A list of States.

Includes.​Plus4Array of strings(Plus4)

A list of Plus4s.

Includes.​DeliveryPointArray of strings(DeliveryPoint)

A list of DeliveryPoints.

Includes.​AddressKeyArray of strings(AddressKey)

A list of AddressKeys.

Includes.​CarrierRouteArray of strings(CarrierRoute)

A list of CarrierRoutes.

Includes.​FIPSCodeArray of strings(FIPSCode)

A list of FIPSCodes.

Includes.​CountyNameArray of strings(CountyName)

A list of CountyNames.

Includes.​PlaceCodeArray of strings(PlaceCode)

A list of PlaceCodes.

Includes.​LatitudeArray of strings(Latitude)

A list of Latitudes.

Includes.​LongitudeArray of strings(Longitude)

A list of Longitudes.

Includes.​CensusKeyArray of strings(CensusKey)

A list of CensusKeys.

Includes.​PhoneNumberArray of strings(PhoneNumber)

A list of PhoneNumbers.

Includes.​PurchasePriceArray of strings(PurchasePrice)

A list of PurchasePrices.

Includes.​SellDateobject(SellDate)

A list of SellDates.

Includes.​LenderArray of strings(Lender)

A list of Lenders.

Includes.​TransactionTypeArray of strings(TransactionType)

A list of TransactionTypes.

Includes.​PublishedDateArray of strings(PublishedDate)

A date range with start and end dates.

Includes.​CondoCodeArray of strings(CondoCode)

A list of CondoCodes.

Includes.​MortgageAmountArray of strings(MortgageAmount)

A list of MortgageAmounts.

Includes.​RateTypeArray of strings(RateType)

A list of RateTypes.

Includes.​LoanTypeArray of strings(LoanType)

A list of LoanTypes.

Excludesobject(NewHomeowners_Excludes)

Any parameter you would like to exclude in the query.

ColumnsArray of strings(NewHomeowners_Columns)

All NewHomeowners Columns you want returned.

Items Enum"MelissaAddressKey""BaseMelissaAddressKey""FirstName""LastName""AddressLine""City""State""ZIPCode""Plus4""DeliveryPoint"
curl -i -X POST \
  https://dataretriever.melissadata.net/web/V1/NewHomeowners/doCount \
  -H 'Content-Type: application/json' \
  -d '{
    "CustomerID": "{REPLACE-WITH-YOUR-LICENSE-KEY}",
    "Includes": {
      "Zips": [
        {
          "Zip": "92688"
        }
      ],
      "SellDate": {
        "StartDate": "2023/01/01",
        "EndDate": "2024/01/01"
      }
    }
  }'

Responses

Successful response

Bodyapplication/json
Countinteger

Number of records returned by the query.

JobIdstring

The JobId to be used to purchase and access the full dataset.

ResultCodestring

Success or Error codes based on the response/request.

Response
application/json
{
  "Count": 406,
  "JobId": "returned_job_id",
  "ResultCode": "LS01"
}

Get a paginated result view of new homeowners

Request

This endpoint returns a paginated result view of the request. This can sometimes take awhile and should be used after DoCount has been used to filter down your dataset.

Bodyapplication/jsonrequired
CustomerIDstring(CustomerID)required

The License Key issued by Melissa.

Includesobject(NewHomeowners_Includes)required

Any parameter you would like to include in the query.

Requires at least one from:

  • Zips
  • Cities
  • Radius
  • ShapeWKTs
Includes.​ZipsArray of objects(Zips)

A list of Zips objects containing Zip codes and optionally Plus4.

Includes.​CitiesArray of objects(Cities)

A list of cities objects each containing City and State.

Includes.​Radiusobject(Radius)

A Radius object containing a Latitude, Longitude, and Distance represented in miles.

Includes.​ShapeWKTsArray of strings(wkt)(ShapeWKTs)

A list of WKT polygon strings

Includes.​MelissaAddressKeyArray of strings(MelissaAddressKey)

A list of Melissa address keys.

Includes.​BaseMelissaAddressKeyArray of strings(BaseMelissaAddressKey)

A list of BaseMelissaAddressKeys.

Includes.​FirstNameArray of strings(FirstName)

A list of FirstNames.

Includes.​LastNameArray of strings(LastName)

A list of LastNames.

Includes.​RBDIArray of strings(RBDI)

An RBDI code.

Includes.​AddressArray of strings(Address)

A list of Addresses.

Includes.​StreetArray of strings(Street)

A list of Streets.

Includes.​StateArray of strings(State)

A list of States.

Includes.​Plus4Array of strings(Plus4)

A list of Plus4s.

Includes.​DeliveryPointArray of strings(DeliveryPoint)

A list of DeliveryPoints.

Includes.​AddressKeyArray of strings(AddressKey)

A list of AddressKeys.

Includes.​CarrierRouteArray of strings(CarrierRoute)

A list of CarrierRoutes.

Includes.​FIPSCodeArray of strings(FIPSCode)

A list of FIPSCodes.

Includes.​CountyNameArray of strings(CountyName)

A list of CountyNames.

Includes.​PlaceCodeArray of strings(PlaceCode)

A list of PlaceCodes.

Includes.​LatitudeArray of strings(Latitude)

A list of Latitudes.

Includes.​LongitudeArray of strings(Longitude)

A list of Longitudes.

Includes.​CensusKeyArray of strings(CensusKey)

A list of CensusKeys.

Includes.​PhoneNumberArray of strings(PhoneNumber)

A list of PhoneNumbers.

Includes.​PurchasePriceArray of strings(PurchasePrice)

A list of PurchasePrices.

Includes.​SellDateobject(SellDate)

A list of SellDates.

Includes.​LenderArray of strings(Lender)

A list of Lenders.

Includes.​TransactionTypeArray of strings(TransactionType)

A list of TransactionTypes.

Includes.​PublishedDateArray of strings(PublishedDate)

A date range with start and end dates.

Includes.​CondoCodeArray of strings(CondoCode)

A list of CondoCodes.

Includes.​MortgageAmountArray of strings(MortgageAmount)

A list of MortgageAmounts.

Includes.​RateTypeArray of strings(RateType)

A list of RateTypes.

Includes.​LoanTypeArray of strings(LoanType)

A list of LoanTypes.

Excludesobject(NewHomeowners_Excludes)

Any parameter you would like to exclude in the query.

ColumnsArray of strings(NewHomeowners_Columns)required

All NewHomeowners Columns you want returned.

Items Enum"MelissaAddressKey""BaseMelissaAddressKey""FirstName""LastName""AddressLine""City""State""ZIPCode""Plus4""DeliveryPoint"
Paginationobject(Pagination)required

Specify the desired page in the results to access. Pages are based on 100 records per page.

Pagination.​Pageinteger
curl -i -X POST \
  https://dataretriever.melissadata.net/web/V1/NewHomeowners/doLookup \
  -H 'Content-Type: application/json' \
  -d '{
    "CustomerID": "{REPLACE-WITH-YOUR-LICENSE-KEY}",
    "Includes": {
      "Zips": [
        {
          "Zip": "92688"
        }
      ],
      "SellDate": {
        "StartDate": "2023/01/01",
        "EndDate": "2024/01/01"
      }
    },
    "Columns": [
      "MelissaAddressKey",
      "AddressLine",
      "PurchasePrice",
      "SellDate"
    ],
    "Pagination": {
      "Page": 1
    }
  }'

Responses

Successful response

Bodyapplication/json
Countinteger

Number of records returned by the query.

ResultsArray of objects

Returned records with requested Columns.

Paginationobject

The current page number and the next page number.

JobIdstring

The JobId to be used to purchase and access the full dataset.

ResultCodestring

Success or Error codes based on the response/request.

Response
application/json
{
  "Count": 406,
  "Results": [
    { … },
    { … }
  ],
  "Pagination": {
    "CurrentPage": 1,
    "NextPage": 2,
    "TotalPages": 4
  },
  "JobId": "returned_job_id",
  "ResultCode": "LS01"
}

Get record count and sample of new homeowners

Request

This endpoint allows API users to retrieve a count and 10 record sample of the results to preview before purchasing a file version of the full dataset.

Bodyapplication/jsonrequired
CustomerIDstring(CustomerID)required

The License Key issued by Melissa.

Includesobject(NewHomeowners_Includes)required

Any parameter you would like to include in the query.

Requires at least one from:

  • Zips
  • Cities
  • Radius
  • ShapeWKTs
Includes.​ZipsArray of objects(Zips)

A list of Zips objects containing Zip codes and optionally Plus4.

Includes.​CitiesArray of objects(Cities)

A list of cities objects each containing City and State.

Includes.​Radiusobject(Radius)

A Radius object containing a Latitude, Longitude, and Distance represented in miles.

Includes.​ShapeWKTsArray of strings(wkt)(ShapeWKTs)

A list of WKT polygon strings

Includes.​MelissaAddressKeyArray of strings(MelissaAddressKey)

A list of Melissa address keys.

Includes.​BaseMelissaAddressKeyArray of strings(BaseMelissaAddressKey)

A list of BaseMelissaAddressKeys.

Includes.​FirstNameArray of strings(FirstName)

A list of FirstNames.

Includes.​LastNameArray of strings(LastName)

A list of LastNames.

Includes.​RBDIArray of strings(RBDI)

An RBDI code.

Includes.​AddressArray of strings(Address)

A list of Addresses.

Includes.​StreetArray of strings(Street)

A list of Streets.

Includes.​StateArray of strings(State)

A list of States.

Includes.​Plus4Array of strings(Plus4)

A list of Plus4s.

Includes.​DeliveryPointArray of strings(DeliveryPoint)

A list of DeliveryPoints.

Includes.​AddressKeyArray of strings(AddressKey)

A list of AddressKeys.

Includes.​CarrierRouteArray of strings(CarrierRoute)

A list of CarrierRoutes.

Includes.​FIPSCodeArray of strings(FIPSCode)

A list of FIPSCodes.

Includes.​CountyNameArray of strings(CountyName)

A list of CountyNames.

Includes.​PlaceCodeArray of strings(PlaceCode)

A list of PlaceCodes.

Includes.​LatitudeArray of strings(Latitude)

A list of Latitudes.

Includes.​LongitudeArray of strings(Longitude)

A list of Longitudes.

Includes.​CensusKeyArray of strings(CensusKey)

A list of CensusKeys.

Includes.​PhoneNumberArray of strings(PhoneNumber)

A list of PhoneNumbers.

Includes.​PurchasePriceArray of strings(PurchasePrice)

A list of PurchasePrices.

Includes.​SellDateobject(SellDate)

A list of SellDates.

Includes.​LenderArray of strings(Lender)

A list of Lenders.

Includes.​TransactionTypeArray of strings(TransactionType)

A list of TransactionTypes.

Includes.​PublishedDateArray of strings(PublishedDate)

A date range with start and end dates.

Includes.​CondoCodeArray of strings(CondoCode)

A list of CondoCodes.

Includes.​MortgageAmountArray of strings(MortgageAmount)

A list of MortgageAmounts.

Includes.​RateTypeArray of strings(RateType)

A list of RateTypes.

Includes.​LoanTypeArray of strings(LoanType)

A list of LoanTypes.

Excludesobject(NewHomeowners_Excludes)

Any parameter you would like to exclude in the query.

ColumnsArray of strings(NewHomeowners_Columns)required

All NewHomeowners Columns you want returned.

Items Enum"MelissaAddressKey""BaseMelissaAddressKey""FirstName""LastName""AddressLine""City""State""ZIPCode""Plus4""DeliveryPoint"
curl -i -X POST \
  https://dataretriever.melissadata.net/web/V1/NewHomeowners/getCount \
  -H 'Content-Type: application/json' \
  -d '{
    "CustomerID": "{REPLACE-WITH-YOUR-LICENSE-KEY}",
    "Includes": {
      "Zips": [
        {
          "Zip": "92688"
        }
      ],
      "SellDate": {
        "StartDate": "2023/01/01",
        "EndDate": "2024/01/01"
      }
    },
    "Columns": [
      "MelissaAddressKey",
      "AddressLine",
      "PurchasePrice",
      "SellDate"
    ]
  }'

Responses

Successful response

Bodyapplication/json
JobIdstring

The JobId to be used to purchase and access the full dataset.

Countinteger

Number of records returned by the query.

ResultCodestring

Success or Error codes based on the response/request.

SampleArray of objects

A 10 record sample response.

Response
application/json
{
  "JobId": "returned_job_id",
  "Count": 406,
  "ResultCode": "LS01",
  "Sample": [
    { … },
    { … }
  ]
}

Consumer

Use this endpoint to retrieve lists of consumers.

Operations

Consumer Two

Use this endpoint to retrieve lists of consumers.

Operations

Business

Use this endpoint to retrieve lists of businesses.

Operations