## List

**get** `/v1/addver_lists`

Retrieve a list of your bulk verification lists.

### Query Parameters

- `limit: optional number`

  The maximum number of lists to return.

- `skip: optional number`

  The number of lists to skip past, for pagination.

### Returns

- `data: object { count, data }`

  A list of bulk verification lists.

  - `count: number`

    The total number of lists.

  - `data: array of AddverList`

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

    - `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"`

  - `"success"`

  - `"error"`

### Example

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

#### 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"
}
```