Address Validation and Standardization API

Owned by Rahul Kumar Sahukar
Last updated: Nov 21, 2024
3 min read

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

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

  2. The API can detect if the address is a residential or business address, a deliverable address, a central delivery address or a vacant address

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

  4. Auto populates the county code when applicable

  5. Detects if the apartment number is missing from the address

  6. Auto suggests a better address if available

Flow

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

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

api/v1/address/validate

Method

POST

Headers

  • tenant_id

  • authToken

Request Payload

{ "requestId": "df3a89af-5de9-4051-82e8-040d9333adaf", "address": { "address1": "123 williams str", "address2": null, "city": "new york", "state": "NY", "country": "US", "zipCode": "10001", "zipCode4": null } }

Response Payload

{ "requestId": null, "originalAddress": { "address1": "123 williams str", "address2": null, "city": "new york", "state": "NY", "country": null, "zipCode": "10001", "zipCode4": null }, "recommendedAddress": { "address1": "123 WILLIAM ST", "address2": null, "city": "NEW YORK", "state": "NY", "country": null, "zipCode": "10038", "zipCode4": "3804" }, "metainfo": { "vacant": false, "business": false }, "addressCorrections": [ { "code": "ZIPCODE_CORRECTED", "description": "Zip Code Corrected" }, { "code": "STREET_NAME_CHANGED", "description": "Street Name changed" } ], "addressErrors": [ { "code": "MISSING_SECONDARY_NUMBER", "description": "Missing Apt/Unit Number" } ], "validationError": null }

Response Status

200 - Success

400 - Failure

Request Attribute Parameters 

Attribute

Required

Description

Attribute

Required

Description

requestId

No

A random identifier that you send in each request

address

Yes

The address that is to be validation

address.address1

Yes

The primary address line

Usually, this refers to the house number, street name, and apartment/flat number

address.address2

No

Additional details about the address like building unit can be specified in address line 2

address.city

Yes

Name of the city

address.state

Yes

State 2 letter code or full state name

address.country

No

Two letter code of the country

Supports US only for now

address.zipCode

Yes

The zip code of the city

address.zipCode4

No

Represents 4 digit county code

Response Attribute Parameters 

Attribute

Required

Description

Attribute

Required

Description

requestId

No

A random identifier that you send in each request

originalAddress

Yes

The address that is given as input to the API

recommendedAddress

Yes

Fenix suggested address

metainfo

Yes

Additional details of the suggested address

metainfo.vacant

Yes

Represents whether the suggested address is vacant or not

metainfo.business

Yes

Represents whether the suggested address is business or residential

addressCorrections

No

Contains the corrections made to the input address

addressCorrections.code

Yes

The correction code

Possible Values

  • ZIPCODE_CORRECTED

  • CITY_OR_STATE_CORRECTED

  • ADDRESS_COMPONENT_CHANGED

  • STREET_NAME_CHANGED

addressCorrections.description

Yes

The description for the above code

addressErrors

No

Represents additional errors in the address

addressErrors.code

Yes

The address error codes

addressErrors.description

Yes

The description for the above code