Upload

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.

Body ParametersForm DataExpand Collapse

file: 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.

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

defaultCountry: optional string

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

runCCOA: optional 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: optional boolean

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

useGeocode: optional boolean

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

useIntlVerification: optional boolean

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

useProperCase: optional boolean

Whether to return addresses in Proper Case.

ReturnsExpand Collapse

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: 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.

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"

Upload

curl https://api.postgrid.com/v1/addver_lists \
    -H 'Content-Type: multipart/form-data' \
    -H "X-API-Key: $POSTGRID_ADDRESS_VERIFICATION_API_KEY" \
    -F 'file=@/path/to/file' \
    -F mappings='{"line1":"line1"}' \
    -F name=name

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