## Batch Verification

**post** `/v1/intl_addver/verifications/batch`

Verify a batch of international 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.
- 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

- `geoData: optional boolean`

- `includeDetails: optional boolean`

- `properCase: optional boolean`

- `useEnhancedChinaDataset: 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 a structured address object.

  - `StructuredAddressInput object { address }`

    Input model for structured international address verification.

    - `address: object { country, line1, postalOrZip, 5 more }`

      - `country: string`

        The country code (ISO 3166-1 alpha-2 or alpha-3).

      - `line1: string`

        The first line of the address (e.g., street address, building, etc.).

      - `postalOrZip: string`

        The postal or ZIP code.

      - `provinceOrState: string`

        The administrative area (e.g., state, province, region).

      - `city: optional string`

        The city, town, or locality of the address.

      - `line2: optional string`

        The second line of the address (e.g., apartment, suite, etc.).

      - `line3: optional string`

        The third line of the address (e.g., additional locality or delivery info).

      - `line4: optional string`

        The fourth line of the address (e.g., further address details).

  - `FreeformAddressInput object { address }`

    Input model for freeform international address verification.

    - `address: string`

      The full address as a single string.

### 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, 13 more }`

      The result of a verified international address.

      - `city: string`

        The city or locality.

      - `country: string`

        The country code (ISO 3166-1 alpha-2).

      - `line1: string`

        The first address line.

      - `postalOrZip: string`

        The postal or ZIP code.

      - `provinceOrState: string`

        The province or state.

      - `countryName: optional string`

        The full country name.

      - `details: optional object { building, buildingType, cityName, 30 more }`

        Additional details about the verified address, such as premise, thoroughfare, and locality.

        - `building: optional string`

          The building name or number.

        - `buildingType: optional string`

          The type of building (e.g., apartment, office).

        - `cityName: optional string`

          The full city name.

        - `citySecondary: optional string`

          Secondary city information.

        - `cityType: optional string`

          The type of city (e.g., city, town, village).

        - `deliveryAddress: optional string`

          The full delivery address.

        - `dependentLocality: optional string`

          The dependent locality (UK addresses).

        - `doubleDependentLocality: optional string`

          The double dependent locality (UK addresses).

        - `organization: optional string`

          The organization or company name.

        - `postalOrZipPrimary: optional string`

          The primary part of the postal or ZIP code.

        - `postalOrZipSecondary: optional string`

          The secondary part of the postal or ZIP code.

        - `postBox: optional string`

          The post box number.

        - `premise: optional string`

          The premise name or number.

        - `premiseNumber: optional string`

          The premise number.

        - `premiseSecondary: optional string`

          Secondary premise information.

        - `premiseType: optional string`

          The type of premise (e.g., house, flat).

        - `provinceOrStateName: optional string`

          The full name of the province or state.

        - `provinceOrStateType: optional string`

          The type of province or state (e.g., province, state, region).

        - `street: optional string`

          The street name.

        - `streetPostDirection: optional string`

          The directional suffix for the street (e.g., N, S, E, W).

        - `streetPreDirection: optional string`

          The directional prefix for the street (e.g., N, S, E, W).

        - `streetType: optional string`

          The type of street (e.g., St, Ave, Blvd).

        - `subAdministrativeArea: optional string`

          The sub-administrative area.

        - `subBuilding: optional string`

          The sub-building name or number (e.g., unit, suite).

        - `SubBuildingFloor: optional string`

          The floor of the sub-building.

        - `subBuildingNumber: optional string`

          The sub-building number.

        - `subBuildingType: optional string`

          The type of sub-building (e.g., floor, wing).

        - `subStreet: optional string`

          The sub-street name.

        - `subStreetPostDirection: optional string`

          The directional suffix for the sub-street.

        - `subStreetPreDirection: optional string`

          The directional prefix for the sub-street.

        - `subStreetType: optional string`

          The type of sub-street.

        - `superAdministrativeArea: optional string`

          The super-administrative area.

        - `telephone: optional string`

          The telephone number associated with the address.

      - `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 or company name, if available.

      - `formattedAddress: optional string`

        The formatted address string.

      - `geoData: optional object { geoAccuracy, latitude, longitude }`

        Geocoding result for the verified address.

        - `geoAccuracy: optional string`

          The geocode accuracy.

        - `latitude: optional string`

          The latitude of the address.

        - `longitude: optional string`

          The longitude of the address.

      - `line2: optional string`

        The second address line.

      - `line3: optional string`

        The third address line, if available.

      - `status: optional Status`

        The verification status of an address.

        - `"verified"`

        - `"corrected"`

        - `"failed"`

      - `summary: optional object { contextIdentificationMatchLevel, lexiconIdentificationMatchLevel, matchScore, 6 more }`

        A summary of the verification process and match levels.

        - `contextIdentificationMatchLevel: optional string`

          Context identification match level.

        - `lexiconIdentificationMatchLevel: optional string`

          Lexicon identification match level.

        - `matchScore: optional number`

          The match score (0-100).

        - `message: optional string`

          Additional message about the verification.

        - `parsingStatus: optional string`

          The parsing status of the address.

        - `postCodeStatus: optional string`

          The status of the postal code.

        - `postProcessedVerificationMatchLevel: optional string`

          The match level after post-processing.

        - `preProcessedVerificationMatchLevel: optional string`

          The match level before post-processing.

        - `verificationStatus: optional string`

          The overall verification status.

      - `zipPlus4: optional string`

        The ZIP+4 code (for US addresses).

- `message: string`

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

  - `"success"`

  - `"error"`

### Example

```http
curl https://api.postgrid.com/v1/intl_addver/verifications/batch \
    -H 'Content-Type: application/json' \
    -H "X-API-Key: $POSTGRID_ADDRESS_VERIFICATION_API_KEY" \
    -d '{
          "addresses": [
            {
              "address": {
                "country": "country",
                "line1": "line1",
                "postalOrZip": "postalOrZip",
                "provinceOrState": "provinceOrState"
              }
            }
          ]
        }'
```

#### Response

```json
{
  "data": {
    "results": [
      {
        "error": "error",
        "verifiedAddress": {
          "city": "city",
          "country": "country",
          "line1": "line1",
          "postalOrZip": "postalOrZip",
          "provinceOrState": "provinceOrState",
          "countryName": "countryName",
          "details": {
            "building": "building",
            "buildingType": "buildingType",
            "cityName": "cityName",
            "citySecondary": "citySecondary",
            "cityType": "cityType",
            "deliveryAddress": "deliveryAddress",
            "dependentLocality": "dependentLocality",
            "doubleDependentLocality": "doubleDependentLocality",
            "organization": "organization",
            "postalOrZipPrimary": "postalOrZipPrimary",
            "postalOrZipSecondary": "postalOrZipSecondary",
            "postBox": "postBox",
            "premise": "premise",
            "premiseNumber": "premiseNumber",
            "premiseSecondary": "premiseSecondary",
            "premiseType": "premiseType",
            "provinceOrStateName": "provinceOrStateName",
            "provinceOrStateType": "provinceOrStateType",
            "street": "street",
            "streetPostDirection": "streetPostDirection",
            "streetPreDirection": "streetPreDirection",
            "streetType": "streetType",
            "subAdministrativeArea": "subAdministrativeArea",
            "subBuilding": "subBuilding",
            "SubBuildingFloor": "SubBuildingFloor",
            "subBuildingNumber": "subBuildingNumber",
            "subBuildingType": "subBuildingType",
            "subStreet": "subStreet",
            "subStreetPostDirection": "subStreetPostDirection",
            "subStreetPreDirection": "subStreetPreDirection",
            "subStreetType": "subStreetType",
            "superAdministrativeArea": "superAdministrativeArea",
            "telephone": "telephone"
          },
          "errors": {
            "city": [
              "string"
            ],
            "generic": [
              "string"
            ],
            "line1": [
              "string"
            ],
            "line2": [
              "string"
            ],
            "postalOrZip": [
              "string"
            ],
            "provinceOrState": [
              "string"
            ]
          },
          "firmName": "firmName",
          "formattedAddress": "formattedAddress",
          "geoData": {
            "geoAccuracy": "geoAccuracy",
            "latitude": "latitude",
            "longitude": "longitude"
          },
          "line2": "line2",
          "line3": "line3",
          "status": "verified",
          "summary": {
            "contextIdentificationMatchLevel": "contextIdentificationMatchLevel",
            "lexiconIdentificationMatchLevel": "lexiconIdentificationMatchLevel",
            "matchScore": 0,
            "message": "message",
            "parsingStatus": "parsingStatus",
            "postCodeStatus": "postCodeStatus",
            "postProcessedVerificationMatchLevel": "postProcessedVerificationMatchLevel",
            "preProcessedVerificationMatchLevel": "preProcessedVerificationMatchLevel",
            "verificationStatus": "verificationStatus"
          },
          "zipPlus4": "zipPlus4"
        }
      }
    ]
  },
  "message": "message",
  "status": "success"
}
```