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.
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
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.
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 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.
Here, we are sending a batch request with 2 records.
This is a string value that serves as a unique identifier for this set of records. It is returned as sent.
The License Key issued by Melissa.
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.
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.
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.
Selects which COA objects to be used in the request.
US Change of Address Object
Canadian Change of Address Object
Requested Output columns
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.
Matches individuals and businesses only. Omits family matches.
Matches with individuals only. Omits business and family matches.
Matches with businesses only. Omits individual and family matches.
Matches with individual and family matches. Omits business matches.
[1 - 52]
Times per year list is used for mailing.
[6 - 48]
Number of months back to search for address change.
Identifies the current list. It will be included in reports returned by SmartMover V3 after processing.
The desired format of the response.
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.
The name of the business.
The full name of an individual. Required unless parsed name inputs are used.
The parsed first name of an individual.
The parsed middle name of an individual.
The title or honorific prefix of the name. E.g. "Mr, Miss, Dr".
The generational or professional suffix of the name. E.g. "Jr, IV, Ph.D.".
The parsed last name of an individual.
Only used for addresses in Puerto Rico. This is used to break ties between similar addresses in the same Postal Code.
A minimum address location for the name / company contact
The second address line.
The suite number.
The private mailbox number, if this address is a box in a private mailbox service.
The city name.
The state name.
The five-digit ZIP Code, the first five digits of a ZIP+4, or a full nine-digit ZIP+4.
The last four digits of a ZIP+4.
The country code. The SmartMover V3 web service can only update addresses within the United States.
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.
Here is a sample response of the REST request from above.
The address verification results with codes for status, error, and changes. See the Results section below for more details.
CASS summary report link.
NCOA summary report link.
Extra Address Information notbelonging to any of the other address fields.
Returns a unique key for the current address.
Address Line 1.
Address Line 2.
Code specifying the type of address. For a list of codes, see SmartMover wiki documentation.
A unique key assigned to the base address of a complex with apartments or suites.
Carrier route code.
The city name.
The city abbreviation.
Name of the business.
The standard code of the country
The full country name.
The RBDI Indicator code based on the address.
Contains the 12th digit of the POSTNET barcode.
Contains the 10th and 11th digits of the POSTNET barcode,
(MAK) A unique key assigned to an address record.
US Only. Returns the effective date of the move in the format "YYYYMM".
Specifies the type of address record matched
Position of the record in the response array.
Returns record specific result codes
Standard two-letter abbreviation of the state.
Full name of the state
Returns the value passed to the Urbanization field in the request.
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.