SmartMover

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

• 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/SmartMover/doSmartMover using HTTPS GET
• https://smartmovercanada.melissadata.net/V3/WEB/SmartMover/doSmartMover 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

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.

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"
}

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.

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.