What is the residential attribute?
The residential attribute on the Address Object can be used to indicate whether an address is residential or commercial. There are 3 possible values for this attribute:
- TRUE
- FALSE
- NULL
Why is the residential attribute important?
The residential attribute can have a significant effect on the rates/service levels returned for various carriers. Most notably, when shipping with FedEx.
Ex: GROUND_HOME_DELIVERY is a returned service level for residential destinations only. FEDEX_GROUND will be returned if the residential attribute is not set for the destination address (i.e., NULL), or is set to FALSE. This indicates that the destination address is commercial.
** Please note that FedEx has their own internal address verification system that they use to confirm whether an address is residential or commercial, so it is possible that you pass the residential attribute set to TRUE, and still do not receive GROUND_HOME_DELIVERY in the response**
How do I set the residential attribute?
EasyPost offers several verification tools that can be used to detect deliverability issues, correct minor errors in spelling/formatting, and determine if an Address is residential or not.
By passing verify: ['delivery'] on your address create call, this will use our address verification system (AVS) to check that the address is deliverable, and make minor corrections to spelling/format. For US addresses, our AVS will also have their "residential" status checked and set to either true or false. Utilizing our AVS is the best practice for verifying the residential status of an address. However, you can also manually set the residential attribute to true or false on the address object.
If you choose to do this manually, please note that the carrier will also do their own address verification on their side, and if their own system "disagrees" with the manually set residential status, it will assign its own residential status and return rates/service levels for residential addresses. This is why we recommend using verify: ['delivery'] for US addresses.
The value of null is returned if no residential status was entered manually and no AVS was used on a US address.