## Get Targeted List Build

`print_mail.targeted_list_builds.retrieve(strid)  -> TargetedListBuildRetrieveResponse`

**get** `/print-mail/v1/targeted_list_builds/{id}`

Retrieve a specific targeted list build by its ID.

### Parameters

- `id: str`

### Returns

- `class TargetedListBuildRetrieveResponse: …`

  A targeted list build represents a request to build a new mailing list by
  targeting US consumers or companies matching the provided filters. Once
  created, a quote is generated asynchronously. After reviewing the quote
  and preview records, you may confirm the build, which kicks off the
  creation of the underlying mailing list.

  - `id: str`

    A unique ID prefixed with targeted_list_build_

  - `created_at: datetime`

    The UTC time at which this resource was created.

  - `live: bool`

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

  - `organization: str`

    The ID of the organization that owns this list build.

  - `status: Literal["generating_quote", "quote_ready", "creating_list", 2 more]`

    Status of a targeted list build.

    - `"generating_quote"`

    - `"quote_ready"`

    - `"creating_list"`

    - `"completed"`

    - `"failed"`

  - `updated_at: datetime`

    The UTC time at which this resource was last updated.

  - `build_progress_percent: Optional[float]`

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

  - `completed_at: Optional[datetime]`

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

  - `confirmed_at: Optional[datetime]`

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

  - `description: Optional[str]`

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

  - `errors: Optional[List[Error]]`

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

    - `message: str`

      A human-readable message describing the error.

    - `type: Literal["not_enough_info_to_quote", "insufficient_credits", "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[int]`

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

  - `mailing_list: Optional[str]`

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

  - `metadata: Optional[Dict[str, object]]`

    See the section on Metadata.

  - `preview_records: Optional[List[PreviewRecord]]`

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

    - `formatted_address: str`

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

    - `name: str`

      The masked name of the contact or business.

  - `quote: Optional[Quote]`

    Details of the quote generated for a targeted list build.

    - `count: int`

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

    - `generated_at: datetime`

      The UTC time at which the quote was generated.

    - `price_per_contact_cents: float`

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

  - `us_companies: Optional[UsCompanies]`

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

    - `postal_codes: List[str]`

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

    - `company_types: Optional[List[Literal["public", "private", "educational", 3 more]]]`

      Filter by ownership structure of the company.

      - `"public"`

      - `"private"`

      - `"educational"`

      - `"government"`

      - `"nonprofit"`

      - `"public_subsidiary"`

    - `employee_count: Optional[List[int]]`

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

    - `founded_year: Optional[List[int]]`

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

    - `industries: Optional[List[str]]`

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

    - `naics_codes: Optional[List[str]]`

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

    - `tags: Optional[List[str]]`

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

  - `us_consumers: Optional[UsConsumers]`

    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.

    - `age_range: Optional[List[int]]`

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

    - `city_states: Optional[List[str]]`

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

    - `education_levels: Optional[List[Literal["high_school", "college", "grad_school", "vocational_training"]]]`

      Filter by highest level of education completed.

      - `"high_school"`

      - `"college"`

      - `"grad_school"`

      - `"vocational_training"`

    - `gender: Optional[Literal["male", "female"]]`

      Gender filter for US consumer list builds.

      - `"male"`

      - `"female"`

    - `home_value_range: Optional[List[int]]`

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

    - `income_range: Optional[List[int]]`

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

    - `num_children_range: Optional[List[int]]`

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

    - `occupations: Optional[List[Literal["professional_technical", "administration_management", "sales_service", 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"`

    - `zip_codes: Optional[List[str]]`

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

    - `zip_codes_around: Optional[UsConsumersZipCodesAround]`

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

      - `radius_in_miles: float`

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

      - `zip_code: str`

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

### Example

```python
import os
from postgrid import PostGrid

client = PostGrid(
    print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"),  # This is the default and can be omitted
)
targeted_list_build = client.print_mail.targeted_list_builds.retrieve(
    "id",
)
print(targeted_list_build.id)
```

#### Response

```json
{
  "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": []
}
```