## Batch Verification

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

Verify a batch of US or Canadian addresses in a single request.
Each address can be freeform or structured, matching the same input formats
accepted by the single verification endpoint.

- Uses 1 lookup per address (plus 1 more per address if geocoding).
- Requires a secret API key.
- Returns results in the same order as the input addresses.
- If an individual address fails, its result will contain an `error` field
  rather than a `verifiedAddress`.

### Query Parameters

- `geocode: optional boolean`

- `includeDetails: optional boolean`

- `properCase: optional boolean`

### Body Parameters

- `addresses: array of object { address }  or object { address }`

  Array of addresses to verify. Each item can be a freeform string or structured address object.

  - `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 { results }`

  - `results: array of object { error, verifiedAddress }`

    - `error: optional string`

      An error message for this address. Present when verification failed.

    - `verifiedAddress: optional object { city, country, line1, 11 more }`

      The verified address result. Present when verification succeeded.

      - `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, 45 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

        - `usCensusFIPS: optional string`

          US Census FIPS code (US address only)

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

        - `usPostnetBarcode: optional string`

          PostNet barcode for the address (US address only)

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

        - `postalOrZip: optional array of string`

          Errors related to the postal or ZIP code.

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

      - `provinceOrStateName: optional string`

        The full name of the province or state.

      - `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/batch \
    -H 'Content-Type: application/json' \
    -H "X-API-Key: $POSTGRID_ADDRESS_VERIFICATION_API_KEY" \
    -d '{
          "addresses": [
            {
              "address": "address"
            }
          ]
        }'
```

#### Response

```json
{
  "data": {
    "results": [
      {
        "error": "error",
        "verifiedAddress": {
          "city": "city",
          "country": "country",
          "line1": "line1",
          "postalOrZip": "postalOrZip",
          "provinceOrState": "provinceOrState",
          "countryName": "countryName",
          "details": {
            "boxID": "boxID",
            "county": "county",
            "countyNum": "countyNum",
            "deliveryInstallationAreaName": "deliveryInstallationAreaName",
            "deliveryInstallationQualifier": "deliveryInstallationQualifier",
            "deliveryInstallationType": "deliveryInstallationType",
            "extraInfo": "extraInfo",
            "postDirection": "postDirection",
            "preDirection": "preDirection",
            "residential": true,
            "ruralRouteNumber": "ruralRouteNumber",
            "ruralRouteType": "ruralRouteType",
            "streetDirection": "streetDirection",
            "streetName": "streetName",
            "streetNumber": "streetNumber",
            "streetType": "streetType",
            "suiteID": "suiteID",
            "suiteKey": "suiteKey",
            "usCensusBlockNumber": "usCensusBlockNumber",
            "usCensusCMSA": "usCensusCMSA",
            "usCensusFIPS": "usCensusFIPS",
            "usCensusMA": "usCensusMA",
            "usCensusMSA": "usCensusMSA",
            "usCensusPMSA": "usCensusPMSA",
            "usCensusTractNumber": "usCensusTractNumber",
            "usCongressionalDistrictNumber": "usCongressionalDistrictNumber",
            "usHasDaylightSavings": true,
            "usMailingCheckDigit": "usMailingCheckDigit",
            "usMailingsCarrierRoute": "usMailingsCarrierRoute",
            "usMailingsDefaultFlag": true,
            "usMailingsDeliveryPoint": "usMailingsDeliveryPoint",
            "usMailingsDpvConfirmationIndicator": "usMailingsDpvConfirmationIndicator",
            "usMailingsDpvCrmaIndicator": "usMailingsDpvCrmaIndicator",
            "usMailingsDpvFootnote1": "usMailingsDpvFootnote1",
            "usMailingsDpvFootnote2": "usMailingsDpvFootnote2",
            "usMailingsDpvFootnote3": "usMailingsDpvFootnote3",
            "usMailingsElotAscDesc": "usMailingsElotAscDesc",
            "usMailingsElotSequenceNumber": "usMailingsElotSequenceNumber",
            "usMailingsEWSFlag": "usMailingsEWSFlag",
            "usMailingsLACSFlag": "usMailingsLACSFlag",
            "usMailingsLACSReturnCode": "usMailingsLACSReturnCode",
            "usMailingsRecordTypeCode": "usMailingsRecordTypeCode",
            "usMailingsSuiteLinkReturnCode": "usMailingsSuiteLinkReturnCode",
            "usPostnetBarcode": "usPostnetBarcode",
            "usStateLegislativeLower": "usStateLegislativeLower",
            "usStateLegislativeUpper": "usStateLegislativeUpper",
            "usTimeZone": "usTimeZone",
            "vacant": true
          },
          "errors": {
            "city": [
              "string"
            ],
            "generic": [
              "string"
            ],
            "line1": [
              "string"
            ],
            "line2": [
              "string"
            ],
            "postalOrZip": [
              "string"
            ],
            "provinceOrState": [
              "string"
            ]
          },
          "firmName": "firmName",
          "geocodeResult": {
            "accuracy": 0,
            "accuracyType": "rooftop",
            "location": {
              "lat": 0,
              "lng": 0
            }
          },
          "line2": "line2",
          "provinceOrStateName": "provinceOrStateName",
          "status": "verified",
          "zipPlus4": "zipPlus4"
        }
      }
    ]
  },
  "message": "message",
  "status": "success"
}
```