# Address Verification

## Verify

**post** `/v1/addver/verifications`

1. **Structured Address** — Verify and standardize a structured address (e.g., with `line1`, `city`, etc.).
1. **Freeform Address** — Verify and standardize a freeform address written on one line. For best results, append the ISO 2-letter country code (e.g., `US`, `CA`) to the end of the line.

- Specifying `includeDetails=true` will provide additional output as documented in the `Details` schema.
- Uses 1 lookup for verification, and 1 more if geocoding (unless your contract says otherwise).

### Query Parameters

- `geocode: optional boolean`

- `includeDetails: optional boolean`

- `properCase: optional boolean`

### Body Parameters

- `body: object { address }  or object { address }`

  - `StandardFreeformAddressInput = object { address }`

    - `address: string`

      The address you want to verify, written on a single line.

  - `StandardStructuredAddressInput = object { address }`

    - `address: object { city, country, line1, 4 more }`

      - `city: string`

        The city of the address.

      - `country: "ca" or "us"`

        The country of your address, one of `ca` or `us`.

        - `"ca"`

        - `"us"`

      - `line1: string`

        The first line of the address.

      - `postalOrZip: string`

        The postal code or ZIP code of the address.

      - `provinceOrState: string`

        The province or state of the address.

      - `line2: optional string`

        The second line of the address.

      - `recipient: optional string`

        The optional firm/recipient name.

### Returns

- `data: object { city, country, line1, 10 more }`

  - `city: string`

    The city name of the address.

  - `country: string`

    The country code of the address.

  - `line1: string`

    The first line of the address.

  - `postalOrZip: string`

    The postal code or ZIP code of the address.

  - `provinceOrState: string`

    The province or state of the address.

  - `countryName: optional string`

    The country name of the address.

  - `details: optional object { boxID, county, countyNum, 43 more }`

    If you supply `includeDetails=true` as a query parameter, we will also populate an additional `details` field that follows the [Address Details](https://avdocs.postgrid.com/#address-details) schema.

    - `boxID: optional string`

      PO Box ID

    - `county: optional string`

      County in the United States (US address only)

    - `countyNum: optional string`

      FIPS code for county (US address only)

    - `deliveryInstallationAreaName: optional string`

      Delivery installation area name

    - `deliveryInstallationQualifier: optional string`

      Delivery installation qualifier

    - `deliveryInstallationType: optional string`

      Delivery installation type

    - `extraInfo: optional string`

      Any extra information relevant to the address

    - `postDirection: optional string`

      The post-direction of the street (after the street name, US addresses only)

    - `preDirection: optional string`

      The pre-direction of the street (before the street name, US addresses only)

    - `residential: optional boolean`

      Indicates that the address is residential (US address only)

    - `ruralRouteNumber: optional string`

      Rural route number

    - `ruralRouteType: optional string`

      Rural route type

    - `streetDirection: optional string`

      The direction of the street (N, S, E, W, etc)

    - `streetName: optional string`

      Name of the street where the address is located

    - `streetNumber: optional string`

      Street number (e.g. the 20 in 20 Bay St)

    - `streetType: optional string`

      Type of the street (DR, ST, BLVD, etc)

    - `suiteID: optional string`

      The unit number/name

    - `suiteKey: optional string`

      The suite key

    - `usCensusBlockNumber: optional string`

      US Census block number

    - `usCensusCMSA: optional string`

      US Census consolidated metropolitan statistical area

    - `usCensusMA: optional string`

      US Census metropolitan area

    - `usCensusMSA: optional string`

      US Census metropolitan statistical area

    - `usCensusPMSA: optional string`

      US Census primary metropolitan statistical area

    - `usCensusTractNumber: optional string`

      US Census tract number

    - `usCongressionalDistrictNumber: optional string`

      US congressional district number

    - `usHasDaylightSavings: optional boolean`

      True if address location recognizes DST

    - `usMailingCheckDigit: optional string`

      PostNet barcode digit

    - `usMailingsCarrierRoute: optional string`

      4-character code assigned to mail delivery route within a 5 digit zip code

    - `usMailingsDefaultFlag: optional boolean`

      True if US address matches a high-rise default or rural route default in the USPS data

    - `usMailingsDeliveryPoint: optional string`

      Unique USPS identifier for the delivery point

    - `usMailingsDpvConfirmationIndicator: optional string`

      See [USPS DPV](https://avdocs.postgrid.com/#usps-dpv)

    - `usMailingsDpvCrmaIndicator: optional string`

      Y if this is a commercial mail receiving agency, N otherwise

    - `usMailingsDpvFootnote1: optional string`

      See [USPS DPV](https://avdocs.postgrid.com/#usps-dpv)

    - `usMailingsDpvFootnote2: optional string`

      See [USPS DPV](https://avdocs.postgrid.com/#usps-dpv)

    - `usMailingsDpvFootnote3: optional string`

      See [USPS DPV](https://avdocs.postgrid.com/#usps-dpv)

    - `usMailingsElotAscDesc: optional string`

      A for ascending, D for descending

    - `usMailingsElotSequenceNumber: optional string`

      eLOT sequence number

    - `usMailingsEWSFlag: optional string`

      Y if address is in early warning system database

    - `usMailingsLACSFlag: optional string`

      Y if address converted by LACS

    - `usMailingsLACSReturnCode: optional string`

      Corresponds to USPS LACSLink return code

    - `usMailingsRecordTypeCode: optional string`

      See [USPS DPV](https://avdocs.postgrid.com/#usps-dpv)

    - `usMailingsSuiteLinkReturnCode: optional string`

      See [USPS DPV](https://avdocs.postgrid.com/#usps-dpv)

    - `usStateLegislativeLower: optional string`

      Lower legislative district for the US address

    - `usStateLegislativeUpper: optional string`

      Upper legislative district for the US address

    - `usTimeZone: optional string`

      Time zone for the US address area

    - `vacant: optional boolean`

      Indicates that the address is vacant according to the USPS (US address only)

  - `errors: optional Errors`

    Errors encountered during address verification.

    - `city: optional array of string`

      Errors related to the city.

    - `generic: optional array of string`

      Generic errors not tied to a specific field.

    - `line1: optional array of string`

      Errors related to the first address line.

    - `line2: optional array of string`

      Errors related to the second address line.

    - `provinceOrState: optional array of string`

      Errors related to the province or state.

  - `firmName: optional string`

    The firm name of the address.

  - `geocodeResult: optional object { accuracy, accuracyType, location }`

    If the `geocode=true` query parameter is supplied, the response will include a geocodeResult
    which follows the [Geocoding](https://avdocs.postgrid.com/#geocoding) schema.  You can request
    this feature be enabled by emailing `support@postgrid.com`. This includes our verification, batch
    verification, suggestions, and POST /completions endpoint. Note that you must supply country when
    geocoding to get the result successfully.

    - `accuracy: number`

      A real number from 0.00 to 1.00 which represents an [accuracy score](https://avdocs.postgrid.com/#accuracy-score)

    - `accuracyType: "rooftop" or "point" or "range_interpolation" or 5 more`

      A string representing the [accuracy type](https://avdocs.postgrid.com/#accuracy-type)

      - `"rooftop"`

      - `"point"`

      - `"range_interpolation"`

      - `"nearest_rooftop_match"`

      - `"intersection"`

      - `"street_center"`

      - `"place"`

      - `"state"`

    - `location: object { lat, lng }`

      Object that contains `lat`, `lng` properties with number values

      - `lat: number`

      - `lng: number`

  - `line2: optional string`

    The second line of the address.

  - `status: optional Status`

    The verification status of an address.

    - `"verified"`

    - `"corrected"`

    - `"failed"`

  - `zipPlus4: optional string`

    The zip plus 4 code of the address.

- `message: string`

- `status: "success" or "error"`

  - `"success"`

  - `"error"`

### Example

```http
curl https://api.postgrid.com/v1/addver/verifications \
    -H 'Content-Type: application/json' \
    -H "X-API-Key: $POSTGRID_ADDRESS_VERIFICATION_API_KEY" \
    -d '{
          "address": "address"
        }'
```

#### Response

```json
{
  "status": "success",
  "message": "Address verified successfully",
  "data": {
    "city": "Los Angeles",
    "country": "US",
    "line1": "1234 Elm St",
    "postalOrZip": "90001",
    "provinceOrState": "CA",
    "status": "verified",
    "errors": {}
  }
}
```

## Domain Types

### Errors

- `Errors = object { city, generic, line1, 2 more }`

  Errors encountered during address verification.

  - `city: optional array of string`

    Errors related to the city.

  - `generic: optional array of string`

    Generic errors not tied to a specific field.

  - `line1: optional array of string`

    Errors related to the first address line.

  - `line2: optional array of string`

    Errors related to the second address line.

  - `provinceOrState: optional array of string`

    Errors related to the province or state.

### Status

- `Status = "verified" or "corrected" or "failed"`

  The verification status of an address.

  - `"verified"`

  - `"corrected"`

  - `"failed"`