# Targeted List Builds

## Create Targeted List Build

`print_mail.targeted_list_builds.create(TargetedListBuildCreateParams**kwargs)  -> TargetedListBuildCreateResponse`

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

Create a new targeted list build. A quote will be generated
asynchronously based on the provided filters.

### Parameters

- `description: Optional[str]`

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

- `limit: Optional[int]`

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

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

  See the section on Metadata.

- `us_companies: Optional[UsCompanies]`

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

  - `postal_codes: Sequence[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[Iterable[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[Iterable[int]]`

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

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

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

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

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

  - `tags: Optional[Sequence[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[Iterable[int]]`

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

  - `city_states: Optional[Sequence[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[Iterable[int]]`

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

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

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

  - `num_children_range: Optional[Iterable[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[Sequence[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.

- `idempotency_key: Optional[str]`

### Returns

- `class TargetedListBuildCreateResponse: …`

  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.create(
    description="Q1 prospecting list",
    limit=1000,
    metadata={
        "campaign": "q1_prospecting"
    },
    us_companies={
        "postal_codes": ["10001", "10002"],
        "industries": ["software"],
        "employee_count": [10, 500],
    },
)
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": []
}
```

## List Targeted List Builds

`print_mail.targeted_list_builds.list(TargetedListBuildListParams**kwargs)  -> SyncSkipLimit[TargetedListBuildListResponse]`

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

### Parameters

- `limit: Optional[int]`

- `search: Optional[str]`

  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[int]`

### Returns

- `class TargetedListBuildListResponse: …`

  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
)
page = client.print_mail.targeted_list_builds.list()
page = page.data[0]
print(page.id)
```

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

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

## Update Targeted List Build

`print_mail.targeted_list_builds.update(strid, TargetedListBuildUpdateParams**kwargs)  -> TargetedListBuildUpdateResponse`

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

Update an existing targeted list build. Only builds that have not yet
been confirmed may be updated. Updating the filters or `limit` will
reset the build's status back to `generating_quote` and a new quote
will be generated.

### Parameters

- `id: str`

- `description: Optional[str]`

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

- `limit: Optional[int]`

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

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

  See the section on Metadata.

- `us_companies: Optional[UsCompanies]`

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

  - `postal_codes: Sequence[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[Iterable[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[Iterable[int]]`

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

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

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

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

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

  - `tags: Optional[Sequence[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[Iterable[int]]`

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

  - `city_states: Optional[Sequence[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[Iterable[int]]`

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

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

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

  - `num_children_range: Optional[Iterable[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[Sequence[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.

### Returns

- `class TargetedListBuildUpdateResponse: …`

  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.update(
    id="id",
    limit=2000,
    us_companies={
        "postal_codes": ["10001", "10002", "10003"],
        "industries": ["software", "fintech"],
        "employee_count": [50, 1000],
    },
)
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": []
}
```

## Delete Targeted List Build

`print_mail.targeted_list_builds.delete(strid)  -> TargetedListBuildDeleteResponse`

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

Delete a targeted list build. List builds can only be deleted before
they have been confirmed — once a build has transitioned to
`creating_list` or `completed` it cannot be deleted.

### Parameters

- `id: str`

### Returns

- `class TargetedListBuildDeleteResponse: …`

  - `id: str`

    A unique ID prefixed with targeted_list_build_

  - `deleted: Literal[true]`

    - `true`

### 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.delete(
    "id",
)
print(targeted_list_build.id)
```

#### Response

```json
{
  "id": "targeted_list_build_123",
  "deleted": true
}
```

## Confirm Targeted List Build

`print_mail.targeted_list_builds.confirm(strid)  -> TargetedListBuildConfirmResponse`

**post** `/print-mail/v1/targeted_list_builds/{id}/confirm`

Confirm a targeted list build whose quote is ready. This deducts the
appropriate amount of list build credits from the organization (in
live mode) and kicks off the asynchronous creation of the underlying
mailing list.

### Parameters

- `id: str`

### Returns

- `class TargetedListBuildConfirmResponse: …`

  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
)
response = client.print_mail.targeted_list_builds.confirm(
    "id",
)
print(response.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:05:00Z",
  "organization": "organization_123",
  "status": "creating_list",
  "usCompanies": {
    "postalCodes": [
      "10001",
      "10002"
    ],
    "industries": [
      "software"
    ],
    "employeeCount": [
      10,
      500
    ]
  },
  "limit": 1000,
  "quote": {
    "generatedAt": "2026-01-05T10:01:30Z",
    "count": 1000,
    "pricePerContactCents": 11.98
  },
  "confirmedAt": "2026-01-05T10:05:00Z",
  "buildProgressPercent": 0,
  "errors": []
}
```

## Domain Types

### Targeted List Build Create Response

- `class TargetedListBuildCreateResponse: …`

  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.

### Targeted List Build List Response

- `class TargetedListBuildListResponse: …`

  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.

### Targeted List Build Retrieve Response

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

### Targeted List Build Update Response

- `class TargetedListBuildUpdateResponse: …`

  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.

### Targeted List Build Delete Response

- `class TargetedListBuildDeleteResponse: …`

  - `id: str`

    A unique ID prefixed with targeted_list_build_

  - `deleted: Literal[true]`

    - `true`

### Targeted List Build Confirm Response

- `class TargetedListBuildConfirmResponse: …`

  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.

# Filters

## Autocomplete Filter Values

`print_mail.targeted_list_builds.filters.autocomplete(FilterAutocompleteParams**kwargs)  -> FilterAutocompleteResponse`

**post** `/print-mail/v1/targeted_list_builds/filters/autocomplete`

Return a list of autocomplete suggestions for a given filter field
(currently only `industry` is supported). Useful when building a UI
around the `industries` company filter.

### Parameters

- `field: Literal["industry"]`

  A field that can be autocompleted when configuring list build filters.

  - `"industry"`

- `size: Optional[int]`

  Maximum number of suggestions to return. Between 1 and 100.
  Defaults to 25 if omitted.

- `text: Optional[str]`

  Optional text prefix to narrow the autocomplete suggestions.

### Returns

- `class FilterAutocompleteResponse: …`

  The list of suggestions returned by an autocomplete query.

  - `data: List[Data]`

    - `type: Literal["industry"]`

      A field that can be autocompleted when configuring list build filters.

      - `"industry"`

    - `value: str`

      The suggested value (e.g., an industry name).

  - `object: Literal["list"]`

    - `"list"`

### 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
)
response = client.print_mail.targeted_list_builds.filters.autocomplete(
    field="industry",
    size=5,
    text="soft",
)
print(response.data)
```

#### Response

```json
{
  "object": "list",
  "data": [
    {
      "value": "software",
      "type": "industry"
    },
    {
      "value": "software development",
      "type": "industry"
    }
  ]
}
```

## Domain Types

### Filter Autocomplete Response

- `class FilterAutocompleteResponse: …`

  The list of suggestions returned by an autocomplete query.

  - `data: List[Data]`

    - `type: Literal["industry"]`

      A field that can be autocompleted when configuring list build filters.

      - `"industry"`

    - `value: str`

      The suggested value (e.g., an industry name).

  - `object: Literal["list"]`

    - `"list"`