Batch Verification

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.

Query ParametersExpand Collapse

geocode: optional boolean

includeDetails: optional boolean

properCase: 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 structured address object.

One of the following:

StandardFreeformAddressInput object { address }

address: string

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

StandardStructuredAddressInput object { address }

address: object { city, country, line1, 4 more }

city: string

The city of the address.

country: "ca" or "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: optional string

The second line of the address.

recipient: optional string

The optional firm/recipient name.

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, 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: optional string

The country name of the address.

details: optional object { 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: optional string

PO Box ID

county: optional string

County in the United States (US address only)

countyNum: optional string

FIPS code for county (US address only)

deliveryInstallationAreaName: optional string

Delivery installation area name

deliveryInstallationQualifier: optional string

Delivery installation qualifier

deliveryInstallationType: optional string

Delivery installation type

extraInfo: optional string

Any extra information relevant to the address

postDirection: optional string

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

preDirection: optional string

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

residential: optional boolean

Indicates that the address is residential (US address only)

ruralRouteNumber: optional string

Rural route number

ruralRouteType: optional string

Rural route type

streetDirection: optional string

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

streetName: optional string

Name of the street where the address is located

streetNumber: optional string

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

streetType: optional string

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

suiteID: optional string

The unit number/name

suiteKey: optional string

The suite key

usCensusBlockNumber: optional string

US Census block number

usCensusCMSA: optional string

US Census consolidated metropolitan statistical area

usCensusFIPS: optional string

US Census FIPS code (US address only)

usCensusMA: optional string

US Census metropolitan area

usCensusMSA: optional string

US Census metropolitan statistical area

usCensusPMSA: optional string

US Census primary metropolitan statistical area

usCensusTractNumber: optional string

US Census tract number

usCongressionalDistrictNumber: optional string

US congressional district number

usHasDaylightSavings: optional boolean

True if address location recognizes DST

usMailingCheckDigit: optional string

PostNet barcode digit

usMailingsCarrierRoute: optional string

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

usMailingsDefaultFlag: optional boolean

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

usMailingsDeliveryPoint: optional string

Unique USPS identifier for the delivery point

usMailingsDpvConfirmationIndicator: optional string

See USPS DPV

usMailingsDpvCrmaIndicator: optional string

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

usMailingsDpvFootnote1: optional string

See USPS DPV

usMailingsDpvFootnote2: optional string

See USPS DPV

usMailingsDpvFootnote3: optional string

See USPS DPV

usMailingsElotAscDesc: optional string

A for ascending, D for descending

usMailingsElotSequenceNumber: optional string

eLOT sequence number

usMailingsEWSFlag: optional string

Y if address is in early warning system database

usMailingsLACSFlag: optional string

Y if address converted by LACS

usMailingsLACSReturnCode: optional string

Corresponds to USPS LACSLink return code

usMailingsRecordTypeCode: optional string

See USPS DPV

usMailingsSuiteLinkReturnCode: optional string

See USPS DPV

usPostnetBarcode: optional string

PostNet barcode for the address (US address only)

usStateLegislativeLower: optional string

Lower legislative district for the US address

usStateLegislativeUpper: optional string

Upper legislative district for the US address

usTimeZone: optional string

Time zone for the US address area

vacant: optional boolean

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

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

geocodeResult: optional object { 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" or "point" or "range_interpolation" or 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: object { lat, lng }

Object that contains lat, lng properties with number values

lat: number

lng: number

line2: optional string

The second line of the address.

provinceOrStateName: optional string

The full name of the province or state.

status: optional Status

The verification status of an address.

One of the following:

"verified"

"corrected"

"failed"

zipPlus4: optional string

The zip plus 4 code of the address.

message: string

status: "success" or "error"

One of the following:

"success"

"error"

Batch Verification

curl https://api.postgrid.com/v1/addver/verifications/batch \
    -H 'Content-Type: application/json' \
    -H "X-API-Key: $POSTGRID_ADDRESS_VERIFICATION_API_KEY" \
    -d '{
          "addresses": [
            {
              "address": "address"
            }
          ]
        }'

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