Guides

Address Validation API

Validate addresses with Shipium's Address Validation API.

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.

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

Required request fields

Request fieldDetails
address.street1Type: String
Example: 123 Main St.
Description: The first address line
address.cityType: String
Example: Albuquerque
Description: The name of the city for the address
address.state or address.regionType: String
Example: NM
Description: The state or region for the address; provide either the state field or the region field.
address.countryCodeType: String
Example: US
Description: The 2-character ISO 3166-1 country code for the address
address.postalCodeType: String
Example: 87121
Description: A country-code-appropriate postal code for the address

Optional request fields

Request fieldDetails
ignoreSecondaryAddressMismatchType: Boolean
Values: true or false
Description: Set to true to ignore secondary address mismatches and addresses with extra information, whether provided as a value for street1 or street2. Default: false
useSimplifiedCarrierValidationType: Boolean
Values: true or false
Description: Set to true to ignore street address mismatches. Default: false
includeCandidateType: Boolean
Values: true or false
Description: When true, an address candidate will be included in the response if the address can be classified.
address.addressTypeType: String (enumeration)
Values: commercial or residential
Description: The type of location for the address; see the note below about the information provided for this field.
address.street2Type: String
Example: Suite 42
Description: The second address line
📘

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

Response attributes

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

Response attributeDescription
addressValidationIdA Shipium-generated ID that uniquely identifies this request
addressThe address that is to be validated by the API
validvalid will return true if the address is valid and false if not.
ignoreSecondaryAddressMismatchIndicates whether the secondary address components were validated
useSimplifiedCarrierValidationIndicates whether the street address(es) were validated
addressPropertiesFor valid addresses, additional properties of the address are populated here. Fields are only included when applicable to the address:
  • poBox - a boolean indicating if this address is a U.S. post office box (true) or not (false)
  • poBoxType - a string providing granular classification of PO box address types. Possible values: PO_BOX (Post Office Box), HC (Highway Contract Route), or RR (Rural Route)
  • militaryAddressType - a string identifying military and diplomatic postal service addresses. Possible values: APO (Army Post Office), FPO (Fleet Post Office), or DPO (Diplomatic Post Office); this field is returned only for APO, FPO, and DPO addresses. It is omitted for all other addresses, including standard domestic addresses and domestic military bases that use a standard ZIP code.
candidateThe address candidate that most closely matches the requested address. A candidate is returned only when includeCandidate is true and the address can be classified as a real, deliverable address. An address that cannot be classified returns no candidate, while an address that classifies successfully can return a candidate even when not every field matched exactly.
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 code identifying the error. Codes follow a consistent convention: MISSING_* when a required field is absent, MALFORMED_* when a field is present but not well-formed, and MISMATCH_* when a field is present and well-formed but disagrees with the validated address. See the full listing of error code values below.
details.[element].errorDescriptionIf there are more details available, the error description will be populated, but will otherwise be an empty string.

Example request and response for a valid address

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": "1415 Western Ave",
      "street2": "Ste 600",
      "city": "Seattle",
      "state": "WA",
      "countryCode": "US",
      "postalCode": "98101"
  },
  "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": "1415 Western Ave",
      "street2": "Ste 600",
      "city": "Seattle",
      "state": "WA",
      "countryCode": "US",
      "postalCode": "98101",
      "addressType": "commercial"
  },
  "valid": true,
  "ignoreSecondaryAddressMismatch": false,
  "useSimplifiedCarrierValidation": false,
  "addressProperties": {
    "poBox": false
  },
  "candidate": {
      "street1": "1415 Western Ave",
      "street2": "Ste 600",
      "city": "Seattle",
      "state": "WA",
      "countryCode": "US",
      "postalCode": "98101",
      "addressType": "commercial"
  }
}

Additional response examples

The examples below show only the response body. Each uses the same request structure shown above, with a different address submitted.

Example response body for a valid address with a PO box

{
  "addressValidationId": "4d9e3ad7-a54b-43a6-92b7-214a8e93d793",
  "address": {
    "street1": "PO Box 4721",
    "street2": null,
    "city": "Springfield",
    "state": "IL",
    "countryCode": "US",
    "postalCode": "62704",
    "addressType": "residential"
  },
  "valid": true,
  "ignoreSecondaryAddressMismatch": false,
  "useSimplifiedCarrierValidation": false,
  "addressProperties": {
    "poBox": true,
    "poBoxType": "PO_BOX"
  },
  "candidate": {
    "street1": "PO Box 4721",
    "street2": null,
    "city": "Springfield",
    "state": "IL",
    "countryCode": "US",
    "postalCode": "62704",
    "addressType": "residential"
  }
}

Example response body for a valid address with a military address

📘

When militaryAddressType is returned

militaryAddressType is included only for APO, FPO, and DPO addresses. Standard domestic addresses do not return a militaryAddressType, and neither do domestic military bases that use a standard ZIP code. The absence of the field for those addresses is expected and does not indicate an error.

{
  "addressValidationId": "4d9e3ad7-a54b-43a6-92b7-214a8e93d793",
  "address": {
      "street1": "UNIT 2050 BOX 4190",
      "street2": null,
      "city": "APO",
      "state": "AE",
      "countryCode": "US",
      "postalCode": "09421",
      "addressType": null
  },
  "valid": true,
  "ignoreSecondaryAddressMismatch": false,
  "useSimplifiedCarrierValidation": false,
  "addressProperties": {
    "poBox": false,
    "militaryAddressType": "APO"
  },
  "candidate": {
    "street1": "UNIT 2050 BOX 4190",
    "street2": null,
    "city": "APO",
    "state": "AE",
    "countryCode": "US",
    "postalCode": "09421",
    "addressType": null
  }
}

Example response body for an invalid address

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

{
  "addressValidationId": "fe3244a0-f7d7-4aaa-9d31-85718505a761",
  "address": {
      "street1": "742 Evergreen ST",
      "street2": null,
      "city": "Springfield",
      "state": "IL",
      "countryCode": "US",
      "postalCode": "62704",
      "addressType": "residential"
  },
  "valid": false,
  "ignoreSecondaryAddressMismatch": false,
  "useSimplifiedCarrierValidation": false,
  "addressProperties": {
    "poBox": false
  },
  "candidate": {
      "street1": "742 Evergreen Ave",
      "street2": null,
      "city": "Springfield",
      "state": "IL",
      "countryCode": "US",
      "postalCode": "62704",
      "addressType": "residential"
  },
  "details": [
    {
      "errorCode": "MISMATCH_STREETLINES",
      "errorDescription": "The provided street line: 742 Evergreen ST does not match detected: 742 EVERGREEN AVE 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_REGIONNeither a state nor a region was provided. Either one satisfies this field.
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.
MALFORMED_REGIONA state or region was provided but is not a recognized ISO 3166-2 code.
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_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: