Skip to content
PostGrid PostGrid
Get startedDashboardSupport
API Reference
Address Verification

Batch Verification

client.addressVerification.batchVerification(AddressVerificationBatchVerificationParams { addresses, geocode, includeDetails, properCase } params, RequestOptionsoptions?): AddressVerificationBatchVerificationResponse { data, message, status }
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.
ParametersExpand Collapse
params: AddressVerificationBatchVerificationParams { addresses, geocode, includeDetails, properCase }
addresses: Array<StandardFreeformAddressInput { address } | StandardStructuredAddressInput { address } >

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

One of the following:
StandardFreeformAddressInput { address }
address: string

The address you want to verify, written on a single line.

StandardStructuredAddressInput { address }
address: Address { city, country, line1, 4 more }
city: string

The city of the address.

country: "ca" | "us"

The country of your address, one of ca or us.

One of the following:
"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?: string

The second line of the address.

recipient?: string

The optional firm/recipient name.

geocode?: boolean

Query param

includeDetails?: boolean

Query param

properCase?: boolean

Query param

ReturnsExpand Collapse
AddressVerificationBatchVerificationResponse { 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, 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?: string

The country name of the address.

details?: Details { 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 schema.

boxID?: string

PO Box ID

county?: string

County in the United States (US address only)

countyNum?: string

FIPS code for county (US address only)

deliveryInstallationAreaName?: string

Delivery installation area name

deliveryInstallationQualifier?: string

Delivery installation qualifier

deliveryInstallationType?: string

Delivery installation type

extraInfo?: string

Any extra information relevant to the address

postDirection?: string

The post-direction of the street (after the street name, US addresses only)

preDirection?: string

The pre-direction of the street (before the street name, US addresses only)

residential?: boolean

Indicates that the address is residential (US address only)

ruralRouteNumber?: string

Rural route number

ruralRouteType?: string

Rural route type

streetDirection?: string

The direction of the street (N, S, E, W, etc)

streetName?: string

Name of the street where the address is located

streetNumber?: string

Street number (e.g. the 20 in 20 Bay St)

streetType?: string

Type of the street (DR, ST, BLVD, etc)

suiteID?: string

The unit number/name

suiteKey?: string

The suite key

usCensusBlockNumber?: string

US Census block number

usCensusCMSA?: string

US Census consolidated metropolitan statistical area

usCensusFIPS?: string

US Census FIPS code (US address only)

usCensusMA?: string

US Census metropolitan area

usCensusMSA?: string

US Census metropolitan statistical area

usCensusPMSA?: string

US Census primary metropolitan statistical area

usCensusTractNumber?: string

US Census tract number

usCongressionalDistrictNumber?: string

US congressional district number

usHasDaylightSavings?: boolean

True if address location recognizes DST

usMailingCheckDigit?: string

PostNet barcode digit

usMailingsCarrierRoute?: string

4-character code assigned to mail delivery route within a 5 digit zip code

usMailingsDefaultFlag?: boolean

True if US address matches a high-rise default or rural route default in the USPS data

usMailingsDeliveryPoint?: string

Unique USPS identifier for the delivery point

usMailingsDpvConfirmationIndicator?: string

See USPS DPV

usMailingsDpvCrmaIndicator?: string

Y if this is a commercial mail receiving agency, N otherwise

usMailingsDpvFootnote1?: string

See USPS DPV

usMailingsDpvFootnote2?: string

See USPS DPV

usMailingsDpvFootnote3?: string

See USPS DPV

usMailingsElotAscDesc?: string

A for ascending, D for descending

usMailingsElotSequenceNumber?: string

eLOT sequence number

usMailingsEWSFlag?: string

Y if address is in early warning system database

usMailingsLACSFlag?: string

Y if address converted by LACS

usMailingsLACSReturnCode?: string

Corresponds to USPS LACSLink return code

usMailingsRecordTypeCode?: string

See USPS DPV

usMailingsSuiteLinkReturnCode?: string

See USPS DPV

usPostnetBarcode?: string

PostNet barcode for the address (US address only)

usStateLegislativeLower?: string

Lower legislative district for the US address

usStateLegislativeUpper?: string

Upper legislative district for the US address

usTimeZone?: string

Time zone for the US address area

vacant?: boolean

Indicates that the address is vacant according to the USPS (US address only)

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 name of the address.

geocodeResult?: GeocodeResult { accuracy, accuracyType, location }

If the geocode=true query parameter is supplied, the response will include a geocodeResult which follows the Geocoding schema. You can request this feature be enabled by emailing [email protected]. 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

accuracyType: "rooftop" | "point" | "range_interpolation" | 5 more

A string representing the accuracy type

One of the following:
"rooftop"
"point"
"range_interpolation"
"nearest_rooftop_match"
"intersection"
"street_center"
"place"
"state"
location: Location { lat, lng }

Object that contains lat, lng properties with number values

lat: number
lng: number
line2?: string

The second line of the address.

provinceOrStateName?: string

The full name of the province or state.

status?: Status

The verification status of an address.

One of the following:
"verified"
"corrected"
"failed"
zipPlus4?: string

The zip plus 4 code of the address.

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.addressVerification.batchVerification({
  addresses: [{ address: 'address' }],
});

console.log(response.data);
{
  "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"
}
Returns Examples
{
  "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"
}