--- title: "List Targeted List Builds" method: GET path: "/print-mail/v1/targeted_list_builds" tags: ["Targeted List Builds"] --- # List Targeted List Builds `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. ## Query parameters - `skip` integer - `limit` integer - `search` union - string - string — You can supply a structured search query instead of supplying unstructured text to any list endpoint help refine your search for a resource. For example, let's say you created a series of letters that all had `metadata: { campaignID: 'abc' }`. You could search for all those letters by passing in `{ "metadata.campaignID": "abc" }` into the `search` parameter. Note that this string must be valid JSON. ## Response `200` A list object containing targeted list builds. - TargetedListBuildList — A list of targeted list builds. - `object` 'list', required - `totalCount` integer, required - `skip` integer, required - `limit` integer, required - `data` TargetedListBuild[], required - `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` — A list object containing targeted list builds. - `401` — A list object containing targeted list builds. - `429` — A list object containing targeted list builds. - `500` — A list object containing targeted list builds. --- [API](https://skmtc.net/postgrid/apis/postgrid-address-verification-api.md) · [All operations](https://skmtc.net/postgrid/apis/postgrid-address-verification-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/postgrid/postgrid-address-verification-api/revisions/537d2bbc624a/schema)