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.

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.

📘

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.

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

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:

• Terms and Definitions

• Troubleshooting Guide

• Contact Shipium Support