Reference Guide

Introduction

Contact data will deteriorate over time as people and businesses move around. SmartMover will allow you to keep that data up to date, both maintaining and confirming accuracy. The SmartMover Cloud Service is able to validate and standardize addresses, detect moves, and provide an updated address for an individual or business. SmartMover is available for both the US and Canada using data from the USPS and Canada Post respectively.

Base URL

• National Change of Address (NCOA)
• Canada Change of Address (CCOA)

https://smartmover.melissadata.net

https://smartmovercanada.melissadata.net

Licensing

The License Key is a software key required to use the web service. You will receive your license key from your Melissa representative. If you don’t have a license key, contact the Melissa sales team by Requesting a Demo or by calling 800-MELISSA ext. 3 (800-635-4772 ext. 3). Without a license key, Smart Mover will not function.

To set the license key, use the id/CustomerID property in your requests.

USPS® NCOA Processing Acknowledgement Form (PAF)

Melissa Data will require PAF documents filed once a year for customers who are:

1. The End User/List Owner: Processes a list for their own private use – Only needs to submit one PAF.

2. Processes lists for multiple clients – Needs to submit a PAF for each client (list owner) and will also need to include how many records will be submitted per file, per customer email address._

Endpoints

US: https://smartmover.melissadata.net/V3/WEB/SmartMover

• Check a move with a name and address.

• Check if the business has changed locations.

Try It Now

Note

Make sure to replace {{customerId}} with your license!

Note

Make sure to replace {{pafId}} with your paf id!

• GET JSON
• POST JSON
• GET XML
• POST XML

curl -X GET "https://smartmover.melissadata.net/V3/WEB/SmartMover/doSmartMover?\
&id={{customerId}}\
&pafid={{pafId}}\
&t=Test\
&a1=22382%20Avenida%20Empresa\
&city=Rancho%20Santa%20Margarita\
&comp=Melissa\
&ctry=US\
&full=Ray%20Melissa\
&postal=92688\
&state=CA" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

curl -X POST "https://smartmover.melissadata.net/V3/WEB/SmartMover/doSmartMover" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
       "Actions": "NCOA",
       "Columns": "",
       "CustomerID": "{{customerId}}",
       "ExecutionID": "Batch_1",
       "Format": "json",
       "JobID": "",
       "Options": "",
       "OptSmartMoverListName": "",
       "PAFId": "{{pafId}}",
       "Records":
       [{
          "AddressLine1": "22382 Avenida Empresa",
          "AddressLine2": "",
          "City": "Rancho Santa Margarita",
          "Company": "Melissa",
          "Country": "US",
          "NameFirst": "",
          "NameFull": "Ray Melissa",
          "NameLast": "",
          "NameMiddle": "",
          "NamePrefix": "",
          "NameSuffix": "",
          "Plus4": "",
          "PostalCode": "92688",
          "PrivateMailbox": "",
          "RecordID": "1",
          "State": "CA",
          "Suite": "",
          "Urbanization": ""
       }],
       "TransmissionReference": "Test"
    }'

curl -X GET "https://smartmover.melissadata.net/V3/WEB/SmartMover/doSmartMover?\
&id={{customerId}}\
&pafid={{pafId}}\
&t=Test\
&a1=22382%20Avenida%20Empresa\
&city=Rancho%20Santa%20Margarita\
&comp=Melissa\
&ctry=US\
&full=Ray%20Melissa\
&postal=92688\
&state=CA" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml"

curl -X POST "https://smartmover.melissadata.net/V3/WEB/SmartMover/doSmartMover" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml" \
-d '<Request>
       <Actions></Actions>
       <Columns></Columns>
       <CustomerID>{{customerId}}</CustomerID>
       <JobID></JobID>
       <Options></Options>
       <OptSmartMoverListName></OptSmartMoverListName>
       <PAFId>{{pafId}}</PAFId>
       <Records>
          <RequestRecord>
             <AddressLine1>22382 Avenida Empresa</AddressLine1>
             <AddressLine2></AddressLine2>
             <City>Rancho Santa Margarita</City>
             <Company></Company>
             <Country></Country>
             <NameFirst></NameFirst>
             <NameFull></NameFull>
             <NameLast></NameLast>
             <NameMiddle></NameMiddle>
             <NamePrefix></NamePrefix>
             <NameSuffix></NameSuffix>
             <Plus4></Plus4>
             <PostalCode>92688</PostalCode>
             <PrivateMailbox></PrivateMailbox>
             <RecordID></RecordID>
             <State>CA</State>
             <Suite></Suite>
             <Urbanization></Urbanization>
          </RequestRecord>
       </Records>
       <TransmissionReference>Test</TransmissionReference>
    </Request>'

Request Parameters

Minimum Inputs

The following are the possible minimum input requirements.

1. NameFirst and NameLast, NameFull, or Company

2. Address Only

3. City and State, ZIP, or AddressLastLine

• GET JSON
• POST JSON
• GET XML
• POST XML

Code	Description
Request Level Parameters
act	Selects which COA objects to be used in the request. For US Change of Address Object, use NCOA.
cols	The column names or groups to be output. See Columns for more information.
format	The desired format of the response.
id	This is a string value containing the License Key issued to the customer by Melissa Data for the web service.
jobid	This value will identify to the service which records belong to the same list for the purposes of the NCOA and CCOA report. All records from the same list should have the same JobID. This is NOT a database unique key, please use the RecordID field for that.
list	Identifies the current list. It will be included in reports returned by SmartMover V3 after processing.
opt	Set Options ListOwnerFreqProcessing NumberofMonthsRequested ProcessingType
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.
t	Optional. Serves as a unique request identifier.
Record Level Parameters
a1	A minimum address location for the name / company contact.
a2	The second address line.
city	The city name.
comp	The name of the business.
ctry	The country code. The SmartMover V3 web service can only update addresses within the United States.
first	The parsed first name of an individual.
full	The full name of an individual. Required unless parsed name inputs are used.
last	The parsed last name of an individual.
middle	The parsed middle name of an individual.
namepre	The title or honorific prefix of the name. E.g. “Mr, Miss, Dr”.
namesufix	The generational or professional suffix of the name. E.g. “Jr, IV, Ph.D.”.
plus4	The last four digits of a ZIP+4.
pmb	The private mailbox number, if this address is a box in a private mailbox service.
postal	The five-digit ZIP Code, the first five digits of a ZIP+4, or a full nine-digit ZIP+4.
state	The state name.
ste	The suite number.
u	Only used for addresses in Puerto Rico. This is used to break ties between similar addresses in the same Postal Code.

Code	Description
Request Level Parameters
Actions	Selects which COA objects to be used in the request. For US Change of Address Object, use NCOA.
Columns	The column names or groups to be output. See Columns for more information.
CustomerID	This is a string value containing the License Key issued to the customer by Melissa Data for the web service.
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.
Format	The desired format of the response.
JobID	This value will identify to the service which records belong to the same list for the purposes of the NCOA and CCOA report. All records from the same list should have the same JobID. This is NOT a database unique key, please use the RecordID field for that.
Options	Set Options ListOwnerFreqProcessing NumberofMonthsRequested ProcessingType
OptionSmartMoverListName	Identifies the current list. It will be included in reports returned by SmartMover V3 after processing.
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.
TransmissionReference	Optional. Serves as a unique request identifier.
Record Level Parameters
Addressline1	A minimum address location for the name / company contact.
Addressline2	The second address line.
City	The city name.
Company	The name of the business.
Country	The country code. The SmartMover V3 web service can only update addresses within the United States.
NameFirst	The parsed first name of an individual.
NameFull	The full name of an individual. Required unless parsed name inputs are used.
NameLast	The parsed last name of an individual.
NameMiddle	The parsed middle name of an individual.
NamePrefix	The title or honorific prefix of the name. E.g. “Mr, Miss, Dr”.
NameSuffix	The generational or professional suffix of the name. E.g. “Jr, IV, Ph.D.”.
Plus4	The last four digits of a ZIP+4.
PostalCode	The five-digit ZIP Code, the first five digits of a ZIP+4, or a full nine-digit ZIP+4.
PrivateMailbox	The private mailbox number, if this address is a box in a private mailbox service.
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.
State	The state name.
Suite	The suite number.
Urbanization	Only used for addresses in Puerto Rico. This is used to break ties between similar addresses in the same Postal Code.

Code	Description
Request Level Parameters
act	Selects which COA objects to be used in the request. For US Change of Address Object, use NCOA.
cols	The column names or groups to be output. See Columns for more information.
format	The desired format of the response.
id	This is a string value containing the License Key issued to the customer by Melissa Data for the web service.
jobid	This value will identify to the service which records belong to the same list for the purposes of the NCOA and CCOA report. All records from the same list should have the same JobID. This is NOT a database unique key, please use the RecordID field for that.
list	Identifies the current list. It will be included in reports returned by SmartMover V3 after processing.
opt	Set Options ListOwnerFreqProcessing NumberofMonthsRequested ProcessingType
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.
t	Optional. Serves as a unique request identifier.
Record Level Parameters
a1	A minimum address location for the name / company contact.
a2	The second address line.
city	The city name.
comp	The name of the business.
ctry	The country code. The SmartMover V3 web service can only update addresses within the United States.
first	The parsed first name of an individual.
full	The full name of an individual. Required unless parsed name inputs are used.
last	The parsed last name of an individual.
middle	The parsed middle name of an individual.
namepre	The title or honorific prefix of the name. E.g. “Mr, Miss, Dr”.
namesufix	The generational or professional suffix of the name. E.g. “Jr, IV, Ph.D.”.
plus4	The last four digits of a ZIP+4.
pmb	The private mailbox number, if this address is a box in a private mailbox service.
postal	The five-digit ZIP Code, the first five digits of a ZIP+4, or a full nine-digit ZIP+4.
state	The state name.
ste	The suite number.
u	Only used for addresses in Puerto Rico. This is used to break ties between similar addresses in the same Postal Code.

Code	Description
Request Level Parameters
Actions	Selects which COA objects to be used in the request. For US Change of Address Object, use NCOA.
Columns	The column names or groups to be output. See Columns for more information.
CustomerID	This is a string value containing the License Key issued to the customer by Melissa Data for the web service.
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.
Format	The desired format of the response.
JobID	This value will identify to the service which records belong to the same list for the purposes of the NCOA and CCOA report. All records from the same list should have the same JobID. This is NOT a database unique key, please use the RecordID field for that.
Options	Set Options ListOwnerFreqProcessing NumberofMonthsRequested ProcessingType
OptionSmartMoverListName	Identifies the current list. It will be included in reports returned by SmartMover V3 after processing.
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.
TransmissionReference	Optional. Serves as a unique request identifier.
Record Level Parameters
Addressline1	A minimum address location for the name / company contact.
Addressline2	The second address line.
City	The city name.
Company	The name of the business.
Country	The country code. The SmartMover V3 web service can only update addresses within the United States.
NameFirst	The parsed first name of an individual.
NameFull	The full name of an individual. Required unless parsed name inputs are used.
NameLast	The parsed last name of an individual.
NameMiddle	The parsed middle name of an individual.
NamePrefix	The title or honorific prefix of the name. E.g. “Mr, Miss, Dr”.
NameSuffix	The generational or professional suffix of the name. E.g. “Jr, IV, Ph.D.”.
Plus4	The last four digits of a ZIP+4.
PostalCode	The five-digit ZIP Code, the first five digits of a ZIP+4, or a full nine-digit ZIP+4.
PrivateMailbox	The private mailbox number, if this address is a box in a private mailbox service.
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.
State	The state name.
Suite	The suite number.
Urbanization	Only used for addresses in Puerto Rico. This is used to break ties between similar addresses in the same Postal Code.

Options

List options in the following format, with multiple options delimited with a ,.

OptionName:Parameter,OptionName:Parameter

ListOwnerFreqProcessing

This option accepts a value from 1 to 52. This is the number of times per year the current mailing list is used for mailing. E.g., for monthly use 12, for quarterly use 4.

Parameter	Description
[1 - 52]	Times per year list is used for mailing.

NumberofMonthsRequested

This option accepts a value from 6 to 48. This is the number of months back you want to search for a change of address.

Parameter	Description
[6 - 48]	Number of months back to search for address change.

ProcessingType

The processing type.

Parameter	Description
Business	Matches with businesses only. Omits individual and family matches.
Individual	Matches with individuals only. Omits business and family matches.
IndividualAndBusiness	Matches individuals and businesses only. Omits family matches.
Residential	Matches with individual and family matches. Omits business matches.
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.
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.

Headers

• GET JSON
• POST JSON
• GET XML
• POST XML

Content-Type: application/json
Accept: application/json

Content-Type: application/json
Accept: application/json

Content-Type: application/xml
Accept: */*

Content-Type: application/xml
Accept: */*

Response

• GET JSON
• POST JSON
• GET XML
• POST XML

{
   "CASSReportLink": "JobId required to generate summary report links...",
   "NCOAReportLink": "JobId required to generate summary report links...",
   "Records":
   [{
      "AddressExtras": "",
      "AddressKey": "92688211282",
      "AddressLine1": "22382 Avenida Empresa",
      "AddressLine2": "",
      "AddressTypeCode": "S",
      "BaseMelissaAddressKey": "",
      "CarrierRoute": "C057",
      "City": "Rancho Santa Margarita",
      "CityAbbreviation": "Rcho Sta Marg",
      "CompanyName": "Melissa",
      "CountryCode": "US",
      "CountryName": "United States",
      "DeliveryIndicator": "B",
      "DeliveryPointCheckDigit": "1",
      "DeliveryPointCode": "82",
      "MelissaAddressKey": "8008006245",
      "MoveEffectiveDate": "",
      "MoveTypeCode": "",
      "PostalCode": "92688-2112",
      "RecordID": "",
      "Results": "AS01,CS02",
      "State": "CA",
      "StateName": "California",
      "Urbanization": ""
   }],
   "TotalRecords": "1",
   "TransmissionReference": "Test",
   "TransmissionResults": "",
   "Version": "7.4.1.4198"
}

{
   "CASSReportLink": "JobId required to generate summary report links...",
   "NCOAReportLink": "JobId required to generate summary report links...",
   "Records":
   [{
      "AddressExtras": "",
      "AddressKey": "92688211282",
      "AddressLine1": "22382 Avenida Empresa",
      "AddressLine2": "",
      "AddressTypeCode": "S",
      "BaseMelissaAddressKey": "",
      "CarrierRoute": "C057",
      "City": "Rancho Santa Margarita",
      "CityAbbreviation": "Rcho Sta Marg",
      "CompanyName": "Melissa",
      "CountryCode": "US",
      "CountryName": "United States",
      "DeliveryIndicator": "B",
      "DeliveryPointCheckDigit": "1",
      "DeliveryPointCode": "82",
      "MelissaAddressKey": "8008006245",
      "MoveEffectiveDate": "",
      "MoveTypeCode": "",
      "PostalCode": "92688-2112",
      "RecordID": "1",
      "Results": "AS01,CS02",
      "State": "CA",
      "StateName": "California",
      "Urbanization": ""
   }],
   "TotalRecords": "1",
   "TransmissionReference": "Test",
   "TransmissionResults": "",
   "Version": "7.4.1.4198"
}

<Response xmlns="urn:mdSmartMover" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
   <CASSReportLink>JobId required to generate summary report links...</CASSReportLink>
   <NCOAReportLink>JobId required to generate summary report links...</NCOAReportLink>
   <Records>
      <ResponseRecord>
         <AddressExtras />
         <AddressKey>92688211282</AddressKey>
         <AddressLine1>22382 Avenida Empresa</AddressLine1>
         <AddressLine2 />
         <AddressTypeCode>S</AddressTypeCode>
         <BaseMelissaAddressKey />
         <CarrierRoute>C057</CarrierRoute>
         <City>Rancho Santa Margarita</City>
         <CityAbbreviation>Rcho Sta Marg</CityAbbreviation>
         <CompanyName>Melissa</CompanyName>
         <CountryCode>US</CountryCode>
         <CountryName>United States</CountryName>
         <DeliveryIndicator>B</DeliveryIndicator>
         <DeliveryPointCheckDigit>1</DeliveryPointCheckDigit>
         <DeliveryPointCode>82</DeliveryPointCode>
         <MelissaAddressKey>8008006245</MelissaAddressKey>
         <MoveEffectiveDate />
         <MoveTypeCode />
         <PostalCode>92688-2112</PostalCode>
         <RecordID />
         <Results>AS01,CS02</Results>
         <State>CA</State>
         <StateName>California</StateName>
         <Urbanization />
      </ResponseRecord>
   </Records>
   <TotalRecords>1</TotalRecords>
   <TransmissionReference>Test</TransmissionReference>
   <TransmissionResults />
   <Version>7.4.1.4198</Version>
</Response>

<Response xmlns="urn:mdSmartMover" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
   <CASSReportLink>JobId required to generate summary report links...</CASSReportLink>
   <NCOAReportLink>JobId required to generate summary report links...</NCOAReportLink>
   <Records>
      <ResponseRecord>
         <AddressExtras />
         <AddressKey>92688211282</AddressKey>
         <AddressLine1>22382 Avenida Empresa</AddressLine1>
         <AddressLine2 />
         <AddressTypeCode>S</AddressTypeCode>
         <BaseMelissaAddressKey />
         <CarrierRoute>C057</CarrierRoute>
         <City>Rancho Santa Margarita</City>
         <CityAbbreviation>Rcho Sta Marg</CityAbbreviation>
         <CompanyName />
         <CountryCode>US</CountryCode>
         <CountryName>United States</CountryName>
         <DeliveryIndicator>B</DeliveryIndicator>
         <DeliveryPointCheckDigit>1</DeliveryPointCheckDigit>
         <DeliveryPointCode>82</DeliveryPointCode>
         <MelissaAddressKey>8008006245</MelissaAddressKey>
         <MoveEffectiveDate />
         <MoveTypeCode />
         <PostalCode>92688-2112</PostalCode>
         <RecordID />
         <Results>AS01,CS02</Results>
         <State>CA</State>
         <StateName>California</StateName>
         <Urbanization />
      </ResponseRecord>
   </Records>
   <TotalRecords>1</TotalRecords>
   <TransmissionReference>Test</TransmissionReference>
   <TransmissionResults />
   <Version>7.4.1.4198</Version>
</Response>

Canada: https://smartmovercanada.melissadata.net/V3/WEB/SmartMover

• Check a move with a name and address.

• Check if the business has changed locations.

Try It Now

Note

Make sure to replace {{customerId}} with your license!

• GET JSON
• POST JSON
• GET XML
• POST XML

curl -X GET "https://smartmovercanada.melissadata.net/V3/WEB/SmartMover/doSmartMover?\
&act=\
&cols=\
&format=json\
&id={{customerId}}\
&jobid=001\
&list=\
&opt=\
&t=Test\
&a1=80%20Wellington%20St%2E\
&city=Ottawa\
&comp=\
&ctry=CA\
&full=Prime%20Minister%20of%20Canada\
&plus4=\
&postal=K1P%205K9\
&state=ON" \
-H "Content-Type: application/json" \
-H "Accept: application/json"

curl -X POST "https://smartmovercanada.melissadata.net/V3/WEB/SmartMover/doSmartMover" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
       "Actions": "",
       "Columns": "",
       "CustomerID": "{{customerId}}",
       "Format": "json",
       "JobID": "001",
       "Options": "",
       "OptSmartMoverListName": "",
       "Records":
       [{
          "AddressLine1": "80 Wellington St.",
          "City": "Ottawa",
          "Company": "",
          "Country": "CA",
          "NameFull": "Prime Minister of Canada",
          "Plus4": "",
          "PostalCode": "K1P 5K9",
          "RecordID": "1",
          "State": "ON"
       }],
       "TransmissionReference": "Test"
    }'

curl -X GET "https://smartmovercanada.melissadata.net/V3/WEB/SmartMover/doSmartMover?\
&act=\
&cols=\
&format=xml\
&id={{customerId}}\
&jobid=001\
&list=\
&opt=\
&t=Test\
&a1=80%20Wellington%20St%2E\
&city=Ottawa\
&comp=\
&ctry=CA\
&full=Prime%20Minister%20of%20Canada\
&plus4=\
&postal=K1P%205K9\
&state=ON" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml"

curl -X POST "https://smartmovercanada.melissadata.net/V3/WEB/SmartMover/doSmartMover" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml" \
-d '<Request>
       <Actions></Actions>
       <Columns></Columns>
       <CustomerID>{{customerId}}</CustomerID>
       <Format>xml</Format>
       <JobID>001</JobID>
       <Options>GrpAll</Options>
       <OptSmartMoverListName></OptSmartMoverListName>
       <Records>
          <RequestRecord>
             <AddressLine1>80 Wellington St.</AddressLine1>
             <City>Ottawa</City>
             <Company></Company>
             <Country>CA</Country>
             <NameFull>Prime Minister of Canada</NameFull>
             <Plus4></Plus4>
             <PostalCode>K1P 5K9</PostalCode>
             <RecordID>1</RecordID>
             <State>ON</State>
          </RequestRecord>
       </Records>
       <TransmissionReference>Test</TransmissionReference>
    </Request>'

Request Parameters

Minimum Inputs

The following are the possible minimum input requirements.

1. NameFirst and NameLast, NameFull, or Company

2. Address Only

3. City and State, ZIP, or AddressLastLine

• GET JSON
• POST JSON
• GET XML
• POST XML

Code	Description
Request Level Parameters
act	Selects which COA objects to be used in the request. For Canadian Change of Address Object, use CCOA.
cols	The column names or groups to be output. See Columns for more information.
format	The desired format of the response.
id	This is a string value containing the License Key issued to the customer by Melissa Data for the web service.
jobid	This value will identify to the service which records belong to the same list for the purposes of the NCOA and CCOA report. All records from the same list should have the same JobID. This is NOT a database unique key, please use the RecordID field for that.
list	Identifies the current list. It will be included in reports returned by SmartMover V3 after processing.
t	Optional. Serves as a unique request identifier.
Record Level Parameters
a1	A minimum address location for the name / company contact.
a2	The second address line.
city	The city name.
comp	The name of the business.
ctry	The country code. The SmartMover V3 web service can only update addresses within the United States.
first	The parsed first name of an individual.
full	The full name of an individual. Required unless parsed name inputs are used.
last	The parsed last name of an individual.
middle	The parsed middle name of an individual.
namepre	The title or honorific prefix of the name. E.g. “Mr, Miss, Dr”.
namesufix	The generational or professional suffix of the name. E.g. “Jr, IV, Ph.D.”.
plus4	The last four digits of a ZIP+4.
pmb	The private mailbox number, if this address is a box in a private mailbox service.
postal	The five-digit ZIP Code, the first five digits of a ZIP+4, or a full nine-digit ZIP+4.
state	The state name.
ste	The suite number.

Code	Description
Request Level Parameters
Actions	Selects which COA objects to be used in the request. For Canadian Change of Address Object, use CCOA.
Columns	The column names or groups to be output. See Columns for more information.
CustomerID	This is a string value containing the License Key issued to the customer by Melissa Data for the web service.
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.
Format	The desired format of the response.
JobID	This value will identify to the service which records belong to the same list for the purposes of the NCOA and CCOA report. All records from the same list should have the same JobID. This is NOT a database unique key, please use the RecordID field for that.
OptionSmartMoverListName	Identifies the current list. It will be included in reports returned by SmartMover V3 after processing.
TransmissionReference	Optional. Serves as a unique request identifier.
Record Level Parameters
Addressline1	A minimum address location for the name / company contact.
Addressline2	The second address line.
City	The city name.
Company	The name of the business.
Country	The country code. The SmartMover V3 web service can only update addresses within the United States.
NameFirst	The parsed first name of an individual.
NameFull	The full name of an individual. Required unless parsed name inputs are used.
NameLast	The parsed last name of an individual.
NameMiddle	The parsed middle name of an individual.
NamePrefix	The title or honorific prefix of the name. E.g. “Mr, Miss, Dr”.
NameSuffix	The generational or professional suffix of the name. E.g. “Jr, IV, Ph.D.”.
Plus4	The last four digits of a ZIP+4.
PostalCode	The five-digit ZIP Code, the first five digits of a ZIP+4, or a full nine-digit ZIP+4.
PrivateMailbox	The private mailbox number, if this address is a box in a private mailbox service.
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.
State	The state name.
Suite	The suite number.

Code	Description
Request Level Parameters
act	Selects which COA objects to be used in the request. For Canadian Change of Address Object, use CCOA.
cols	The column names or groups to be output. See Columns for more information.
format	The desired format of the response.
id	This is a string value containing the License Key issued to the customer by Melissa Data for the web service.
jobid	This value will identify to the service which records belong to the same list for the purposes of the NCOA and CCOA report. All records from the same list should have the same JobID. This is NOT a database unique key, please use the RecordID field for that.
list	Identifies the current list. It will be included in reports returned by SmartMover V3 after processing.
t	Optional. Serves as a unique request identifier.
Record Level Parameters
a1	A minimum address location for the name / company contact.
a2	The second address line.
city	The city name.
comp	The name of the business.
ctry	The country code. The SmartMover V3 web service can only update addresses within the United States.
first	The parsed first name of an individual.
full	The full name of an individual. Required unless parsed name inputs are used.
last	The parsed last name of an individual.
middle	The parsed middle name of an individual.
namepre	The title or honorific prefix of the name. E.g. “Mr, Miss, Dr”.
namesufix	The generational or professional suffix of the name. E.g. “Jr, IV, Ph.D.”.
plus4	The last four digits of a ZIP+4.
pmb	The private mailbox number, if this address is a box in a private mailbox service.
postal	The five-digit ZIP Code, the first five digits of a ZIP+4, or a full nine-digit ZIP+4.
state	The state name.
ste	The suite number.

Code	Description
Request Level Parameters
Actions	Selects which COA objects to be used in the request. For Canadian Change of Address Object, use CCOA.
Columns	The column names or groups to be output. See Columns for more information.
CustomerID	This is a string value containing the License Key issued to the customer by Melissa Data for the web service.
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.
Format	The desired format of the response.
JobID	This value will identify to the service which records belong to the same list for the purposes of the NCOA and CCOA report. All records from the same list should have the same JobID. This is NOT a database unique key, please use the RecordID field for that.
OptionSmartMoverListName	Identifies the current list. It will be included in reports returned by SmartMover V3 after processing.
TransmissionReference	Optional. Serves as a unique request identifier.
Record Level Parameters
Addressline1	A minimum address location for the name / company contact.
Addressline2	The second address line.
City	The city name.
Company	The name of the business.
Country	The country code. The SmartMover V3 web service can only update addresses within the United States.
NameFirst	The parsed first name of an individual.
NameFull	The full name of an individual. Required unless parsed name inputs are used.
NameLast	The parsed last name of an individual.
NameMiddle	The parsed middle name of an individual.
NamePrefix	The title or honorific prefix of the name. E.g. “Mr, Miss, Dr”.
NameSuffix	The generational or professional suffix of the name. E.g. “Jr, IV, Ph.D.”.
Plus4	The last four digits of a ZIP+4.
PostalCode	The five-digit ZIP Code, the first five digits of a ZIP+4, or a full nine-digit ZIP+4.
PrivateMailbox	The private mailbox number, if this address is a box in a private mailbox service.
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.
State	The state name.
Suite	The suite number.

Headers

• GET JSON
• POST JSON
• GET XML
• POST XML

Content-Type: application/json
Accept: application/json

Content-Type: application/json
Accept: application/json

Content-Type: application/xml
Accept: */*

Content-Type: application/xml
Accept: */*

Response

• GET JSON
• POST JSON
• GET XML
• POST XML

{
   "Records":
   [{
      "AddressExtras": "",
      "AddressKey": "K1A0A2",
      "AddressLine1": "80 Wellington St",
      "AddressLine2": "",
      "AddressTypeCode": "1",
      "BaseMelissaAddressKey": "",
      "CarrierRoute": "",
      "City": "Ottawa",
      "CityAbbreviation": "Ottawa",
      "CompanyName": "",
      "CountryCode": "CA",
      "CountryName": "Canada",
      "DeliveryIndicator": "",
      "DeliveryPointCheckDigit": "",
      "DeliveryPointCode": "",
      "MelissaAddressKey": "8620912446",
      "MoveEffectiveDate": "",
      "MoveTypeCode": "",
      "PostalCode": "K1A 0A2",
      "RecordID": "1",
      "Results": "AC01,AS01",
      "State": "ON",
      "StateName": "Ontario",
      "Urbanization": ""
   }],
   "TotalRecords": "1",
   "TransmissionReference": "Test",
   "TransmissionResults": "",
   "Version": "8.4.1.1130"
}

{
   "Records":
   [{
      "AddressExtras": "",
      "AddressKey": "K1A0A2",
      "AddressLine1": "80 Wellington St",
      "AddressLine2": "",
      "AddressTypeCode": "1",
      "BaseMelissaAddressKey": "",
      "CarrierRoute": "",
      "City": "Ottawa",
      "CityAbbreviation": "Ottawa",
      "CompanyName": "",
      "CountryCode": "CA",
      "CountryName": "Canada",
      "DeliveryIndicator": "",
      "DeliveryPointCheckDigit": "",
      "DeliveryPointCode": "",
      "MelissaAddressKey": "8620912446",
      "MoveEffectiveDate": "",
      "MoveTypeCode": "",
      "PostalCode": "K1A 0A2",
      "RecordID": "1",
      "Results": "AC01,AS01",
      "State": "ON",
      "StateName": "Ontario",
      "Urbanization": ""
   }],
   "TotalRecords": "1",
   "TransmissionReference": "Test",
   "TransmissionResults": "",
   "Version": "8.4.1.1130"
}

<Response xmlns="urn:mdSmartMover" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
   <Records>
      <ResponseRecord>
         <AddressExtras />
         <AddressKey>K1A0A2</AddressKey>
         <AddressLine1>80 Wellington St</AddressLine1>
         <AddressLine2 />
         <AddressTypeCode>1</AddressTypeCode>
         <BaseMelissaAddressKey />
         <CarrierRoute />
         <City>Ottawa</City>
         <CityAbbreviation>Ottawa</CityAbbreviation>
         <CompanyName />
         <CountryCode>CA</CountryCode>
         <CountryName>Canada</CountryName>
         <DeliveryIndicator />
         <DeliveryPointCheckDigit />
         <DeliveryPointCode />
         <MelissaAddressKey>8620912446</MelissaAddressKey>
         <MoveEffectiveDate />
         <MoveTypeCode />
         <PostalCode>K1A 0A2</PostalCode>
         <RecordID>1</RecordID>
         <Results>AC01,AS01</Results>
         <State>ON</State>
         <StateName>Ontario</StateName>
         <Urbanization />
      </ResponseRecord>
   </Records>
   <TotalRecords>1</TotalRecords>
   <TransmissionReference>Test</TransmissionReference>
   <TransmissionResults />
   <Version>8.4.1.1130</Version>
</Response>

<Response xmlns="urn:mdSmartMover" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
   <Records>
      <ResponseRecord>
         <AddressExtras />
         <AddressKey>K1A0A2</AddressKey>
         <AddressLine1>80 Wellington St</AddressLine1>
         <AddressLine2 />
         <AddressTypeCode>1</AddressTypeCode>
         <BaseMelissaAddressKey />
         <CarrierRoute />
         <City>Ottawa</City>
         <CityAbbreviation>Ottawa</CityAbbreviation>
         <CompanyName />
         <CountryCode>CA</CountryCode>
         <CountryName>Canada</CountryName>
         <DeliveryIndicator />
         <DeliveryPointCheckDigit />
         <DeliveryPointCode />
         <MelissaAddressKey>8620912446</MelissaAddressKey>
         <MoveEffectiveDate />
         <MoveTypeCode />
         <PostalCode>K1A 0A2</PostalCode>
         <RecordID>1</RecordID>
         <Results>AC01,AS01</Results>
         <State>ON</State>
         <StateName>Ontario</StateName>
         <Urbanization />
      </ResponseRecord>
   </Records>
   <TotalRecords>1</TotalRecords>
   <TransmissionReference>Test</TransmissionReference>
   <TransmissionResults />
   <Version>8.4.1.1130</Version>
</Response>

Columns

Entering the column name will return the column. Specifying a group name will return all columns in the group.

Delimit multiple columns with a ,.

Group Name	Included Fields
[DEFAULT] - Always return in the output structure.	AddressExtras AddressKey AddressLine1 AddressLine2 AddressTypeCode BaseMelissaAddressKey CarrierRoute CASSReportLink City CityAbbreviation CompanyName CountryCode CountryName DeliveryIndicator DeliveryPointCheckDigit DeliveryPointCode MelissaAddressKey MoveEffectiveDate MoveTypeCode NCOAReportLink PostalCode RecordID Records Results State StateName TotalRecords TransmissionReference TransmissionResults Urbanization Version
GrpName - Name Details	NameFirst NameFull NameLast NameMiddle NamePrefix NameSuffix
GrpOriginal - Original Address Details	OriginalAddressLine1 OriginalAddressLine2 OriginalCity OriginalCityAbbreviation OriginalCountryCode OriginalPlus4 OriginalPostalCode OriginalPrivateMailbox OriginalResults OriginalState OriginalStateName OriginalSuite OriginalUrbanization
GrpParsed - Parsed Address Details	AddressDeliveryInstallation AddressHouseNumber AddressLockBox AddressPostDirection AddressPreDirection AddressPrivateMailboxName AddressPrivateMailboxRange AddressRouteService AddressStreetName AddressStreetSuffix AddressSuiteName AddressSuiteNumber
GrpStandardized - Standardized Addres Details	StandardizedAddressLine1 StandardizedAddressLine2 StandardizedBaseMelissaAddressKey StandardizedCarrierRoute StandardizedCity StandardizedCityAbbreviation StandardizedCountryCode StandardizedDeliveryIndicator StandardizedDeliveryPointCheckDigit StandardizedDeliveryPointCode StandardizedMelissaAddressKey StandardizedPlus4 StandardizedPostalCode StandardizedPrivateMailbox StandardizedResults StandardizedState StandardizedStateName StandardizedSuite StandardizedUrbanization
[COLUMN NAME ONLY] - These columns can only be requested by using their name.	DPVFootNotes MoveReturnCode Plus4 PrivateMailbox Suite

Service Level Response Fields

Output Name	Description
Version	The current service version.
TransmissionReference	A pass-through of the input TransmissionReference field.
TransmissionResults	Service and General Transmission Errors
TotalRecords	Total number of records returned.
Results	The address verification results with codes for status, error, and changes.
CASSReportLink	CASS summary report link.
NCOAReportLink	NCOA summary report link.

Record Level Response Fields

[DEFAULT]

Output Name	Description
AddressExtras	Returns any text that could not be identified as belonging 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 V3 Product Codes.
BaseMelissaAddressKey	A unique key assigned to the base address of a complex with apartments or suites.
CarrierRoute	Carrier route code, with the first character being alphabetic and the following three characters being numeric. The alphabetic letter indicates the type of delivery associated with the address. For a list of codes, see SmartMover V3 Product Codes.
City	City name. If the city name is more than 28 characters long, CityAbbreviation will contain the official USPS abbreviation for the city.
CityAbbreviation	City abbreviation. If the city name is more than 28 characters long, this will contain the official USPS abbreviation for the city.
CompanyName	Name of the business.
CountryCode	The standard code of the country. Currently only Canada and the United States are supported.
CountryName	The full country name. Currently only Canada and the United States are supported.
DeliveryIndicator	The RBDI Indicator code based on the address. For a list of codes, see SmartMover V3 Product Codes.
DeliveryPointCheckDigit	Contains the 12th digit of the POSTNET barcode.
DeliveryPointCode	Contains the 10th and 11th digits of the POSTNET barcode, usually the last two digits of the street number.
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. For a list of codes, see SmartMover V3 Product Codes.
PostalCode	Postal Code.
RecordID	Position of the record in the response array.
Records	This is the returned array of records.
Results	Returns record specific result codes. For a list of codes, see SmartMover V3 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. Only used for addresses in Puerto Rico. This is used to break ties between similar addresses in the same Postal Code.

GrpName

Output Name	Description
NameFirst	Returns the first name as submitted to the NameFirst field in the request.
NameFull	Returns the full name as submitted to the NameFull field in the request.
NameLast	Returns the last name as submitted to the NameLast field in the request.
NameMiddle	Returns the middle name as submitted to the NameMiddle field in the request.
NamePrefix	Returns the name prefix as submitted to the NamePrefix field in the request.
NameSuffix	Returns the name suffix as submitted to the NameSuffix field in the request.

GrpOriginal

Output Name	Description
OriginalAddressLine1	Returns the original address line 1 exactly as submitted in the request.
OriginalAddressLine2	Returns the original address line 2 exactly as submitted in the request.
OriginalCity	Returns the original city exactly as submitted in the request.
OriginalCityAbbreviation	Returns the original country abbreviation exactly as submitted in the request.
OriginalCountryCode	Returns the original country code exactly as submitted in the request.
OriginalPlus4	Returns the original Plus + 4 exactly as submitted in the request.
OriginalPostalCode	Returns the original postal code exactly as submitted in the request.
OriginalPrivateMailbox	Returns the original private mailbox exactly as submitted in the request.
OriginalResults	Returns the original results exactly as submitted in the request.
OriginalState	Returns the original state exactly as submitted in the request.
OriginalStateName	Returns the original state name exactly as submitted in the request.
OriginalSuite	Returns the original suite exactly as submitted in the request.
OriginalUrbanization	Returns the original urbanization exactly as submitted in the request.

GrpParsed

Output Name	Description
AddressDeliveryInstallation	Canada Only. Returns the parsed delivery installation of the address.
AddressHouseNumber	Returns the parsed numeric portion of the street address.
AddressLockBox	Returns the parsed lockbox.
AddressPostDirection	Returns the parsed directional abbreviation that comes after the street name. For example, “Park Ave South” would return “S”.
AddressPreDirection	Returns the parsed directional abbreviation that comes before the street name. For example, “100 North Main Street” would return “N”.
AddressPrivateMailboxName	Returns the parsed non-numeric portion of a private mailbox number. Either “#” or “PMB”.
AddressPrivateMailboxRange	Returns the parsed numeric portion of an address if it is located at a Commercial Mail Receiving Agency (CMRA).
AddressRouteService	Returns the parsed route service.
AddressStreetName	Returns the parsed name portion of the street address. This excludes the street number, suffix, and any directionals.
AddressStreetSuffix	Returns the parsed street suffix. E.g. “Rd”, “St”, or “Blvd”.
AddressSuiteName	Returns the parsed standardized text from the suite. E.g. “STE” or “Unit”.
AddressSuiteNumber	Returns the parsed numeric portion of the suite.

GrpStandardized

Output Name	Description
StandardizedAddressLine1	Returns the standardized address line 1 using USPS addressing standards.
StandardizedAddressLine2	Returns the standardized address line 2 using USPS addressing standards.
StandardizedBaseMelissaAddressKey	Returns the Base Melissa Address Key of the standardized address.
StandardizedCarrierRoute	Returns the standardized carrier route using USPS addressing standards.
StandardizedCity	Returns the standardized city using USPS addressing standards.
StandardizedCityAbbreviation	Returns the standardized city abbreviation using USPS addressing standards.
StandardizedCountryCode	Returns the standardized country code using USPS addressing standards.
StandardizedDeliveryIndicator	Returns the standardized delivery indicatior using USPS addressing standards.
StandardizedDeliveryPointCheckDigit	Returns the standardized delivery point check digit using USPS addressing standards.
StandardizedDeliveryPointCode	Returns the standardized delivery point code using USPS addressing standards.
StandardizedMelissaAddressKey	Returns the Melissa Address Key of the standardized address.
StandardizedPlus4	Returns the standardized Plus + 4 using USPS addressing standards.
StandardizedPostalCode	Returns the standardized postal code using USPS addressing standards.
StandardizedPrivateMailbox	Returns the standardized private mailbox using USPS addressing standards.
StandardizedResults	Returns the results of the standardized address.
StandardizedState	Returns the standardized state using USPS addressing standards.
StandardizedStateName	Returns the standardized state name using USPS addressing standards.
StandardizedSuite	Returns the standardized suite using USPS addressing standards.
StandardizedUrbanization	Returns the standardized urbanization using USPS addressing standards.

[COLUMN NAME ONLY]

These columns can only be requested by using their name.

Output Name	Description
DPVFootNotes	Indicates the level of matching between the current address and the USPS’s DPV database. This footnote may be up to six characters long. For a list of codes, see SmartMover V3 Product Codes.
MoveReturnCode	Code indicating the level of matching between the record and the NCOA Link database. For a list of codes, see Record Level Product Codes.
Plus4	The last four digits of the ZIP + 4.
PrivateMailbox	If the address is a private mailbox serivce the number will be returned here.
Suite	Address suite.

Result Codes

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 the full list of all possible result codes, please visit here.

Understanding the Code

To fully understand result codes, you need to know them. Knowing what codes are possible and what they indicate will be key in building an effective application. It is useful to know all the codes, but this does not necessarily mean you will use them all. Just because you have a toolbox, doesn’t mean you will also try to use a screwdriver along with a hammer on a nail.

SmartMover Result Codes