Reference Guide

Introduction

Welcome to the AddrLib Service by Melissa.

The AddrLib Service is a powerful tool that helps businesses improve the accuracy and completeness of their address data. It can be used to verify address data and formatting, clean bad and incomplete contact data, match street names against ZIP Codes to return valid address ranges, match geographic data to ZIP Codes and city information, and break down street addresses into their component parts.

As a self-hosted container, you deploy and manage AddrLib on-premises. This gives you complete control over your data, security, and performance. Storing your data in a specific location can be important for data sovereignty and comliance reasons, like for GDPR. This also allows you greater security over your data, if needed. Self-hosting can also offer better performance, especially if you require a low latency or high throughput.

Data Path

This is set during the containerization service setup. It is whatever data path you set.

See {{data_path}} in the AddrLibService-Quickstart-ExampleDockerSetup.

Service Port Number

This is set during the containerization service setup. It defaults to 6245, but can be any port you set.

See {{port_number}} in the AddrLibService-Quickstart-ExampleDockerSetup.

Machine Name

This is your local machine name. You’ll use this in every request you send to your local containerization service. You can view your machine name by using the hostname command in the command prompt.

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 at sales@melissa.com or 800-MELISSA ext. 3 (800-635-4772 ext. 3). Without a license key the service will not function.

Endpoints

/V3/WEB/ContactVerify/GetVersion

Introduction

Use this endpoint to check the version of the AddrLib Service.

Try It Now

• GET JSON

curl -X GET \
"http://{{machine_name}}:{{port_number}}/V3/WEB/ContactVerify/GetVersion" \
-H "accept: application/json"

Headers

• GET JSON

cache-control: no-cache,no-store,must-revalidate,private
content-type: application/json; charset=utf-8
pragma: no-cache

Response

• GET JSON

{
  "Version_0": "7.4.1.17768",
  "ServiceName_0": "addrLibService",
  "InitializationErrorCode_0": "0",
  "InitializationErrorMessage_0": "No error.",
  "BuildNumber_0": "17768",
  "DatabaseDate_0": "2023-07-01",
  "ExpirationDate_0": "2024-07-02",
  "LicenseExpirationDate_0": "2024-07-02",
  "CanadaDatabaseDate_0": "2023-07-15",
  "CanadaExpirationDate_0": "2024-07-02",
  "Version_1": "7.4.1.17768",
  "ServiceName_1": "addrLibService",
  "InitializationErrorCode_1": "0",
  "InitializationErrorMessage_1": "No error.",
  "BuildNumber_1": "17768",
  "DatabaseDate_1": "2023-07-01",
  "ExpirationDate_1": "2024-07-02",
  "LicenseExpirationDate_1": "2024-07-02",
  "CanadaDatabaseDate_1": "2023-07-15",
  "CanadaExpirationDate_1": "2024-07-02",
  "Version_2": "7.4.1.17768",
  "ServiceName_2": "addrLibService",
  "InitializationErrorCode_2": "0",
  "InitializationErrorMessage_2": "No error.",
  "BuildNumber_2": "17768",
  "DatabaseDate_2": "2023-07-01",
  "ExpirationDate_2": "2024-07-02",
  "LicenseExpirationDate_2": "2024-07-02",
  "CanadaDatabaseDate_2": "2023-07-15",
  "CanadaExpirationDate_2": "2024-07-02"
}

/V3/WEB/ContactVerify/doContactVerify

Introduction

Use this endpoint to use all the address verification capabilities of Address Object.

Try It Now

Note

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

Get it here!

• GET JSON
• POST JSON

curl -X GET \
"http://{{machine_name}}:{{port_number}}/V3/WEB/ContactVerify/doContactVerify?\
t=test\
&id={{license_key}}\
&ctry=US\
&a1=22382%20Avenida%20Empresa\
&city=Rancho%20Santa%20Margarita\
&state=CA\
&postal=92688\
&comp=Melissa\
&format=json"\
-H "accept:application/json"

curl -X 'POST' \
  'http://{{machine_name}}:{{port_number}}/V3/WEB/ContactVerify/doContactVerify' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "customerId": "{{license_key}}",
  "options": "",
  "transmissionReference": "test",
  "records": [
    {
      "recordID": "1",
      "addressLine1": "22382 Avenida Empresa",
      "addressLine2": "",
      "suite": "",
      "city": "Rancho Santa Margarita",
      "state": "CA",
      "postalCode": "92688",
      "lastLine": "",
      "plus4": "",
      "deliverypointcode": "",
      "company": "Melissa",
      "urbanization": "",
      "lastName": "",
      "country": "US"
    }
  ]
}'

Request Parameters

• GET JSON
• POST JSON

Code	Description
t	This is a string value that serves as a unique identifier for this set of records. It is returned as sent.
id	The License Key issued by Melissa.
opt	Set Options UseUSPSPreferredCityNames CASSEnable DiacriticsMode StandardizeType InRangeOnly OfficialCityNameOnly
a1	The input field for the address line 1.
a2	The input field for the address line 2.
city	The city name.
comp	The company name.
ctry	The country. This can only take in variations of US or Canada. All other countries will return AS09 (Foreign Address).
format	The format of the response.
lastline	The city, state, and ZIP.
last	The family (last) name.
p4	The Plus 4 extension for US ZIP codes, specifying a delivery route in the ZIP code area.
postal	The postal code.
state	The US state.
ste	Suite name, an alphanumeric code identifying an individual location.
urb	Urbanization name, a smaller population center data element. These are used only in Puerto Rican addresses.

Code	Description
transmissionReference	This is a string value that serves as a unique identifier for this set of records. It is returned as sent.
customerId	The License Key issued by Melissa.
options	Set Options UseUSPSPreferredCityNames CASSEnable DiacriticsMode StandardizeType InRangeOnly OfficialCityNameOnly
addressLine1	The input field for the address line 1.
addressLine2	The input field for the address line 2.
city	The city name.
company	The company name.
country	The country. This can only take in variations of US or Canada. All other countries will return AS09 (Foreign Address).
format	The format of the response.
lastLine	The city, state, and ZIP.
lastName	The family (last) name.
plus4	The Plus 4 extension for US ZIP codes, specifying a delivery route in the ZIP code area.
postalCode	The postal code.
recordID	A unique identifier for the current record.
state	The US state.
suite	Suite name, an alphanumeric code identifying an individual location.
urbanization	Urbanization name, a smaller population center data element. These are used only in Puerto Rican addresses.

Headers

• GET JSON
• POST JSON

cache-control: no-cache,no-store,must-revalidate,private
content-type: application/json; charset=utf-8
pragma: no-cache

cache-control: no-cache,no-store,must-revalidate,private
content-type: application/json; charset=utf-8
pragma: no-cache

Response

• GET JSON
• POST JSON

{
  "TransmissionResults": "",
  "TransmissionReference": "test",
  "Version": "7.4.1.17768",
  "TotalRecords": 1,
  "Records": [
    {
      "RecordID": "",
      "AddressLine1": "22382 Avenida Empresa",
      "AddressLine2": "",
      "Company": "Melissa",
      "LastName": "",
      "Suite": "",
      "City": "Rancho Santa Margarita",
      "State": "CA",
      "PostalCode": "92688",
      "Plus4": "2112",
      "Urbanization": "",
      "ParsedAddressRange": "22382",
      "ParsedPreDirection": "",
      "ParsedSuffix": "",
      "ParsedPostDirection": "",
      "ParsedSuiteName": "",
      "ParsedSuiteRange": "",
      "ParsedRouteService": "",
      "ParsedLockBox": "",
      "ParsedDeliveryInstallation": "",
      "ParsedStreetName": "Avenida Empresa",
      "CarrierRoute": "C057",
      "DeliveryPointCode": "82",
      "DeliveryPointCheckDigit": "1",
      "ELotNumber": "-1",
      "ELotOrder": "X",
      "CountyFips": "06059",
      "CountyName": "Orange",
      "AddressKey": "92688211282",
      "MelissaAddressKey": "8008006245",
      "MelissaAddressKeyBase": "",
      "AddressTypeCode": "S",
      "CityAbbreviation": "Rcho Sta Marg",
      "AddressTypeString": "Street",
      "CMRA": "N",
      "DPVFootnotes": "AABB",
      "DSFNoStats": "N",
      "DSFVacant": "N",
      "ErrorCode": " ",
      "ErrorString": "No Error",
      "LACS": " ",
      "LACSLinkIndicator": " ",
      "LACSLinkReturnCode": " ",
      "Results": "AS01",
      "RBDI": "B",
      "SuiteLinkReturnCode": "",
      "SuiteStatus": "V",
      "CongressionalDistrict": "40",
      "Country": "US",
      "ParsedPrivateMailboxName": "",
      "ParsedPrivateMailboxNumber": "",
      "ParsedGarbage": "",
      "PrivateMailbox": "",
      "TimeZone": "Pacific Time",
      "TimeZoneCode": "08",
      "ZipType": " ",
      "Msa": "",
      "Pmsa": "",
      "DefaultFlagIndicator": " ",
      "EWSFlag": " ",
      "FalseTable": "N",
      "z_TimeZone": "Pacific Time",
      "z_TimeZoneCode": "08",
      "z_Longitude": "-117.6043",
      "z_Latitude": "33.6369",
      "z_CountyFips": "06059",
      "z_CountyName": "Orange"
    }
  ]
}

{
  "TransmissionResults": "",
  "TransmissionReference": "test",
  "Version": "7.4.1.17768",
  "TotalRecords": 1,
  "Records": [
    {
      "RecordID": "",
      "AddressLine1": "22382 Avenida Empresa",
      "AddressLine2": "",
      "Company": "Melissa",
      "LastName": "",
      "Suite": "",
      "City": "Rancho Santa Margarita",
      "State": "CA",
      "PostalCode": "92688",
      "Plus4": "2112",
      "Urbanization": "",
      "ParsedAddressRange": "22382",
      "ParsedPreDirection": "",
      "ParsedSuffix": "",
      "ParsedPostDirection": "",
      "ParsedSuiteName": "",
      "ParsedSuiteRange": "",
      "ParsedRouteService": "",
      "ParsedLockBox": "",
      "ParsedDeliveryInstallation": "",
      "ParsedStreetName": "Avenida Empresa",
      "CarrierRoute": "C057",
      "DeliveryPointCode": "82",
      "DeliveryPointCheckDigit": "1",
      "ELotNumber": "-1",
      "ELotOrder": "X",
      "CountyFips": "06059",
      "CountyName": "Orange",
      "AddressKey": "92688211282",
      "MelissaAddressKey": "8008006245",
      "MelissaAddressKeyBase": "",
      "AddressTypeCode": "S",
      "CityAbbreviation": "Rcho Sta Marg",
      "AddressTypeString": "Street",
      "CMRA": "N",
      "DPVFootnotes": "AABB",
      "DSFNoStats": "N",
      "DSFVacant": "N",
      "ErrorCode": " ",
      "ErrorString": "No Error",
      "LACS": " ",
      "LACSLinkIndicator": " ",
      "LACSLinkReturnCode": " ",
      "Results": "AS01",
      "RBDI": "B",
      "SuiteLinkReturnCode": "",
      "SuiteStatus": "V",
      "CongressionalDistrict": "40",
      "Country": "US",
      "ParsedPrivateMailboxName": "",
      "ParsedPrivateMailboxNumber": "",
      "ParsedGarbage": "",
      "PrivateMailbox": "",
      "TimeZone": "Pacific Time",
      "TimeZoneCode": "08",
      "ZipType": " ",
      "Msa": "",
      "Pmsa": "",
      "DefaultFlagIndicator": " ",
      "EWSFlag": " ",
      "FalseTable": "N",
      "z_TimeZone": "Pacific Time",
      "z_TimeZoneCode": "08",
      "z_Longitude": "-117.6043",
      "z_Latitude": "33.6369",
      "z_CountyFips": "06059",
      "z_CountyName": "Orange"
    }
  ]
}

Service Level Response Fields

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

Record Level Response Fields

Output Name	Description
AddressKey	Returns a unique identifier for an address. This key can be used with other current and future Melissa services.
AddressLine1	Returns the address entered in the AddressLine field. If two addresses were entered and only one is valid, the valid address is returned instead. This includes the suite and private mailbox.
AddressLine2	If two addresses are passed into the AddressLine field, the second address is returned here. If only one of two addresses is valid, the valid address will be returned in Address Line 1.
AddressTypeCode	Returns a type code for the record address.
AddressTypeString	Returns a string defining the type codes returned by the AddressTypeCode field.
CarrierRoute	Returns a 4-character code defining the carrier route for the record address.
City	Returns the city for the record.
CityAbbreviation	Returns an abbreviation for the city of the record address, if any.
CMRA	Retruns if the address was identified as a Commercial Mail Receiving Agency (CMRA) and the secondary address information is present.
Company	Returns the company name.
CongressionalDistrict	Returns the 2-digit congressional district that belongs to the record address.
Country	Returns the country name for the record.
CountyFIPS	Returns the FIPS code for the county of the record address.
CountyName	Returns the county name for the record address.
DefaultFlagIndicator	Indicates the record matched a highrise, rural route, or street default record in the ZIP + 4 product. Y = Default Flag Indicator is set
DeliveryPointCheckDigit	Returns a string value containing the 1-digit delivery point check digit.
DeliveryPointCode	Returns a string value containing the 2-digit delivery point code.
DPVFootnotes	Indicates the level of matching between the current address and the USPS’s DPV database. This footnote may be up to six characters long.
DSFNoStats	Indicates address is not receiving delivery or possible delivery because: delivery has not been established; or the customer receives mail as a part of a drop; or the address is no longer a possible delivery because the carrier destroys or returns all of the mail. This field also contains the results of the call to the DPV SEASONAL table: dph.hss Y = Address was found in Seasonal table N = Address was not found in Seasonal table [Blank] = Address was not presented to hash table
DSFVacant	A delivery point was active in the past, but is currently vacant (in most cases unoccupied over 90 days) and not receiving delivery.
ErrorCode	Returns any error codes for the record.
ErrorString	Returns a string defining the error codes returned by the ErrorCode field.
EWSFlag	US Only. This address currently cannot be verified but was identified by the Early Warning System (EWS) as belonging to a upcoming area and will likely be included in a future update.
ELotNumber	Enhanced Line of Travel Number. It is used by mailing customers to qualify for enhanced carrier route discounts by sorting their mail in the order that the mail carrier would deliver them.
ELotOrder	Enhanced Line of Travel Order. It is used by mailing customers to qualify for enhanced carrier route discounts by sorting their mail in the order that the mail carrier would deliver them.
FalseTable	Contains false positive addresses. Stop processing and email the false positive records to DSF2Stop@usps.gov.
LACS	Locatable Address Conversion System. Returns any address conversion done by LACS.
LACSLinkIndicator	LACSLink is required for CASS by the USPS.
LACSLinkReturnCode	Returns any return codes from the LACSLinkIndicator field.
MelissaAddressKey	Returns a unique key associated with an address.
MelissaAddressKeyBase	Returns a unique key associated with a building containing multiple suites/apartments.
Msa	Returns the Metropolian Statistical Area (MSA) associated with the record address.
LastName	Returns the last name for the record.
ParsedAddressRange	Returns the parsed house number range for the record address.
ParsedDeliveryInstallation	Canada Only. Returns the parsed delivery installation for the record address.
ParsedGarbage	Retruns extraneous information not used in verifying the address. This includes unnecessary sub premises and other unrecognized data.
ParsedLockBox	Canada Only. Returns the parsed lock box number for the record address.
ParsedPreDirection	Returns the parsed pre-direction for the record address.
ParsedPrivateMailboxName	Returns the parsed private mailbox name for the record address.
ParsedPrivateMailboxRange	Returns the parsed private mailbox range for the record address.
ParsedPostDirection	Returns the parsed post-direction for the record address.
ParsedRouteService	Canada Only. Returns the parsed route service number for the record address.
ParsedStreetName	Returns the parsed street name for the record address.
ParsedSuffix	Returns the parsed street suffix for the record address.
ParsedSuiteName	Returns the parsed suite name for the record address.
ParsedSuiteRange	Returns the parsed suite number range for the record address.
Plus4	Returns the 4-digit plus4 for the input address.
Pmsa	Returns the Primary Metropolitan Statistical Area (PMSA) associated with the record address.
PostalCode	Returns the 5-digit postal code for U.S. addresses and 6-digit postal code for Canadian addresses.
PrivateMailBox	Returns the private mail box number for the record address, if any. Private mailboxes are private mail boxes in commercial mail receiving agencies, like a UPS Store.
RBDI	Returns an indicator of whether the record address is a business address or residential address.
RecordID	This is a string value that is a unique identifier for the current record if one was sent in the request. Use this element to match a request record and the corresponding response record.
Results	This is a string value with comma delimited status, error codes, and change codes for the record.
State	Returns the state for the record.
Suite	Returns the suite for the address.
TimeZone	Returns a string description of the time zone of the record address.
TimeZoneCode	Returns the time zone code of the record address.
Urbanization	Returns the urbanization name for the record. Usually only used if the address is in Puerto Rico.
ZipType	Returns a code indicating the type of address belonging to the ZIP Code™.

Options

List options in the following format, with multiple options delimited with a ;.

OptionName:Parameter;OptionName:Parameter

UseUSPSPreferredCityNames

US Only

For every city, there is an official name that is preferred by the U.S. Postal Service. There may be one or more unofficial or “vanity” names in use. Normally, the AddrLib service allows you to verify addresses using known vanity names. If this option is set to True the preferred city name will be subsituted for any vanity name when it verifies an address.

Parameter	Description
True	Default. Will always use the preferred city name.
False	Will not substitute a given vanity name for the preferred city name.

CASSEnable

This option enables full CASS Certified™ address verification. By default it is disabled. Set it to True to enable CASS™.

Parameter	Description
True	CASS™ is enabled.
False	Default. CASS™ is disabled.

DiacriticsMode

Canada Only

Determines whether or not French language characters are returned. If set to Auto, those characters are only returned if they are in the input.

Parameter	Description
Auto	Default. Diacritics only returned if in the input.
On	Will return diacritics.
Off	No diacritics returned.

StandardizeType

Determines the handling of abbreviations of suffixes and directionals when standardizing a street address.

Parameter	Description
ShortFormat	Default. Directionals and suffixes will be shortened to postal standards.
LongFormat	Directionals and suffixes will be spelled out.
AutoFormat	Original standardization will be preserved.

InRangeOnly

This options handles returning addresses that fall within the parsed range of the input address.

Parameter	Description
True	Only addresses in range of the input address will be returned.
False	Default. All addresses will be returned.

OfficialCityNameOnly

This option handles which cities are returned during a Find Cities in ZIP Code Search. The default of False will return all cities associated with the ZIP/Postal Code. True will only reutrn the official city.

Parameter	Description
True	Returns only one search record, the official city.
False	Default. Return all cities found in the input ZIP/Postal code.