{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"eaec2af5-e424-4004-a630-863093e30290","name":"PostGrid Verify: Address Verification & Validation API","description":"Allows you to autocomplete, verify, and standardize addresses in real-time.  \nIt also offers batch verification which allows you to do the same for thousands of addresses per second.\n\nYou can access the platform [here](https://app.postgrid.com) where you can also bulk verify lists without having to use the API.\n\n**Note that you can supply JSON data instead of urlencoded data for all endpoints.**\n\n**Also note that the API key in this documentation is just an example. please create a new key on the dashboard.**\n\n# Authorization\n\nYou can authorize your HTTP requests by setting the `x-api-key` HTTP header to your API key.\n\n# API Keys\n\nYou 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.\n\n# Rate Limit\n\nAll 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](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](https://mailto:support@postgrid.com).\n\n# Maximizing Throughput\n\nIn 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](https://mailto:support@postgrid.com).\n\n# Integration\n\nIf 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.\n\nOtherwise, you can use the endpoints documented below to create a completely custom integration.\n\n# Integrating Autocomplete\n\nWe 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:\n\n1. Use the `GET /completions` endpoint and supply `partialStreet` via the query params\n    \n    - This endpoint does not use any lookups\n        \n2. Allow the user to select one of the autocompleted address previews\n    \n3. Make a `POST /completions?index=N` request where N is the index of the address the user selected\n    \n\nIf you follow these steps, there will only be 1 lookup made in total (when the user selects the address).\n\n# Response\n\nThe top-level JSON response has the following structure:\n\n| Name | Type | Description |\n| --- | --- | --- |\n| status | string | Either `success` or `error` |\n| message | string | Describes the result of the request |\n| data | object or array | The response data. |\n\n# Errors\n\nThis 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.\n\n| Name | Type | Description |\n| --- | --- | --- |\n| line1 | array of string | Issues related to the first line of the address |\n| line2 | array of string | Issues related to the second line of the address |\n| city | array of string | Issues related to the city |\n| provinceOrState | array of string | Issues related to the province or state |\n| generic | array of string | Issues with the address in general |\n\n# USPS DPV\n\nPostGrid 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.\n\nFor the `usMailingsDpvConfirmationIndicator`\n\n| Value | Description |\n| --- | --- |\n| Empty | Address not found in database |\n| `N` | Address is not DPV-confirmed |\n| `Y` | Address is DPV-confirmed |\n| `D` | Primary number (e.g. street number) confirmed, secondary missing |\n| `S` | Primary confirmed, secondary present, but not confirmed |\n\nFor the `usMailingsDpvFootnote1`\n\n| Value | Description |\n| --- | --- |\n| `AA` | Address matched to zip4 |\n| `A1` | Address not matched |\n\nFor the `usMailingsDpvFootnote2`\n\n| Value | Description |\n| --- | --- |\n| `BB` | All components of the address matched to DPV |\n| `CC` | Primary number matched, secondary present but not matched |\n| `N1` | Primary matched, secondary missing |\n| `M1` | Primary missing |\n| `M3` | Primary number invalid |\n| `U1` | Address matched to unique ZIP code |\n| `F1` | Military address |\n| `G1` | General delivery address |\n| `P1` | PO Box, rural route, or HC box number is missing |\n| `P3` | Invalid PO Box, rural route, or HC box number |\n\nFor the `usMailingsDpvFootnote3`\n\n| Value | Description |\n| --- | --- |\n| `RR` | Matched to CMRA with secondary present |\n| `R1` | Matched to CMRA but missing secondary number |\n\nFor the `usMailingsRecordTypeCode`\n\n| Value | Description |\n| --- | --- |\n| `F` | Firm or business |\n| `G` | General delivery |\n| `P` | P.O. box |\n| `H` | High-rise |\n| `S` | Street |\n| `R` | Rural route/highway |\n\nFor the `usMailingsSuiteLinkReturnCode`\n\n| Value | Description |\n| --- | --- |\n| `00` | No match in SuiteLink data |\n| `A` | Match found in SuiteLink data |\n| Empty | Not presented to SuiteLink |\n\n# Address Details\n\nYou can request additional address details when using the verification endpoints (both batch and single address) by supplying a query parameter `includeDetails=true`.\n\nThe details have the following schema:\n\n| Name | Type | Description |\n| --- | --- | --- |\n| streetName | string or null | Name of the street where the address is located |\n| streetType | string or null | Type of the street (DR, ST, BLVD, etc) |\n| streetDirection | string or null | The direction of the street (N, S, E, W, etc) |\n| streetNumber | string or null | Street number (e.g. the 20 in 20 Bay St) |\n| suiteID | string or null | The unit number/name |\n| boxID | string or null | PO Box ID |\n| deliveryInstallationAreaName | string or null | Delivery installation area name |\n| deliveryInstallationType | string or null | Delivery installation type |\n| deliveryInstallationQualifier | string or null | Delivery installation qualifier |\n| ruralRouteNumber | string or null | Rural route number |\n| ruralRouteType | string or null | Rural route type |\n| extraInfo | string or null | Any extra information relevant to the address |\n| county | string or null | County in the United States (US address only) |\n| countyNum | string or null | FIPS code for county (US address only) |\n| residential | boolean or null | Indicates that the address is residential (US address only) |\n| vacant | boolean or null | Indicates that the address is vacant according to the USPS (US address only) |\n| preDirection | string or null | The pre-direction of the street (before the street name, US addresses only). |\n| postDirection | string or null | The post-direction of the street (after the street name, US addresses only). |\n| usCensusCMSA | string or null | US Census consolidated metropolitan statistical area |\n| usCensusBlockNumber | string or null | US Census block number |\n| usCensusTractNumber | string or null | US Census tract number |\n| usCensusMA | string or null | US Census metropolitan area |\n| usCensusMSA | string or null | US Census metropolitan statistical area |\n| usCensusPMSA | string or null | US Census primary metropolitan statistical area |\n| usCongressionalDistrictNumber | string or null | US congressional district number |\n| usStateLegislativeUpper | string or null | Upper legislative district for the US address |\n| usStateLegislativeLower | string or null | Lower legislative district for the US address |\n| usMailingsCarrierRoute | string or null | 4-character code assigned to mail delivery route within a 5 digit zip code |\n| usMailingsCheckDigit | string or null | PostNet barcode digit |\n| usMailingsDefaultFlag | boolean or null | True if US address matches a high-rise default or rural route default in the USPS data |\n| usMailingsDeliveryPoint | string or null | Unique USPS identifier for the delivery point |\n| usMailingsDpvConfirmationIndicator | string or null | See [USPS DPV](#usps-dpv) |\n| usMailingsDpvCrmaIndicator | string or null | `Y` if this is a commercial mail receiving agency, `N` otherwise |\n| usMailingsDpvFootnote1 | string or null | See [USPS DPV](#usps-dpv) |\n| usMailingsDpvFootnote2 | string or null | See [USPS DPV](#usps-dpv) |\n| usMailingsDpvFootnote3 | string or null | See [USPS DPV](#usps-dpv) |\n| usMailingsElotAscDesc | string or null | `A` for ascending, `D` for descending |\n| usMailingsElotSequenceNumber | string or null | eLOT sequence number |\n| usMailingsEWSFlag | string or null | `Y` if address is in early warning system database |\n| usMailingsLACSFlag | string or null | `Y` if address converted by LACS |\n| usMailingsLACSReturnCode | string or null | Corresponds to USPS LACSLink return code |\n| usMailingsRecordTypeCode | string or null | See [USPS DPV](#usps-dpv) |\n| usMailingsSuiteLinkReturnCode | string or null | See [USPS DPV](#usps-dpv) |\n\n**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.**\n\n# Proper Case\n\nYou 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`.\n\n# Geocoding\n\nAll 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** [<b>support@postgrid.com</b>](https://mailto: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.**\n\nIf the query parameter is supplied, the response will include a `geocodeResult` which has the following schema:\n\n| Name | Type | Description |\n| --- | --- | --- |\n| location | Object | Object that contains `lat`, `lng` properties with number values |\n| accuracy | number | A real number from 0.00 to 1.00 which represents an [accuracy score](#accuracy-score) |\n| accuracyType | string | A string representing the [accuracy type](#accuracy-type) |\n\n# Accuracy Score\n\nThis 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.\n\n# Accuracy Type\n\nOne of the following values:\n\n- `rooftop` indicating that the exact point was found\n    \n- `point` indicating that the exact point was found within a range of addresses\n    \n- `range_interpolation` indicating that we used [interpolation](https://en.wikipedia.org/wiki/Address_geocoding#Address_interpolation) to generate the result (still fairly accurate)\n    \n- `nearest_rooftop_match` indicating we found a nearby rooftop point and used that\n    \n- `intersection` indicating we found a street intersection at the point\n    \n- `street_center` indicating we used the center of the closest street\n    \n- `place` indicating that the point was a city/town/place\n    \n- `state` indicating that the point was just a state\n    \n\n# Verification\n\nThis 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).\n\n| Name | Type | Description |\n| --- | --- | --- |\n| line1 | string or null | The first line of the resulting address |\n| line2 | string or null | The second line of the resulting address |\n| city | string or null | The city of the resulting address |\n| provinceOrState | string or null | The province or state of the resulting address |\n| postalOrZip | string or null | The Postal/ZIP code of the resulting address |\n| zipPlus4 | string or null | 4-digit USPS ZIP+4 code |\n| firmName | string or null | USPS Firm Name |\n| country | string or null | One of 'ca' or 'us' |\n| errors | [Errors](#errors) | The address errors that were fixed or caused verification failure |\n| status | string | Either 'verified', 'corrected' or 'failed' |\n| details | [Address Details](#address-details) or null | Detailed information about the address |\n| geocodeResult | [Geocode Result](#geocoding) | The geocoding result, if `geocode=true` query was supplied |\n\n# Completion Preview\n\nThis is the data returned from the `GET` completion endpoint (i.e. the preview endpoint). Each element of the returned array follows this schema.\n\n| Name | Type | Description |\n| --- | --- | --- |\n| address | string | The first line of the autocompleted address |\n| city | string | The city of the autocompleted address |\n| pc | string | The first 3 digits of the postal/ZIP code of the autocompleted address |\n\n# Autocompleted Address\n\nThis is the data stored in the `address` field of the full completion response (see below).\n\n| Name | Type | Description |\n| --- | --- | --- |\n| address | string | First line of the autocompleted address |\n| city | string | City of the autocompleted address |\n| prov | string | Province or state of the autocompleted address |\n| pc | string | Postal/ZIP code of the autocompleted address |\n| country | string | One of 'CA' or 'US' |\n\n# Completion\n\nThis 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`.\n\n| Name | Type | Description |\n| --- | --- | --- |\n| address | [Autocompleted Address](#autocompleted-address) | The address |\n| geocodeResult | [Geocode Result](#geocoding) | The geocoding result |\n| errors | [Errors](#errors) | Issues with the address (e.g. user also needs to supply unit number) |","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"17206988","team":1674902,"collectionId":"eaec2af5-e424-4004-a630-863093e30290","publishedId":"TzzEoZuC","public":true,"publicUrl":"https://avdocs.postgrid.com","privateUrl":"https://go.postman.co/documentation/17206988-eaec2af5-e424-4004-a630-863093e30290","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"2d58f9"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":"PostGrid Address Verification API for Validation"}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"2d58f9"}}]}},"version":"8.11.4","publishDate":"2025-07-11T20:04:41.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"PostGrid Address Verification API for Validation","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[{"name":"PG Production","id":"ea9db708-4a1e-4e68-8a5a-148898bc8285","owner":"17207010","values":[{"key":"pg-base","value":"https://api.postgrid.com/v1/","enabled":true}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/34bd04019e69deb8dbe2753382c09c0e8683157cabf78a2860fcea37da95f5af","favicon":"https://postman-image-service.postman.com/api/cloudinary-proxy/postman/image/upload/v1779743392/team/1745f1ed0c315f894e75bc0c6dff7054"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"PG Production","value":"17207010-ea9db708-4a1e-4e68-8a5a-148898bc8285"}],"canonicalUrl":"https://avdocs.postgrid.com/view/metadata/TzzEoZuC"}