Skip to content
PostGrid PostGrid
Get startedDashboardSupport
API Reference
Bulk Verification

List

bulk_verification.list(BulkVerificationListParams**kwargs) -> BulkVerificationListResponse
GET/v1/addver_lists

Retrieve a list of your bulk verification lists.

ParametersExpand Collapse
limit: Optional[int]

The maximum number of lists to return.

ReturnsExpand Collapse
class BulkVerificationListResponse: …
data: Data

A list of bulk verification lists.

count: int

The total number of lists.

data: List[AddverList]

The requested lists.

id: str

A unique ID prefixed with addver_list_.

cost: int

The cost charged for processing this list.

count: int

The number of addresses in the uploaded file.

created_at: datetime

The UTC time at which this list was created.

formatdate-time
file: str

A signed URL to the uploaded input CSV file.

mappings: Mappings

The mapping of your CSV column names to PostGrid address fields. Each value is the name of a column in your uploaded file.

line1: str

The column containing the first line of each address. If your entire address is in a single column, specify only this mapping.

city: Optional[str]

The column containing the city of each address.

country: Optional[str]

The column containing the 2-letter ISO country code of each address (e.g. US, not United States).

first_name: Optional[str]

The column containing the first name of the person at each address. Only used when NCOA is run.

full_name: Optional[str]

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.

last_name: Optional[str]

The column containing the last name of the person at each address. Only used when NCOA is run.

line2: Optional[str]

The column containing the second line of each address.

postal_or_zip: Optional[str]

The column containing the postal or ZIP code of each address.

province_or_state: Optional[str]

The column containing the province or state of each address.

name: str

The name supplied for the list. This only affects what is displayed in the dashboard.

organization: str

The ID of the organization that owns this list.

status: str

The processing status of the list, e.g. pending, processing, or processed.

updated_at: datetime

The UTC time at which this list was last updated.

formatdate-time
use_geocode: bool

Whether geocoding (latitude/longitude) output was requested.

use_intl_verification: bool

Whether international (outside US & Canada) verification was requested.

use_proper_case: bool

Whether Proper Case output was requested.

user: str

The ID of the user that created this list.

default_country: Optional[str]

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.

metadata: Optional[Metadata]

Additional metadata about the list, including a count of each status.

status_count: Optional[MetadataStatusCount]

The number of addresses by resulting verification status.

corrected: Optional[int]
failed: Optional[int]
verified: Optional[int]
num_invalid_rows: Optional[int]

The number of invalid or skipped rows in the uploaded file. May be omitted on lists created before this field was introduced.

result: Optional[str]

A signed URL to the processed output CSV file. Present once the list has finished processing.

run_ccoa: Optional[bool]

Whether CCOA (Canada Post change of address) was requested. May be omitted on lists created before COA support was introduced.

run_ncoa: Optional[bool]

Whether NCOA (US National Change of Address) was requested. May be omitted on lists created before COA support was introduced.

message: str
status: Literal["success", "error"]
One of the following:
"success"
"error"

List

import os
from postgrid import PostGrid

client = PostGrid(
    address_verification_api_key=os.environ.get("POSTGRID_ADDRESS_VERIFICATION_API_KEY"),  # This is the default and can be omitted
)
bulk_verifications = client.bulk_verification.list()
print(bulk_verifications.data)
{
  "data": {
    "count": 0,
    "data": [
      {
        "id": "id",
        "cost": 0,
        "count": 0,
        "createdAt": "2019-12-27T18:11:19.117Z",
        "file": "file",
        "mappings": {
          "line1": "line1",
          "city": "city",
          "country": "country",
          "firstName": "firstName",
          "fullName": "fullName",
          "lastName": "lastName",
          "line2": "line2",
          "postalOrZip": "postalOrZip",
          "provinceOrState": "provinceOrState"
        },
        "name": "name",
        "organization": "organization",
        "status": "status",
        "updatedAt": "2019-12-27T18:11:19.117Z",
        "useGeocode": true,
        "useIntlVerification": true,
        "useProperCase": true,
        "user": "user",
        "defaultCountry": "defaultCountry",
        "metadata": {
          "statusCount": {
            "corrected": 0,
            "failed": 0,
            "verified": 0
          }
        },
        "numInvalidRows": 0,
        "result": "result",
        "runCCOA": true,
        "runNCOA": true
      }
    ]
  },
  "message": "message",
  "status": "success"
}
Returns Examples
{
  "data": {
    "count": 0,
    "data": [
      {
        "id": "id",
        "cost": 0,
        "count": 0,
        "createdAt": "2019-12-27T18:11:19.117Z",
        "file": "file",
        "mappings": {
          "line1": "line1",
          "city": "city",
          "country": "country",
          "firstName": "firstName",
          "fullName": "fullName",
          "lastName": "lastName",
          "line2": "line2",
          "postalOrZip": "postalOrZip",
          "provinceOrState": "provinceOrState"
        },
        "name": "name",
        "organization": "organization",
        "status": "status",
        "updatedAt": "2019-12-27T18:11:19.117Z",
        "useGeocode": true,
        "useIntlVerification": true,
        "useProperCase": true,
        "user": "user",
        "defaultCountry": "defaultCountry",
        "metadata": {
          "statusCount": {
            "corrected": 0,
            "failed": 0,
            "verified": 0
          }
        },
        "numInvalidRows": 0,
        "result": "result",
        "runCCOA": true,
        "runNCOA": true
      }
    ]
  },
  "message": "message",
  "status": "success"
}