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

  • Put the input address into JSON, XML, or REST format.
  • Make sure to include your license key.
  • Specify any options you would like to modify from their default
  • Send the request to one of the service URLs:
    • https://smartmover.melissadata.net/v3/WEB/doSmartMover using HTTPS GET
    • https://smartmovercanada.melissadata.net/V3/WEB/SmartMover/ using HTTPS GET
  • Receive the result back from the service

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:
    • https://SmartMover.melissadata.net/v3/WEB/SmartMover/doSmartMover using HTTP POST
  • 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=[YourLicense]&full=john%20smith&city=RSM%20&a1=22382%20Avenida%20Empresa&state=CA&postal=92688&format=json

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",
  "PAFId":" ",
  "ExecutionID":" ",
  "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
JobID jobid This identifies to the service the records belonging to the same list for NCOA and CCOA report purposes. All records from the same list should have the same JobID. This is NOT a unique database key, RecordID should be used for that. NO
PAFId pafid Only applies for Broker accounts and not to CCOA. For Smartmover Brokers with their own set of end users, use the PAF ID to identify which end user this record belongs to. NO
ExecutionID In rare situations you may run into a situation where a request will be time-out by a client but finished on the server. The client then resends the same request but the server believes it is another request. So, that can result in the same record counting twice on the NCOA and CCOA report. To account for that possibility, we have the Execution ID input. We will take a hash of the input and if the hash of the current input is identical to the previous input with the same ExecutionID, we will consider it a duplicate and not count it towards the report. Specify different values for different threads.
Default value is 0 if not set.		 NO
Actions act Selects which COA objects to be used in the request.
Code Description
NCOA US Change of Address Object
CCOA Canadian Change of Address Object
Columns cols Requested Output columns NO
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.
OptSmartMoverListName list Identifies the current list. It will be included in reports returned by SmartMover V3 after processing. NO
Format format The desired format of the response. NO
RecordID This is a string value containing a unique identifier for the current record. Use this to match the record submitted with the record returned. It will return what is inputted. NO
Company comp The name of the business. NO
NameFull full The full name of an individual. Required unless parsed name inputs are used. YES/NO
NameFirst first The parsed first name of an individual. NO
NameMiddle middle The parsed middle name of an individual. NO
NamePrefix namepre The title or honorific prefix of the name. E.g. "Mr, Miss, Dr". NO
NameSuffix namesfx The generational or professional suffix of the name. E.g. "Jr, IV, Ph.D.". NO
NameLast last The parsed last name of an individual. NO
Urbanization u Only used for addresses in Puerto Rico. This is used to break ties between similar addresses in the same Postal Code. NO
AddressLine1 a1 A minimum address location for the name / company contact YES
AddressLine2 a2 The second address line. NO
Suite ste The suite number. NO
PrivateMailbox pmb The private mailbox number, if this address is a box in a private mailbox service. NO
City city The city name. NO
State state The state name. NO
PostalCode postal The five-digit ZIP Code, the first five digits of a ZIP+4, or a full nine-digit ZIP+4. NO
Plus4 plus4 The last four digits of a ZIP+4. NO
Country ctry The country code. The SmartMover V3 web service can only update addresses within the United States. NO

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.