Upload

bulk_verification.upload() -> BulkVerificationUploadResponse

POST/v1/addver_lists

Upload a CSV file of addresses to be verified in bulk. Supply a mappings object describing which CSV columns correspond to which address fields.

ParametersExpand Collapse

file: FileTypes

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.

A name for the uploaded list. This only affects what is displayed in the dashboard.

default_country: Optional[str]

An ISO 2-letter country code used as the fallback when a row is missing a value in the country column.

run_ccoa: Optional[bool]

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.

run_ncoa: Optional[bool]

Whether to run NCOA (US National Change of Address) on the list.

use_geocode: Optional[bool]

Whether to append geographical location information (latitude, longitude) to your output. Bulk geocoding must be enabled by contacting support.

use_intl_verification: Optional[bool]

Whether to perform international (outside US & Canada) verification.

use_proper_case: Optional[bool]

Whether to return addresses in Proper Case.

ReturnsExpand Collapse

class BulkVerificationUploadResponse: …

data: AddverList

A bulk address verification list — an uploaded CSV file of addresses and its processing state.

id: str

A unique ID prefixed with addver_list_.

cost: int

The cost charged for processing this list.

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.

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"

Upload

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
)
response = client.bulk_verification.upload(
    file=b"Example data",
    mappings={
        "line1": "line1"
    },
    name="name",
)
print(response.data)

{
  "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": {
    "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"
}