SmartMover V3:Request: Difference between revisions

From Melissa Data Wiki
Jump to navigation Jump to search
← Older edit
No edit summary
No edit summary
 
(3 intermediate revisions by the same user not shown)
Line 9: Line 9:


SmartMover V3 supports the JSON and REST protocols to access the service.
SmartMover V3 supports the JSON and REST protocols to access the service.
==URL==
{{URL-SmartMoverV3}}




Line 23: Line 27:
|Job ID||jobid||JobID
|Job ID||jobid||JobID
|-
|-
|PAF ID||pafid||PAFID
|PAF ID||pafid||PAFId
|-
|-
|Execution ID|| ||ExecutionID
|Execution ID|| ||ExecutionID
Line 87: Line 91:


<h3 style="background-color:rgb(240,240,240);">Transmission Reference</h3>
<h3 style="background-color:rgb(240,240,240);">Transmission Reference</h3>
:''Optional.''


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


<h3 style="background-color:rgb(240,240,240);">Job ID</h3>
<h3 style="background-color:rgb(240,240,240);">Job ID</h3>
:''Optional.''
: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.
 
: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.


:{| class="alternate01"
:{| class="alternate01"
Line 133: Line 132:


<h3 style="background-color:rgb(240,240,240);">PAF ID</h3>
<h3 style="background-color:rgb(240,240,240);">PAF ID</h3>
:''Optional.''
:''Only applies for Broker accounts and not to CCOA.''


:Identifies the individual list owner when the request is submitted froma broker account.
:For Smartmover Brokers with their own set of end users, use the PAF ID to identify which end user this record belongs to.
 
:This is required for any License Key issued to a broker account. Not applicable to CCOA.


:{| class="alternate01"
:{| class="alternate01"
!Protocol !! Syntax
!Protocol !! Syntax
|-
|-
|JSON||<code>"PAFID":"'''''string'''''"</code>
|JSON||<code>"PAFId":"'''''string'''''"</code>
|-
|-
|REST||<code>&pafid = '''''string'''''</code>
|REST||<code>&pafid = '''''string'''''</code>
Line 149: Line 146:


<h3 style="background-color:rgb(240,240,240);">Execution ID</h3>
<h3 style="background-color:rgb(240,240,240);">Execution ID</h3>
:''Optional.''
: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.
 
: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 <code>0</code> if not set.
:Default value is <code>0</code> if not set.


:{| class="alternate01"
:{| class="alternate01"
Line 163: Line 158:


<h3 style="background-color:rgb(240,240,240);">Actions</h3>
<h3 style="background-color:rgb(240,240,240);">Actions</h3>
:''Optional.''


:Selects which COA objects to be used in the request.
:Selects which COA objects to be used in the request.
Line 410: Line 404:


<h3 style="background-color:rgb(240,240,240);">Options</h3>
<h3 style="background-color:rgb(240,240,240);">Options</h3>
:''Optional.''


:This is a string value containing the options set by the user.
:This is a string value containing the options set by the user.
Line 476: Line 469:


<h3 style="background-color:rgb(240,240,240);">OptSmartMoverListName</h3>
<h3 style="background-color:rgb(240,240,240);">OptSmartMoverListName</h3>
:''Optional.''


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


<h3 style="background-color:rgb(240,240,240);">Format</h3>
<h3 style="background-color:rgb(240,240,240);">Format</h3>
:''Optional.''


:The desired format of the response.
:The desired format of the response.
Line 528: Line 519:


<h3 style="background-color:rgb(240,240,240);">Company</h3>
<h3 style="background-color:rgb(240,240,240);">Company</h3>
:''Optional.''


:The name of the business.
:The name of the business.
Line 542: Line 532:


<h3 style="background-color:rgb(240,240,240);">Full Name</h3>
<h3 style="background-color:rgb(240,240,240);">Full Name</h3>
:''Optional.''


:The full name of an individual.
:The full name of an individual.
Line 556: Line 545:


<h3 style="background-color:rgb(240,240,240);">First Name</h3>
<h3 style="background-color:rgb(240,240,240);">First Name</h3>
:''Optional.''


:The first name of an individual.
:The first name of an individual.
Line 570: Line 558:


<h3 style="background-color:rgb(240,240,240);">Middle Name</h3>
<h3 style="background-color:rgb(240,240,240);">Middle Name</h3>
:''Optional.''


:The middle name of an individual.
:The middle name of an individual.
Line 584: Line 571:


<h3 style="background-color:rgb(240,240,240);">Name Prefix</h3>
<h3 style="background-color:rgb(240,240,240);">Name Prefix</h3>
:''Optional.''


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


<h3 style="background-color:rgb(240,240,240);">Name Suffix</h3>
<h3 style="background-color:rgb(240,240,240);">Name Suffix</h3>
:''Optional.''


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


<h3 style="background-color:rgb(240,240,240);">Last Name</h3>
<h3 style="background-color:rgb(240,240,240);">Last Name</h3>
:''Optional.''


:The last name of the individual.
:The last name of the individual.
Line 626: Line 610:


<h3 style="background-color:rgb(240,240,240);">Urbanization</h3>
<h3 style="background-color:rgb(240,240,240);">Urbanization</h3>
:''Optional.''


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


<h3 style="background-color:rgb(240,240,240);">Address Line 1</h3>
<h3 style="background-color:rgb(240,240,240);">Address Line 1</h3>
:''Optional.''


:The first address line.
:The first address line.
Line 654: Line 636:


<h3 style="background-color:rgb(240,240,240);">Address Line 2</h3>
<h3 style="background-color:rgb(240,240,240);">Address Line 2</h3>
:''Optional.''


:The second address line.
:The second address line.
Line 668: Line 649:


<h3 style="background-color:rgb(240,240,240);">Suite</h3>
<h3 style="background-color:rgb(240,240,240);">Suite</h3>
:''Optional.''


:The suite number.
:The suite number.
Line 682: Line 662:


<h3 style="background-color:rgb(240,240,240);">Private Mailbox</h3>
<h3 style="background-color:rgb(240,240,240);">Private Mailbox</h3>
:''Optional.''


:The private mailbox number, if this address is a box in a private mailbox service.
:The private mailbox number, if this address is a box in a private mailbox service.
Line 696: Line 675:


<h3 style="background-color:rgb(240,240,240);">City</h3>
<h3 style="background-color:rgb(240,240,240);">City</h3>
:''Optional.''


:The city name.
:The city name.
Line 710: Line 688:


<h3 style="background-color:rgb(240,240,240);">State</h3>
<h3 style="background-color:rgb(240,240,240);">State</h3>
:''Optional.''


:The state name.
:The state name.
Line 724: Line 701:


<h3 style="background-color:rgb(240,240,240);">Postal Code</h3>
<h3 style="background-color:rgb(240,240,240);">Postal Code</h3>
:''Optional.''


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


<h3 style="background-color:rgb(240,240,240);">Country</h3>
<h3 style="background-color:rgb(240,240,240);">Country</h3>
:''Optional.''


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

Latest revision as of 00:58, 23 November 2021

← SmartMover

SmartMover Navigation
Introduction
Licensing
Transitioning From V2b
Input/Output
Request Fields
Response Fields
Examples
REST JSON
JSON
XML
Result Codes
Result Code Use
SmartMover Result Codes
Sample Code



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
Retrieved from "http://wiki.melissadata.com/index.php?title=SmartMover_V3:Request&oldid=18266"