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

- Accepts up to 2,000 addresses per request.
- 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`.
- If you are not subscribed and the batch would exceed your remaining free
  lookups, the entire batch fails (nothing is verified). Size your batch to
  the number of lookups you have left.

### 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"
}
```