---
title: "Create Targeted List Build"
method: POST
path: "/print-mail/v1/targeted_list_builds"
tags: ["Targeted List Builds"]
---

# Create Targeted List Build

`POST /print-mail/v1/targeted_list_builds`

Create a new targeted list build. A quote will be generated
asynchronously based on the provided filters.

## Headers

- `idempotency-key` string

## Request body

- TargetedListBuildCreate — Parameters for creating a new 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.
  - `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 `201`

The newly created 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 newly created targeted list build.
- `401` — The newly created targeted list build.
- `404` — The newly created targeted list build.
- `422` — The newly created targeted list build.
- `429` — The newly created targeted list build.
- `500` — The newly created targeted list build.

---

[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)