--- title: Core Concepts | PostGrid description: Cross-cutting concepts for the PostGrid Address Verification API — authorization, API keys, rate limits, autocomplete, verification results, USPS DPV, geocoding, and international verification. --- 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](/openapi/address-verification.yaml) 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](https://app.postgrid.com) 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](https://app.postgrid.com/addver/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 . ## 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 . ## Integration If you’re looking to install autocomplete and verification on a website, you can access the [Developers](https://app.postgrid.com/addver/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](#errors) | The address errors that were fixed or caused verification failure | | status | string | Either ‘verified’, ‘corrected’ or ‘failed’ | | details | [Address Details](#address-details) or null | Detailed information about the address | | geocodeResult | [Geocode Result](#geocoding) | 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](#usps-dpv) | | usMailingsDpvCrmaIndicator | string or null | `Y` if this is a commercial mail receiving agency, `N` otherwise | | usMailingsDpvFootnote1 | string or null | See [USPS DPV](#usps-dpv) | | usMailingsDpvFootnote2 | string or null | See [USPS DPV](#usps-dpv) | | usMailingsDpvFootnote3 | string or null | See [USPS DPV](#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](#usps-dpv) | | usMailingsSuiteLinkReturnCode | string or null | See [USPS DPV](#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](#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** . 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](#accuracy-score) | | accuracyType | string | A string representing the [accuracy type](#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](https://en.wikipedia.org/wiki/Address_geocoding#Address_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](#autocompleted-address) | The address | | geocodeResult | [Geocode Result](#geocoding) | The geocoding result | | errors | [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](#verification-status)). In addition, the `summary` field provides other information regarding the quality of each verification (see [Summary of Verification](#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](#summary-of-verification) or null | Contains accuracy information of the verification | | geoData | [Geographical Data](#geographical-data) or null | Contains geographic information | | details | [International Address 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](#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](#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](#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](#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](#verification-match-level) | | postCodeStatus | string or null | The status about postal code. See [Postcode Status](#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 |