Quickstart Guide

SmartMover

Introduction

Melissa’s Smart Mover Web API offers a straightforward REST or JSON-based service that will verify a US or Canadian address and determine if the associated Name or Company has moved to a new location.

SmartMover Web API can be used to:

  • Keep contact addresses from the US and Canada up to date.
  • Standardize and validate addresses.

SmartMover has the ability to:

  • Identify moves up to 48 months back.
  • Identify Business, Individual or Family type moves.
  • Return the date (in the form YYYY-MM) of identified moves

Basic Order of Operations

  • Create an instance of the request object.
  • Populate the request element CustomerID with your product license key.
  • Add input Names or Companies and Addresses to the “Records” array with anywhere from 1 to 100 records.
  • Call the doSmartMover method and pass in the request to the service using the WEB endpoint for JSON requests.
  • Examine and parse the response from the reply object back from the service.
  • Interpret the result codes.

Real Time

Batch

  • Put the input request together using JSON or XML. Put up to 100 records into the request array.
  • Make sure to include your license key.
  • Specify any options you would like to modify from their default. They will apply to all records in the request.
  • Make sure to specify the same options for all records in the batch to maintain consistency.
  • Send the full request to the service URL:
  • Receive the result back for all addresses from the input

Input Request

NOTE: It expects UTF-8 character encoding. Be on the lookout for question marks (?), squares (▖) or other weird characters like �. They may be an indication of encoding issues and may result in data loss. Bad encoding or character loss is not something our service can correct for you.

Real Time

With a REST request, you can include all the input along with the URL for an easy and quick way of sending a single record. 

curl -X GET "https://smartmover.melissadata.net/V3/WEB/SmartMover/doSmartMover?t=test&id=61468773&full=john%20smith&city=RSM%20&a1=22382%20Avenida%20Empresa&state=CA&postal=92688"&format=restjson"

You can also put the URL without the "curl -X GET" command directly into your browser. You can also toggle between getting XML or JSON back using the format input parameter. As you can see, in this example, we are asking for JSON back.

Batch

Batch requests from 1 to 100 records at a time are sent using HTTP POST. This means you cannot send it in a browser like with HTTP GET.

Header

Make sure the header includes this line.

Accept: application/json

Body

{
  "TransmissionReference":" ",
  "CustomerID":"########",
  "JobID":"47",
  "Actions":" ",
  "Columns":"",
  "Options":"",
  "OptSmartMoverListName":" ",
  "Format":" ",
  "Records":[{
    "RecordID":"1",
    "Company":"Melissa Data",
    "NameFull":" ",
    "AddressLine1":"22382 Avenida Empresa",
    "PostalCode":"92688",
    "Plus4":" ",
    "Country":"US"
  },{
    "RecordID":"2",
    "Company":" ",
    "NameFull":"John Smith",
    "AddressLine1":"12 Main St",
    "City":" ",
    "State":" ",
    "PostalCode":"11111",
    "Plus4":" ",
    "Country":"US"
  }]
}

Here, we are sending a batch request with 2 records.

Input Fields

Batch Input REST Input Description REQUIRED
TransmissionReference t This is a string value that serves as a unique identifier for this set of records. It is returned as sent. NO
CustomerID id The License Key issued by Melissa. YES
Options opt ProcessingType
Code Description
Standard Matches in the following order:
  • Business - Match on business name.
  • Individual - Math on first name, middle name, surname, and title. Gender is checked and nickname possibilities are considered.
  • Family - Match on surname only.
IndividualAndBusiness Matches individuals and businesses only. Omits family matches.
Individual Matches with individuals only. Omits business and family matches.
Business Matches with businesses only. Omits individual and family matches.
Residential Matches with individual and family matches. Omits business matches.
ListOwnerFreqProcessing
Code Description
[1 - 52] Times per year list is used for mailing.
NumberofMonthsRequested
Code Description
[6 - 48] Number of months back to search for address change.
Columns cols Requested Output columns NO
NameFull full A full Name at a location. Required unless parsed name inputs are used. YES/NO
Company comp A company at a location NO
NameFirst first A parsed first name of a fullname at a location NO
NameLast last A parsed last name of a fullname at a location NO
AddressLine1 a1 A minimum address location for the name / company contact YES

Input Best Practices

Standardize input names before using the Smartmover service. Having the Company or Individual name in a recognized, valid format will improve the likelihood of an associated Address more likely.

If using the batch mode, monitor throughput and adjust record array size accordingly.

Output Response

XML Response

Here is a sample response of the REST request from above.

<Response xmlns="urn:mdSmartMover" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <CASSReportLink>https://smartmover...</CASSReportLink>
  <NCOAReportLink>https://smartmover...</NCOAReportLink>
  <Records>
    <ResponseRecord>
      <AddressExtras/>
      <AddressKey>V2T2K800000</AddressKey>
      <AddressLine1>620 Lincoln Ave</AddressLine1>
      <AddressLine2/>
      <AddressTypeCode/>
      <BaseMelissaAddressKey/>
      <CarrierRoute/>
      <City>Anytown</City>
      <CityAbbreviation>Anytown</CityAbbreviation>
      <CompanyName/>
      <CountryCode>US</CountryCode>
      <CountryName>United States</CountryName>
      <DeliveryIndicator/>
      <DeliveryPointCheckDigit/>
      <DeliveryPointCode/>
      <MelissaAddressKey/>
      <MoveEffectiveDate/>
      <MoveTypeCode/>
      <PostalCode>98069-4222</PostalCode>
      <RecordID>1</RecordID>
      <Results>AE01</Results>
      <State>CA</State>
      <StateName/>
      <Urbanization/>
    </ResponseRecord>
  </Records>
  <TotalRecords>1</TotalRecords>
  <TransmissionReference/>
  <TransmissionResults/>
  <Version>4.0.4.51</Version>
</Response>

Batch

Here is the response from the sample batch request.

{
    "Records": [{
      "AddressExtras": "",
      "AddressKey": "92688211282",
      "AddressLine1": "22382 Avenida Empresa",
      "AddressLine2": "",
      "AddressTypeCode": "S",
      "BaseMelissaAddressKey": "",
      "CarrierRoute": "C057",
      "City": "Rancho Santa Margarita",
      "CityAbbreviation": "Rcho Sta Marg",
      "CompanyName": "Melissa Data",
      "CountryCode": "US",
      "CountryName": "United States",
      "DeliveryIndicator": "B",
      "DeliveryPointCheckDigit": "1",
      "DeliveryPointCode": "82",
      "MelissaAddressKey": "8008006245",
      "MoveEffectiveDate": "",
      "MoveTypeCode": "",
      "PostalCode": "92688-2112",
      "RecordID": "1",
      "Results": "AC02,AC03,AS01,CS02",
      "State": "CA",
      "StateName": "California",
      "Urbanization": ""
    },{
      "AddressExtras": "",
      "AddressKey": "11111000000",
      "AddressLine1": "12 Main St",
      "AddressLine2": "",
      "AddressTypeCode": "",
      "BaseMelissaAddressKey": "",
      "CarrierRoute": "",
      "City": "",
      "CityAbbreviation": "",
      "CompanyName": "",
      "CountryCode": "US",
      "CountryName": "United States",
      "DeliveryIndicator": "",
      "DeliveryPointCheckDigit": "",
      "DeliveryPointCode": "",
      "MelissaAddressKey": "",
      "MoveEffectiveDate": "",
      "MoveTypeCode": "",
      "PostalCode": "11111",
      "RecordID": "2",
      "Results": "AE01",
      "State": "",
      "StateName": " ",
      "Urbanization": ""
    }],
  "TotalRecords": "2",
  "TransmissionReference": "",
  "TransmissionResults": "",
  "Version": "4.0.4.54"
}

Output Fields

Response (Base Level)

Output Name Description
Version The current service version
TransmissionReference Optional request identifier
TransmissionResults Service and General Transmission Errors
TotalRecords Total number of records returned.
Results The address verification results with codes for status, error, and changes. See the Results section below for more details.
CASSReportLink CASS summary report link.
NCOAReportLink NCOA summary report link.

Record Level

Output Name Description
AddressExtras Extra Address Information notbelonging to any of the other address fields.
AddressKey Returns a unique key for the current address.
AddressLine1 Address Line 1.
AddressLine2 Address Line 2.
AddressTypeCode Code specifying the type of address. For a list of codes, see SmartMover wiki documentation.
BaseMelissaAddressKey A unique key assigned to the base address of a complex with apartments or suites.
CarrierRoute Carrier route code.
City The city name.
CityAbbreviation The city abbreviation.
CompanyName Name of the business.
CountryCode The standard code of the country
CountryName The full country name.
DeliveryIndicator The RBDI Indicator code based on the address.
DeliveryPointCheckDigit Contains the 12th digit of the POSTNET barcode.
DeliveryPointCode Contains the 10th and 11th digits of the POSTNET barcode,
MelissaAddressKey (MAK) A unique key assigned to an address record.
MoveEffectiveDate US Only. Returns the effective date of the move in the format "YYYYMM".
MoveTypeCode Specifies the type of address record matched
PostalCode Postal Code.
RecordID Position of the record in the response array.
Results Returns record specific result codes
State Standard two-letter abbreviation of the state.
StateName Full name of the state
Urbanization Returns the value passed to the Urbanization field in the request.

Interpreting Results

Melissa products use a result code system to indicate data quality; the status and any errors. These result codes are four-character codes (two letters followed by two numbers), delimited by commas. Result code definitions are shared among Melissa products. Instead of looking at multiple properties and methods to determine status, you can look at the output of the results parameter.

Code Description Recommendation
CS01 Move with New Address Good
CS02 Standardized Address Good
CS03 Move Input Requirements not Satisfied Medium
CS04 Move but No New Address Good
CS10 Individual Move Good
CS11 Family Move Good
CM01 COA Match Good
CM03 Moved no forwarding Medium
ASO1 Address was verified Good
AE** Associated Error with input address Bad
AC** A change was made to an input address property Medium

For a list of the common transmission errors, see the General Info - Response Level Errors page.

For the full list of all possible result codes, please visit our Result Wiki page at SmartMover Result Code Details.