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

Consumer

Use this endpoint to retrieve lists of consumers.

Operations

Get total record count of consumers

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(Consumer_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.​RBDIArray of strings(RBDI)

An RBDI code.

Includes.​FIPSCodeArray of strings(FIPSCode)

A list of FIPSCodes.

Includes.​AddressStreetNameArray of objects(AddressStreetName)

A list of address street name objects.

Excludesobject(Consumer_Excludes)

Any parameter you would like to exclude in the query.

curl -i -X POST \
  https://dataretriever.melissadata.net/web/V1/Consumer/doCount \
  -H 'Content-Type: application/json' \
  -d '{
    "CustomerID": "{REPLACE-WITH-YOUR-LICENSE-KEY}",
    "Includes": {
      "Zips": [
        {
          "Zip": "92688",
          "CarrierRoute": "C057"
        }
      ]
    },
    "Excludes": {
      "AddressStreetName": [
        {
          "ZipCode": "92688",
          "Street": "Arado"
        }
      ]
    }
  }'

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": 606,
  "JobId": "returned_job_id",
  "ResultCode": "LS01"
}

Get a paginated result view of consumers

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(Consumer_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.​RBDIArray of strings(RBDI)

An RBDI code.

Includes.​FIPSCodeArray of strings(FIPSCode)

A list of FIPSCodes.

Includes.​AddressStreetNameArray of objects(AddressStreetName)

A list of address street name objects.

Excludesobject(Consumer_Excludes)

Any parameter you would like to exclude in the query.

ColumnsArray of strings(Consumer_Columns)required

All Consumer Columns you want returned.

Items Enum"MelissaAddressKey""BaseMelissaAddressKey""TitlePrefixInd""FirstName""MiddleNameInitial""LastName""FullName""NameSuffix""AddressLine""Suite"
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/Consumer/doLookup \
  -H 'Content-Type: application/json' \
  -d '{
    "CustomerID": "{REPLACE-WITH-YOUR-LICENSE-KEY}",
    "Includes": {
      "Zips": [
        {
          "Zip": "92688",
          "CarrierRoute": "C057"
        }
      ]
    },
    "Excludes": {
      "AddressStreetName": [
        {
          "ZipCode": "92688",
          "Street": "Arado"
        }
      ]
    },
    "Columns": [
      "MelissaAddressKey",
      "AddressLine",
      "RBDI"
    ],
    "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": 606,
  "Results": [
    { … },
    { … }
  ],
  "Pagination": {
    "CurrentPage": 1,
    "NextPage": 2,
    "TotalPages": 6
  },
  "JobId": "returned_job_id",
  "ResultCode": "LS01"
}

Get record count and sample of consumers

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(Consumer_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.​RBDIArray of strings(RBDI)

An RBDI code.

Includes.​FIPSCodeArray of strings(FIPSCode)

A list of FIPSCodes.

Includes.​AddressStreetNameArray of objects(AddressStreetName)

A list of address street name objects.

Excludesobject(Consumer_Excludes)

Any parameter you would like to exclude in the query.

ColumnsArray of strings(Consumer_Columns)required

All Consumer Columns you want returned.

Items Enum"MelissaAddressKey""BaseMelissaAddressKey""TitlePrefixInd""FirstName""MiddleNameInitial""LastName""FullName""NameSuffix""AddressLine""Suite"
curl -i -X POST \
  https://dataretriever.melissadata.net/web/V1/Consumer/getCount \
  -H 'Content-Type: application/json' \
  -d '{
    "CustomerID": "{REPLACE-WITH-YOUR-LICENSE-KEY}",
    "Includes": {
      "Zips": [
        {
          "Zip": "92688",
          "CarrierRoute": "C057"
        }
      ]
    },
    "Excludes": {
      "AddressStreetName": [
        {
          "ZipCode": "92688",
          "Street": "Arado"
        }
      ]
    },
    "Columns": [
      "MelissaAddressKey",
      "AddressLine",
      "RBDI"
    ]
  }'

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": 606,
  "ResultCode": "LS01",
  "Sample": [
    { … },
    { … }
  ]
}

Consumer Two

Use this endpoint to retrieve lists of consumers.

Operations

Business

Use this endpoint to retrieve lists of businesses.

Operations