MatchUp Web Service:Introduction

From Melissa Data Wiki
Jump to navigation Jump to search

← MatchUp Web Service

MatchUp Web Service Navigation
Introduction
Licensing
Input/Output
GetMatchcodeList
CreateJob
SubmitRecords
SubmitJob
GetJobStatus
RetrieveRecords
Examples
REST JSON
Batch JSON
Result Codes
Result Code Use
MatchUp Web Service Result Codes
Sample Code



Welcome to the Melissa Data MatchUp Web Service. The MatchUp Web Service is used to match user records according to a user-specified matchcode. This web service is different from most of the other Melissa Data Web Services in that it is batch-oriented. This means that a single request record is not returned with response data about that record independent of other record requests. A user submits a series of records, tells the web service to start processing, and then retrieves the records. The service response for each record will indicate whether it matched any other records in the submitted job.

The MatchUp Web Service does not currently have Global Matching capability. In other words, only domestic US/CAN matchcodes are available. See GetMatchcodeList for available Matchcodes.

You can use MatchUp to:

  • Indicate if a record is unique or matches any other records in a submitted record set.
  • Create a unique group identifier used to group and query all records that matched each other
  • Count number of records in each matched group
  • Using these output properties not only indicates the status of a single record, but by aggregating them, can be used to clean or evaluate the status of an entire database.


Basic Usage

Order of Operations

Unlike our other single request Web Service Solutions, to have MatchUp Web Service process your database requires a series of requests and responses.

  1. GetMatchcodeList
  2. CreateJob
  3. SubmitRecords
  4. SubmitJob
  5. GetJobStatus
  6. RetrieveRecords

The developer should evaluate the response of the submitted request before proceeding to the next required request.

GetMatchcodeList

Retrieves a list of available matchcodes and their descriptions. Although this request is optional, it is good practice to select a matchcode from the response of available matchcodes to ensure a CreateJob request will not return an error. The GetMatchcodeList response will also return the description of the matchcode and the combination of input Field datatypes necessary to process your database.

CreateJob

Creates a new deduplication job. A response which does not not return an error code indicates that you can start submitting records to your job.

SubmitRecords

Submit a subset of records for processing. This request is called as many times as needed to pass Arrays of records to the service for processing. Each request requires the dataframe property to be uniquely set, so when the output is retrieved, the records can be identified. The number of dataframes submitted should equal the number of dataframes returned.

While GetMatchcodeList will give a list of required Input Fields required for successful matching, MatchUp can still accurately match records if each record submitted contains... a FullName or parsed Last / First names for matchcodes evaluating a name at least 1, but up to 3 Address Lines for matchcodes evaluating an address a Zip code or a City & State pair for matchcodes evaluating an address.

SubmitJob

Submit a job for processing. Using this request lets the service know that you are done adding records to our servers for this job and you are now ready to begin processing.

GetJobStatus

Query a submitted job's status. Although this request is non-essential, it is recommended that this request always be called. Depending on the size of your submitted database, evaluating this request lets you know when it is OK to proceed with retrieving records, or if the job was terminated.

RetrieveRecords

Retrieve processing results. When GetJobStatus returns a Result Code informing you that the job is done and can begin retrieving records. The user must then send a Retrieve Results request for each data frame that was successfully submitted.


Matchcode Information

The following are the current list of available matchcodes when using the MatchUp service. For each respective matchcode, each numbered rule represents a combination of input datatypes which will be evaluated in determining whether two records match or not.

The numbered rules correlate to the following result codes:

  1. MS06
  2. MS07
  3. MS08
  4. MS09

Each combination of rules is evaluated simultaneously, even if the first condition returns a match. This allows MatchUp to internally group dissimilar records which have different data pieces.

For example
John Smith, 12 Main St, john@mydomain.com
John Smith 781-332-8888
john@mydomain.com, 781-332-8888

Address

Match the address via zip, street number and street name and/or PO Box. This is a basic "Householding" matchcode.

  1. Zip5 AND Street Number AND Street Name AND Secondary
  2. Zip5 AND PO Box

Address, Last Name

Match records via Last Name and Address. This is a basic "family" level matchcode.

  1. Zip5 AND Last Name AND Street Number AND Street Name AND Secondary
  2. Zip5 AND Last Name AND PO Box

Address, Last Name, First Name

Match records via First Name, Last Name and Address. This is a basic "individual" (or customer) level matchcode.

  1. Zip5 AND First Name AND Last Name AND Street Number AND Street Name AND Secondary
  2. Zip5 AND First Name AND Last Name AND PO Box

Address, Company

Match records Company and Address. This is a basic "Business" matchcode.

  1. Zip5 AND Company AND Street Number AND Street Name AND Secondary
  2. Zip5 AND Company AND PO Box

Address, Company AND Last Name, First Name

Match records via Company, First Name, Last Name and Address. This is a basic "employee" level matchcode.

  1. Zip5 AND Last Name AND First Name AND Company AND Street Number AND Street Name AND Secondary
  2. Zip5 AND Last Name AND First Name AND Company AND PO Box

Address, Company OR Last Name, First Name

Match records via Company and Address, or Last Name, First Name and Address. This matchcode is used when there is a mix of business and individual records.

  1. Zip5 AND Last Name AND First Name AND Street Number AND Street Name AND Secondary
  2. Zip5 AND Last Name AND First Name AND PO Box
  3. Zip5 AND Company AND Street Number AND Street Name AND Secondary
  4. Zip5 AND Company AND PO Box

Address, Fuzzy Last Name, Fuzzy First Name

Match records via First Name, Last Name and Address. This is a basic "individual" (or customer) with errors level matchcode.

  1. Zip5 AND First Name AND Last Name AND Street Number AND Street Name AND Secondary
  2. Zip5 AND First Name AND Last Name AND PO Box
  3. Zip5 AND First Nickname AND Last Name AND Street Number AND Street Name AND Secondary
  4. Zip5 AND First Nickname AND Last Name AND PO Box

Name AND Address OR Phone OR E-mail

Match records via First Name, Last Name and Address, or by phone, or by email. This is a "match by contact piece" level matchcode.

  1. Zip5 AND First Name AND Last Name AND Street Number AND Street Name AND Secondary
  2. Zip5 AND First Name AND Last Name AND PO Box
  3. Phone/Fax
  4. E-Mail Address

Phone OR E-mail

This is a basic "communication piece" matchcode.

  1. Phone/Fax
  2. E-Mail Address