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 Example Docker Setup.

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 Example Docker Setup.

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#

  • 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.