Shipium Address Validation API

Validate addresses with Shipium's Address Validation API.

Suggest Edits

About the Address Validation API

When fulfilling a shipment, prior to making a call to get a carrier label, you may want to validate the address. This enables you to sideline and repair any address issues prior to getting to a warehouse environment or at least ahead of packing and print-and-apply operations areas when a package might then languish.

The Address Validation API enables you to validate an address based on its deliverability. Please note that an address being valid does not necessarily mean that any given carrier will be able to deliver to that address or that all carriers will support the format of the address fields.

Authentication

The Shipium Address Validation API assumes you're using one of the authentication mechanisms detailed in our authentication documentation. The endpoint for Address Validation API calls is included in the table below.

API typeAPI endpoint
POST/api/v1/address/validate

📘

Authentication for API Calls

In the cURL example on this page, the environment variable AUTHSTRING is used to handle authorization. The recipe below shows how to set it correctly for both API Key and OAuth users.

🔐
Authenticating for Curl
Open Recipe

Request body details

PropertyTypeDescription
addressA valid address entity (see API Listing)The address that is to be validated by the API.
See "A note about "addressType" below for details.
ignoreSecondaryAddressMismatchBoolean valueIf this value is set to true, then mismatches related to the address.street2 value will be ignored, assuming the address would otherwise match.
This value defaults to false

Example cURL call

This example shows a request to validate an address:

curl --request POST \
  --url https://api.shipium.com/api/v1/address/validate \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data '{"address": {"street1": "123 Warehouse St.", "street2": "Suite 42", "city": "Albuquerque", "state": "NM", "countryCode": "US", "postalCode": "87121", "addressType": "residential"}'

Example request body

The following fields should be included in your JSON request.

{
  "address": {
      "street1": "123 Warehouse St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121",
      "addressType": "residential"
  }
}

Response Codes

This API follows the standard Shipium API Response Codes standards.

📘

Request errors v. invalid addresses

A good request, whether the address is valid or not, will result in a 200 with details about the validation.

A bad request will result in a 400 as usual.


Example response body for a VALID address

{
  "addressValidationId": "4d9e3ad7-a54b-43a6-92b7-214a8e93d793",
  "address": {
      "street1": "123 Warehouse St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121",
      "addressType": "residential"
  },
  "valid": true,
  "addressProperties": {
    "poBox": false
  }
}

Example response body for an INVALID address

{
  "addressValidationId": "4d9e3ad7-a54b-43a6-92b7-214a8e93d793",
  "address": {
      "street1": "123 Warehouse St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121",
      "addressType": "residential"
  },
  "valid": false,
  "details": [
    {
      "errorCode": "INVALID_STREET1",
      "errorDescription": "the street1 value passed was invalid"
    }
  ]
}

Response body details

PropertyTypeDescription
addressA valid address entity (see API Listing)The address that is to be validated by the API.
See "A note about "addressType" below for details.
validBoolean valuevalid will return true if the address is valid and false if not.
addressPropertiesKey value pairsFor valid addresses, additional properties of the address are populated here and include:
* poBox - a boolean indicating if this address is a U.S. post office box (true) or not (false)
detailsAn array of objects, each containing two elementsThe details object will only appear if the valid value is false and contains details about why the address is not valid (if available).
details.[element].errorCodeString enumerationA short enumeration of the error, such as "INVALID_STREET1". Most error values will be in the form of "INVALID\_{propertyName}", referencing the propertyName that is invalid from the passed address or "MISSING\_{propertyName}" if a required property is missing.
You can see an up-to-date list of valid errorCode values and details Shipium Address Validation Error Codes
details.[element].errorDescriptionString valueIf there are more details available, the error description will be populated, but will otherwise be an empty string.

About address type

📘

A note about "addressType"

If you do not include an "addressType" key and value in the "address" passed in the request, the value of "addressType" will be populated with the correct value for the address that was passed.
Note: if we are unable to determine the address type for this address, it will be populated as null.

If you do pass an "addressType" of either "residential" or "commercial" and it is found to be incorrect, then you will receive an error with an "errorCode" value of "MISMATCH_ADDRESSTYPE".

If you pass "addressType" and it is correct, then you will just see this reflected in the address value returned in the response.

If you pass a completely invalid "addressType" value (e.g.,"badfaketype"), then you will receive an "errorCode" value of "MALFORMED_ADDRESSTYPE".

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful:


Updated 29 days ago