Address Validation API

Validate addresses with Shipium's Address Validation API.

Suggest Edits

Get started

To use the Address Validation API, you can follow the instructions on this page. Information about address validation within the Shipium platform can be found in the Address Validation documentation.

Verify addresses with the Address Validation API

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
POSThttps://api.shipium.com/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

The following table provides the required and optional fields for calling the Address Validation API. You can find additional support in the Address Validation API Reference.

Request fieldRequired/OptionalField propertiesDescription
address.street1RequiredString
Example: 123 Main St.		The first address line
address.street2RequiredString
Example: Suite 42		The second address line
address.cityRequiredString
Example: Albuquerque		The name of the city for the address
address.stateRequiredString
Example: NM		The 2-character abbreviation of the state for the address
address.countryCodeRequiredString
Example: US		The 2-character ISO 3166-1 country code for the address
address.postalCodeRequiredString
Example: 87121		A country-code-appropriate postal code for the address
address.addressTypeRequiredString
Commercial or Residential		The type of location for the address; see the note below about the information provided for this field
ignoreSecondaryAddressMismatchOptionalBoolean
true or false		Set to true in order to ignore secondary address mismatches and addresses with extra information, whether provided as a value for street1 or street2.
Defaults to false.

📘

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

The Address Validation response attributes are defined in the following table.

Response attributeDescription
addressThe address that is to be validated by the API
validvalid will return true if the address is valid and false if not.
addressPropertiesFor 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)
detailsThe 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].errorCodeA 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.
details.[element].errorDescriptionIf there are more details available, the error description will be populated, but will otherwise be an empty string.

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 'INSERT REQUEST BODY FROM BELOW'

Example request body

The following fields should be included in your JSON request.

{
  "address": {
      "street1": "1600 Pennsylvania Ave NW",
      "street2": "null",
      "city": "Washington",
      "state": "DC",
      "countryCode": "US",
      "postalCode": "20500",
      "addressType": "residential"
  }
}

📘

Response codes

A bad request will result in a 400.

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

Example response body for a VALID address

{
  "addressValidationId": "4d9e3ad7-a54b-43a6-92b7-214a8e93d793",
  "address": {
      "street1": "1600 Pennsylvania Ave NW",
      "street2": "null",
      "city": "Washington",
      "state": "DC",
      "countryCode": "US",
      "postalCode": "20500",
      "addressType": "residential"
  },
  "valid": true,
  "addressProperties": {
    "poBox": false
  }
}

Example response body for an INVALID address

For this example response, an invalid street address was provided (1600 Pennsylvania ST instead of the correct 1600 Pennsylvania Ave NW).

{
  "addressValidationId": "fe3244a0-f7d7-4aaa-9d31-85718505a761",
  "address": {
      "street1": "1600 Pennsylvania ST",
      "street2": "null",
      "city": "Washington",
      "state": "DC",
      "countryCode": "US",
      "postalCode": "20500",
      "addressType": "residential"
  },
  "valid": false,
  "details": [
    {
      "errorCode": "MISMATCH_STREETLINES",
      "errorDescription": "The provided street line: 1600 Pennsylvania ST does not match detected: 1600 PENNSYLVANIA AVE NW because street suffix"
    }
  ]
}

Listing of error code values and descriptions

errorCode ValueDescription
INVALID_UNKNOWN_REASONThe validation source determined that the address was invalid but returned no additional information.
MISSING_CITYA value for the required city field was not provided.
MISSING_POSTALCODEA value for the required postalCode field was not provided.
MISSING_REGIONA value for the required region field was not provided.
MISSING_STREET1A value for the required street1 field was not provided.
MALFORMED_ADDRESSTYPEInvalid address type in the call. If provided, addressType must be either commercial or residential.
MALFORMED_POSTALCODEThe postal code was in an invalid format for the region.
For the US, postalCode must be of the format: 12345 or 12345-7890.
MISMATCH_ADDRESSTYPEThe addressType provided in the call did not match the addressType of the validated address.
MISMATCH_POSTALCODEThe postalCode value provided did not match the correct postalCode for this address.
Note that we will ignore a city mismatch if the state and postalcode are both correct to handle neighborhood designations.
MISMATCH_REGIONThe provided state or region did not match with the address.
MISMATCH_REGION_AND_POSTALThe provided postalCode is not valid for the state or region passed.
MISMATCH_STREETLINESThe provided street1/street2 combination has one or more errors, which are detailed in the errorDescription.

Additional details are provided about streetlines mismatches in the errorDescription field. Additional details can be found in the table below.

Listing of MISMATCH_STREETLINES error descriptions

MISMATCH_STREETLINES contains additional information about the reason for the mismatch due to the larger number of potential issues with these fields.

At the end of the errorDescription field, there is additional information that can be used to understand the specifics of the issue in order to help you resolve the issue. The format is:
The provided street line {street line} does not match detected: {alternate address} because {reason}.

Resources

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

Updated about 2 months ago

What’s Next