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 ParametersExpand Collapse

geoData: optional boolean

includeDetails: optional boolean

properCase: optional boolean

useEnhancedChinaDataset: optional boolean

Body ParametersJSONExpand Collapse

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.

One of the following:

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.

ReturnsExpand Collapse

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 { city, generic, line1, 3 more }

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.

One of the following:

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

One of the following:

"success"

"error"

Batch Verification

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"
              }
            }
          ]
        }'

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