Skip to content
PostGrid PostGrid
Get startedDashboardSupport
API Reference

Bulk Verification

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 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 [email protected] to enable the feature.

Upload
bulk_verification.upload(BulkVerificationUploadParams**kwargs) -> BulkVerificationUploadResponse
POST/v1/addver_lists
List
bulk_verification.list(BulkVerificationListParams**kwargs) -> BulkVerificationListResponse
GET/v1/addver_lists
Retrieve
bulk_verification.retrieve(strid) -> BulkVerificationRetrieveResponse
GET/v1/addver_lists/{id}
ModelsExpand Collapse
class 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.

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.

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.

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"
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"
class BulkVerificationRetrieveResponse: …
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.

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"