SmartMover V3:Request

← SmartMover

A request consists of a protocol to make a call to the service, detailing desired elements. Your License Key is required.

SmartMover V3 supports the JSON and REST protocols to access the service.

URL

NCOA

Use	URL
SOAP	https://smartmover.melissadata.net/V3/SOAP/SmartMover
WEB/REST	https://smartmover.melissadata.net/V3/WEB/SmartMover/doSmartMover

CCOA

Use	URL
SOAP	https://smartmovercanada.melissadata.net/V3/SOAP/SmartMover
WEB/REST	https://smartmovercanada.melissadata.net/V3/WEB/SmartMover/doSmartMover

Field Names

This is a list of the request field names and their protocol naming conventions.

Field Name	Level	REST	JSON
Transmission Reference	Request	t	TransmissionReference
License Key		id	CustomerID
Job ID		jobid	JobID
PAF ID		pafid	PAFId
Execution ID			ExecutionID
Actions		act	Actions
Columns		cols	Columns
Options		opt	Options
List Name		list	OptSmartMoverListName
Format		format	Format
Record ID	Record		RecordID
Company		comp	Company
Full Name		full	NameFull
First Name		first	NameFirst
Middle Name		middle	NameMiddle
Name Prefix		namepre	NamePrefix
Name Suffix		namesfx	NameSuffix
Last Name		last	NameLast
Urbanization		u	Urbanization
Address Line 1		a1	AddressLine1
Address Line 2		a2	AddressLine2
Suite		ste	Suite
Private Mailbox		pmb	PrivateMailbox
City		city	City
State		state	State
Postal Code		postal	PostalCode
Plus 4		plus4	Plus4
Country		ctry	Country

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

Request Elements

The following elements set the basic options for each request. These apply to the entire request, not the individual records.

Transmission Reference

This is a string value that serves as a unique identifier for this set of records. It is returned as sent.

Protocol	Syntax
JSON	"TransmissionReference":"string"
REST	?t = string

License Key

Required.

This is a string value containing the License Key issued to the customer by Melissa for SmartMover V3.

If this element is absent, the Web Service will return an error. To receive a License Key, please contact your Melissa sales representative at 1-800-MELISSA.

Protocol	Syntax
JSON	"CustomerID":"string"
REST	&id = string

Job ID

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.

Protocol	Syntax
JSON	"JobID":"string"
REST	&jobid = string

PAF ID

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.

Protocol	Syntax
JSON	"PAFId":"string"
REST	&pafid = string

Execution ID

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.

Protocol	Syntax
JSON	"ExecutionID":"string"

Actions

Selects which COA objects to be used in the request.

Protocol	Syntax
JSON	"Actions":"string"
REST	&act = string

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

Syntax
ActionName,ActionName

NCOA

US Change of Address Object

Action Name	Parameter
NCOA	NCOA

CCOA

Canadian Change of Address Object

Action Name	Parameter
CCOA	CCOA

Columns

Optional.

This string value specifies which column(s) to be output as a comma delimited string.

Protocol	Syntax
JSON	"Columns":"string"
REST	&cols = string

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

List multiple actions in the following format, with multiple actions delimited with a ",".

Syntax
ColumnName,ColumnName,ColumnName

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

Options

This is a string value containing the options set by the user.

Not applicable to CCOA.

Protocol	Syntax
JSON	"Options":"string"
REST	&opt = string

List multiple options in the following format, with multiple options delimited with a "," and a ":" to separate the option from its value.

Syntax
OptionName:Parameter,OptionName:Parameter

ProcessingType

The processing type.

Option Name	Parameter	Description
ProcessingType	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

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.

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

NumberofMonthsRequested

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

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

OptSmartMoverListName

Identifies the current list. It will be included in reports returned by SmartMover V3 after processing.

Protocol	Syntax
JSON	"OptSmartMoverListName":"string"
REST	&list = string

Format

The desired format of the response.

Protocol	Syntax
JSON	"Format":"string"
REST	&format = string

Request Record Elements

REST will only contain the Records element.

Protocol	Definition
JSON	Each record will be contained within [{}] under the Records element.
REST	The REST interface only allows a single record per request.

Record ID

Optional.

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.

Protocol	Syntax
JSON	"RecordID":"string"

Company

The name of the business.

Protocol	Syntax
JSON	"Company":"string"
REST	&comp = string

Full Name

The full name of an individual.

Protocol	Syntax
JSON	"NameFull":"string"
REST	&full = string

First Name

The first name of an individual.

Protocol	Syntax
JSON	"NameFirst":"string"
REST	&first = string

Middle Name

The middle name of an individual.

Protocol	Syntax
JSON	"NameMiddle":"string"
REST	&middle = string

Name Prefix

The title or honorific prefix of the name. E.g. "Mr, Miss, Dr".

Protocol	Syntax
JSON	"NamePrefix":"string"
REST	&namepre = string

Name Suffix

The generational or professional suffix of the name. E.g. "Jr, IV, Ph.D.".

Protocol	Syntax
JSON	"NameSuffix":"string"
REST	&namesfx = string

Last Name

The last name of the individual.

Protocol	Syntax
JSON	"NameLast":"string"
REST	&last = string

Urbanization

Only used for addresses in Puerto Rico. This is used to break ties between similar addresses in the same Postal Code.

Protocol	Syntax
JSON	"Urbanization":"string"
REST	&u = string

Address Line 1

The first address line.

Protocol	Syntax
JSON	"AddressLine1":"string"
REST	&a1 = string

Address Line 2

The second address line.

Protocol	Syntax
JSON	"AddressLine2":"string"
REST	&a2 = string

Suite

The suite number.

Protocol	Syntax
JSON	"Suite":"string"
REST	&ste = string

Private Mailbox

The private mailbox number, if this address is a box in a private mailbox service.

Protocol	Syntax
JSON	"PrivateMailbox":"string"
REST	&pmb = string

City

The city name.

Protocol	Syntax
JSON	"City":"string"
REST	&city = string

State

The state name.

Protocol	Syntax
JSON	"State":"string"
REST	&state = string

Postal Code

The five-digit ZIP Code, the first five digits of a ZIP+4, or a full nine-digit ZIP+4.

Protocol	Syntax
JSON	"PostalCode":"string"
REST	&postal = string

Plus 4

Optional.

The last four digits of a ZIP+4.

Protocol	Syntax
JSON	"Plus4":"string"
REST	&plus4 = string

Country

The country code. The SmartMover V3 web service can only update addresses within the United States.

Protocol	Syntax
JSON	"Country":"string"
REST	&ctry = string