Core Concepts

The PostGrid Address Verification API lets you autocomplete, verify, and standardize addresses in real-time. It also offers batch verification, which lets you do the same for thousands of addresses per second.

Prefer to work in your own tooling? Download the OpenAPI spec to import the API into Postman, Insomnia, a code generator, or any OpenAPI-compatible app.

Download the OpenAPI spec

There are two APIs:

• The Standard API covers US and Canadian addresses, with USPS delivery point verification (DPV) detail and geocoding.
• The International API covers addresses worldwide, with international match-level verification.

You can also access the PostGrid dashboard to bulk verify lists without having to use the API.

Note that you can supply JSON data instead of urlencoded data for all endpoints. Also note that the API key shown in the examples is just an example — please create a new key on the dashboard.

Authorization

You can authorize your HTTP requests by setting the x-api-key HTTP header to your API key.

API Keys

You can create an API key by accessing the Developers section of the platform. There, you can click “Create new access key” and select the type of key you want. For batch verification, you must use a secret key.

Rate Limit

All API endpoints (except preview endpoints) have a default rate limit of 5 requests per second. Users are encouraged to use the batch verification endpoint (POST /addver/verifications/batch) for processing a large number of addresses. To increase the rate limit, reach out to [email protected].

Maximizing Throughput

In the event that you are verifying millions of addresses, we recommend doing at most 2 concurrent calls with batch sizes of 2000 addresses each. In general, your throughput is limited to 100 addresses per second, so making more concurrent calls will not necessarily speed up the overall process. If you would like to increase your effective throughput, reach out to [email protected].

Integration

If you’re looking to install autocomplete and verification on a website, you can access the Developers section of the dashboard, create a public key, and then click on the API key name. This will show you a guide for installing our pre-built integration on your website without having to access the API directly.

Otherwise, you can use the endpoints documented in the API reference to create a completely custom integration.

Response

The top-level JSON response has the following structure:

Name	Type	Description
status	string	Either success or error
message	string	Describes the result of the request
data	object or array	The response data.

Proper Case

You can have the verification and suggestion endpoints return addresses in Proper Case (e.g. 22-20 Bay St) by supplying a query parameter properCase=true.

Standard Address Verification (US & Canada)

The Standard API verifies, corrects, and standardizes addresses in the United States and Canada.

Integrating Autocomplete

We provide a pre-built web-based autocomplete integration in the Developers section of the dashboard. However, if you want to integrate autocomplete manually, here are our recommended steps:

1. Use the GET /completions endpoint and supply partialStreet via the query params.
   • This endpoint does not use any lookups.
2. Allow the user to select one of the autocompleted address previews.
3. Make a POST /completions?index=N request where N is the index of the address the user selected.

If you follow these steps, there will only be 1 lookup made in total (when the user selects the address).

Errors

This object is returned from the verification and autocomplete endpoints to describe issues or incomplete aspects of the given address that were either fixed (which the verification endpoint will always attempt to do) or caused verification failure.

Name	Type	Description
line1	array of string	Issues related to the first line of the address
line2	array of string	Issues related to the second line of the address
city	array of string	Issues related to the city
provinceOrState	array of string	Issues related to the province or state
generic	array of string	Issues with the address in general

Verification

This is the data returned from the verification endpoints. The batch verification endpoint returns an array of these. Note that a verified status means that an address is deliverable as-is, corrected indicates we fixed it (errors will explain what we fixed), and failed means we were not able to fix it (errors might explain why).

Name	Type	Description
line1	string or null	The first line of the resulting address
line2	string or null	The second line of the resulting address
city	string or null	The city of the resulting address
provinceOrState	string or null	The province or state of the resulting address
postalOrZip	string or null	The Postal/ZIP code of the resulting address
zipPlus4	string or null	4-digit USPS ZIP+4 code
firmName	string or null	USPS Firm Name
country	string or null	One of ‘ca’ or ‘us’
errors	Errors	The address errors that were fixed or caused verification failure
status	string	Either ‘verified’, ‘corrected’ or ‘failed’
details	Address Details or null	Detailed information about the address
geocodeResult	Geocode Result	The geocoding result, if geocode=true query was supplied

Address Details

You can request additional address details when using the verification endpoints (both batch and single address) by supplying a query parameter includeDetails=true.

The details have the following schema:

Name	Type	Description
streetName	string or null	Name of the street where the address is located
streetType	string or null	Type of the street (DR, ST, BLVD, etc)
streetDirection	string or null	The direction of the street (N, S, E, W, etc)
streetNumber	string or null	Street number (e.g. the 20 in 20 Bay St)
suiteID	string or null	The unit number/name
boxID	string or null	PO Box ID
deliveryInstallationAreaName	string or null	Delivery installation area name
deliveryInstallationType	string or null	Delivery installation type
deliveryInstallationQualifier	string or null	Delivery installation qualifier
ruralRouteNumber	string or null	Rural route number
ruralRouteType	string or null	Rural route type
extraInfo	string or null	Any extra information relevant to the address
county	string or null	County in the United States (US address only)
countyNum	string or null	FIPS code for county (US address only)
residential	boolean or null	Indicates that the address is residential (US address only)
vacant	boolean or null	Indicates that the address is vacant according to the USPS (US address only)
preDirection	string or null	The pre-direction of the street (before the street name, US addresses only).
postDirection	string or null	The post-direction of the street (after the street name, US addresses only).
usCensusCMSA	string or null	US Census consolidated metropolitan statistical area
usCensusBlockNumber	string or null	US Census block number
usCensusTractNumber	string or null	US Census tract number
usCensusMA	string or null	US Census metropolitan area
usCensusMSA	string or null	US Census metropolitan statistical area
usCensusPMSA	string or null	US Census primary metropolitan statistical area
usCongressionalDistrictNumber	string or null	US congressional district number
usStateLegislativeUpper	string or null	Upper legislative district for the US address
usStateLegislativeLower	string or null	Lower legislative district for the US address
usMailingsCarrierRoute	string or null	4-character code assigned to mail delivery route within a 5 digit zip code
usMailingsCheckDigit	string or null	PostNet barcode digit
usMailingsDefaultFlag	boolean or null	True if US address matches a high-rise default or rural route default in the USPS data
usMailingsDeliveryPoint	string or null	Unique USPS identifier for the delivery point
usMailingsDpvConfirmationIndicator	string or null	See USPS DPV
usMailingsDpvCrmaIndicator	string or null	Y if this is a commercial mail receiving agency, N otherwise
usMailingsDpvFootnote1	string or null	See USPS DPV
usMailingsDpvFootnote2	string or null	See USPS DPV
usMailingsDpvFootnote3	string or null	See USPS DPV
usMailingsElotAscDesc	string or null	A for ascending, D for descending
usMailingsElotSequenceNumber	string or null	eLOT sequence number
usMailingsEWSFlag	string or null	Y if address is in early warning system database
usMailingsLACSFlag	string or null	Y if address converted by LACS
usMailingsLACSReturnCode	string or null	Corresponds to USPS LACSLink return code
usMailingsRecordTypeCode	string or null	See USPS DPV
usMailingsSuiteLinkReturnCode	string or null	See USPS DPV

Note that the details will be returned in a details subobject and only the relevant fields for a given address will be returned. The fields that are empty will not.

USPS DPV

PostGrid performs USPS delivery point verification (DPV) on US addresses. The relevant fields are returned in the Address Details starting with usMailingsDpv. Here is a breakdown of the different return codes for those values.

For the usMailingsDpvConfirmationIndicator:

Value	Description
Empty	Address not found in database
N	Address is not DPV-confirmed
Y	Address is DPV-confirmed
D	Primary number (e.g. street number) confirmed, secondary missing
S	Primary confirmed, secondary present, but not confirmed

For the usMailingsDpvFootnote1:

Value	Description
AA	Address matched to zip4
A1	Address not matched

For the usMailingsDpvFootnote2:

Value	Description
BB	All components of the address matched to DPV
CC	Primary number matched, secondary present but not matched
N1	Primary matched, secondary missing
M1	Primary missing
M3	Primary number invalid
U1	Address matched to unique ZIP code
F1	Military address
G1	General delivery address
P1	PO Box, rural route, or HC box number is missing
P3	Invalid PO Box, rural route, or HC box number

For the usMailingsDpvFootnote3:

Value	Description
RR	Matched to CMRA with secondary present
R1	Matched to CMRA but missing secondary number

For the usMailingsRecordTypeCode:

Value	Description
F	Firm or business
G	General delivery
P	P.O. box
H	High-rise
S	Street
R	Rural route/highway

For the usMailingsSuiteLinkReturnCode:

Value	Description
00	No match in SuiteLink data
A	Match found in SuiteLink data
Empty	Not presented to SuiteLink

Geocoding

All of our POST endpoints also provide geolocation information when geocode=true is provided as a query parameter. You can request this feature be enabled by emailing [email protected]. This includes our verification, batch verification, suggestions, and POST /completions endpoints. Note that you must supply country when geocoding to get the result successfully.

If the query parameter is supplied, the response will include a geocodeResult which has the following schema:

Name	Type	Description
location	Object	Object that contains lat, lng properties with number values
accuracy	number	A real number from 0.00 to 1.00 which represents an accuracy score
accuracyType	string	A string representing the accuracy type

Accuracy Score

This real number value from 0.00 to 1.00 represents our confidence in the geocodes. Generally speaking, scores larger than 0.8 are quite accurate. Anything below could be a rough match.

Accuracy Type

One of the following values:

• rooftop indicating that the exact point was found
• point indicating that the exact point was found within a range of addresses
• range_interpolation indicating that we used interpolation to generate the result (still fairly accurate)
• nearest_rooftop_match indicating we found a nearby rooftop point and used that
• intersection indicating we found a street intersection at the point
• street_center indicating we used the center of the closest street
• place indicating that the point was a city/town/place
• state indicating that the point was just a state

Completion Preview

This is the data returned from the GET completion endpoint (i.e. the preview endpoint). Each element of the returned array follows this schema.

Name	Type	Description
address	string	The first line of the autocompleted address
city	string	The city of the autocompleted address
pc	string	The first 3 digits of the postal/ZIP code of the autocompleted address

Autocompleted Address

This is the data stored in the address field of the full completion response (see below).

Name	Type	Description
address	string	First line of the autocompleted address
city	string	City of the autocompleted address
prov	string	Province or state of the autocompleted address
pc	string	Postal/ZIP code of the autocompleted address
country	string	One of ‘CA’ or ‘US’

Completion

This is the data returned from the POST completions endpoint. Each element of the returned array follows this schema. If you supply an index query parameter to the completions endpoint, it returns an object instead of an array in data.

Name	Type	Description
address	Autocompleted Address	The address
geocodeResult	Geocode Result	The geocoding result
errors	Errors	Issues with the address (e.g. user also needs to supply unit number)

International Address Verification

The International API verifies and standardizes addresses worldwide. Its verification model differs from the Standard API: results carry a verificationStatus and a match-level summary rather than the verified/corrected/failed model.

Integrating International Autocomplete

We provide a pre-built web-based autocomplete integration in the Developers section of the dashboard. However, if you want to integrate autocomplete manually, here are our recommended steps:

1. Use the GET /completions endpoint and supply partialStreet via the query params.
   • This endpoint does not use any lookups.
2. Allow the user to select one of the autocompleted international address previews.
3. If the selected type is Address, make a POST /completions request with request body id, whose value comes from the id field of the selected preview.
4. If the selected type is not Address, use the GET /completions endpoint again, but this time supply container (whose value comes from the id of the selected preview) as a query param. In addition, supply query param advanced=true. Then proceed to step 2 again.

International Verification

This is the data returned from the international verification endpoints. The batch verification endpoint returns an array of these. The final status of each result is stored inside the verificationStatus property of the summary field (see Verification Status). In addition, the summary field provides other information regarding the quality of each verification (see Summary of Verification).

Name	Type	Description
formattedAddress	string	The complete address including all details
line1	string	The first line of the resulting address
line2	string or null	The second line of the resulting address
line3	string or null	The third line of the resulting address
line4	string or null	The fourth line of the resulting address
city	string or null	The city of the resulting address
provinceOrState	string or null	The province or state of the resulting address
postalOrZip	string or null	The Postal/ZIP code of the resulting address
country	string or null	The country of the resulting address
summary	Summary of Verification or null	Contains accuracy information of the verification
geoData	Geographical Data or null	Contains geographic information
details	International Address Details or null	Detailed information about the address
errors	string or null	The address errors that were fixed or caused verification failure

Summary of Verification

Name	Type	Description
verificationStatus	string or null	The status of the verification. See Verification Status
postProcessedVerificationMatchLevel	string or null	The level to which the input data matches the available reference data once all changes and additions performed during the verification process have been taken into account. See Verification Match Level
preProcessedVerificationMatchLevel	string or null	The level to which the input data matches the available reference data prior to any changes or additions performed during the verification process. See Verification Match Level
parsingStatus	string or null	Either ‘identified_and_parsed’ or ‘unable_to_parse’
lexiconIdentificationMatchLevel	string or null	The level to which the output data has some recognized form, through the use of pattern matching and lexicon matching. See Verification Match Level
contextIdentificationMatchLevel	string or null	The level to which the output data can be recognized based on the context in which it appears. See Verification Match Level
postCodeStatus	string or null	The status about postal code. See Postcode Status
matchScore	number	Indicates how much the input data has been changed during the verification process in order to achieve the post-processed verification match level

Verification Status

• verified — A complete match was made between the input data and a single record from the available reference data
• partially_verified — A partial match was made between the input data and a single record from the available reference data
• unverified — Unable to verify. The output fields will contain the input data
• ambiguous — More than one close reference data match
• conflict — More than one close reference data match with conflicting values
• reverted — Record could not be verified to the specified minimum acceptable level. The output fields will contain the input data

Verification Match Level

• Delivery Point (PostBox or SubBuilding)
• Premise (Premise or Building)
• Thoroughfare (Street or Road)
• Locality (City)
• AdministrativeArea (Province or State)
• None

Postcode Status

• postal_code_primary_and_postal_code_secondary_verified
• postal_code_primary_verified, postal_code_secondary_added_or_changed
• postal_code_primary_verified
• postal_code_primary_verified_with_small_change
• postal_code_primary_verified_with_large_change
• postal_code_primary_added
• postal_code_primary_identified_by_lexicon
• postal_code_primary_identified_by_context
• postal_code_primary_empty

Geographical Data

You can request additional geographical details when using the verification endpoints (both batch and single address) by supplying a query parameter geoData=true.

Name	Type	Description
latitude	string or null	The latitude of the resulting address
longitude	string or null	The longitude of the resulting address
geoAccuracy	string or null	The accuracy of the geographical information of the resulting address

International Address Details

You can request additional address details when using the verification endpoints (both batch and single address) by supplying a query parameter includeDetails=true.

The details have the following schema:

Name	Type	Description
organization	string or null	Name of the company or organization where the address is located
building	string or null	Name of the building where the address is located
subBuilding	string or null	Name of the sub building where the address is located
premise	string or null	Premise number where the address is located
postBox	string or null	Postal box number where the address is located
telephone	string or null	Telephone number registered where the address is located

Note that the details will be returned in a details subobject and only the relevant fields for a given address will be returned. The fields that are empty will not.

International Completion Preview

This is the data returned from the GET completion endpoint (i.e. the preview endpoint). Each element of the returned array follows this schema.

Name	Type	Description
id	string	The ID of the autocompleted address
type	string	Either ‘Address’, ‘Container’ or ‘BuildingNumber’
text	string	The name of the autocompleted address
highlight	string	A list of number ranges identifying the matched characters in the text and description
description	string or undefined	Descriptive information about the result

International Autocompleted Address

This is the data returned from the POST completions endpoint.

Name	Type	Description
formattedAddress	string	The complete address including all details
line1	string	The first line of the resulting address
line2	string or null	The second line of the resulting address
line3	string or null	The third line of the resulting address
line4	string or null	The fourth line of the resulting address
city	string or null	The city of the resulting address
provinceOrState	string or null	The province or state of the resulting address
postalOrZip	string or null	The Postal/ZIP code of the resulting address
country	string or null	The country of the resulting address
building	string or null	Name of the building where the address is located
department	string or null	Name of the department where the address is located
company	string or null	Name of the company where the address is located
errors	string or null	The address errors that were fixed or caused verification failure