--- title: "Confirm Targeted List Build" method: POST path: "/print-mail/v1/targeted_list_builds/{id}/confirm" tags: ["Targeted List Builds"] --- # Confirm Targeted List Build `POST /print-mail/v1/targeted_list_builds/{id}/confirm` ## Request - Base URL: `https://api.postgrid.com` - URL: `https://api.postgrid.com/print-mail/v1/targeted_list_builds/{id}/confirm` - Auth: API key in header `X-API-Key` 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. ## Path parameters - `id` string, required ## Response `200` The targeted list build after transitioning to `creating_list`. - 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 targeted list build after transitioning to `creating_list`. - `401`: The targeted list build after transitioning to `creating_list`. - `404`: The targeted list build after transitioning to `creating_list`. - `422`: The targeted list build after transitioning to `creating_list`. - `429`: The targeted list build after transitioning to `creating_list`. - `500`: The targeted list build after transitioning to `creating_list`. ## 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 [Operation history](https://skmtc.dev/postgrid/apis/postgrid-address-verification-api/changes/print-mail/v1/targeted_list_builds/:id/confirm/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.dev/postgrid/apis/postgrid-address-verification-api/revisions/537d2bbc624a?raw)