Documentation

DS API - Address Validation (AVS) Call

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.

What is address validation?

The Address Validation System (AVS) is an API that verifies if a package's destination address is correct or incorrect. In addition, the AVS obtains information that some carriers require such as a route number or the type of address (commercial or residential). If the address is incorrect, the AVS API that DesktopShipper communicates with will return a corrected address that matches what is stored in the USPS address database. Nothing will be returned if the AVS API can not locate the correct address.

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.

Why perform an address validation call to our API?

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:

{
    "name": "John C. Customer",
    "company": "DesktopShipper Demo",
    "address1": "123 Main St.",
    "address2": "",
    "city": "Hillsboro",
    "postalCode": "97123",
    "state": "OR",
    "countryCode": "US",
    "countryName": "United States",
    "phone": " (503) 331-4000",
    "email": "documentation@desktopshipper.com"
}

Data Template:

{
    "name": name,
    "company": company,
    "address1": address1,
    "address2": address2,
    "city": city,
    "postalCode":zip code,
    "state": state (2 characters),
    "countryCode": country code (2 characters),
    "countryName": country,
    "phone": phone,
    "email": email
}

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
email	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:

API response-1

Explanation of AVS Fields in the Response

"correctedAddress": {

....

"avsInfo": {

"validationState": 1,

"isResidential": false,

"uspsCarrierRoute": "C005"

}

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.

"avsResponseInformation": {

"avsServiceUsed": "PubApi",

"avsShortResult": "valid",

"avsErrorMessage": null,

"avsFailMessage": null,

"avsCarrierRt": "C005",

"avsUPSRuralFlag": "",

"avsResidentialIndicatorFlag": "B",

"avsPRUrbanization": "",

"avsRecordType": "VALIDATED_CHANGED"

}

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