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