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 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 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 field	Details
`address.street1`	Type: String Example: `123 Main St.` Description: The first address line
`address.city`	Type: String Example: `Albuquerque` Description: The name of the city for the address
`address.state` or `address.region`	Type: String Example: `NM` Description: The state or region for the address; provide either the state field or the region field.
`address.countryCode`	Type: String Example: `US` Description: The 2-character ISO 3166-1 country code for the address
`address.postalCode`	Type: String Example: `87121` Description: A country-code-appropriate postal code for the address

Optional request fields

Request field	Details
`ignoreSecondaryAddressMismatch`	Type: Boolean Values: `true` or `false` Description: Set to `true` to ignore secondary address mismatches and addresses with extra information. Default: `false`
`useSimplifiedCarrierValidation`	Type: Boolean Values: `true` or `false` Description: Set to `true` to ignore street address mismatches. Default: `false`
`includeCandidate`	Type: Boolean Values: `true` or `false` Description: When `true`, an address candidate will be included in the response if the address can be classified.
`address.addressType`	Type: String (enumeration) Values: `commercial` or `residential` Description: The type of location for the address.
`address.street2`	Type: 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 an "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 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.
`candidate`	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).

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