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.

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
Callback		callback	Callback
Record ID	Record		RecordID
Company Name		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 Mail Box		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

Optional.

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

Optional.

A unique string of characters used to identify a group of records submitted with this request.

This is also used to retrieve summary reports returned by SmartMover V3.

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

PAF ID

Optional.

Identifies the individual list owner when the request is submitted froma broker account.

This is required for any License Key issued to a broker account. Not applicable to CCOA.

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

Execution ID

Optional.

Identifies the thread you are processing under when using multiple threads. This allows the system to track individual threads if a request times out.

If you send the same request with the same Execution ID immediately after a request times out, the system will process the second request but will not count it against the total number of records in the NCOA and CASS reports. The default value is 0 if not set.

Protocol	Syntax
JSON	"ExecutionID":"string"

Actions

Optional.

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
AddressExtras	[Default] These columns are returned by default.
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
MoveReturnCode
Plus4
PrivateMailBox
Suite

Options

Optional.

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

Optional.

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

Optional.

The desired format of the response.

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

Callback

Optional.

Protocol	Syntax
JSON	"Callback":"string"
REST	&callback = 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"
REST	&rec = string

Company Name

Optional.

The name of the business.

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

Address Line 1

Optional.

The first address line of the business.

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

Address Line 2

Optional.

The second address line of the business.

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

Address Line 3

Optional.

The third address line of the business.

Protocol	Syntax
JSON	"AddressLine3":"string"
REST	&a3 = string

Address Line 4

Optional.

The fourth address line of the business.

Protocol	Syntax
JSON	"AddressLine4":"string"
REST	&a4 = string

Locality

Optional.

The most common population center data element.

Protocol	Syntax
JSON	"Locality":"string"
REST	&loc = string

Dependent Locality

Optional.

The smaller population center data element. This depends on the Locality element.

Protocol	Syntax
JSON	"DependentLocality":"string"
REST	&dloc = string

Double Dependent Locality

Optional.

The smallest population center data element. This depends on the Locality and DependentLocality elements.

Protocol	Syntax
JSON	"DoubleDependentLocality":"string"
REST	&ddloc = string

Sub Administrative Area

Optional.

The smallest geographic data element.

Protocol	Syntax
JSON	"SubAdministrativeArea":"string"
REST	&sarea = string

Administrative Area

Optional.

The most common geographic data element.

Protocol	Syntax
JSON	"AdministrativeArea":"string"
REST	&area = string

Sub National Area

Optional.

The administrative region within a country on an arbitrary level below that of the sovereign state.

Protocol	Syntax
JSON	"SubNationalArea":"string"
REST	&subnat = string

Postal Code

Optional.

The complete postal code for a particular delivery point.

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

Country

Optional.

The country name, abbreviation, or code.

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

Melissa Address Key (MAK)

Optional.

A propietary unique key identifier for an address. This is derived from Address Checking.

Protocol	Syntax
JSON	"MelissaAddressKey":"string"
REST	&mak = string