Batch Verification

client.intlAddressVerification.batchVerification(, ?): IntlAddressVerificationBatchVerificationResponse { data, message, status }

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.

ParametersExpand Collapse

params: IntlAddressVerificationBatchVerificationParams { addresses, geoData, includeDetails, 2 more }

addresses: Array<StructuredAddressInput { address } | FreeformAddressInput { address } >

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

One of the following:

StructuredAddressInput { address }

Input model for structured international address verification.

address: Address { 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?: string

The city, town, or locality of the address.

line2?: string

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

line3?: string

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

line4?: string

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

FreeformAddressInput { address }

Input model for freeform international address verification.

address: string

The full address as a single string.

geoData?: boolean

Query param

includeDetails?: boolean

Query param

properCase?: boolean

Query param

useEnhancedChinaDataset?: boolean

Query param

ReturnsExpand Collapse

IntlAddressVerificationBatchVerificationResponse { data, message, status }

data: Data { results }

results: Array<Result>

error?: string

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

verifiedAddress?: VerifiedAddress { 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?: string

The full country name.

details?: Details { building, buildingType, cityName, 30 more }

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

building?: string

The building name or number.

buildingType?: string

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

cityName?: string

The full city name.

citySecondary?: string

Secondary city information.

cityType?: string

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

deliveryAddress?: string

The full delivery address.

dependentLocality?: string

The dependent locality (UK addresses).

doubleDependentLocality?: string

The double dependent locality (UK addresses).

organization?: string

The organization or company name.

postalOrZipPrimary?: string

The primary part of the postal or ZIP code.

postalOrZipSecondary?: string

The secondary part of the postal or ZIP code.

postBox?: string

The post box number.

premise?: string

The premise name or number.

premiseNumber?: string

The premise number.

premiseSecondary?: string

Secondary premise information.

premiseType?: string

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

provinceOrStateName?: string

The full name of the province or state.

provinceOrStateType?: string

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

street?: string

The street name.

streetPostDirection?: string

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

streetPreDirection?: string

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

streetType?: string

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

subAdministrativeArea?: string

The sub-administrative area.

subBuilding?: string

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

SubBuildingFloor?: string

The floor of the sub-building.

subBuildingNumber?: string

The sub-building number.

subBuildingType?: string

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

subStreet?: string

The sub-street name.

subStreetPostDirection?: string

The directional suffix for the sub-street.

subStreetPreDirection?: string

The directional prefix for the sub-street.

subStreetType?: string

The type of sub-street.

superAdministrativeArea?: string

The super-administrative area.

telephone?: string

The telephone number associated with the address.

errors?: Errors { city, generic, line1, 3 more }

Errors encountered during address verification.

city?: Array<string>

Errors related to the city.

generic?: Array<string>

Generic errors not tied to a specific field.

line1?: Array<string>

Errors related to the first address line.

line2?: Array<string>

Errors related to the second address line.

postalOrZip?: Array<string>

Errors related to the postal or ZIP code.

provinceOrState?: Array<string>

Errors related to the province or state.

firmName?: string

The firm or company name, if available.

formattedAddress?: string

The formatted address string.

geoData?: GeoData { geoAccuracy, latitude, longitude }

Geocoding result for the verified address.

geoAccuracy?: string

The geocode accuracy.

latitude?: string

The latitude of the address.

longitude?: string

The longitude of the address.

line2?: string

The second address line.

line3?: string

The third address line, if available.

status?: Status

The verification status of an address.

One of the following:

"verified"

"corrected"

"failed"

summary?: Summary { contextIdentificationMatchLevel, lexiconIdentificationMatchLevel, matchScore, 6 more }

A summary of the verification process and match levels.

contextIdentificationMatchLevel?: string

Context identification match level.

lexiconIdentificationMatchLevel?: string

Lexicon identification match level.

matchScore?: number

The match score (0-100).

message?: string

Additional message about the verification.

parsingStatus?: string

The parsing status of the address.

postCodeStatus?: string

The status of the postal code.

postProcessedVerificationMatchLevel?: string

The match level after post-processing.

preProcessedVerificationMatchLevel?: string

The match level before post-processing.

verificationStatus?: string

The overall verification status.

zipPlus4?: string

The ZIP+4 code (for US addresses).

message: string

status: "success" | "error"

One of the following:

"success"

"error"

Batch Verification

import PostGrid from 'postgrid-node';

const client = new PostGrid({
  addressVerificationAPIKey: process.env['POSTGRID_ADDRESS_VERIFICATION_API_KEY'], // This is the default and can be omitted
});

const response = await client.intlAddressVerification.batchVerification({
  addresses: [
    {
      address: {
        country: 'country',
        line1: 'line1',
        postalOrZip: 'postalOrZip',
        provinceOrState: 'provinceOrState',
      },
    },
  ],
});

console.log(response.data);

{
  "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"
}

Returns Examples

{
  "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"
}