avdocs.postgrid.com Open in urlscan Pro
2606:4700:3031::ac43:95c6  Public Scan

Form analysis
0 forms found in the DOM

Text Content

Public


Documentation Settings

ENVIRONMENT
PG Production

LAYOUT
Double Column

LANGUAGE
cURL - cURL



PostGrid Verify
Introduction
Authorization
API Keys
Rate Limit
Maximizing Throughput
Integration
Integrating Autocomplete
Response
Errors
USPS DPV
Address Details
Proper Case
Geocoding
Accuracy Score
Accuracy Type
Verification
Completion Preview
Autocompleted Address
Completion
Bulk Verification & NCOA
GET
Get Lookup Info
GET
Get Autocomplete Previews
POST
Autocomplete an Address
POST
Verify a Structured Address
POST
Verify a Freeform Address
POST
Batch Verify Addresses
POST
Suggest Addresses
POST
Suggest Addresses Freeform
POST
Parse an Address
POST
Lookup City/State from Postal or ZIP Code
POST
Lookup ZIP Codes From US City/State


POSTGRID VERIFY

Allows you to autocomplete, verify, and standardize addresses in real-time.
It also offers batch verification which allows you to do the same for thousands
of addresses per second.

You can access the platform here where you can also 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 in this documentation 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) documented here have default rate
limit of 5 requests per second. Users are encouraged to use the batch endpoint
(https://api.postgrid.com/addver/verifications/batch) documented below for
processing large number of addresses. For users who would like to increase the
rate limit, please feel free to reach out to support@postgrid.com.


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


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 below to create a completely
custom integration.


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:

   
 * Use the GET /completions endpoint and supply partialStreet via the query
   params
     
   * This endpoint does not use any lookups
     
   
 * Allow the user to select one of the autocompleted address previews
   
 * 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).


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.


ERRORS

This object is returned from the verification and autocomplete endpoint 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


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

View More

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


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:

View More

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
usHasDaylightSavings boolean or null True if address location recognizes DST
usTimeZone string or null Time zone for the US address 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.


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.


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

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


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).

View More

Name Type Description line1 string 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


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)