## 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` ### Body Parameters - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `limit: optional number` Maximum number of contacts to include in the built mailing list. If omitted, all matching contacts are included. - `metadata: optional map[unknown]` See the section on Metadata. - `usCompanies: optional object { postalCodes, companyTypes, employeeCount, 4 more }` Filters used to target US companies (B2B) when building a list. - `postalCodes: array of string` Required list of five-digit US ZIP codes to target. - `companyTypes: optional array of "public" or "private" or "educational" or 3 more` Filter by ownership structure of the company. - `"public"` - `"private"` - `"educational"` - `"government"` - `"nonprofit"` - `"public_subsidiary"` - `employeeCount: optional array of number` Inclusive `[min, max]` range for the number of employees at the company. Values must be between 1 and 1,000,000. - `foundedYear: optional array of number` Inclusive `[min, max]` range for the year the company was founded. Values must be between 1600 and 2100. - `industries: optional array of string` Filter by free-form industry names (see the autocomplete endpoint). - `naicsCodes: optional array of string` Filter by six-digit [NAICS](https://www.census.gov/naics/) industry codes. - `tags: optional array of string` Filter by free-form company tags (e.g., `"saas"`, `"b2b"`). - `usConsumers: optional object { ageRange, cityStates, educationLevels, 7 more }` Filters used to target US consumers (B2C) when building a list. The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are mutually exclusive — you may supply at most one of them. - `ageRange: optional array of number` Inclusive `[min, max]` age range. Values must be between 18 and 80. - `cityStates: optional array of string` A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target. - `educationLevels: optional array of "high_school" or "college" or "grad_school" or "vocational_training"` Filter by highest level of education completed. - `"high_school"` - `"college"` - `"grad_school"` - `"vocational_training"` - `gender: optional "male" or "female"` Gender filter for US consumer list builds. - `"male"` - `"female"` - `homeValueRange: optional array of number` Inclusive `[min, max]` home value range, in US dollars. Values must be between 0 and 1,000,000. - `incomeRange: optional array of number` Inclusive `[min, max]` annual household income range, in US dollars. Values must be between 0 and 200,000. - `numChildrenRange: optional array of number` Inclusive `[min, max]` number of children in the household. Values must be between 0 and 8. - `occupations: optional array of "professional_technical" or "administration_management" or "sales_service" or 23 more` Filter by occupation classification. - `"professional_technical"` - `"administration_management"` - `"sales_service"` - `"clerical_white_collar"` - `"craftsmen_blue_collar"` - `"student"` - `"homemaker"` - `"retired"` - `"farmer"` - `"military"` - `"religious"` - `"self_employed"` - `"self_employed_professional_technical"` - `"self_employed_administration_management"` - `"self_employed_sales_service"` - `"self_employed_clerical_white_collar"` - `"self_employed_craftsmen_blue_collar"` - `"self_employed_student"` - `"self_employed_homemaker"` - `"self_employed_retired"` - `"self_employed_other"` - `"educator"` - `"financial_professional"` - `"legal_professional"` - `"medical_professional"` - `"other"` - `zipCodes: optional array of string` A list of five-digit US ZIP codes to target. - `zipCodesAround: optional object { radiusInMiles, zipCode }` A geographic filter that selects all ZIP codes within a given radius of a center ZIP code. - `radiusInMiles: number` The radius in miles around `zipCode` to include. Between 0.1 and 100. - `zipCode: string` The five-digit ZIP code at the center of the search circle. ### Returns - `id: string` A unique ID prefixed with targeted_list_build_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `organization: string` The ID of the organization that owns this list build. - `status: "generating_quote" or "quote_ready" or "creating_list" or 2 more` Status of a targeted list build. - `"generating_quote"` - `"quote_ready"` - `"creating_list"` - `"completed"` - `"failed"` - `updatedAt: string` The UTC time at which this resource was last updated. - `buildProgressPercent: optional number` A percentage from 0 to 100 representing how much of the build has completed. Only populated while `status` is `creating_list`. - `completedAt: optional string` The UTC time at which the build finished successfully. Only present once `status` is `completed`. - `confirmedAt: optional string` The UTC time at which the build was confirmed, if any. - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `errors: optional array of object { message, type }` Any errors encountered while generating a quote or building the list. - `message: string` A human-readable message describing the error. - `type: "not_enough_info_to_quote" or "insufficient_credits" or "internal_service_error"` Type of error encountered while generating a quote or building the list. - `"not_enough_info_to_quote"` - `"insufficient_credits"` - `"internal_service_error"` - `limit: optional number` Maximum number of contacts to include in the built mailing list. If omitted, all matching contacts are included. - `mailingList: optional string` The ID of the mailing list that was built. Present once `status` is `completed`. - `metadata: optional map[unknown]` See the section on Metadata. - `previewRecords: optional array of object { formattedAddress, name }` A small number of masked sample records for the configured filters, populated alongside `quote`. - `formattedAddress: string` The masked, comma-joined formatted address of the contact. - `name: string` The masked name of the contact or business. - `quote: optional object { count, generatedAt, pricePerContactCents }` Details of the quote generated for a targeted list build. - `count: number` The number of contacts that will be included in the built mailing list. This accounts for any `limit` that was provided. - `generatedAt: string` The UTC time at which the quote was generated. - `pricePerContactCents: number` The price per contact, in cents. Multiply by `count` to get the total cost of building the list. - `usCompanies: optional object { postalCodes, companyTypes, employeeCount, 4 more }` Filters used to target US companies (B2B) when building a list. - `postalCodes: array of string` Required list of five-digit US ZIP codes to target. - `companyTypes: optional array of "public" or "private" or "educational" or 3 more` Filter by ownership structure of the company. - `"public"` - `"private"` - `"educational"` - `"government"` - `"nonprofit"` - `"public_subsidiary"` - `employeeCount: optional array of number` Inclusive `[min, max]` range for the number of employees at the company. Values must be between 1 and 1,000,000. - `foundedYear: optional array of number` Inclusive `[min, max]` range for the year the company was founded. Values must be between 1600 and 2100. - `industries: optional array of string` Filter by free-form industry names (see the autocomplete endpoint). - `naicsCodes: optional array of string` Filter by six-digit [NAICS](https://www.census.gov/naics/) industry codes. - `tags: optional array of string` Filter by free-form company tags (e.g., `"saas"`, `"b2b"`). - `usConsumers: optional object { ageRange, cityStates, educationLevels, 7 more }` Filters used to target US consumers (B2C) when building a list. The geographic filters (`zipCodesAround`, `cityStates`, `zipCodes`) are mutually exclusive — you may supply at most one of them. - `ageRange: optional array of number` Inclusive `[min, max]` age range. Values must be between 18 and 80. - `cityStates: optional array of string` A list of `"City, ST"` strings (e.g. `"New York, NY"`) to target. - `educationLevels: optional array of "high_school" or "college" or "grad_school" or "vocational_training"` Filter by highest level of education completed. - `"high_school"` - `"college"` - `"grad_school"` - `"vocational_training"` - `gender: optional "male" or "female"` Gender filter for US consumer list builds. - `"male"` - `"female"` - `homeValueRange: optional array of number` Inclusive `[min, max]` home value range, in US dollars. Values must be between 0 and 1,000,000. - `incomeRange: optional array of number` Inclusive `[min, max]` annual household income range, in US dollars. Values must be between 0 and 200,000. - `numChildrenRange: optional array of number` Inclusive `[min, max]` number of children in the household. Values must be between 0 and 8. - `occupations: optional array of "professional_technical" or "administration_management" or "sales_service" or 23 more` Filter by occupation classification. - `"professional_technical"` - `"administration_management"` - `"sales_service"` - `"clerical_white_collar"` - `"craftsmen_blue_collar"` - `"student"` - `"homemaker"` - `"retired"` - `"farmer"` - `"military"` - `"religious"` - `"self_employed"` - `"self_employed_professional_technical"` - `"self_employed_administration_management"` - `"self_employed_sales_service"` - `"self_employed_clerical_white_collar"` - `"self_employed_craftsmen_blue_collar"` - `"self_employed_student"` - `"self_employed_homemaker"` - `"self_employed_retired"` - `"self_employed_other"` - `"educator"` - `"financial_professional"` - `"legal_professional"` - `"medical_professional"` - `"other"` - `zipCodes: optional array of string` A list of five-digit US ZIP codes to target. - `zipCodesAround: optional object { radiusInMiles, zipCode }` A geographic filter that selects all ZIP codes within a given radius of a center ZIP code. - `radiusInMiles: number` The radius in miles around `zipCode` to include. Between 0.1 and 100. - `zipCode: string` The five-digit ZIP code at the center of the search circle. ### Example ```http curl https://api.postgrid.com/print-mail/v1/targeted_list_builds/$ID \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### 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": [] } ```