Skip to content
SmartMover US/
/
Check change of addresses

SmartMover US

Overview

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 API is able to validate and standardize addresses, detect moves, and provide an updated address for an individual or business. SmartMover is available for the US using data from USPS.

You can use SmartMover US to:

  • Keep contact addresses from the US up to date.
  • Standardize and validate addresses.

SmartMover is also available for Canada.

Documentation

Useful Resources

Product Page

https://www.melissa.com/ncoalink-processing

Support Center

https://www.melissa.com/company/product-support

Download OpenAPI description
smartmover-us.json
smartmover-us.yaml
Languages
Servers
National Change of Address (NCOA)
https://smartmover.melissadata.net/V3/WEB/SmartMover/

Change of Address Detection

Use this endpoint to check a move with a name and address, or check if a business has changed locations.

Operations

Check a move

Request

Uses HTTPS GET to accept one input record and returns the response in JSON format.

The following are the possible minimum input requirements:

  1. First and Last Name, Full Name, or Company

  2. Address Only

  3. City and State, ZIP Code, or AddressLastLine

Query
actstring

Selects which COA objects to be used in the request. For US Change of Address Object, use NCOA.

colsstring

Columns - The column names or groups to be output.

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

Delimit multiple columns with a ,.

For example: ColumnName,ColumnName.

Columns:

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 Address 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
formatstring

The desired format of the response.

Enum"json""xml"
Example: format=json
idany(password)required

Required. The License Key issued by Melissa.

Example: id={REPLACE-WITH-YOUR-LICENSE-KEY}
jobidstring

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.

liststring

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

optstring

Options - Specify which options to use for the selected action. List of options in <OptionName>:<Parameter> format. Multiple options are delimited with a ,.

For example: OptionName:Parameter,OptionName:Parameter.

  • ListOwnerFreqProcessing:< [1 - 52] > - 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.
  • ProcessingType:< Business | Individual | IndividualAndBusiness | Residential | Standard > - The processing type.
pafidstring

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.

tstring

Transmission Reference - Optional. Serves as a unique identifier for this set of records.

Example: t=Test
a1stringrequired

A minimum address location for the name / company contact.

Example: a1=22382 Avenida Empresa
a2string

The second address line.

citystringrequired

The city name.

Example: city=Rancho Santa Margarita
compstringrequired

The name of the business.

Example: comp=Melissa
ctrystring

The country code. SmartMover US can only update addresses within the United States.

Example: ctry=US
firststring

The parsed first name of an individual.

fullstringrequired

The full name of an individual. Required unless parsed name inputs are used.

Example: full=Ray Melissa
laststring

The parsed last name of an individual.

middlestring

The parsed middle name of an individual.

nameprestring

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

namesuffixstring

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

plus4string

The last four digits of a ZIP+4.

pmbstring

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

postalstringrequired

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

Example: postal=92688
statestringrequired

The state name.

Example: state=CA
stestring

The suite number.

ustring

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

curl -i -X GET \
  'https://smartmover.melissadata.net/V3/WEB/SmartMover/doSmartMover?id={REPLACE-WITH-YOUR-LICENSE-KEY}&a1=22382+Avenida+Empresa&city=Rancho+Santa+Margarita&comp=Melissa&full=Ray+Melissa&postal=92688&state=CA'

Responses

Successful response

Body
Versionstring

The current service version number.

TransmissionReferencestring

A pass-through of the input TransmissionReference field.

TransmissionResultsstring

Lists error codes from any errors caused by the most recent request as a whole. For more information, see SmartMover Result Codes.

TotalRecordsstring

Total number of records.

CASSReportLinkstring

CASS summary report link.

NCOAReportLinkstring

NCOA summary report link.

RecordsArray of objects(ResponseRecord)

This is the returned array of records.

Response
{
  "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"
}

Check change of addresses

Request

An HTTPS POST is issued with the "ContentType" header specifying the format of the request and the "Accept" header specifying the format of the response.

Body
required
Actionsstring

Selects which COA objects to be used in the request. For US Change of Address Object, use NCOA.

Columnsstring

Columns - The column names or groups to be output.

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

Delimit multiple columns with a ,.

For example: ColumnName,ColumnName.

Columns:

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 Address 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
CustomerIDstringrequired

The License Key issued by Melissa.

ExecutionIDstring

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.

Formatstring

The desired format of the response.

Enum"json""xml"
JobIDstring

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.

Optionsstring

Options - Specify which options to use for the selected action. List of options in <OptionName>:<Parameter> format. Multiple options are delimited with a ,.

For example: OptionName:Parameter,OptionName:Parameter.

  • ListOwnerFreqProcessing:< [1 - 52] > - 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.
  • ProcessingType:< Business | Individual | IndividualAndBusiness | Residential | Standard > - The processing type.
OptionSmartMoverListNamestring

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

PAFIdstring

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.

TransmissionReferencestring

Serves as a unique identifier for this set of records. This allows you to match a response to a request.

RecordsArray of objects(RequestRecord)[ 1 .. 100 ] items
curl -i -X POST \
  https://smartmover.melissadata.net/V3/WEB/SmartMover/doSmartMover \
  -H 'Content-Type: application/json' \
  -d '{
    "Actions": "NCOA",
    "Columns": "",
    "CustomerID": "{REPLACE-WITH-YOUR-LICENSE-KEY}",
    "ExecutionID": "Batch_1",
    "Format": "json",
    "JobID": "",
    "Options": "",
    "OptionSmartMoverListName": "",
    "PAFId": "",
    "TransmissionReference": "Test",
    "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": ""
      }
    ]
  }'

Responses

Successful response

Body
Versionstring

The current service version number.

TransmissionReferencestring

A pass-through of the input TransmissionReference field.

TransmissionResultsstring

Lists error codes from any errors caused by the most recent request as a whole. For more information, see SmartMover Result Codes.

TotalRecordsstring

Total number of records.

CASSReportLinkstring

CASS summary report link.

NCOAReportLinkstring

NCOA summary report link.

RecordsArray of objects(ResponseRecord)

This is the returned array of records.

Response
{
  "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"
}