## List Targeted List Builds

**get** `/print-mail/v1/targeted_list_builds`

Retrieve a paginated list of targeted list builds for the authenticated
organization, ordered from most recently updated to least recently
updated.

### Query Parameters

- `limit: optional number`

- `search: optional string`

  You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.

- `skip: optional number`

### Returns

- `data: array of object { id, createdAt, live, 15 more }`

  - `id: string`

    A unique ID prefixed with targeted_list_build_

  - `createdAt: string`

    The UTC time at which this resource was created.

  - `live: boolean`

    `true` if this is a live mode resource else `false`.

  - `organization: string`

    The ID of the organization that owns this list build.

  - `status: "generating_quote" or "quote_ready" or "creating_list" or 2 more`

    Status of a targeted list build.

    - `"generating_quote"`

    - `"quote_ready"`

    - `"creating_list"`

    - `"completed"`

    - `"failed"`

  - `updatedAt: string`

    The UTC time at which this resource was last updated.

  - `buildProgressPercent: optional number`

    A percentage from 0 to 100 representing how much of the build has
    completed. Only populated while `status` is `creating_list`.

  - `completedAt: optional string`

    The UTC time at which the build finished successfully. Only present
    once `status` is `completed`.

  - `confirmedAt: optional string`

    The UTC time at which the build was confirmed, if any.

  - `description: optional string`

    An optional string describing this resource. Will be visible in the API and the dashboard.

  - `errors: optional array of object { message, type }`

    Any errors encountered while generating a quote or building the list.

    - `message: string`

      A human-readable message describing the error.

    - `type: "not_enough_info_to_quote" or "insufficient_credits" or "internal_service_error"`

      Type of error encountered while generating a quote or building the list.

      - `"not_enough_info_to_quote"`

      - `"insufficient_credits"`

      - `"internal_service_error"`

  - `limit: optional number`

    Maximum number of contacts to include in the built mailing list. If
    omitted, all matching contacts are included.

  - `mailingList: optional string`

    The ID of the mailing list that was built. Present once `status` is
    `completed`.

  - `metadata: optional map[unknown]`

    See the section on Metadata.

  - `previewRecords: optional array of object { formattedAddress, name }`

    A small number of masked sample records for the configured filters,
    populated alongside `quote`.

    - `formattedAddress: string`

      The masked, comma-joined formatted address of the contact.

    - `name: string`

      The masked name of the contact or business.

  - `quote: optional object { count, generatedAt, pricePerContactCents }`

    Details of the quote generated for a targeted list build.

    - `count: number`

      The number of contacts that will be included in the built mailing
      list. This accounts for any `limit` that was provided.

    - `generatedAt: string`

      The UTC time at which the quote was generated.

    - `pricePerContactCents: number`

      The price per contact, in cents. Multiply by `count` to get the total
      cost of building the list.

  - `usCompanies: optional object { postalCodes, companyTypes, employeeCount, 4 more }`

    Filters used to target US companies (B2B) when building a list.

    - `postalCodes: array of string`

      Required list of five-digit US ZIP codes to target.

    - `companyTypes: optional array of "public" or "private" or "educational" or 3 more`

      Filter by ownership structure of the company.

      - `"public"`

      - `"private"`

      - `"educational"`

      - `"government"`

      - `"nonprofit"`

      - `"public_subsidiary"`

    - `employeeCount: optional array of number`

      Inclusive `[min, max]` range for the number of employees at the
      company. Values must be between 1 and 1,000,000.

    - `foundedYear: optional array of number`

      Inclusive `[min, max]` range for the year the company was founded.
      Values must be between 1600 and 2100.

    - `industries: optional array of string`

      Filter by free-form industry names (see the autocomplete endpoint).

    - `naicsCodes: optional array of string`

      Filter by six-digit
      [NAICS](https://www.census.gov/naics/) industry codes.

    - `tags: optional array of string`

      Filter by free-form company tags (e.g., `"saas"`, `"b2b"`).

  - `usConsumers: optional object { ageRange, cityStates, educationLevels, 7 more }`

    Filters used to target US consumers (B2C) when building a list.

    The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are
    mutually exclusive — you may supply at most one of them.

    - `ageRange: optional array of number`

      Inclusive `[min, max]` age range. Values must be between 18 and 80.

    - `cityStates: optional array of string`

      A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target.

    - `educationLevels: optional array of "high_school" or "college" or "grad_school" or "vocational_training"`

      Filter by highest level of education completed.

      - `"high_school"`

      - `"college"`

      - `"grad_school"`

      - `"vocational_training"`

    - `gender: optional "male" or "female"`

      Gender filter for US consumer list builds.

      - `"male"`

      - `"female"`

    - `homeValueRange: optional array of number`

      Inclusive `[min, max]` home value range, in US dollars. Values must be
      between 0 and 1,000,000.

    - `incomeRange: optional array of number`

      Inclusive `[min, max]` annual household income range, in US dollars.
      Values must be between 0 and 200,000.

    - `numChildrenRange: optional array of number`

      Inclusive `[min, max]` number of children in the household. Values must
      be between 0 and 8.

    - `occupations: optional array of "professional_technical" or "administration_management" or "sales_service" or 23 more`

      Filter by occupation classification.

      - `"professional_technical"`

      - `"administration_management"`

      - `"sales_service"`

      - `"clerical_white_collar"`

      - `"craftsmen_blue_collar"`

      - `"student"`

      - `"homemaker"`

      - `"retired"`

      - `"farmer"`

      - `"military"`

      - `"religious"`

      - `"self_employed"`

      - `"self_employed_professional_technical"`

      - `"self_employed_administration_management"`

      - `"self_employed_sales_service"`

      - `"self_employed_clerical_white_collar"`

      - `"self_employed_craftsmen_blue_collar"`

      - `"self_employed_student"`

      - `"self_employed_homemaker"`

      - `"self_employed_retired"`

      - `"self_employed_other"`

      - `"educator"`

      - `"financial_professional"`

      - `"legal_professional"`

      - `"medical_professional"`

      - `"other"`

    - `zipCodes: optional array of string`

      A list of five-digit US ZIP codes to target.

    - `zipCodesAround: optional object { radiusInMiles, zipCode }`

      A geographic filter that selects all ZIP codes within a given radius of a
      center ZIP code.

      - `radiusInMiles: number`

        The radius in miles around `zipCode` to include. Between 0.1 and 100.

      - `zipCode: string`

        The five-digit ZIP code at the center of the search circle.

- `limit: number`

- `object: "list"`

  - `"list"`

- `skip: number`

- `totalCount: number`

### Example

```http
curl https://api.postgrid.com/print-mail/v1/targeted_list_builds \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```

#### Response

```json
{
  "object": "list",
  "totalCount": 1,
  "skip": 0,
  "limit": 10,
  "data": [
    {
      "id": "targeted_list_build_123",
      "live": false,
      "description": "Q1 prospecting list",
      "metadata": {
        "campaign": "q1_prospecting"
      },
      "createdAt": "2026-01-05T10:00:00Z",
      "updatedAt": "2026-01-05T10:01:30Z",
      "organization": "organization_123",
      "status": "quote_ready",
      "usCompanies": {
        "postalCodes": [
          "10001",
          "10002"
        ],
        "industries": [
          "software"
        ],
        "employeeCount": [
          10,
          500
        ]
      },
      "limit": 1000,
      "quote": {
        "generatedAt": "2026-01-05T10:01:30Z",
        "count": 1000,
        "pricePerContactCents": 11.98
      },
      "previewRecords": [
        {
          "name": "Acm***",
          "formattedAddress": "12** Main St, New York, NY, 100**"
        }
      ],
      "errors": []
    }
  ]
}
```