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:

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=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",
  "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.