This article covers everything you need to know about DesktopShipper's API call for address validation.
Welcome to the DesktopShipper's Address Validation API documentation. This guide
is here to help you seamlessly integrate our powerful address management tool into
your applications. Whether you're running an online store, a shipping service, or any
application that deals with addresses, our API can enhance your data quality and
streamline your processes.
In this documentation, you'll learn how to easily incorporate the Address Validation
API into your software. We've designed it to be user-friendly, and we're here to
support you every step of the way.
Contents:
Why perform an address validation call?
How to make a test AVS API call using Postman
Explanation of AVS Fields in the Response
What is address validation?
Please note that the address validation system can only be used for domestic orders in the United States. The AVS system will not verify international addresses.
Address validation is critical for ensuring all of your shipments reach their destinations. Carriers such as FedEx and UPS require an address type to determine the correct shipping fee. The AVS can return the address type as either a residential home or a business. In addition, some carriers such as DHL require a route number for some of their services. An AVS call can provide this data as well.
Our Address Validation API ensures that addresses are accurate and reliable in real-time. It fixes mistakes, fills in missing details, and confirms the authenticity of addresses. This means fewer shipping hiccups, fewer returns, and happier customers.
Making an API AVS call:
When testing an API call with an application such as Postman, you will need a bearer token, which can be obtained using DesktopShipper. The following are steps for obtaining the bearer token.
1) Log into "https://shipv2.desktopshipper.com"
2) Click "Settings", then "API"
3) Create a new API user if needed.
4) Expand your user to get the token.
5) Click to obtain the token. Copy it to a notepad as you will be needing it shortly.
The DesktopShipper API AVS endpoint is:
https://next_io.desktopshipper.com/api/v1/Rate/AddressVerify?avsType=0
The request type is POST
The "avsType" parameter can have a 0 or 1 value.
0 | Default. Full address verification. |
1 | Minimal AVS. Will verify the city, state, and zip, but not the address lines. |
How to make a test AVS API Call Using Postman
1) Using Postman, create a new collection by clicking "+".
2) You can rename the New Collection if desired.
3) Under the collection click "Add a request".
4) You can rename the "New Request" to AVS API call" or whatever you prefer by clicking on the 3 dots at the end of the request name.
5) Set the following for the endpoint and use "POST" for the method.
6) Click the Authorization tab and set "Bearer Token for the Authorization type.
7) Next you will need the Token that was obtained from the DesktopShipper UI.
8) In Postman, click the "Authentication" tab and paste the copied token into the token field.
9) Next we will add the test request order data.
10) Click the "Body" tab.
11) Select the "Raw" option and select "JSON" from the data type dropdown.
12) copy the following test data or use the template with your own data:
Sample Data: { |
Data Template: { |
The following are the character lengths for the fields in the AVS API request:
Field | Length |
name | 35 |
company | 35 |
address1 | 35 |
address2 | 35 |
address3 | 35 |
city | 30 |
postalCode | 10 |
state | 5 |
countryCode | 3 |
countryName | 50 |
phone | 15 |
50 |
13) Paste the data into the body request section and click "Send".
14) You should receive a response with the correct address included (if the original address is incorrect). Click the "Body" tab and the "Pretty" option to view the response in
JSON format:
Explanation of AVS Fields in the Response
validationState |
0 = unverified 1 = valid -1 = invalid |
isResidential |
true = a residential address false = business or commercial address. This field's value is mainly Used by UPS and FedEx when determining the correct service or charge amount. |
uspsCarrierRoute | Some carrier services require a carrier route when shipping. If no carrier route is returned, the rating will fail for that service will fail. |
avsServiceUsed | Type of AVS used. Should always return the value "PubApi" for this call. |
avsShortResult | Will return "Valid" if the call is successful. Can return "error", "unknown", "non-us", or "invalid" upon failure. |
avsErrorMessage | Error Message Returned from AVS response. |
avsFailMessage | Error Message Returned from AVS response. |
avsCarrierRt | Some carrier services require a carrier route when shipping. If no carrier route is returned, the rating will fail for that service will fail. |
avsUPSRuralFlag |
Should always return an empty string. |
avsResidentialIndicatorFlag | Returns "R" for residential or "B" for business or an empty string if undetected. The Residential Indicator Flag is used for carries such as |
avsPRUrbanization | Should always return an empty string. |
avsRecordType |
Will return either: "NOT_CHANGED", "VALIDATED_AND_NOT_CHANGED", "VALIDATED_CHANGED". |