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 type	API endpoint
POST	https://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 field	Required/Optional	Field properties	Description
`address.street1`	Required	String Ex.: `123 Main St.`	The first address line
`address.street2`	Required	String Ex.: `Suite 42`	The second address line
`address.city`	Required	String Ex.: `Albuquerque`	The name of the city for the address
`address.state`	Required	String Ex.: `NM`	The 2-character abbreviation of the state for the address
`address.countryCode`	Required	String Ex.: `US`	The 2-character ISO 3166-1 country code for the address
`address.postalCode`	Required	String Ex.: `87121`	A country-code-appropriate postal code for the address
`address.addressType`	Required	String `commercial` or `residential`	The type of location for the address; see the note below about the information provided for this field
`ignoreSecondaryAddressMismatch`	Optional	Boolean `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`. The default value is `false`.
`useSimplifiedCarrierValidation`	Optional	Boolean `true` or `false`	Set to `true` in order to ignore street address mismatches. The default value is `false`.
`includeCandidate`	Optional	Boolean `true` or `false`	When `true`, an address candidate will be included in the response if one is found.

📘
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 attribute	Description
`addressValidationId`	A Shipium-generated ID that uniquely identifies this request
`address`	The address that is to be validated by the API
`valid`	`valid` will return `true` if the address is valid and `false` if not.
`ignoreSecondaryAddressMismatch`	Indicates whether the secondary address components were validated
`useSimplifiedCarrierValidation`	Indicates whether the street address(es) were validated
`addressProperties`	For 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`)
`candidate`	If the `includeCandidate` field was set to `true` in the request, this is the address candidate that most closely matches the requested address.
`details`	The 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].errorCode`	A 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].errorDescription`	If 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"
  },
  "ignoreSecondaryAddressMismatch": false,
  "useSimplifiedCarrierValidation": false,
  "includeCandidate": true
}

📘
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,
  "ignoreSecondaryAddressMismatch": false,
  "useSimplifiedCarrierValidation": false,
  "addressProperties": {
    "poBox": false
  },
  "candidate": {
    "street1": "1600 Pennsylvania Ave NW",
      "street2": null,
      "city": "Washington",
      "state": "DC",
      "countryCode": "US",
      "postalCode": "20500",
      "addressType": "residential"
 }
}

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,
  "ignoreSecondaryAddressMismatch": false,
  "useSimplifiedCarrierValidation": false,
  "addressProperties": {
    "poBox": false
  },
  "candidate": {
    "street1": "1600 Pennsylvania Ave NW",
      "street2": null,
      "city": "Washington",
      "state": "DC",
      "countryCode": "US",
      "postalCode": "20500",
      "addressType": "residential"
},
  "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 Value	Description
`INVALID_UNKNOWN_REASON`	The validation source determined that the address was invalid but returned no additional information.
`MISSING_CITY`	A value for the required `city` field was not provided.
`MISSING_POSTALCODE`	A value for the required `postalCode` field was not provided.
`MISSING_REGION`	A value for the required `region` field was not provided.
`MISSING_STREET1`	A value for the required `street1` field was not provided.
`MALFORMED_ADDRESSTYPE`	Invalid address type in the call. If provided, `addressType` must be either commercial or residential.
`MALFORMED_POSTALCODE`	The postal code was in an invalid format for the region. For the US, `postalCode` must be of the format: `12345` or `12345-7890`.
`MISMATCH_ADDRESSTYPE`	The `addressType` provided in the call did not match the `addressType` of the validated address.
`MISMATCH_POSTALCODE`	The `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_REGION`	The provided state or region did not match with the address.
`MISMATCH_REGION_AND_POSTAL`	The provided postalCode is not valid for the state or region passed.
`MISMATCH_STREETLINES`	The 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 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:

Get started

Verify addresses with the Address Validation API

Authentication for API Calls

A note about "addressType"

Example cURL call

Example request body

Response codes

Example response body for a VALID address

Example response body for an INVALID address

Listing of error code values and descriptions

Listing of MISMATCH_STREETLINES error descriptions

Resources

A note about `"addressType"`