Reference Guide

Introduction

The Melissa Contribution cloud service allows you to submit corrections for data in Melissa products.

This includes:

• Specify problem GeoPoints using Melissa Address Keys (MAKs).

• Submit latitude and longitude corrections.

• Provide an email for correction notifications.

• Submit additional comments about the problem MAK.

Base URL

http://contribution.melissadata.net

Licensing

The License Key is a software key required to use the web service. You will receive your license key from your Melissa representative. If you don’t have a license key, contact the Melissa sales team by Requesting a Demo or by calling 800-MELISSA ext. 3 (800-635-4772 ext. 3). Without a license key, Global IP will not function.

To set the license key, use the id/CustomerID property in your requests.

Endpoints

/V4/WEB/addMAK

Use this endpoint to submit a request to add a new Melissa Address Key (MAK).

Try it Now

Note

Make sure to replace {{customerId}} with your license key.

Get it here!

• GET JSON
• POST JSON

curl -X GET "https://contribution.melissadata.net/V4/WEB/addMAK?\
&id={{customerId}}\
&t=Test\
&a1=22382%20Avenida%20Empresa\
&a2=\
&city=Ranch%20Santa%20Margarita\
&ctry=US\
&lat=33%2E637562\
&long=-117%2E606887\
&postal=92688\
&reason=Add%20a%20MAK\
&respondto=youremail%40melissadata%2Ecom\
&state=CA\
&ste=" \
-H "Content-Type:application/json" \
-H "Accept:application/json"

curl -X POST "https://contribution.melissadata.net/V4/WEB/addMAK" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
    "CustomerID": {{customerId}},
    "TransmissionReference": "Test",
    "AddressLine1": "22382 Avenida Empresa",
    "AddressLine2": "",
    "City": "Rancho Stanta Margarita",
    "Country": "US",
    "Latitude": "33.637562",
    "Longitude": "-117.606887",
    "PostalCode": "string",
    "Reason": "Add a MAK",
    "RespondToEmail": "youremail@melissadata.com",
    "State": "CA",
    "Suite": ""
    }'

Request Parameters

• GET JSON
• POST JSON

Code	Description
Request Level Parameters
id	Required. The License Key issued by Melissa.
t	Optional. Value passed through unchanged to the response for identification or any other purpose.
Record Level Parameters
a1	Required. A minimum address location for the contact.
a2	Optional. The second address line.
city	Required. The city name.
ctry	Required. ISO2 code for the country.
lat	Required. The corrected latitude. Optional if Longitude is provided.
long	Required. The corrected longitude. Optional if Latitude is provided.
postal	Required. The ZIP Code.
reason	Optional. Any additional information you want to add about the change request.
respondto	Optional. The email addres to receive updates about the change request.
state	Required. The state name.
ste	Optional. The suite number.

Code	Description
Request Level Parameters
CustomerID	Required. The License Key issued by Melissa.
TransmissionReferece	Optional. Value passed through unchanged to the response for identification or any other purpose.
Record Level Parameters
AddressLine1	Required. A minimum address location for the contact.
AddressLine2	Optional. The second address line.
City	Required. The city name.
Country	Required. ISO2 code for the country.
Latitude	Required. The corrected latitude. Optional if Longitude is provided.
Longitude	Required. The corrected longitude. Optional if Latitude is provided.
PostalCode	Required. The ZIP Code.
Reason	Optional. Any additional information you want to add about the change request.
RespondToEmail	Optional. The email addres to receive updates about the change request.
State	Required. The state name.
Suite	Optional. The suite number.

Headers

• GET JSON
• POST JSON

 Content-Type: application/json
 Accept: application/json

 Content-Type: application/json
 Accept: application/json

Response

• GET JSON
• POST JSON

{
    "Version": "8.4.0.1026",
    "TransmissionReference": "Test",
    "TransmissionResults": "",
    "Results": "MS01",
    "Message": "Thank you for submitting your correction. All submissions will be reviewed and added. We cannot guarantee that all submissions will be reflected in our final products or when they will be added. Usual turn-around time is several months."
}

{
    "Version": "8.4.0.1026",
    "TransmissionReference": "Test",
    "TransmissionResults": "",
    "Results": "MS01",
    "Message": "Thank you for submitting your correction. All submissions will be reviewed and added. We cannot guarantee that all submissions will be reflected in our final products or when they will be added. Usual turn-around time is several months."
}

/V4/WEB/addMIK

Use this endpoint to submit a request to add a new Melissa Identity Address Key (MIK).

Try it Now

Note

Make sure to replace {{customerId}} with your license key.

Get it here!

• POST JSON

curl -X POST "https://contribution.melissadata.net/V4/WEB/addMIK" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
    "CustomerID": {{customerId}},
    "TransmissionReference": "Test",
    "Add":
    [{
       "Key": "AddressLine1",
       "Value": "22382 Avenida Empresa"
    },
    {
       "Key": "City",
       "Value": "Rancho Stanta Margarita"
    },
    {
       "Key": "State",
       "Value": "CA"
    },
    {
       "Key": "Country",
       "Value": "US"
    },
    {
       "Key": "Latitude",
       "Value": "33.637562"
    },
    {
       "Key": "Longitude",
       "Value": "-117.606887"
    }],
    "Reason": "Add a MAK",
    "RespondToEmail": "youremail@melissadata.com"
    }'

Request Parameters

• POST JSON

Code	Description
Request Level Parameters
CustomerID	Required. The License Key issued by Melissa.
TransmissionReferece	Optional. Value passed through unchanged to the response for identification or any other purpose.
Record Level Parameters
Add	Required. A list of key/value pairs containing new values to be added. Code Description Key Required. The name of the field for data set by the associated value. Value Required. The data for a field set by the associated key.
Reason	Optional. Any additional information you want to add about the change request.
RespondToEmail	Optional. The email addres to receive updates about the change request.
Key Field Values (For Add Parameter)
AddressLine1	Required. A minimum address location for the contact.
AddressLine2	Optional. The second address line.
City	Required. The city name.
Country	Required. ISO2 code for the country.
Latitude	Required. The corrected latitude. Optional if Longitude is provided.
Longitude	Required. The corrected longitude. Optional if Latitude is provided.
State	Required. The state name.
Suite	Optional. The suite number.
Urbanization	Optional. Only used for addresses in Puerto Rico. This is used to break ties between similar addresses in the same Postal Code.

Headers

• POST JSON

 Content-Type: application/json
 Accept: application/json

Response

• POST JSON

{
    "Version": "8.4.0.1026",
    "TransmissionReference": "Test",
    "TransmissionResults": "",
    "Results": "MS01",
    "Message": "Thank you for submitting your correction. All submissions will be reviewed and added. We cannot guarantee that all submissions will be reflected in our final products or when they will be added. Usual turn-around time is several months."
}

/V4/WEB/changeGeoPoint

Use this endpoint to submit problem GeoPoints with comments and corrections.

Try It Now

Note

Make sure to replace {{customerId}} with your license key.

Get it here!

• GET JSON
• POST JSON

curl -X GET "http://kstagem1.melissadata.com:31001/V4/WEB/changeGeoPoint?\
&id={{customerId}}\
&t=Test\
&lat=33%2E637562\
&long=-117%2E606887\
&mak=8008006245\
&reason=GeoPoint Change needed\
&respondto=youremail%40melissadata%2Ecom" \
-H "Content-Type:application/json" \
-H "Accept:application/json"

curl -X POST "http://kstagem1.melissadata.com:31001/V4/WEB/changeGeoPoint" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
    "CustomerID": {{customerId}},
    "TransmissionReference": "Test",
    "Latitude": "33.637562",
    "Longitude": "-117.606887",
    "MelissaAddressKey": "8008006245",
    "Reason": "GeoPoint Change needed",
    "RespondToEmail": "youremail@melissadata.com"
    }'

Request Parameters

• GET JSON
• POST JSON

Code	Description
Request Level Parameters
id	Required. The License Key issued by Melissa.
t	Optional. Value passed through unchanged to the response for identification or any other purpose.
Record Level Parameters
mak	Required. A proprietary unique key identifier for an address.
lat	Required. The corrected latitude. Optional if Longitude is provided.
long	Required. The corrected longitude. Optional if Latitude is provided.
reason	Optional. Any additional information you want to add about the change request.
respondto	Optional. The email addres to receive updates about the change request.

Code	Description
Request Level Parameters
CustomerID	Required. The License Key issued by Melissa.
TransmissionReferece	Optional. Value passed through unchanged to the response for identification or any other purpose.
Record Level Parameters
MelissaAddressKey	Required. A proprietary unique key identifier for an address.
Latitude	Required. The corrected latitude. Optional if Longitude is provided.
Longitude	Required. The corrected longitude. Optional if Latitude is provided.
Reason	Optional. Any additional information you want to add about the change request.
RespondToEmail	Optional. The email addres to receive updates about the change request.

Headers

• GET JSON
• POST JSON

 Content-Type: application/json
 Accept: application/json

 Content-Type: application/json
 Accept: application/json

Response

• GET JSON
• POST JSON

{
    "Version": "8.4.0.1026",
    "TransmissionReference": "Test",
    "TransmissionResults": "",
    "Results": "MS01",
    "Message": "Thank you for submitting your geocoding correction. All submissions will be reviewed and added. We cannot guarantee that all submissions will be reflected in our final products or when they will be added. Usual turn-around time is several months."
}

{
    "Version": "8.4.0.1026",
    "TransmissionReference": "Test",
    "TransmissionResults": "",
    "Results": "MS01",
    "Message": "Thank you for submitting your geocoding correction. All submissions will be reviewed and added. We cannot guarantee that all submissions will be reflected in our final products or when they will be added. Usual turn-around time is several months."
}

/V4/WEB/changeMAK

Use this endpoint to submit a request to change a Melissa Address Key (MAK).

Try It Now

Note

Make sure to replace {{customerId}} with your license key.

Get it here!

• POST JSON

curl -X POST "https://contribution.melissadata.net/V4/WEB/changeMAK" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
    "CustomerID": {{customerId}},
    "TransmissionReference": "Test",
    "Current":
    [{
       "Key": "AddressLine1",
       "Value": ""
    },
    {
       "Key": "City",
       "Value": ""
    }],
    "ChangeTo":
    [{
       "Key": "AddressLine1",
       "Value": "22382 Avenida Empresa"
    },
    {
       "Key": "City",
       "Value": "Rancho Stanta Margarita"
    }],
    "MelissaAddressKey": "",
    "Reason": "MAK Change needed",
    "RespondToEmail": "youremail@melissadata.com"
    }'

Request Parameters

• POST JSON

Code	Description
Request Level Parameters
CustomerID	Required. The License Key issued by Melissa.
TransmissionReferece	Optional. Value passed through unchanged to the response for identification or any other purpose.
Record Level Parameters
Current	Required. This is a list of key/value pairs containing the original values before the change. The keys passed-in must align with ChangeTo. Empty or NULL values indicate no change. Code Description Key Required. The name of the field for data set by the associated value. Value Required. The data for a field set by the associated key.
ChangeTo	Required. This is a list of key/value pairs containing the new values after the change. The keys passed-in must align with Current. Empty or NULL values indicate no change. Code Description Key Required. The name of the field for data set by the associated value. Value Required. The data for a field set by the associated key.
MelissaAddressKey	Required. A proprietary unique key identifier for an address.
Reason	Optional. Any additional information you want to add about the change request.
RespondToEmail	Optional. The email addres to receive updates about the change request.
Key Field Values (For Current/ChangeTo Parameters)
AddressKey	Optional. A unique identifier for a given address.
AddressLine1	Required. A minimum address location for the contact.
AddressLine2	Optional. The second address line.
City	Required. The city name.
Country	Required. ISO2 code for the country.
Latitude	Required. The corrected latitude. Optional if Longitude is provided.
Longitude	Required. The corrected longitude. Optional if Latitude is provided.
State	Required. The state name.
Suite	Optional. The suite number.
Urbanization	Optional. Only used for addresses in Puerto Rico. This is used to break ties between similar addresses in the same Postal Code.

Headers

• POST JSON

 Content-Type: application/json
 Accept: application/json

Response

• POST JSON

{
    "Version": "8.4.0.1026",
    "TransmissionReference": "Test",
    "TransmissionResults": "",
    "Results": "MS01",
    "Message": "Thank you for submitting your correction. All submissions will be reviewed and added. We cannot guarantee that all submissions will be reflected in our final products or when they will be added. Usual turn-around time is several months."
}

/V4/WEB/changeMIK

Use this endpoint to submit a request to change a Melissa Identification Key (MIK).

Try It Now

Note

Make sure to replace {{customerId}} with your license key.

Get it here!

• POST JSON

curl -X POST "https://contribution.melissadata.net/V4/WEB/changeMIK" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
    "CustomerID": {{customerId}},
    "TransmissionReference": "Test",
    "Current":
    [{
       "Key": "AddressLine1",
       "Value": ""
    },
    {
       "Key": "City",
       "Value": ""
    }],
    "ChangeTo":
    [{
       "Key": "AddressLine1",
       "Value": "22382 Avenida Empresa"
    },
    {
       "Key": "City",
       "Value": "Rancho Stanta Margarita"
    }],
    "MelissaIdentityKey": "",
    "Reason": "MIK Change needed",
    "RespondToEmail": "youremail@melissadata.com"
    }'

Request Parameters

• POST JSON

Code	Description
Request Level Parameters
CustomerID	Required. The License Key issued by Melissa.
TransmissionReferece	Optional. Value passed through unchanged to the response for identification or any other purpose.
Record Level Parameters
Current	Required. This is a list of key/value pairs containing the original values before the change. The keys passed-in must align with ChangeTo. Empty or NULL values indicate no change. Code Description Key Required. The name of the field for data set by the associated value. Value Required. The data for a field set by the associated key.
ChangeTo	Required. This is a list of key/value pairs containing the new values after the change. The keys passed-in must align with Current. Empty or NULL values indicate no change. Code Description Key Required. The name of the field for data set by the associated value. Value Required. The data for a field set by the associated key.
MelissaIdentityKey	Required. A proprietary unique key associated with a person.
Reason	Optional. Any additional information you want to add about the change request.
RespondToEmail	Optional. The email addres to receive updates about the change request.
Key Field Values (For Current/ChangeTo Parameters)
AddressKey	Optional. A unique identifier for a given address.
AddressLine1	Required. A minimum address location for the contact.
AddressLine2	Optional. The second address line.
City	Required. The city name.
Country	Required. ISO2 code for the country.
Latitude	Required. The corrected latitude. Optional if Longitude is provided.
Longitude	Required. The corrected longitude. Optional if Latitude is provided.
State	Required. The state name.
Suite	Optional. The suite number.
Urbanization	Optional. Only used for addresses in Puerto Rico. This is used to break ties between similar addresses in the same Postal Code.

Headers

• POST JSON

 Content-Type: application/json
 Accept: application/json

Response

• POST JSON

{
    "Version": "8.4.0.1026",
    "TransmissionReference": "Test",
    "TransmissionResults": "",
    "Results": "MS01",
    "Message": "Thank you for submitting your correction. All submissions will be reviewed and added. We cannot guarantee that all submissions will be reflected in our final products or when they will be added. Usual turn-around time is several months."
}

/V4/WEB/removeMAK

Use this endpoint to submit a request to remove a Melissa Address Key (MAK) from the system.

Try It Now

Note

Make sure to replace {{customerId}} with your license key.

Get it here!

• GET JSON
• POST JSON

curl -X GET "https://contribution.melissadata.net/V4/WEB/removeMAK?\
&id={{customerId}}\
&t=Test\
&act=delete\
&mak=8008006245\
&respondto=youremail%40melissadata%2Ecom" \
-H "Content-Type:application/json" \
-H "Accept:application/json"

curl -X POST "https://contribution.melissadata.net/V4/WEB/removeMAK" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
    "CustomerID": {{customerId}},
    "TransmissionReference": "Test",
    "Action": "delete",
    "MelissaAddressKey": "8008006245",
    "RespondToEmail": "youremail@melissadata.com"
    }'

Note

MelissaAddressKey (mak) must already exist in the system.

Request Parameters

• GET JSON
• POST JSON

Code	Description
Request Level Parameters
id	Required. The License Key issued by Melissa.
t	Optional. Value passed through unchanged to the response for identification or any other purpose.
Record Level Parameters
act	Required. This specifies the action to be taken. Possible Values delete suppression
mak	Required. A proprietary unique key identifier for an address.
respondto	Optional. The email addres to receive updates about the change request.

Code	Description
Request Level Parameters
CustomerID	Required. The License Key issued by Melissa.
TransmissionReferece	Optional. Value passed through unchanged to the response for identification or any other purpose.
Record Level Parameters
Action	Required. This specifies the action to be taken. Possible Values delete suppression
MelissaAddressKey	Required. A proprietary unique key identifier for an address.
RespondToEmail	Optional. The email addres to receive updates about the change request.

Headers

• GET JSON
• POST JSON

 Content-Type: application/json
 Accept: application/json

 Content-Type: application/json
 Accept: application/json

Response

• GET JSON
• POST JSON

{
    "Version": "8.4.0.1026",
    "TransmissionReference": "Test",
    "TransmissionResults": "",
    "Results": "MS01",
    "Message": "Thank you for submitting your correction. All submissions will be reviewed and added. We cannot guarantee that all submissions will be reflected in our final products or when they will be added. Usual turn-around time is several months."
}

{
    "Version": "8.4.0.1026",
    "TransmissionReference": "Test",
    "TransmissionResults": "",
    "Results": "MS01",
    "Message": "Thank you for submitting your correction. All submissions will be reviewed and added. We cannot guarantee that all submissions will be reflected in our final products or when they will be added. Usual turn-around time is several months."
}

/V4/WEB/removeMIK

Use this endpoint to submit a request to remove a Melissa Identification Key (MIK) from the system.

Try It Now

Note

Make sure to replace {{customerId}} with your license key.

Get it here!

• GET JSON
• POST JSON

curl -X GET "https://contribution.melissadata.net/V4/WEB/removeMIK?\
&id={{customerId}}\
&t=Test\
&act=delete\
&mik=8008006245\
&respondto=youremail%40melissadata%2Ecom" \
-H "Content-Type:application/json" \
-H "Accept:application/json"

curl -X POST "https://contribution.melissadata.net/V4/WEB/removeMIK" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
    "CustomerID": {{customerId}},
    "TransmissionReference": "Test",
    "Action": "delete",
    "MelissaIdentityKey": "8008006245",
    "RespondToEmail": "youremail@melissadata.com"
    }'

Note

MelissaIdentityKey (mik) must already exist in the system.

Request Parameters

• GET JSON
• POST JSON

Code	Description
Request Level Parameters
id	Required. The License Key issued by Melissa.
t	Optional. Value passed through unchanged to the response for identification or any other purpose.
Record Level Parameters
act	Required. This specifies the action to be taken. Possible Values cpadelete - Erase personal data. cpalimit - Object to personal data processing, including profiling and direct marketing. cpaoptout - Withdraw any consent given for personal data processing. delete suppression
a1	Required. A minimum address location for the contact.
a2	Optional. The second address line.
city	Required. The city name.
first	Required. The parsed first name of an individual.
full	Required. The full name of an individual.
last	Required. The parsed last name of an individual.
mik	Required. A proprietary unique key associated with a person.
postal	Required. The ZIP Code.
respondto	Optional. The email addres to receive updates about the change request.
state	Required. The state name.

Code	Description
Request Level Parameters
CustomerID	Required. The License Key issued by Melissa.
TransmissionReferece	Optional. Value passed through unchanged to the response for identification or any other purpose.
Record Level Parameters
Action	Required. This specifies the action to be taken. Possible Values cpadelete - Erase personal data. cpalimit - Object to personal data processing, including profiling and direct marketing. cpaoptout - Withdraw any consent given for personal data processing. delete suppression
AddressLine1	Required. A minimum address location for the contact.
AddressLine2	Optional. The second address line.
City	Required. The city name.
FirstName	Required. The parsed first name of an individual.
FullName	Required. The full name of an individual.
LastName	Required. The parsed last name of an individual.
MelissaIdentityKey	Required. A proprietary unique key associated with a person.
PostalCode	Required. The ZIP Code.
RespondToEmail	Optional. The email addres to receive updates about the change request.
State	Required. The state name.

Optional Configurations

There are three ways to use this endpoint, depending on what request properties you send in.

• GET JSON
• POST JSON

Option 1

Required Fields
id
act
mik

Option 2

Required Fields
id
act
a1
a2
city
first
last
postal
state

Option 3

Required Fields
id
a1
a2
act
city
full
postal
state

Option 1

Required Fields
CustomerID
Action
MelissaIdentificationKey

Option 2

Required Fields
CustomerID
Action
AddressLine1
AddressLine2
City
FirstName
LastName
PostalCode
State

Option 3

Required Fields
CustomerID
Action
AddressLine1
AddressLine2
City
FullName
PostalCode
State

Headers

• GET JSON
• POST JSON

 Content-Type: application/json
 Accept: application/json

 Content-Type: application/json
 Accept: application/json

Response

• GET JSON
• POST JSON

{
    "Version": "8.4.0.1026",
    "TransmissionReference": "Test",
    "TransmissionResults": "",
    "Results": "MS01",
    "Message": "Thank you for submitting your correction. All submissions will be reviewed and added. We cannot guarantee that all submissions will be reflected in our final products or when they will be added. Usual turn-around time is several months."
}

{
    "Version": "8.4.0.1026",
    "TransmissionReference": "Test",
    "TransmissionResults": "",
    "Results": "MS01",
    "Message": "Thank you for submitting your correction. All submissions will be reviewed and added. We cannot guarantee that all submissions will be reflected in our final products or when they will be added. Usual turn-around time is several months."
}

Response Fields

Service Level Response Fields

Output Name	Description
Version	The current service version number.
TransmissionReference	Optional. Serves as a unique request identifier.
TransmissionResults	Lists error codes from any errors caused by the most recent request as a whole.

Record Level Response Fields

Output Name	Description
Results	Comma delimited status, error codes, and change codes for the record.
Message	The response message for the request.

Result Codes

Melissa products use a result code system to indicate data quality; the status and any errors. These result codes are four-character codes (two letters followed by two numbers), delimited by commas. Result code definitions are shared among Melissa products.

Understanding the Code

To fully understand result codes, you need to know them. Knowing what codes are possible and what they indicate will be key in building an effective application. It is useful to know all the codes, but this does not necessarily mean you will use them all. Just because you have a toolbox, doesn’t mean you will also try to use a screwdriver along with a hammer on a nail.

Contribution Result Codes