Address Validation and Standardization API

Introduction

Fenix’s Address Validation and Standardization API (FAVS) corrects errors in street addresses including abbreviations and missing information, and supplies standard 5 digit zip code and ZIP+4 Codes. By eliminating address errors, retailers would improve the overall shipping process and reduce unnecessary shipping spend on returns and for address corrections.

Fenix Address Validation and Standardization API (FAVS)

With FAVS API, you can improve delivery predictability and reduce delivery failures, thereby providing improved customer experience. You do this by catching incorrect addresses and obtaining better awareness of address characteristics.

Features

Following are some of the features of FAVS

The API is Real Time and is able to validate addresses in real-time, allowing users to receive instant feedback on whether an address is valid or not
The API can detect if the address is a residential or business address, a deliverable address, a central delivery address, vacant address or a military address
The API automatically corrects contents of address such as misspellings, no city name, incorrect zip code and it also formats the address compatible with USPS address standards
Auto populates the county code when applicable
Detects if the apartment number is missing from the address
Auto suggests a better address if available

API Details

FAVS API is a REST based API that takes the US address as the input and returns the corrected or proposed address as per validation.

Below is the sample Fenix Address Validation request and response.

Request

Response

{

"address1": "xyz",

"address2": "47 W Broadway",

"city": "Bangor",

"state": "",

"country": "",

"zipCode": "04401"

}

{

"error": {

"code": "SUCCESS",

"identifier": 200,

"description": "We found a better match for your address"

},

"originalAddress": {

"address1": "47 W Broadway",

"address2": "Apt #1",

"city": "Bangor",

"state": "NV",

"country": "US",

"zipCode": "04401"

},

"proposedAddresses": [

{

"address1": "47 W Broadway",

"address2": "Apt #1",

"city": "BANGOR",

"state": "ME",

"country": "US",

"zipCode": "04401",

"zipCode4": "4502",

"metainfo": {

"deliverable": true,

"business": true,

"vacant": false,

"cmrvIndicator": false

}

]

}

Flow

Retailers can integrate with Fenix Address Validation at three important places in the order flow.

Checkout

Once the customer comes to checkout, the Fenix Address Validation api call gets triggered and gives the corrected/proposed address as per the validation.

2. Order Placed

Once the order is placed, the Fenix Address Validation API gets called and updates the useful information (tags, notes, note attributes, metafields, etc.) to the Shopify order based on the address validation response.

3. Label Printing

Retailers can call FAVS API at the time of label printing to make sure the label is printed for the correct address. Printing labels for incorrect addresses can lead to delivery delays, additional shipping spend to correct addresses and in the worst case, return the package back to the warehouse.

API Details

Resource Name	Fenix Address Validation and Standardization
Resource URL	/fenixaddressvalidate/api/v1/address/validate
Method	POST
Params (query/path)
Headers	store_name
Request Payload	{ "address1": "xyz", "address2": "47 W Broadway", "city": "Bangor", "state": "", "country": "", "zipCode": "04401" }
Response Payload	{ "error": { "code": "SUCCESS", "identifier": 200, "description": "We found a better match for your address" }, "originalAddress": { "address1": "47 W Broadway", "address2": "Apt #1", "city": "Bangor", "state": "NV", "country": "US", "zipCode": "04401" }, "proposedAddresses": [ { "address1": "47 W Broadway", "address2": "Apt #1", "city": "BANGOR", "state": "ME", "country": "US", "zipCode": "04401", "zipCode4": "4502", "metainfo": { "deliverable": true, "business": true, "vacant": false, "cmrvIndicator": false, "partialAddressIndicator": false, } } ] }
Response Status	200 - Success 400 - Failure

Error Codes

S No	Use Case	Description	Error Identifier	Error Codes
1	Valid address provided	Thank You for providing correct address	200	SUCCESS
2	Address corrected	We found a better match for your address	200	SUCCESS_WITH_CORRECTION
3	Partial address provided	Some fields of the address are missing. See metainfo.partialAddressIndicator for what’s missing	206	PARTIAL_ADDRESS
4	Invalid address provided	Your address appears to be incorrect	400	INVALID_ADDRESS

Use Cases

In partial address validation use cases, Fenix takes care of the below things.

S No	Description	Definition
1	Zip Code Corrected	The address was found to have a different 5-digit Zip Code than given in the submitted list. The correct Zip Code is shown in the output address.
2	City / State Spelling Corrected	The spelling of the city name and/or state abbreviation in the submitted address was found to be different from the standard spelling. The standard spelling of the city name and state abbreviation are shown in the output address.
3	Street Name Changed	The spelling of the street name was changed in order to achieve a match.
4	Apartment number missing	Incorrect apartment number or missing apartment number

Partial Address Indicator

When the address has some fields corrected or missing in it, Fenix populates an indicator that suggests what part of the address is corrected or missing. The possible values are as follows.

Indicator	Description
A	Zip Code corrected
B	City or State name corrected
H	Missing apartment number
M	Street name changed