## Confirm Targeted List Build

**post** `/print-mail/v1/targeted_list_builds/{id}/confirm`

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`

### 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/confirm \
    -X POST \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"
```

#### 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:05:00Z",
  "organization": "organization_123",
  "status": "creating_list",
  "usCompanies": {
    "postalCodes": [
      "10001",
      "10002"
    ],
    "industries": [
      "software"
    ],
    "employeeCount": [
      10,
      500
    ]
  },
  "limit": 1000,
  "quote": {
    "generatedAt": "2026-01-05T10:01:30Z",
    "count": 1000,
    "pricePerContactCents": 11.98
  },
  "confirmedAt": "2026-01-05T10:05:00Z",
  "buildProgressPercent": 0,
  "errors": []
}
```