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 ParametersExpand Collapse

limit: optional number

formatint32

search: optional string

You can supply any string to help narrow down the list of resources. For example, if you pass "New York" (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on StructuredSearchQuery for more details.

skip: optional number

formatint32

ReturnsExpand Collapse

data: array of object { id, createdAt, live, 15 more }

id: string

A unique ID prefixed with targeted_list_build_

createdAt: string

The UTC time at which this resource was created.

formatdate-time

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.

One of the following:

"generating_quote"

"quote_ready"

"creating_list"

"completed"

"failed"

updatedAt: string

The UTC time at which this resource was last updated.

formatdate-time

buildProgressPercent: optional number

A percentage from 0 to 100 representing how much of the build has completed. Only populated while status is creating_list.

formatfloat

minimum0

maximum100

completedAt: optional string

The UTC time at which the build finished successfully. Only present once status is completed.

formatdate-time

confirmedAt: optional string

The UTC time at which the build was confirmed, if any.

formatdate-time

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.

One of the following:

"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.

formatint32

minimum1

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.

formatint32

generatedAt: string

The UTC time at which the quote was generated.

formatdate-time

pricePerContactCents: number

The price per contact, in cents. Multiply by count to get the total cost of building the list.

formatdouble

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.

One of the following:

"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 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.

One of the following:

"high_school"

"college"

"grad_school"

"vocational_training"

gender: optional "male" or "female"

Gender filter for US consumer list builds.

One of the following:

"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.

One of the following:

"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.

formatfloat

minimum0.1

maximum100

zipCode: string

The five-digit ZIP code at the center of the search circle.

limit: number

formatint32

object: "list"

skip: number

formatint32

totalCount: number

formatint32

List Targeted List Builds

curl https://api.postgrid.com/print-mail/v1/targeted_list_builds \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY"

{
  "object": "list",
  "totalCount": 1,
  "skip": 0,
  "limit": 10,
  "data": [
    {
      "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": []
    }
  ]
}

Returns Examples

{
  "object": "list",
  "totalCount": 1,
  "skip": 0,
  "limit": 10,
  "data": [
    {
      "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": []
    }
  ]
}