List

GET/v1/addver_lists

Retrieve a list of your bulk verification lists.

Query ParametersExpand Collapse

limit: optional number

The maximum number of lists to return.

skip: optional number

The number of lists to skip past, for pagination.

ReturnsExpand Collapse

data: object { count, data }

A list of bulk verification lists.

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.

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"

List

curl https://api.postgrid.com/v1/addver_lists \
    -H "X-API-Key: $POSTGRID_ADDRESS_VERIFICATION_API_KEY"

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

Returns Examples

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