Batch Verification

client.addressVerification.batchVerification(, ?): 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.

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.

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 support@postgrid.com. 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"
}