# Bulk Verification ## Upload `client.bulkVerification.upload(BulkVerificationUploadParamsbody, RequestOptionsoptions?): 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. ### Parameters - `body: BulkVerificationUploadParams` - `file: Uploadable` - `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: string` The column containing the first line of each address. If your entire address is in a single column, specify only this mapping. - `city?: string` The column containing the city of each address. - `country?: string` The column containing the 2-letter ISO country code of each address (e.g. `US`, not `United States`). - `firstName?: string` The column containing the first name of the person at each address. Only used when NCOA is run. - `fullName?: 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?: string` The column containing the last name of the person at each address. Only used when NCOA is run. - `line2?: string` The column containing the second line of each address. - `postalOrZip?: string` The column containing the postal or ZIP code of each address. - `provinceOrState?: string` The column containing the province or state of each address. - `name: string` A name for the uploaded list. This only affects what is displayed in the dashboard. - `defaultCountry?: string` An ISO 2-letter country code used as the fallback when a row is missing a value in the `country` column. - `runCCOA?: boolean` 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. - `runNCOA?: boolean` Whether to run NCOA (US National Change of Address) on the list. - `useGeocode?: boolean` Whether to append geographical location information (latitude, longitude) to your output. Bulk geocoding must be enabled by contacting support. - `useIntlVerification?: boolean` Whether to perform international (outside US & Canada) verification. - `useProperCase?: boolean` Whether to return addresses in Proper Case. ### Returns - `BulkVerificationUploadResponse` - `data: AddverList` 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. - `file: string` 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: string` The column containing the first line of each address. If your entire address is in a single column, specify only this mapping. - `city?: string` The column containing the city of each address. - `country?: string` The column containing the 2-letter ISO country code of each address (e.g. `US`, not `United States`). - `firstName?: string` The column containing the first name of the person at each address. Only used when NCOA is run. - `fullName?: 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?: string` The column containing the last name of the person at each address. Only used when NCOA is run. - `line2?: string` The column containing the second line of each address. - `postalOrZip?: string` The column containing the postal or ZIP code of each address. - `provinceOrState?: 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. - `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?: 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?: Metadata` Additional metadata about the list, including a count of each status. - `statusCount?: StatusCount` The number of addresses by resulting verification status. - `corrected?: number` - `failed?: number` - `verified?: number` - `numInvalidRows?: number` The number of invalid or skipped rows in the uploaded file. May be omitted on lists created before this field was introduced. - `result?: string` A signed URL to the processed output CSV file. Present once the list has finished processing. - `runCCOA?: boolean` Whether CCOA (Canada Post change of address) was requested. May be omitted on lists created before COA support was introduced. - `runNCOA?: 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" | "error"` - `"success"` - `"error"` ### Example ```typescript import fs from 'fs'; import PostGrid from 'postgrid-node'; const client = new PostGrid({ addressVerificationAPIKey: process.env['POSTGRID_ADDRESS_VERIFICATION_API_KEY'], // This is the default and can be omitted }); const response = await client.bulkVerification.upload({ file: fs.createReadStream('path/to/file'), mappings: { line1: 'line1' }, name: 'name', }); console.log(response.data); ``` #### Response ```json { "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" } ``` ## List `client.bulkVerification.list(BulkVerificationListParamsquery?, RequestOptionsoptions?): BulkVerificationListResponse` **get** `/v1/addver_lists` Retrieve a list of your bulk verification lists. ### Parameters - `query: BulkVerificationListParams` - `limit?: number` The maximum number of lists to return. - `skip?: number` The number of lists to skip past, for pagination. ### Returns - `BulkVerificationListResponse` - `data: Data` A list of bulk verification lists. - `count: number` The total number of lists. - `data: Array` 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. - `file: string` 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: string` The column containing the first line of each address. If your entire address is in a single column, specify only this mapping. - `city?: string` The column containing the city of each address. - `country?: string` The column containing the 2-letter ISO country code of each address (e.g. `US`, not `United States`). - `firstName?: string` The column containing the first name of the person at each address. Only used when NCOA is run. - `fullName?: 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?: string` The column containing the last name of the person at each address. Only used when NCOA is run. - `line2?: string` The column containing the second line of each address. - `postalOrZip?: string` The column containing the postal or ZIP code of each address. - `provinceOrState?: 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. - `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?: 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?: Metadata` Additional metadata about the list, including a count of each status. - `statusCount?: StatusCount` The number of addresses by resulting verification status. - `corrected?: number` - `failed?: number` - `verified?: number` - `numInvalidRows?: number` The number of invalid or skipped rows in the uploaded file. May be omitted on lists created before this field was introduced. - `result?: string` A signed URL to the processed output CSV file. Present once the list has finished processing. - `runCCOA?: boolean` Whether CCOA (Canada Post change of address) was requested. May be omitted on lists created before COA support was introduced. - `runNCOA?: 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" | "error"` - `"success"` - `"error"` ### Example ```typescript import PostGrid from 'postgrid-node'; const client = new PostGrid({ addressVerificationAPIKey: process.env['POSTGRID_ADDRESS_VERIFICATION_API_KEY'], // This is the default and can be omitted }); const bulkVerifications = await client.bulkVerification.list(); console.log(bulkVerifications.data); ``` #### Response ```json { "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" } ``` ## Retrieve `client.bulkVerification.retrieve(stringid, RequestOptionsoptions?): BulkVerificationRetrieveResponse` **get** `/v1/addver_lists/{id}` Retrieve a single bulk verification list by ID, including its processing status and — once processed — a link to the output CSV. ### Parameters - `id: string` ### Returns - `BulkVerificationRetrieveResponse` - `data: AddverList` 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. - `file: string` 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: string` The column containing the first line of each address. If your entire address is in a single column, specify only this mapping. - `city?: string` The column containing the city of each address. - `country?: string` The column containing the 2-letter ISO country code of each address (e.g. `US`, not `United States`). - `firstName?: string` The column containing the first name of the person at each address. Only used when NCOA is run. - `fullName?: 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?: string` The column containing the last name of the person at each address. Only used when NCOA is run. - `line2?: string` The column containing the second line of each address. - `postalOrZip?: string` The column containing the postal or ZIP code of each address. - `provinceOrState?: 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. - `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?: 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?: Metadata` Additional metadata about the list, including a count of each status. - `statusCount?: StatusCount` The number of addresses by resulting verification status. - `corrected?: number` - `failed?: number` - `verified?: number` - `numInvalidRows?: number` The number of invalid or skipped rows in the uploaded file. May be omitted on lists created before this field was introduced. - `result?: string` A signed URL to the processed output CSV file. Present once the list has finished processing. - `runCCOA?: boolean` Whether CCOA (Canada Post change of address) was requested. May be omitted on lists created before COA support was introduced. - `runNCOA?: 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" | "error"` - `"success"` - `"error"` ### Example ```typescript import PostGrid from 'postgrid-node'; const client = new PostGrid({ addressVerificationAPIKey: process.env['POSTGRID_ADDRESS_VERIFICATION_API_KEY'], // This is the default and can be omitted }); const bulkVerification = await client.bulkVerification.retrieve('id'); console.log(bulkVerification.data); ``` #### Response ```json { "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" } ``` ## Domain Types ### Addver List - `AddverList` 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. - `file: string` 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: string` The column containing the first line of each address. If your entire address is in a single column, specify only this mapping. - `city?: string` The column containing the city of each address. - `country?: string` The column containing the 2-letter ISO country code of each address (e.g. `US`, not `United States`). - `firstName?: string` The column containing the first name of the person at each address. Only used when NCOA is run. - `fullName?: 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?: string` The column containing the last name of the person at each address. Only used when NCOA is run. - `line2?: string` The column containing the second line of each address. - `postalOrZip?: string` The column containing the postal or ZIP code of each address. - `provinceOrState?: 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. - `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?: 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?: Metadata` Additional metadata about the list, including a count of each status. - `statusCount?: StatusCount` The number of addresses by resulting verification status. - `corrected?: number` - `failed?: number` - `verified?: number` - `numInvalidRows?: number` The number of invalid or skipped rows in the uploaded file. May be omitted on lists created before this field was introduced. - `result?: string` A signed URL to the processed output CSV file. Present once the list has finished processing. - `runCCOA?: boolean` Whether CCOA (Canada Post change of address) was requested. May be omitted on lists created before COA support was introduced. - `runNCOA?: boolean` Whether NCOA (US National Change of Address) was requested. May be omitted on lists created before COA support was introduced. ### Bulk Verification Upload Response - `BulkVerificationUploadResponse` - `data: AddverList` 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. - `file: string` 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: string` The column containing the first line of each address. If your entire address is in a single column, specify only this mapping. - `city?: string` The column containing the city of each address. - `country?: string` The column containing the 2-letter ISO country code of each address (e.g. `US`, not `United States`). - `firstName?: string` The column containing the first name of the person at each address. Only used when NCOA is run. - `fullName?: 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?: string` The column containing the last name of the person at each address. Only used when NCOA is run. - `line2?: string` The column containing the second line of each address. - `postalOrZip?: string` The column containing the postal or ZIP code of each address. - `provinceOrState?: 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. - `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?: 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?: Metadata` Additional metadata about the list, including a count of each status. - `statusCount?: StatusCount` The number of addresses by resulting verification status. - `corrected?: number` - `failed?: number` - `verified?: number` - `numInvalidRows?: number` The number of invalid or skipped rows in the uploaded file. May be omitted on lists created before this field was introduced. - `result?: string` A signed URL to the processed output CSV file. Present once the list has finished processing. - `runCCOA?: boolean` Whether CCOA (Canada Post change of address) was requested. May be omitted on lists created before COA support was introduced. - `runNCOA?: 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" | "error"` - `"success"` - `"error"` ### Bulk Verification List Response - `BulkVerificationListResponse` - `data: Data` A list of bulk verification lists. - `count: number` The total number of lists. - `data: Array` 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. - `file: string` 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: string` The column containing the first line of each address. If your entire address is in a single column, specify only this mapping. - `city?: string` The column containing the city of each address. - `country?: string` The column containing the 2-letter ISO country code of each address (e.g. `US`, not `United States`). - `firstName?: string` The column containing the first name of the person at each address. Only used when NCOA is run. - `fullName?: 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?: string` The column containing the last name of the person at each address. Only used when NCOA is run. - `line2?: string` The column containing the second line of each address. - `postalOrZip?: string` The column containing the postal or ZIP code of each address. - `provinceOrState?: 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. - `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?: 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?: Metadata` Additional metadata about the list, including a count of each status. - `statusCount?: StatusCount` The number of addresses by resulting verification status. - `corrected?: number` - `failed?: number` - `verified?: number` - `numInvalidRows?: number` The number of invalid or skipped rows in the uploaded file. May be omitted on lists created before this field was introduced. - `result?: string` A signed URL to the processed output CSV file. Present once the list has finished processing. - `runCCOA?: boolean` Whether CCOA (Canada Post change of address) was requested. May be omitted on lists created before COA support was introduced. - `runNCOA?: 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" | "error"` - `"success"` - `"error"` ### Bulk Verification Retrieve Response - `BulkVerificationRetrieveResponse` - `data: AddverList` 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. - `file: string` 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: string` The column containing the first line of each address. If your entire address is in a single column, specify only this mapping. - `city?: string` The column containing the city of each address. - `country?: string` The column containing the 2-letter ISO country code of each address (e.g. `US`, not `United States`). - `firstName?: string` The column containing the first name of the person at each address. Only used when NCOA is run. - `fullName?: 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?: string` The column containing the last name of the person at each address. Only used when NCOA is run. - `line2?: string` The column containing the second line of each address. - `postalOrZip?: string` The column containing the postal or ZIP code of each address. - `provinceOrState?: 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. - `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?: 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?: Metadata` Additional metadata about the list, including a count of each status. - `statusCount?: StatusCount` The number of addresses by resulting verification status. - `corrected?: number` - `failed?: number` - `verified?: number` - `numInvalidRows?: number` The number of invalid or skipped rows in the uploaded file. May be omitted on lists created before this field was introduced. - `result?: string` A signed URL to the processed output CSV file. Present once the list has finished processing. - `runCCOA?: boolean` Whether CCOA (Canada Post change of address) was requested. May be omitted on lists created before COA support was introduced. - `runNCOA?: 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" | "error"` - `"success"` - `"error"`