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
POST/v1/addver_lists
List
GET/v1/addver_lists
Retrieve
GET/v1/addver_lists/{id}
ModelsExpand Collapse
AddverList object { id, cost, count, 17 more }

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

id: string

A unique ID prefixed with addver_list_.

cost: number

The cost charged for processing this list.

count: number

The number of addresses in the uploaded file.

createdAt: string

The UTC time at which this list was created.

formatdate-time
file: string

A signed URL to the uploaded input CSV file.

mappings: object { line1, city, country, 6 more }

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

line1: string

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

city: optional string

The column containing the city of each address.

country: optional string

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

firstName: optional string

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

fullName: optional string

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.

lastName: optional string

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

line2: optional string

The column containing the second line of each address.

postalOrZip: optional string

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

provinceOrState: optional string

The column containing the province or state of each address.

name: string

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

organization: string

The ID of the organization that owns this list.

status: string

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

updatedAt: string

The UTC time at which this list was last updated.

formatdate-time
useGeocode: boolean

Whether geocoding (latitude/longitude) output was requested.

useIntlVerification: boolean

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

useProperCase: boolean

Whether Proper Case output was requested.

user: string

The ID of the user that created this list.

defaultCountry: optional string

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 object { statusCount }

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

statusCount: optional object { corrected, failed, verified }

The number of addresses by resulting verification status.

corrected: optional number
failed: optional number
verified: optional number
numInvalidRows: optional number

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

result: optional string

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

runCCOA: optional boolean

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

runNCOA: optional boolean

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

BulkVerificationUploadResponse object { data, message, status }
data: AddverList { id, cost, count, 17 more }

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

id: string

A unique ID prefixed with addver_list_.

cost: number

The cost charged for processing this list.

count: number

The number of addresses in the uploaded file.

createdAt: string

The UTC time at which this list was created.

formatdate-time
file: string

A signed URL to the uploaded input CSV file.

mappings: object { line1, city, country, 6 more }

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

line1: string

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

city: optional string

The column containing the city of each address.

country: optional string

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

firstName: optional string

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

fullName: optional string

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.

lastName: optional string

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

line2: optional string

The column containing the second line of each address.

postalOrZip: optional string

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

provinceOrState: optional string

The column containing the province or state of each address.

name: string

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

organization: string

The ID of the organization that owns this list.

status: string

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

updatedAt: string

The UTC time at which this list was last updated.

formatdate-time
useGeocode: boolean

Whether geocoding (latitude/longitude) output was requested.

useIntlVerification: boolean

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

useProperCase: boolean

Whether Proper Case output was requested.

user: string

The ID of the user that created this list.

defaultCountry: optional string

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 object { statusCount }

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

statusCount: optional object { corrected, failed, verified }

The number of addresses by resulting verification status.

corrected: optional number
failed: optional number
verified: optional number
numInvalidRows: optional number

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

result: optional string

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

runCCOA: optional boolean

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

runNCOA: optional boolean

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

message: string
status: "success" or "error"
One of the following:
"success"
"error"
BulkVerificationListResponse object { data, message, status }
data: object { count, data }

A list of bulk verification lists.

count: number

The total number of lists.

data: array of AddverList { id, cost, count, 17 more }

The requested lists.

id: string

A unique ID prefixed with addver_list_.

cost: number

The cost charged for processing this list.

count: number

The number of addresses in the uploaded file.

createdAt: string

The UTC time at which this list was created.

formatdate-time
file: string

A signed URL to the uploaded input CSV file.

mappings: object { line1, city, country, 6 more }

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

line1: string

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

city: optional string

The column containing the city of each address.

country: optional string

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

firstName: optional string

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

fullName: optional string

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.

lastName: optional string

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

line2: optional string

The column containing the second line of each address.

postalOrZip: optional string

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

provinceOrState: optional string

The column containing the province or state of each address.

name: string

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

organization: string

The ID of the organization that owns this list.

status: string

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

updatedAt: string

The UTC time at which this list was last updated.

formatdate-time
useGeocode: boolean

Whether geocoding (latitude/longitude) output was requested.

useIntlVerification: boolean

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

useProperCase: boolean

Whether Proper Case output was requested.

user: string

The ID of the user that created this list.

defaultCountry: optional string

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 object { statusCount }

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

statusCount: optional object { corrected, failed, verified }

The number of addresses by resulting verification status.

corrected: optional number
failed: optional number
verified: optional number
numInvalidRows: optional number

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

result: optional string

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

runCCOA: optional boolean

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

runNCOA: optional boolean

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

message: string
status: "success" or "error"
One of the following:
"success"
"error"
BulkVerificationRetrieveResponse object { data, message, status }
data: AddverList { id, cost, count, 17 more }

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

id: string

A unique ID prefixed with addver_list_.

cost: number

The cost charged for processing this list.

count: number

The number of addresses in the uploaded file.

createdAt: string

The UTC time at which this list was created.

formatdate-time
file: string

A signed URL to the uploaded input CSV file.

mappings: object { line1, city, country, 6 more }

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

line1: string

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

city: optional string

The column containing the city of each address.

country: optional string

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

firstName: optional string

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

fullName: optional string

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.

lastName: optional string

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

line2: optional string

The column containing the second line of each address.

postalOrZip: optional string

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

provinceOrState: optional string

The column containing the province or state of each address.

name: string

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

organization: string

The ID of the organization that owns this list.

status: string

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

updatedAt: string

The UTC time at which this list was last updated.

formatdate-time
useGeocode: boolean

Whether geocoding (latitude/longitude) output was requested.

useIntlVerification: boolean

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

useProperCase: boolean

Whether Proper Case output was requested.

user: string

The ID of the user that created this list.

defaultCountry: optional string

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 object { statusCount }

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

statusCount: optional object { corrected, failed, verified }

The number of addresses by resulting verification status.

corrected: optional number
failed: optional number
verified: optional number
numInvalidRows: optional number

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

result: optional string

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

runCCOA: optional boolean

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

runNCOA: optional boolean

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

message: string
status: "success" or "error"
One of the following:
"success"
"error"