openapi: 3.0.0 info: title: PostGrid Address Verification API contact: email: support@postgrid.com url: postgrid.com version: "1.0" tags: - name: International API description: " International Address Verification API. \ Provides endpoints to verify and standardize international addresses, \ supporting both structured and freeform inputs. \ " - name: Standard API description: " Standard Address Verification API. \ Provides endpoints to verify and standardize addresses across US and Canada, \ supporting both structured and freeform inputs. \ Note that this uses a different set of lookups than our international API. \ " - name: Bulk Verification description: " **Note: For verifying batches of addresses in real-time via JSON, please use \ the \"Batch Verify Addresses\" endpoint.** \ The bulk verification API allows you to submit CSV files to be processed \ through our address verification engine. Each file can contain up to 250,000 \ addresses, and the output lines up with what is returned from our batch \ verification API. \ Note that you will be invoiced for every list that processes successfully. \ You can pre-purchase bulk verification credits from our \ [dashboard](https://app.postgrid.com/dashboard/upgrade) to prevent this. \ However, these cannot be used for geocoded lists, and you must individually \ pay for every list that you process with those flags. \ **Also note that in order to access bulk geocoding you must contact** \ [support@postgrid.com](mailto:support@postgrid.com) **to enable the feature.** \ " paths: /v1/addver/: get: operationId: StandardAPI_getLookupInfo description: |- Returns your organization's current lookup usage and plan information. Useful for checking how many lookups you have consumed and whether you are on a paid plan. If you are not subscribed, any lookup past your free limit will fail — use this endpoint to check your remaining lookups. parameters: [] responses: "200": description: The request has succeeded. content: application/json: schema: type: object required: - status - message - data properties: status: type: string enum: - success - error readOnly: true message: type: string readOnly: true data: type: object properties: used: type: integer description: The number of lookups consumed in the current billing period. freeLimit: type: integer nullable: true description: >- The maximum number of lookups allowed in the current billing period. `null` indicates an unlimited plan. subscribed: type: boolean description: Whether the organization is on a paid (subscribed) plan. required: - used - freeLimit - subscribed readOnly: true "400": description: The server could not understand the request due to invalid syntax. content: application/json: schema: type: string enum: - Invalid request tags: - Standard API /v1/addver/city_states: post: operationId: StandardAPI_lookupCityCounty description: |- Looks up city, county, and other location metadata for a given US or Canadian postal code or ZIP code. A single postal code may map to multiple cities (e.g. a ZIP that spans several towns), so the response is an array. - Uses 1 lookup. parameters: [] responses: "200": description: The request has succeeded. content: application/json: schema: type: object required: - status - message - data properties: status: type: string enum: - success - error readOnly: true message: type: string readOnly: true data: type: array items: $ref: "#/components/schemas/CityState" readOnly: true "400": description: The server could not understand the request due to invalid syntax. content: application/json: schema: type: string enum: - Invalid request "403": description: Access is forbidden. content: application/json: schema: type: string enum: - You cannot perform any more lookups. tags: - Standard API requestBody: required: true content: application/json: schema: type: object properties: postalOrZip: type: string required: - postalOrZip /v1/addver/completions: get: operationId: StandardAPI_getCompletionPreviews description: >- Returns address completion previews for a partial street address, suitable for populating an autocomplete dropdown without consuming a lookup per keystroke. Each result contains a partial address preview (street, city, and — for non-US addresses — only the first 3 digits of the postal code, to avoid revealing the full code before a lookup is charged). - Does not consume a lookup. - Use `POST /completions` to resolve a full address once the user selects a result. parameters: - name: partialStreet in: query required: true schema: type: string explode: false - name: cityFilter in: query required: false schema: type: string explode: false - name: stateFilter in: query required: false schema: type: string explode: false - name: pcFilter in: query required: false schema: type: string explode: false - name: countryFilter in: query required: false schema: type: string explode: false - name: properCase in: query required: false schema: type: boolean explode: false - name: verifiedOnly in: query required: false schema: type: boolean explode: false - name: filterExact in: query required: false schema: type: boolean explode: false - name: limit in: query required: false schema: type: integer explode: false - name: provInsteadOfPC in: query required: false schema: type: boolean explode: false responses: "200": description: The request has succeeded. content: application/json: schema: type: object required: - status - message - data properties: status: type: string enum: - success - error readOnly: true message: type: string readOnly: true data: type: array items: $ref: "#/components/schemas/CompletionPreviewItem" readOnly: true "400": description: The server could not understand the request due to invalid syntax. content: application/json: schema: type: string enum: - Invalid request tags: - Standard API post: operationId: StandardAPI_complete description: >- Resolves a partial street address into a list of full address candidates, optionally selecting a specific candidate by index and verifying it. **Basic usage** — omit `index`: returns an array of `CompletedAddressItem` results for the given `partialStreet`. **With `index`** — specify `index` to resolve a single candidate. Returns a single `CompletedAddressItem`. **With `index` + `verify=true`** — additionally runs the selected address through the USPS/Canada Post verifier and returns a `StandardVerifiedAddress`. - Uses 1 lookup per call (plus 1 more if geocoding a result). parameters: - name: index in: query required: false schema: type: integer explode: false - name: verify in: query required: false schema: type: boolean explode: false - name: properCase in: query required: false schema: type: boolean explode: false - name: geocode in: query required: false schema: type: boolean explode: false - name: includeDetails in: query required: false schema: type: boolean explode: false - name: verifiedOnly in: query required: false schema: type: boolean explode: false - name: filterExact in: query required: false schema: type: boolean explode: false - name: limit in: query required: false schema: type: integer explode: false responses: "200": description: The request has succeeded. content: application/json: schema: type: object required: - status - message - data properties: status: type: string enum: - success - error readOnly: true message: type: string readOnly: true data: anyOf: - $ref: "#/components/schemas/CompletedAddressItem" - type: array items: $ref: "#/components/schemas/CompletedAddressItem" - $ref: "#/components/schemas/StandardVerifiedAddress" readOnly: true "400": description: The server could not understand the request due to invalid syntax. content: application/json: schema: type: string enum: - Invalid request "403": description: Access is forbidden. content: application/json: schema: type: string enum: - You cannot perform any more lookups. tags: - Standard API requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CompletionInput" /v1/addver/parses: post: operationId: StandardAPI_parseAddress description: |- Parses a freeform address string into its individual components (house number, street name, city, state, postal code, etc.). Useful for extracting structured data from a single-line address without running a full verification. - Uses 1 lookup. parameters: [] responses: "200": description: The request has succeeded. content: application/json: schema: type: object required: - status - message - data properties: status: type: string enum: - success - error readOnly: true message: type: string readOnly: true data: allOf: - $ref: "#/components/schemas/ParsedAddress" readOnly: true "400": description: The server could not understand the request due to invalid syntax. content: application/json: schema: type: string enum: - Invalid request "403": description: Access is forbidden. content: application/json: schema: type: string enum: - You cannot perform any more lookups. tags: - Standard API requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/StandardFreeformAddressInput" /v1/addver/suggestions: post: operationId: StandardAPI_suggestAddress description: >- Returns up to 3 verified address suggestions for a given input address. Useful as a fallback when `POST /verifications` returns a `failed` status — suggestions represent the closest matches found and may help the user identify the correct address. Accepts the same freeform or structured input formats as `POST /verifications`. - Uses 1 lookup per call (plus 1 more if geocoding). parameters: - name: includeDetails in: query required: false schema: type: boolean explode: false - name: properCase in: query required: false schema: type: boolean explode: false - name: geocode in: query required: false schema: type: boolean explode: false responses: "200": description: The request has succeeded. content: application/json: schema: type: object required: - status - message - data properties: status: type: string enum: - success - error readOnly: true message: type: string readOnly: true data: type: array items: $ref: "#/components/schemas/StandardVerifiedAddress" readOnly: true examples: Freeform Address: summary: Freeform Address value: status: success message: Addresses suggested successfully data: - city: Los Angeles country: US line1: 1234 Elm St postalOrZip: "90001" provinceOrState: CA status: verified errors: {} Structured Address: summary: Structured Address value: status: success message: Addresses suggested successfully data: - city: Los Angeles country: US line1: 1234 Elm St postalOrZip: "90001" provinceOrState: CA status: verified errors: {} "400": description: The server could not understand the request due to invalid syntax. content: application/json: schema: type: string enum: - Invalid request "403": description: Access is forbidden. content: application/json: schema: type: string enum: - You cannot perform any more lookups. tags: - Standard API requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/StandardAddressInput" examples: Freeform Address: summary: Freeform Address value: address: 1234 Elm St, Los Angeles, CA 90001, US Structured Address: summary: Structured Address value: address: recipient: John Doe line1: 1234 Elm St line2: Apt 567 city: Los Angeles provinceOrState: CA postalOrZip: "90001" country: us /v1/addver/verifications: post: operationId: StandardAPI_verifyAddress description: >- 1. **Structured Address** — Verify and standardize a structured address (e.g., with `line1`, `city`, etc.). 2. **Freeform Address** — Verify and standardize a freeform address written on one line. For best results, append the ISO 2-letter country code (e.g., `US`, `CA`) to the end of the line. - Specifying `includeDetails=true` will provide additional output as documented in the `Details` schema. - Uses 1 lookup for verification, and 1 more if geocoding (unless your contract says otherwise). parameters: - name: includeDetails in: query required: false schema: type: boolean explode: false - name: properCase in: query required: false schema: type: boolean explode: false - name: geocode in: query required: false schema: type: boolean explode: false responses: "200": description: The request has succeeded. content: application/json: schema: type: object required: - status - message - data properties: status: type: string enum: - success - error readOnly: true message: type: string readOnly: true data: allOf: - $ref: "#/components/schemas/StandardVerifiedAddress" readOnly: true examples: Freeform Address: summary: Freeform Address value: status: success message: Address verified successfully data: city: Los Angeles country: US line1: 1234 Elm St postalOrZip: "90001" provinceOrState: CA status: verified errors: {} Structured Address: summary: Structured Address value: status: success message: Address verified successfully data: city: Los Angeles country: US line1: 1234 Elm St postalOrZip: "90001" provinceOrState: CA status: verified errors: {} "400": description: The server could not understand the request due to invalid syntax. content: application/json: schema: type: string enum: - Invalid request "403": description: Access is forbidden. content: application/json: schema: type: string enum: - You cannot perform any more lookups. tags: - Standard API requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/StandardAddressInput" examples: Freeform Address: summary: Freeform Address value: address: 1234 Elm St, Los Angeles, CA 90001, US Structured Address: summary: Structured Address value: address: recipient: John Doe line1: 1234 Elm St line2: Apt 567 city: Los Angeles provinceOrState: CA postalOrZip: "90001" country: us /v1/addver/verifications/batch: post: operationId: StandardAPI_verifyBatch description: >- 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. parameters: - name: includeDetails in: query required: false schema: type: boolean explode: false - name: properCase in: query required: false schema: type: boolean explode: false - name: geocode in: query required: false schema: type: boolean explode: false responses: "200": description: The request has succeeded. content: application/json: schema: type: object required: - status - message - data properties: status: type: string enum: - success - error readOnly: true message: type: string readOnly: true data: type: object properties: results: type: array items: $ref: "#/components/schemas/StandardBatchVerificationResult" required: - results readOnly: true "400": description: The server could not understand the request due to invalid syntax. content: application/json: schema: type: string enum: - Invalid request "403": description: Access is forbidden. content: application/json: schema: type: string enum: - You cannot perform any more lookups. tags: - Standard API requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/StandardBatchInput" /v1/addver/zip_codes: post: operationId: StandardAPI_lookupZipCodes description: |- Looks up all ZIP codes that correspond to a given US city and state. - Currently only supported for US addresses (`countryCode: "US"`). - Uses 1 lookup. parameters: [] responses: "200": description: The request has succeeded. content: application/json: schema: type: object required: - status - message - data properties: status: type: string enum: - success - error readOnly: true message: type: string readOnly: true data: type: object properties: zipCodes: type: array items: type: string required: - zipCodes readOnly: true "400": description: The server could not understand the request due to invalid syntax. content: application/json: schema: type: string enum: - Invalid request "403": description: Access is forbidden. content: application/json: schema: type: string enum: - You cannot perform any more lookups. tags: - Standard API requestBody: required: true content: application/json: schema: type: object properties: city: type: string description: The city name. state: type: string description: The state abbreviation (e.g. `NY`). countryCode: type: string description: The country code. Currently only `US` is supported. required: - city - state - countryCode /v1/addver_lists: post: operationId: BulkVerification_uploadList description: >- Upload a CSV file of addresses to be verified in bulk. Supply a `mappings` object describing which CSV columns correspond to which address fields. parameters: [] responses: "200": description: The request has succeeded. content: application/json: schema: type: object required: - status - message - data properties: status: type: string enum: - success - error readOnly: true message: type: string readOnly: true data: allOf: - $ref: "#/components/schemas/AddverList" readOnly: true "400": description: The server could not understand the request due to invalid syntax. content: application/json: schema: type: string enum: - Invalid request tags: - Bulk Verification requestBody: required: true content: multipart/form-data: schema: $ref: "#/components/schemas/AddverListUploadMultiPart" get: operationId: BulkVerification_listLists description: Retrieve a list of your bulk verification lists. parameters: - name: skip in: query required: false description: The number of lists to skip past, for pagination. schema: type: integer default: 0 explode: false - name: limit in: query required: false description: The maximum number of lists to return. schema: type: integer default: 100 explode: false responses: "200": description: The request has succeeded. content: application/json: schema: type: object required: - status - message - data properties: status: type: string enum: - success - error readOnly: true message: type: string readOnly: true data: allOf: - $ref: "#/components/schemas/AddverListList" readOnly: true "400": description: The server could not understand the request due to invalid syntax. content: application/json: schema: type: string enum: - Invalid request tags: - Bulk Verification /v1/addver_lists/{id}: get: operationId: BulkVerification_retrieveList description: |- Retrieve a single bulk verification list by ID, including its processing status and — once processed — a link to the output CSV. parameters: - name: id in: path required: true schema: type: string responses: "200": description: The request has succeeded. content: application/json: schema: type: object required: - status - message - data properties: status: type: string enum: - success - error readOnly: true message: type: string readOnly: true data: allOf: - $ref: "#/components/schemas/AddverList" readOnly: true "400": description: The server could not understand the request due to invalid syntax. content: application/json: schema: type: string enum: - Invalid request tags: - Bulk Verification /v1/intl_addver/completions: get: operationId: InternationalAPI_getCompletionPreviews description: >- Returns address completion previews for a partial address string, suitable for populating an autocomplete dropdown. **Regular mode** — supply `partialStreet` to search by partial street address. Results may include directly-resolvable `Address` results and non-`Address` results (e.g. `BuildingNumber`) that represent buildings/complexes requiring a follow-up call. **Advanced mode** — supply `advanced=true` and a `container` ID (the `id` of a non-`Address` result from a previous regular call) to drill into a building or complex and retrieve individual unit addresses. Results with `type: "Address"` can be fully resolved by passing their `id` to `POST /completions`. - Results are biased by the caller's IP address by default; pass `disableIPBiasing=true` to turn this off. - Does not consume a lookup. parameters: - name: partialStreet in: query required: false schema: type: string explode: false - name: container in: query required: false schema: type: string explode: false - name: countriesFilter in: query required: false schema: type: string explode: false - name: limit in: query required: false schema: type: integer explode: false - name: language in: query required: false schema: type: string explode: false - name: cityFilter in: query required: false schema: type: string explode: false - name: streetFilter in: query required: false schema: type: string explode: false - name: postalOrZipFilter in: query required: false schema: type: string explode: false - name: advanced in: query required: false schema: type: boolean explode: false - name: disableIPBiasing in: query required: false schema: type: boolean explode: false - name: standardFallback in: query required: false schema: type: boolean explode: false - name: useEnhancedChinaDataset in: query required: false schema: type: boolean explode: false responses: "200": description: The request has succeeded. content: application/json: schema: type: object required: - status - message - data properties: status: type: string enum: - success - error readOnly: true message: type: string readOnly: true data: type: array items: $ref: "#/components/schemas/IntlAddressPreview" readOnly: true examples: Advanced (drill into a building): summary: Advanced (drill into a building) value: status: success message: Address previews retrieved successfully data: - id: GB|RM|A|54186236 type: Address text: Flat 1, One Canada Square description: London, E14 5AB Regular: summary: Regular value: status: success message: Address previews retrieved successfully data: - id: GB|RM|A|54186236 type: Address text: 10 Downing Street description: London, SW1A 2AA "400": description: The server could not understand the request due to invalid syntax. content: application/json: schema: type: string enum: - Invalid request tags: - International API post: operationId: InternationalAPI_complete description: >- Resolves an address preview `id` (from `GET /completions`) into a full address. Optionally verifies the resolved address through the standard US/CA verifier when `verify=true` is supplied and the address is in the US or Canada. - Uses 1 lookup per call. - When `verify=true` resolves a US or CA address, the response will be a `VerifiedAddress` instead of an `IntlAddressCompletion`. parameters: - name: verify in: query required: false schema: type: boolean explode: false - name: includeDetails in: query required: false schema: type: boolean explode: false - name: properCase in: query required: false schema: type: boolean explode: false - name: useEnhancedChinaDataset in: query required: false schema: type: boolean explode: false responses: "200": description: The request has succeeded. content: application/json: schema: type: object required: - status - message - data properties: status: type: string enum: - success - error readOnly: true message: type: string readOnly: true data: anyOf: - $ref: "#/components/schemas/IntlAddressCompletion" - $ref: "#/components/schemas/VerifiedAddress" readOnly: true "400": description: The server could not understand the request due to invalid syntax. content: application/json: schema: type: string enum: - Invalid request "403": description: Access is forbidden. content: application/json: schema: type: string enum: - You cannot perform any more lookups. tags: - International API requestBody: required: true content: application/json: schema: type: object properties: id: type: string required: - id /v1/intl_addver/verifications: post: operationId: InternationalAPI_verifyAddress description: >- Verify and standardize an international address. - Supports both structured and freeform address inputs. - Specify `includeDetails=true` to get additional details as per the `IntlDetails` schema. - Uses 1 lookup. parameters: - name: includeDetails in: query required: false schema: type: boolean explode: false - name: properCase in: query required: false schema: type: boolean explode: false - name: geoData in: query required: false schema: type: boolean explode: false responses: "200": description: The request has succeeded. content: application/json: schema: type: object required: - status - message - data properties: status: type: string enum: - success - error readOnly: true message: type: string readOnly: true data: allOf: - $ref: "#/components/schemas/VerifiedAddress" readOnly: true examples: Freeform Address: summary: Freeform Address value: status: success message: International address verified successfully. data: city: Scarborough country: CA details: premise: "31" formattedAddress: 31 Fl,scarborough On geoData: latitude: "43.761961" longitude: "-79.245693" geoAccuracy: A2 line1: 31 Fl line2: Scarborough On provinceOrState: ON postalOrZip: "" summary: verificationStatus: partially_verified postProcessedVerificationMatchLevel: city preProcessedVerificationMatchLevel: city parsingStatus: unable_to_parse lexiconIdentificationMatchLevel: city contextIdentificationMatchLevel: premise_or_building postCodeStatus: postal_code_primary_empty matchScore: 100 Structured Address: summary: Structured Address value: status: success message: International address verified successfully. data: city: Reilingen country: DE details: building: Reilingen Baden Wurtemberg premise: "43" formattedAddress: Reilingen Baden Wurtemberg,hockenheimer Str. 43,68799 Reilingen geoData: latitude: "49.297010" longitude: "8.571100" geoAccuracy: P4 line1: Reilingen Baden Wurtemberg line2: Hockenheimer Str. 43 line3: 68799 Reilingen postalOrZip: "68799" provinceOrState: Baden-Württemberg summary: verificationStatus: verified postProcessedVerificationMatchLevel: premise_or_building preProcessedVerificationMatchLevel: premise_or_building parsingStatus: unable_to_parse lexiconIdentificationMatchLevel: premise_or_building contextIdentificationMatchLevel: premise_or_building postCodeStatus: postal_code_primary_empty matchScore: 100 "400": description: The server could not understand the request due to invalid syntax. content: application/json: schema: type: string enum: - Invalid request "403": description: Access is forbidden. content: application/json: schema: type: string enum: - You cannot perform any more lookups. tags: - International API requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AddressInput" examples: Freeform Address: summary: Freeform Address value: address: 31 Fl Scarborough, Canada Structured Address: summary: Structured Address value: address: line1: Hockenheimerstr 43 line2: Reilingen line3: Baden Wurtemberg line4: "" city: "" provinceOrState: Baden-Württemberg postalOrZip: "68799" country: DEU /v1/intl_addver/verifications/batch: post: operationId: InternationalAPI_verifyBatch description: >- Verify a batch of international 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. - 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. parameters: - name: includeDetails in: query required: false schema: type: boolean explode: false - name: properCase in: query required: false schema: type: boolean explode: false - name: geoData in: query required: false schema: type: boolean explode: false - name: useEnhancedChinaDataset in: query required: false schema: type: boolean explode: false responses: "200": description: The request has succeeded. content: application/json: schema: type: object required: - status - message - data properties: status: type: string enum: - success - error readOnly: true message: type: string readOnly: true data: type: object properties: results: type: array items: $ref: "#/components/schemas/IntlBatchVerificationResult" required: - results readOnly: true "400": description: The server could not understand the request due to invalid syntax. content: application/json: schema: type: string enum: - Invalid request "403": description: Access is forbidden. content: application/json: schema: type: string enum: - You cannot perform any more lookups. tags: - International API requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/IntlBatchInput" security: - AddressVerificationApiKeyAuth: [] components: schemas: AddressInput: anyOf: - $ref: "#/components/schemas/StructuredAddressInput" - $ref: "#/components/schemas/FreeformAddressInput" AddverList: type: object required: - id - name - status - count - cost - useIntlVerification - useGeocode - useProperCase - mappings - file - organization - user - createdAt - updatedAt properties: id: type: string description: A unique ID prefixed with `addver_list_`. readOnly: true name: type: string description: >- The name supplied for the list. This only affects what is displayed in the dashboard. readOnly: true status: type: string description: |- The processing status of the list, e.g. `pending`, `processing`, or `processed`. readOnly: true count: type: integer description: The number of addresses in the uploaded file. readOnly: true numInvalidRows: type: integer description: |- The number of invalid or skipped rows in the uploaded file. May be omitted on lists created before this field was introduced. readOnly: true cost: type: integer description: The cost charged for processing this list. readOnly: true defaultCountry: type: string description: >- The ISO 2-letter country code used as the fallback when a row is missing a country. Not returned for lists uploaded without one, e.g. lists which map the entire address into `line1`. readOnly: true useIntlVerification: type: boolean description: Whether international (outside US & Canada) verification was requested. readOnly: true useGeocode: type: boolean description: Whether geocoding (latitude/longitude) output was requested. readOnly: true useProperCase: type: boolean description: Whether Proper Case output was requested. readOnly: true runNCOA: type: boolean description: |- Whether NCOA (US National Change of Address) was requested. May be omitted on lists created before COA support was introduced. readOnly: true runCCOA: type: boolean description: |- Whether CCOA (Canada Post change of address) was requested. May be omitted on lists created before COA support was introduced. readOnly: true mappings: allOf: - $ref: "#/components/schemas/AddverListMappings" description: The mapping of CSV columns to address fields. readOnly: true file: type: string description: A signed URL to the uploaded input CSV file. readOnly: true result: type: string description: >- A signed URL to the processed output CSV file. Present once the list has finished processing. readOnly: true metadata: type: object properties: statusCount: type: object properties: verified: type: integer corrected: type: integer failed: type: integer description: The number of addresses by resulting verification status. description: Additional metadata about the list, including a count of each status. readOnly: true organization: type: string description: The ID of the organization that owns this list. readOnly: true user: type: string description: The ID of the user that created this list. readOnly: true createdAt: type: string format: date-time description: The UTC time at which this list was created. readOnly: true updatedAt: type: string format: date-time description: The UTC time at which this list was last updated. readOnly: true description: >- A bulk address verification list — an uploaded CSV file of addresses and its processing state. AddverListList: type: object required: - count - data properties: count: type: integer description: The total number of lists. readOnly: true data: type: array items: $ref: "#/components/schemas/AddverList" description: The requested lists. readOnly: true description: A list of bulk verification lists. AddverListMappings: type: object required: - line1 properties: line1: type: string description: |- The column containing the first line of each address. If your entire address is in a single column, specify only this mapping. line2: type: string description: The column containing the second line of each address. city: type: string description: The column containing the city of each address. provinceOrState: type: string description: The column containing the province or state of each address. postalOrZip: type: string description: The column containing the postal or ZIP code of each address. country: type: string description: >- The column containing the 2-letter ISO country code of each address (e.g. `US`, not `United States`). firstName: type: string description: >- The column containing the first name of the person at each address. Only used when NCOA is run. lastName: type: string description: >- The column containing the last name of the person at each address. Only used when NCOA is run. fullName: type: string description: >- The column containing the full name of the person at each address. Can be supplied instead of `firstName` and `lastName`. Only used when NCOA or CCOA is run. description: >- The mapping of your CSV column names to PostGrid address fields. Each value is the name of a column in your uploaded file. AddverListUploadMultiPart: type: object required: - name - mappings - file properties: name: type: string description: >- A name for the uploaded list. This only affects what is displayed in the dashboard. useIntlVerification: type: boolean description: Whether to perform international (outside US & Canada) verification. useGeocode: type: boolean description: >- Whether to append geographical location information (latitude, longitude) to your output. Bulk geocoding must be enabled by contacting support. useProperCase: type: boolean description: Whether to return addresses in Proper Case. runNCOA: type: boolean description: Whether to run NCOA (US National Change of Address) on the list. runCCOA: type: boolean description: >- Whether to run CCOA (Canada Post change of address) on the list. Note that a list cannot run both NCOA and CCOA — split mixed US/Canadian files into separate lists. defaultCountry: type: string description: >- An ISO 2-letter country code used as the fallback when a row is missing a value in the `country` column. mappings: allOf: - $ref: "#/components/schemas/AddverListMappings" description: The mapping of your CSV column names to PostGrid address fields. file: type: string format: binary description: The fields used to upload a new bulk verification list. CityState: type: object required: - city - country - provinceOrState properties: city: type: string description: The city name. country: type: string description: The ISO 2-letter country code. county: type: string description: The county name (US addresses only). countyFIPS: type: string description: The FIPS code for the county (US addresses only). mailable: type: boolean description: Whether the location is mailable. preferredCity: type: string description: The USPS preferred city name for this postal code. provinceOrState: type: string description: The province or state abbreviation. zipClass: type: string description: The USPS ZIP code class (e.g. `S` for standard, `P` for PO Box only). CompletedAddressItem: type: object required: - address properties: address: type: object properties: address: type: string description: The first line of the address. address2: type: string description: The second line of the address. city: type: string description: The city. prov: type: string description: The province or state abbreviation. pc: type: string description: The postal code. country: type: string description: The ISO 2-letter country code. required: - address description: The resolved address components. geocodeResult: allOf: - $ref: "#/components/schemas/GeocodeResult" description: Geocoding result. Only present when `geocode=true` is supplied and an `index` is specified. errors: allOf: - $ref: "#/components/schemas/Errors" description: Any errors associated with this address. CompletionInput: type: object required: - partialStreet properties: partialStreet: type: string description: The partial street address to complete (e.g. `"22 Bay"`). cityFilter: type: string description: Filter results to a specific city. stateFilter: type: string description: Filter results to a specific state or province abbreviation. pcFilter: type: string description: Filter results to a specific postal code prefix. countryFilter: type: string description: Filter results to a specific country code. verifiedOnly: type: boolean description: If true, only return addresses that passed USPS/Canada Post verification. CompletionPreviewItem: type: object required: - preview properties: preview: type: object properties: address: type: string description: The street address line. city: type: string description: The city. pc: type: string description: >- For US addresses, the full postal code. For non-US addresses, only the first 3 digits are returned to avoid consuming a lookup. prov: type: string description: The province or state abbreviation. Returned instead of `pc` when `provInsteadOfPC=true`. required: - address description: A partial view of the address, suitable for display in an autocomplete dropdown. Errors: type: object properties: line1: type: array items: type: string description: Errors related to the first address line. line2: type: array items: type: string description: Errors related to the second address line. city: type: array items: type: string description: Errors related to the city. provinceOrState: type: array items: type: string description: Errors related to the province or state. postalOrZip: type: array items: type: string description: Errors related to the postal or ZIP code. generic: type: array items: type: string description: Generic errors not tied to a specific field. description: Errors encountered during address verification. FreeformAddressInput: type: object required: - address properties: address: type: string description: The full address as a single string. description: Input model for freeform international address verification. GeoData: type: object properties: latitude: type: string description: The latitude of the address. longitude: type: string description: The longitude of the address. geoAccuracy: type: string description: The geocode accuracy. description: Geocoding result for the verified address. GeocodeResult: type: object required: - location - accuracy - accuracyType properties: location: type: object properties: lat: type: number lng: type: number required: - lat - lng description: Object that contains `lat`, `lng` properties with number values accuracy: type: number description: A real number from 0.00 to 1.00 which represents an [accuracy score](https://avdocs.postgrid.com/#accuracy-score) accuracyType: type: string enum: - rooftop - point - range_interpolation - nearest_rooftop_match - intersection - street_center - place - state description: A string representing the [accuracy type](https://avdocs.postgrid.com/#accuracy-type) IntlAddressCompletion: type: object properties: formattedAddress: type: string description: The full formatted address string. line1: type: string description: The first address line. line2: type: string description: The second address line. line3: type: string description: The third address line. line4: type: string description: The fourth address line. city: type: string description: The city or locality. provinceOrState: type: string description: The province or state name. provinceCode: type: string description: The province or state code. country: type: string description: The country name. countryCode: type: string description: The ISO 2-letter country code. postalOrZip: type: string description: The postal or ZIP code. building: type: string description: The building name, if applicable. department: type: string description: The department or floor, if applicable. company: type: string description: The company or organization name, if applicable. error: type: string description: An error message if resolution failed. description: A fully resolved international address returned by `POST /completions`. IntlAddressPreview: type: object properties: id: type: string description: >- The unique identifier for this result. If the result is a fully resolvable address (`type` is `Address`), pass this to `POST /completions` to retrieve the full address. Otherwise, pass it as the `container` query parameter to `GET /completions` to drill down further. type: type: string description: >- The type of result. `Address` means this can be resolved directly via `POST /completions`. `Container` means the result represents a building or complex — perform another `GET /completions` with this `id` as `container` to get individual unit addresses. text: type: string description: The human-readable address suggestion text. highlight: type: string description: Character ranges within `text` that match the search input, for bolding in UI. description: type: string description: A secondary description of the result (e.g. city and country). error: type: string description: An error message if the lookup failed for this result. description: |- A single address suggestion returned by `GET /completions`. Use the `id` field to retrieve the full address via `POST /completions`. IntlBatchInput: type: object required: - addresses properties: addresses: type: array items: $ref: "#/components/schemas/AddressInput" description: Array of addresses to verify. Each item can be a freeform string or a structured address object. IntlBatchVerificationResult: type: object properties: verifiedAddress: allOf: - $ref: "#/components/schemas/VerifiedAddress" description: The verified address result. Present when verification succeeded. error: type: string description: An error message for this address. Present when verification failed. IntlDetails: type: object properties: organization: type: string description: The organization or company name. building: type: string description: The building name or number. buildingType: type: string description: The type of building (e.g., apartment, office). subBuilding: type: string description: The sub-building name or number (e.g., unit, suite). subBuildingType: type: string description: The type of sub-building (e.g., floor, wing). subBuildingNumber: type: string description: The sub-building number. SubBuildingFloor: type: string description: The floor of the sub-building. premise: type: string description: The premise name or number. premiseType: type: string description: The type of premise (e.g., house, flat). premiseNumber: type: string description: The premise number. premiseSecondary: type: string description: Secondary premise information. postBox: type: string description: The post box number. telephone: type: string description: The telephone number associated with the address. street: type: string description: The street name. streetType: type: string description: The type of street (e.g., St, Ave, Blvd). streetPreDirection: type: string description: The directional prefix for the street (e.g., N, S, E, W). streetPostDirection: type: string description: The directional suffix for the street (e.g., N, S, E, W). subStreet: type: string description: The sub-street name. subStreetType: type: string description: The type of sub-street. subStreetPreDirection: type: string description: The directional prefix for the sub-street. subStreetPostDirection: type: string description: The directional suffix for the sub-street. provinceOrStateName: type: string description: The full name of the province or state. provinceOrStateType: type: string description: The type of province or state (e.g., province, state, region). cityName: type: string description: The full city name. cityType: type: string description: The type of city (e.g., city, town, village). citySecondary: type: string description: Secondary city information. doubleDependentLocality: type: string description: The double dependent locality (UK addresses). dependentLocality: type: string description: The dependent locality (UK addresses). subAdministrativeArea: type: string description: The sub-administrative area. superAdministrativeArea: type: string description: The super-administrative area. postalOrZipPrimary: type: string description: The primary part of the postal or ZIP code. postalOrZipSecondary: type: string description: The secondary part of the postal or ZIP code. deliveryAddress: type: string description: The full delivery address. description: Additional details about the verified address, such as premise, thoroughfare, and locality. ParsedAddress: type: object properties: house: type: string description: The name of the location. category: type: string description: The category of the location (e.g. restaurant). near: type: string description: Populated if the input query contains a near/in qualifier. houseNumber: type: string description: The house or street number. road: type: string description: The street name. unit: type: string description: The apartment, unit, office, lot, or other secondary unit designator. level: type: string description: The floor. poBox: type: string description: The postal office box. postcode: type: string description: The postal or ZIP code. suburb: type: string description: The unofficial neighborhood name. cityDistrict: type: string description: The borough within a city. city: type: string description: The city name. island: type: string description: The name of the island. stateDistrict: type: string description: The county. state: type: string description: The state or province. country: type: string description: The country. StandardAddressInput: anyOf: - $ref: "#/components/schemas/StandardFreeformAddressInput" - $ref: "#/components/schemas/StandardStructuredAddressInput" StandardBatchInput: type: object required: - addresses properties: addresses: type: array items: $ref: "#/components/schemas/StandardAddressInput" description: Array of addresses to verify. Each item can be a freeform string or structured address object. StandardBatchVerificationResult: type: object properties: verifiedAddress: allOf: - $ref: "#/components/schemas/StandardVerifiedAddress" description: The verified address result. Present when verification succeeded. error: type: string description: An error message for this address. Present when verification failed. StandardDetails: type: object properties: streetName: type: string description: Name of the street where the address is located streetType: type: string description: Type of the street (DR, ST, BLVD, etc) streetDirection: type: string description: The direction of the street (N, S, E, W, etc) streetNumber: type: string description: Street number (e.g. the 20 in 20 Bay St) preDirection: type: string description: The pre-direction of the street (before the street name, US addresses only) postDirection: type: string description: The post-direction of the street (after the street name, US addresses only) suiteKey: type: string description: The suite key suiteID: type: string description: The unit number/name boxID: type: string description: PO Box ID deliveryInstallationAreaName: type: string description: Delivery installation area name deliveryInstallationType: type: string description: Delivery installation type deliveryInstallationQualifier: type: string description: Delivery installation qualifier ruralRouteNumber: type: string description: Rural route number ruralRouteType: type: string description: Rural route type extraInfo: type: string description: Any extra information relevant to the address county: type: string description: County in the United States (US address only) countyNum: type: string description: FIPS code for county (US address only) usCensusFIPS: type: string description: US Census FIPS code (US address only) usCensusCMSA: type: string description: US Census consolidated metropolitan statistical area usCensusBlockNumber: type: string description: US Census block number usCensusTractNumber: type: string description: US Census tract number usCensusMA: type: string description: US Census metropolitan area usCensusMSA: type: string description: US Census metropolitan statistical area usCensusPMSA: type: string description: US Census primary metropolitan statistical area usHasDaylightSavings: type: boolean description: True if address location recognizes DST usTimeZone: type: string description: Time zone for the US address area usCongressionalDistrictNumber: type: string description: US congressional district number usStateLegislativeUpper: type: string description: Upper legislative district for the US address usStateLegislativeLower: type: string description: Lower legislative district for the US address usMailingsCarrierRoute: type: string description: 4-character code assigned to mail delivery route within a 5 digit zip code usMailingCheckDigit: type: string description: PostNet barcode digit usMailingsDefaultFlag: type: boolean description: True if US address matches a high-rise default or rural route default in the USPS data usMailingsDeliveryPoint: type: string description: Unique USPS identifier for the delivery point usMailingsDpvConfirmationIndicator: type: string description: See [USPS DPV](https://avdocs.postgrid.com/#usps-dpv) usMailingsDpvCrmaIndicator: type: string description: Y if this is a commercial mail receiving agency, N otherwise usMailingsDpvFootnote1: type: string description: See [USPS DPV](https://avdocs.postgrid.com/#usps-dpv) usMailingsDpvFootnote2: type: string description: See [USPS DPV](https://avdocs.postgrid.com/#usps-dpv) usMailingsDpvFootnote3: type: string description: See [USPS DPV](https://avdocs.postgrid.com/#usps-dpv) usMailingsElotAscDesc: type: string description: A for ascending, D for descending usMailingsElotSequenceNumber: type: string description: eLOT sequence number usMailingsEWSFlag: type: string description: Y if address is in early warning system database usMailingsLACSFlag: type: string description: Y if address converted by LACS usMailingsLACSReturnCode: type: string description: Corresponds to USPS LACSLink return code usMailingsRecordTypeCode: type: string description: See [USPS DPV](https://avdocs.postgrid.com/#usps-dpv) usMailingsSuiteLinkReturnCode: type: string description: See [USPS DPV](https://avdocs.postgrid.com/#usps-dpv) usPostnetBarcode: type: string description: PostNet barcode for the address (US address only) residential: type: boolean description: Indicates that the address is residential (US address only) vacant: type: boolean description: Indicates that the address is vacant according to the USPS (US address only) StandardFreeformAddressInput: type: object required: - address properties: address: type: string description: The address you want to verify, written on a single line. StandardStructuredAddressInput: type: object required: - address properties: address: type: object properties: recipient: type: string description: The optional firm/recipient name. line1: type: string description: The first line of the address. line2: type: string description: The second line of the address. city: type: string description: The city of the address. provinceOrState: type: string description: The province or state of the address. postalOrZip: type: string description: The postal code or ZIP code of the address. country: type: string enum: - ca - us description: The country of your address, one of `ca` or `us`. required: - line1 - city - provinceOrState - postalOrZip - country StandardVerifiedAddress: type: object required: - city - country - line1 - postalOrZip - provinceOrState properties: city: type: string description: The city name of the address. country: type: string description: The country code of the address. countryName: type: string description: The country name of the address. details: allOf: - $ref: "#/components/schemas/StandardDetails" description: If you supply `includeDetails=true` as a query parameter, we will also populate an additional `details` field that follows the [Address Details](https://avdocs.postgrid.com/#address-details) schema. errors: allOf: - $ref: "#/components/schemas/Errors" description: Any issues with the address that were either fixed or caused verification failure. firmName: type: string description: The firm name of the address. geocodeResult: allOf: - $ref: "#/components/schemas/GeocodeResult" description: >- If the `geocode=true` query parameter is supplied, the response will include a geocodeResult which follows the [Geocoding](https://avdocs.postgrid.com/#geocoding) schema. 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. line1: type: string description: The first line of the address. line2: type: string description: The second line of the address. postalOrZip: type: string description: The postal code or ZIP code of the address. provinceOrState: type: string description: The province or state of the address. provinceOrStateName: type: string description: The full name of the province or state. status: allOf: - $ref: "#/components/schemas/Status" description: The status of the address. zipPlus4: type: string description: The zip plus 4 code of the address. Status: type: string enum: - verified - corrected - failed description: The verification status of an address. StructuredAddressInput: type: object required: - address properties: address: type: object properties: line1: type: string description: The first line of the address (e.g., street address, building, etc.). line2: type: string description: The second line of the address (e.g., apartment, suite, etc.). line3: type: string description: The third line of the address (e.g., additional locality or delivery info). line4: type: string description: The fourth line of the address (e.g., further address details). city: type: string description: The city, town, or locality of the address. provinceOrState: type: string description: The administrative area (e.g., state, province, region). country: type: string description: The country code (ISO 3166-1 alpha-2 or alpha-3). postalOrZip: type: string description: The postal or ZIP code. required: - line1 - provinceOrState - country - postalOrZip description: Input model for structured international address verification. VerifiedAddress: type: object required: - city - country - line1 - postalOrZip - provinceOrState properties: city: type: string description: The city or locality. country: type: string description: The country code (ISO 3166-1 alpha-2). countryName: type: string description: The full country name. details: allOf: - $ref: "#/components/schemas/IntlDetails" description: Additional address details. errors: allOf: - $ref: "#/components/schemas/Errors" description: Errors encountered during verification. firmName: type: string description: The firm or company name, if available. geoData: allOf: - $ref: "#/components/schemas/GeoData" description: Geocoding result for the address. line1: type: string description: The first address line. line2: type: string description: The second address line. postalOrZip: type: string description: The postal or ZIP code. provinceOrState: type: string description: The province or state. status: allOf: - $ref: "#/components/schemas/Status" description: The verification status. zipPlus4: type: string description: The ZIP+4 code (for US addresses). formattedAddress: type: string description: The formatted address string. line3: type: string description: The third address line, if available. summary: type: object properties: verificationStatus: type: string description: The overall verification status. postProcessedVerificationMatchLevel: type: string description: The match level after post-processing. preProcessedVerificationMatchLevel: type: string description: The match level before post-processing. parsingStatus: type: string description: The parsing status of the address. lexiconIdentificationMatchLevel: type: string description: Lexicon identification match level. contextIdentificationMatchLevel: type: string description: Context identification match level. postCodeStatus: type: string description: The status of the postal code. matchScore: type: number description: The match score (0-100). message: type: string description: Additional message about the verification. description: A summary of the verification process and match levels. description: The result of a verified international address. Versions: type: string enum: - "1.0" securitySchemes: AddressVerificationApiKeyAuth: type: apiKey in: header name: X-API-Key servers: - url: https://api.postgrid.com description: Primary endpoint for all of PostGrid's APIs variables: {}