# 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](https://docs.shipium.com/docs/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](https://docs.shipium.com/docs/authentication). 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](https://docs.shipium.com/reference/validatev1).

## Required request fields

| Request field | Details |
| --- | --- |
| `address.street1` | **Type:** String<br>**Example:** `123 Main St.`<br>**Description:** The first address line |
| `address.city` | **Type:** String<br>**Example:** `Albuquerque`<br>**Description:** The name of the city for the address |
| `address.state` or `address.region` | **Type:** String<br>**Example:** `NM`<br>**Description:** The state or region for the address; provide either the state field or the region field. |
| `address.countryCode` | **Type:** String<br>**Example:** `US`<br>**Description:** The 2-character [ISO 3166-1 country code](https://docs.shipium.com/docs/non-us-address-formats) for the address |
| `address.postalCode` | **Type:** String<br>**Example:** `87121`<br>**Description:** A country-code-appropriate postal code for the address |

## Optional request fields

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

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

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

```json
{
  "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"
    }
  ]
}
```