Upload

client.bulkVerification.upload(, ?): BulkVerificationUploadResponse { data, message, status }

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

body: BulkVerificationUploadParams { file, mappings, name, 6 more }

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.

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.

ReturnsExpand Collapse

BulkVerificationUploadResponse { 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.

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: Mappings { 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?: 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.

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?: 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 { statusCount }

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

statusCount?: StatusCount { corrected, failed, verified }

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"

One of the following:

"success"

"error"

Upload

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);

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