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

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

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