Quickstart Guide
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:
SmartMover has the ability to:
doSmartMover
method and pass in the request to the service using the WEB endpoint for JSON requests.Real Time
Batch
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.
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
|
||||||||||||||||||||
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 |
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.
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" }
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. |
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.