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.

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

Optional request fields

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.

• 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. | | candidate | The 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. | | 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 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].errorDescription | If 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
}

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

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 an invalid address

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