--- title: "Update Targeted List Build" method: POST path: "/print-mail/v1/targeted_list_builds/{id}" tags: ["Targeted List Builds"] --- # Update Targeted List Build `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. ## Path parameters - `id` string, required ## Request body - TargetedListBuildUpdate — Parameters for updating an existing targeted list build. Updates may only be made while the build has not yet been confirmed. Changing `usConsumers` or `usCompanies` will reset the build's `status` back to `generating_quote` and clear the previously generated `quote` and preview records. Providing `usConsumers` while the build had `usCompanies` (or vice versa) will clear the other side. - `description` string — An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata` object — See the section on Metadata. - `usConsumers` USConsumerListFilters — 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. - `zipCodesAround` USZipsAroundFilter — A geographic filter that selects all ZIP codes within a given radius of a center ZIP code. - `zipCode` string, required — The five-digit ZIP code at the center of the search circle. - `radiusInMiles` number, float, required — The radius in miles around `zipCode` to include. Between 0.1 and 100. - `cityStates` string[] — A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target. - `zipCodes` string[] — A list of five-digit US ZIP codes to target. - `ageRange` USConsumerAge[] — Inclusive `[min, max]` age range. Values must be between 18 and 80. - `incomeRange` USConsumerIncomeUSD[] — Inclusive `[min, max]` annual household income range, in US dollars. Values must be between 0 and 200,000. - `gender` 'male' | 'female' — Gender filter for US consumer list builds. - `educationLevels` USConsumerEducationLevel[] — Filter by highest level of education completed. - `occupations` USConsumerOccupation[] — Filter by occupation classification. - `numChildrenRange` USConsumerNumChildren[] — Inclusive `[min, max]` number of children in the household. Values must be between 0 and 8. - `homeValueRange` USConsumerHomeValueUSD[] — Inclusive `[min, max]` home value range, in US dollars. Values must be between 0 and 1,000,000. - `usCompanies` USCompanyListFilters — Filters used to target US companies (B2B) when building a list. - `postalCodes` string[], required — Required list of five-digit US ZIP codes to target. - `companyTypes` USCompanyType[] — Filter by ownership structure of the company. - `industries` string[] — Filter by free-form industry names (see the autocomplete endpoint). - `tags` string[] — Filter by free-form company tags (e.g., `"saas"`, `"b2b"`). - `naicsCodes` string[] — Filter by six-digit [NAICS](https://www.census.gov/naics/) industry codes. - `employeeCount` USCompanyEmployeeCount[] — Inclusive `[min, max]` range for the number of employees at the company. Values must be between 1 and 1,000,000. - `foundedYear` USCompanyFoundedYear[] — Inclusive `[min, max]` range for the year the company was founded. Values must be between 1600 and 2100. - `limit` integer — Maximum number of contacts to include in the built mailing list. If omitted, all matching contacts are included. ## Response `200` The updated targeted list build. - TargetedListBuild — 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` string, required — A unique ID prefixed with targeted_list_build_ - `description` string — An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata` object — See the section on Metadata. - `live` boolean, required — `true` if this is a live mode resource else `false`. - `createdAt` string, date-time, required — The UTC time at which this resource was created. - `updatedAt` string, date-time, required — The UTC time at which this resource was last updated. - `organization` string, required — The ID of the organization that owns this list build. - `status` 'generating_quote' | 'quote_ready' | 'creating_list' | 'completed' | 'failed', required — Status of a targeted list build. - `usConsumers` USConsumerListFilters — 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. - `zipCodesAround` USZipsAroundFilter — A geographic filter that selects all ZIP codes within a given radius of a center ZIP code. - `zipCode` string, required — The five-digit ZIP code at the center of the search circle. - `radiusInMiles` number, float, required — The radius in miles around `zipCode` to include. Between 0.1 and 100. - `cityStates` string[] — A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target. - `zipCodes` string[] — A list of five-digit US ZIP codes to target. - `ageRange` USConsumerAge[] — Inclusive `[min, max]` age range. Values must be between 18 and 80. - `incomeRange` USConsumerIncomeUSD[] — Inclusive `[min, max]` annual household income range, in US dollars. Values must be between 0 and 200,000. - `gender` 'male' | 'female' — Gender filter for US consumer list builds. - `educationLevels` USConsumerEducationLevel[] — Filter by highest level of education completed. - `occupations` USConsumerOccupation[] — Filter by occupation classification. - `numChildrenRange` USConsumerNumChildren[] — Inclusive `[min, max]` number of children in the household. Values must be between 0 and 8. - `homeValueRange` USConsumerHomeValueUSD[] — Inclusive `[min, max]` home value range, in US dollars. Values must be between 0 and 1,000,000. - `usCompanies` USCompanyListFilters — Filters used to target US companies (B2B) when building a list. - `postalCodes` string[], required — Required list of five-digit US ZIP codes to target. - `companyTypes` USCompanyType[] — Filter by ownership structure of the company. - `industries` string[] — Filter by free-form industry names (see the autocomplete endpoint). - `tags` string[] — Filter by free-form company tags (e.g., `"saas"`, `"b2b"`). - `naicsCodes` string[] — Filter by six-digit [NAICS](https://www.census.gov/naics/) industry codes. - `employeeCount` USCompanyEmployeeCount[] — Inclusive `[min, max]` range for the number of employees at the company. Values must be between 1 and 1,000,000. - `foundedYear` USCompanyFoundedYear[] — Inclusive `[min, max]` range for the year the company was founded. Values must be between 1600 and 2100. - `limit` integer — Maximum number of contacts to include in the built mailing list. If omitted, all matching contacts are included. - `quote` TargetedListBuildQuote — Details of the quote generated for a targeted list build. - `generatedAt` string, date-time, required — The UTC time at which the quote was generated. - `count` integer, required — The number of contacts that will be included in the built mailing list. This accounts for any `limit` that was provided. - `pricePerContactCents` number, double, required — The price per contact, in cents. Multiply by `count` to get the total cost of building the list. - `previewRecords` TargetedListBuildPreviewRecord[] — A small number of masked sample records for the configured filters, populated alongside `quote`. - `name` string, required — The masked name of the contact or business. - `formattedAddress` string, required — The masked, comma-joined formatted address of the contact. - `confirmedAt` string, date-time — The UTC time at which the build was confirmed, if any. - `completedAt` string, date-time — The UTC time at which the build finished successfully. Only present once `status` is `completed`. - `buildProgressPercent` number, float — A percentage from 0 to 100 representing how much of the build has completed. Only populated while `status` is `creating_list`. - `mailingList` string — The ID of the mailing list that was built. Present once `status` is `completed`. - `errors` TargetedListBuildError[] — Any errors encountered while generating a quote or building the list. - `type` 'not_enough_info_to_quote' | 'insufficient_credits' | 'internal_service_error', required — Type of error encountered while generating a quote or building the list. - `message` string, required — A human-readable message describing the error. ## Other responses - `400` — The updated targeted list build. - `401` — The updated targeted list build. - `404` — The updated targeted list build. - `422` — The updated targeted list build. - `429` — The updated targeted list build. - `500` — The updated targeted list build. ## Changes - **2026-05-05** `0e40d1471df0` — 1 breaking - the `quote/allOf[#/components/schemas/TargetedListBuildQuote]/pricePerContactCents` response's property type changed from `integer` to `number`, and format from `int32` to `double` for status `200` - **2026-05-01** `c8fedcbd705e` — 1 info - endpoint added [Change history](https://skmtc.dev/postgrid/apis/postgrid-address-verification-api/changes/print-mail/v1/targeted_list_builds/:id/post.md) --- [API](https://skmtc.dev/postgrid/apis/postgrid-address-verification-api.md) · [All operations](https://skmtc.dev/postgrid/apis/postgrid-address-verification-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/postgrid/postgrid-address-verification-api/revisions/537d2bbc624a/schema)