API Reference

Print Mail

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Targeted List Builds

Beta: the targeted list builds API is in beta and is subject to breaking changes. Endpoint shapes, status values, and filter fields may change without notice.

The targeted list builds API lets you programmatically build mailing lists of US consumers (B2C) or US companies (B2B) that match a set of demographic, geographic, and firmographic filters.

The lifecycle of a list build is:

1. Create a list build by supplying either usConsumers or usCompanies filters. A quote is generated asynchronously — poll the resource or wait for its status to become quote_ready.
2. Review the quote (total count and price per contact) and masked previewRecords. Adjust the filters with an update call if needed — this will regenerate the quote.
3. Confirm the build. This deducts the appropriate amount of list build credits from your organization (in live mode) and begins constructing the mailing list. buildProgressPercent reflects progress from 0 to 100.
4. Once status is completed, the ID of the resulting mailing list is available in the mailingList field and can be used like any other mailing list in the PostGrid API.

Targeted list builds must be enabled on your organization before they can be used. Contact PostGrid support to request access.

Create Targeted List Build

print_mail.targeted_list_builds.create(TargetedListBuildCreateParams**kwargs) -> TargetedListBuildCreateResponse

POST/print-mail/v1/targeted_list_builds

List Targeted List Builds

print_mail.targeted_list_builds.list(TargetedListBuildListParams**kwargs) -> SyncSkipLimit[TargetedListBuildListResponse]

GET/print-mail/v1/targeted_list_builds

Get Targeted List Build

print_mail.targeted_list_builds.retrieve(strid) -> TargetedListBuildRetrieveResponse

GET/print-mail/v1/targeted_list_builds/{id}

Update Targeted List Build

print_mail.targeted_list_builds.update(strid, TargetedListBuildUpdateParams**kwargs) -> TargetedListBuildUpdateResponse

POST/print-mail/v1/targeted_list_builds/{id}

Delete Targeted List Build

print_mail.targeted_list_builds.delete(strid) -> TargetedListBuildDeleteResponse

DELETE/print-mail/v1/targeted_list_builds/{id}

Confirm Targeted List Build

print_mail.targeted_list_builds.confirm(strid) -> TargetedListBuildConfirmResponse

POST/print-mail/v1/targeted_list_builds/{id}/confirm

ModelsExpand Collapse

class TargetedListBuildCreateResponse: …

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: str

A unique ID prefixed with targeted_list_build_

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

organization: str

The ID of the organization that owns this list build.

status: Literal["generating_quote", "quote_ready", "creating_list", 2 more]

Status of a targeted list build.

One of the following:

"generating_quote"

"quote_ready"

"creating_list"

"completed"

"failed"

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

build_progress_percent: Optional[float]

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

formatfloat

minimum0

maximum100

completed_at: Optional[datetime]

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

formatdate-time

confirmed_at: Optional[datetime]

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

formatdate-time

description: Optional[str]

An optional string describing this resource. Will be visible in the API and the dashboard.

errors: Optional[List[Error]]

Any errors encountered while generating a quote or building the list.

message: str

A human-readable message describing the error.

type: Literal["not_enough_info_to_quote", "insufficient_credits", "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[int]

Maximum number of contacts to include in the built mailing list. If omitted, all matching contacts are included.

formatint32

minimum1

mailing_list: Optional[str]

The ID of the mailing list that was built. Present once status is completed.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

preview_records: Optional[List[PreviewRecord]]

A small number of masked sample records for the configured filters, populated alongside quote.

formatted_address: str

The masked, comma-joined formatted address of the contact.

name: str

The masked name of the contact or business.

quote: Optional[Quote]

Details of the quote generated for a targeted list build.

count: int

The number of contacts that will be included in the built mailing list. This accounts for any limit that was provided.

formatint32

generated_at: datetime

The UTC time at which the quote was generated.

formatdate-time

price_per_contact_cents: float

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

formatdouble

us_companies: Optional[UsCompanies]

Filters used to target US companies (B2B) when building a list.

postal_codes: List[str]

Required list of five-digit US ZIP codes to target.

company_types: Optional[List[Literal["public", "private", "educational", 3 more]]]

Filter by ownership structure of the company.

One of the following:

"public"

"private"

"educational"

"government"

"nonprofit"

"public_subsidiary"

employee_count: Optional[List[int]]

Inclusive [min, max] range for the number of employees at the company. Values must be between 1 and 1,000,000.

founded_year: Optional[List[int]]

Inclusive [min, max] range for the year the company was founded. Values must be between 1600 and 2100.

industries: Optional[List[str]]

Filter by free-form industry names (see the autocomplete endpoint).

naics_codes: Optional[List[str]]

Filter by six-digit NAICS industry codes.

tags: Optional[List[str]]

Filter by free-form company tags (e.g., "saas", "b2b").

us_consumers: Optional[UsConsumers]

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.

age_range: Optional[List[int]]

Inclusive [min, max] age range. Values must be between 18 and 80.

city_states: Optional[List[str]]

A list of "City, ST" strings (e.g. "New York, NY") to target.

education_levels: Optional[List[Literal["high_school", "college", "grad_school", "vocational_training"]]]

Filter by highest level of education completed.

One of the following:

"high_school"

"college"

"grad_school"

"vocational_training"

gender: Optional[Literal["male", "female"]]

Gender filter for US consumer list builds.

One of the following:

"male"

"female"

home_value_range: Optional[List[int]]

Inclusive [min, max] home value range, in US dollars. Values must be between 0 and 1,000,000.

income_range: Optional[List[int]]

Inclusive [min, max] annual household income range, in US dollars. Values must be between 0 and 200,000.

num_children_range: Optional[List[int]]

Inclusive [min, max] number of children in the household. Values must be between 0 and 8.

occupations: Optional[List[Literal["professional_technical", "administration_management", "sales_service", 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"

zip_codes: Optional[List[str]]

A list of five-digit US ZIP codes to target.

zip_codes_around: Optional[UsConsumersZipCodesAround]

A geographic filter that selects all ZIP codes within a given radius of a center ZIP code.

radius_in_miles: float

The radius in miles around zipCode to include. Between 0.1 and 100.

formatfloat

minimum0.1

maximum100

zip_code: str

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

class TargetedListBuildListResponse: …

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: str

A unique ID prefixed with targeted_list_build_

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

organization: str

The ID of the organization that owns this list build.

status: Literal["generating_quote", "quote_ready", "creating_list", 2 more]

Status of a targeted list build.

One of the following:

"generating_quote"

"quote_ready"

"creating_list"

"completed"

"failed"

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

build_progress_percent: Optional[float]

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

formatfloat

minimum0

maximum100

completed_at: Optional[datetime]

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

formatdate-time

confirmed_at: Optional[datetime]

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

formatdate-time

description: Optional[str]

An optional string describing this resource. Will be visible in the API and the dashboard.

errors: Optional[List[Error]]

Any errors encountered while generating a quote or building the list.

message: str

A human-readable message describing the error.

type: Literal["not_enough_info_to_quote", "insufficient_credits", "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[int]

Maximum number of contacts to include in the built mailing list. If omitted, all matching contacts are included.

formatint32

minimum1

mailing_list: Optional[str]

The ID of the mailing list that was built. Present once status is completed.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

preview_records: Optional[List[PreviewRecord]]

A small number of masked sample records for the configured filters, populated alongside quote.

formatted_address: str

The masked, comma-joined formatted address of the contact.

name: str

The masked name of the contact or business.

quote: Optional[Quote]

Details of the quote generated for a targeted list build.

count: int

The number of contacts that will be included in the built mailing list. This accounts for any limit that was provided.

formatint32

generated_at: datetime

The UTC time at which the quote was generated.

formatdate-time

price_per_contact_cents: float

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

formatdouble

us_companies: Optional[UsCompanies]

Filters used to target US companies (B2B) when building a list.

postal_codes: List[str]

Required list of five-digit US ZIP codes to target.

company_types: Optional[List[Literal["public", "private", "educational", 3 more]]]

Filter by ownership structure of the company.

One of the following:

"public"

"private"

"educational"

"government"

"nonprofit"

"public_subsidiary"

employee_count: Optional[List[int]]

Inclusive [min, max] range for the number of employees at the company. Values must be between 1 and 1,000,000.

founded_year: Optional[List[int]]

Inclusive [min, max] range for the year the company was founded. Values must be between 1600 and 2100.

industries: Optional[List[str]]

Filter by free-form industry names (see the autocomplete endpoint).

naics_codes: Optional[List[str]]

Filter by six-digit NAICS industry codes.

tags: Optional[List[str]]

Filter by free-form company tags (e.g., "saas", "b2b").

us_consumers: Optional[UsConsumers]

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.

age_range: Optional[List[int]]

Inclusive [min, max] age range. Values must be between 18 and 80.

city_states: Optional[List[str]]

A list of "City, ST" strings (e.g. "New York, NY") to target.

education_levels: Optional[List[Literal["high_school", "college", "grad_school", "vocational_training"]]]

Filter by highest level of education completed.

One of the following:

"high_school"

"college"

"grad_school"

"vocational_training"

gender: Optional[Literal["male", "female"]]

Gender filter for US consumer list builds.

One of the following:

"male"

"female"

home_value_range: Optional[List[int]]

Inclusive [min, max] home value range, in US dollars. Values must be between 0 and 1,000,000.

income_range: Optional[List[int]]

Inclusive [min, max] annual household income range, in US dollars. Values must be between 0 and 200,000.

num_children_range: Optional[List[int]]

Inclusive [min, max] number of children in the household. Values must be between 0 and 8.

occupations: Optional[List[Literal["professional_technical", "administration_management", "sales_service", 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"

zip_codes: Optional[List[str]]

A list of five-digit US ZIP codes to target.

zip_codes_around: Optional[UsConsumersZipCodesAround]

A geographic filter that selects all ZIP codes within a given radius of a center ZIP code.

radius_in_miles: float

The radius in miles around zipCode to include. Between 0.1 and 100.

formatfloat

minimum0.1

maximum100

zip_code: str

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

class TargetedListBuildRetrieveResponse: …

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: str

A unique ID prefixed with targeted_list_build_

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

organization: str

The ID of the organization that owns this list build.

status: Literal["generating_quote", "quote_ready", "creating_list", 2 more]

Status of a targeted list build.

One of the following:

"generating_quote"

"quote_ready"

"creating_list"

"completed"

"failed"

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

build_progress_percent: Optional[float]

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

formatfloat

minimum0

maximum100

completed_at: Optional[datetime]

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

formatdate-time

confirmed_at: Optional[datetime]

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

formatdate-time

description: Optional[str]

An optional string describing this resource. Will be visible in the API and the dashboard.

errors: Optional[List[Error]]

Any errors encountered while generating a quote or building the list.

message: str

A human-readable message describing the error.

type: Literal["not_enough_info_to_quote", "insufficient_credits", "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[int]

Maximum number of contacts to include in the built mailing list. If omitted, all matching contacts are included.

formatint32

minimum1

mailing_list: Optional[str]

The ID of the mailing list that was built. Present once status is completed.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

preview_records: Optional[List[PreviewRecord]]

A small number of masked sample records for the configured filters, populated alongside quote.

formatted_address: str

The masked, comma-joined formatted address of the contact.

name: str

The masked name of the contact or business.

quote: Optional[Quote]

Details of the quote generated for a targeted list build.

count: int

The number of contacts that will be included in the built mailing list. This accounts for any limit that was provided.

formatint32

generated_at: datetime

The UTC time at which the quote was generated.

formatdate-time

price_per_contact_cents: float

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

formatdouble

us_companies: Optional[UsCompanies]

Filters used to target US companies (B2B) when building a list.

postal_codes: List[str]

Required list of five-digit US ZIP codes to target.

company_types: Optional[List[Literal["public", "private", "educational", 3 more]]]

Filter by ownership structure of the company.

One of the following:

"public"

"private"

"educational"

"government"

"nonprofit"

"public_subsidiary"

employee_count: Optional[List[int]]

Inclusive [min, max] range for the number of employees at the company. Values must be between 1 and 1,000,000.

founded_year: Optional[List[int]]

Inclusive [min, max] range for the year the company was founded. Values must be between 1600 and 2100.

industries: Optional[List[str]]

Filter by free-form industry names (see the autocomplete endpoint).

naics_codes: Optional[List[str]]

Filter by six-digit NAICS industry codes.

tags: Optional[List[str]]

Filter by free-form company tags (e.g., "saas", "b2b").

us_consumers: Optional[UsConsumers]

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.

age_range: Optional[List[int]]

Inclusive [min, max] age range. Values must be between 18 and 80.

city_states: Optional[List[str]]

A list of "City, ST" strings (e.g. "New York, NY") to target.

education_levels: Optional[List[Literal["high_school", "college", "grad_school", "vocational_training"]]]

Filter by highest level of education completed.

One of the following:

"high_school"

"college"

"grad_school"

"vocational_training"

gender: Optional[Literal["male", "female"]]

Gender filter for US consumer list builds.

One of the following:

"male"

"female"

home_value_range: Optional[List[int]]

Inclusive [min, max] home value range, in US dollars. Values must be between 0 and 1,000,000.

income_range: Optional[List[int]]

Inclusive [min, max] annual household income range, in US dollars. Values must be between 0 and 200,000.

num_children_range: Optional[List[int]]

Inclusive [min, max] number of children in the household. Values must be between 0 and 8.

occupations: Optional[List[Literal["professional_technical", "administration_management", "sales_service", 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"

zip_codes: Optional[List[str]]

A list of five-digit US ZIP codes to target.

zip_codes_around: Optional[UsConsumersZipCodesAround]

A geographic filter that selects all ZIP codes within a given radius of a center ZIP code.

radius_in_miles: float

The radius in miles around zipCode to include. Between 0.1 and 100.

formatfloat

minimum0.1

maximum100

zip_code: str

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

class TargetedListBuildUpdateResponse: …

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: str

A unique ID prefixed with targeted_list_build_

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

organization: str

The ID of the organization that owns this list build.

status: Literal["generating_quote", "quote_ready", "creating_list", 2 more]

Status of a targeted list build.

One of the following:

"generating_quote"

"quote_ready"

"creating_list"

"completed"

"failed"

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

build_progress_percent: Optional[float]

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

formatfloat

minimum0

maximum100

completed_at: Optional[datetime]

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

formatdate-time

confirmed_at: Optional[datetime]

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

formatdate-time

description: Optional[str]

An optional string describing this resource. Will be visible in the API and the dashboard.

errors: Optional[List[Error]]

Any errors encountered while generating a quote or building the list.

message: str

A human-readable message describing the error.

type: Literal["not_enough_info_to_quote", "insufficient_credits", "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[int]

Maximum number of contacts to include in the built mailing list. If omitted, all matching contacts are included.

formatint32

minimum1

mailing_list: Optional[str]

The ID of the mailing list that was built. Present once status is completed.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

preview_records: Optional[List[PreviewRecord]]

A small number of masked sample records for the configured filters, populated alongside quote.

formatted_address: str

The masked, comma-joined formatted address of the contact.

name: str

The masked name of the contact or business.

quote: Optional[Quote]

Details of the quote generated for a targeted list build.

count: int

The number of contacts that will be included in the built mailing list. This accounts for any limit that was provided.

formatint32

generated_at: datetime

The UTC time at which the quote was generated.

formatdate-time

price_per_contact_cents: float

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

formatdouble

us_companies: Optional[UsCompanies]

Filters used to target US companies (B2B) when building a list.

postal_codes: List[str]

Required list of five-digit US ZIP codes to target.

company_types: Optional[List[Literal["public", "private", "educational", 3 more]]]

Filter by ownership structure of the company.

One of the following:

"public"

"private"

"educational"

"government"

"nonprofit"

"public_subsidiary"

employee_count: Optional[List[int]]

Inclusive [min, max] range for the number of employees at the company. Values must be between 1 and 1,000,000.

founded_year: Optional[List[int]]

Inclusive [min, max] range for the year the company was founded. Values must be between 1600 and 2100.

industries: Optional[List[str]]

Filter by free-form industry names (see the autocomplete endpoint).

naics_codes: Optional[List[str]]

Filter by six-digit NAICS industry codes.

tags: Optional[List[str]]

Filter by free-form company tags (e.g., "saas", "b2b").

us_consumers: Optional[UsConsumers]

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.

age_range: Optional[List[int]]

Inclusive [min, max] age range. Values must be between 18 and 80.

city_states: Optional[List[str]]

A list of "City, ST" strings (e.g. "New York, NY") to target.

education_levels: Optional[List[Literal["high_school", "college", "grad_school", "vocational_training"]]]

Filter by highest level of education completed.

One of the following:

"high_school"

"college"

"grad_school"

"vocational_training"

gender: Optional[Literal["male", "female"]]

Gender filter for US consumer list builds.

One of the following:

"male"

"female"

home_value_range: Optional[List[int]]

Inclusive [min, max] home value range, in US dollars. Values must be between 0 and 1,000,000.

income_range: Optional[List[int]]

Inclusive [min, max] annual household income range, in US dollars. Values must be between 0 and 200,000.

num_children_range: Optional[List[int]]

Inclusive [min, max] number of children in the household. Values must be between 0 and 8.

occupations: Optional[List[Literal["professional_technical", "administration_management", "sales_service", 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"

zip_codes: Optional[List[str]]

A list of five-digit US ZIP codes to target.

zip_codes_around: Optional[UsConsumersZipCodesAround]

A geographic filter that selects all ZIP codes within a given radius of a center ZIP code.

radius_in_miles: float

The radius in miles around zipCode to include. Between 0.1 and 100.

formatfloat

minimum0.1

maximum100

zip_code: str

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

class TargetedListBuildDeleteResponse: …

id: str

A unique ID prefixed with targeted_list_build_

deleted: Literal[true]

class TargetedListBuildConfirmResponse: …

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: str

A unique ID prefixed with targeted_list_build_

created_at: datetime

The UTC time at which this resource was created.

formatdate-time

live: bool

true if this is a live mode resource else false.

organization: str

The ID of the organization that owns this list build.

status: Literal["generating_quote", "quote_ready", "creating_list", 2 more]

Status of a targeted list build.

One of the following:

"generating_quote"

"quote_ready"

"creating_list"

"completed"

"failed"

updated_at: datetime

The UTC time at which this resource was last updated.

formatdate-time

build_progress_percent: Optional[float]

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

formatfloat

minimum0

maximum100

completed_at: Optional[datetime]

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

formatdate-time

confirmed_at: Optional[datetime]

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

formatdate-time

description: Optional[str]

An optional string describing this resource. Will be visible in the API and the dashboard.

errors: Optional[List[Error]]

Any errors encountered while generating a quote or building the list.

message: str

A human-readable message describing the error.

type: Literal["not_enough_info_to_quote", "insufficient_credits", "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[int]

Maximum number of contacts to include in the built mailing list. If omitted, all matching contacts are included.

formatint32

minimum1

mailing_list: Optional[str]

The ID of the mailing list that was built. Present once status is completed.

metadata: Optional[Dict[str, object]]

See the section on Metadata.

preview_records: Optional[List[PreviewRecord]]

A small number of masked sample records for the configured filters, populated alongside quote.

formatted_address: str

The masked, comma-joined formatted address of the contact.

name: str

The masked name of the contact or business.

quote: Optional[Quote]

Details of the quote generated for a targeted list build.

count: int

The number of contacts that will be included in the built mailing list. This accounts for any limit that was provided.

formatint32

generated_at: datetime

The UTC time at which the quote was generated.

formatdate-time

price_per_contact_cents: float

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

formatdouble

us_companies: Optional[UsCompanies]

Filters used to target US companies (B2B) when building a list.

postal_codes: List[str]

Required list of five-digit US ZIP codes to target.

company_types: Optional[List[Literal["public", "private", "educational", 3 more]]]

Filter by ownership structure of the company.

One of the following:

"public"

"private"

"educational"

"government"

"nonprofit"

"public_subsidiary"

employee_count: Optional[List[int]]

Inclusive [min, max] range for the number of employees at the company. Values must be between 1 and 1,000,000.

founded_year: Optional[List[int]]

Inclusive [min, max] range for the year the company was founded. Values must be between 1600 and 2100.

industries: Optional[List[str]]

Filter by free-form industry names (see the autocomplete endpoint).

naics_codes: Optional[List[str]]

Filter by six-digit NAICS industry codes.

tags: Optional[List[str]]

Filter by free-form company tags (e.g., "saas", "b2b").

us_consumers: Optional[UsConsumers]

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.

age_range: Optional[List[int]]

Inclusive [min, max] age range. Values must be between 18 and 80.

city_states: Optional[List[str]]

A list of "City, ST" strings (e.g. "New York, NY") to target.

education_levels: Optional[List[Literal["high_school", "college", "grad_school", "vocational_training"]]]

Filter by highest level of education completed.

One of the following:

"high_school"

"college"

"grad_school"

"vocational_training"

gender: Optional[Literal["male", "female"]]

Gender filter for US consumer list builds.

One of the following:

"male"

"female"

home_value_range: Optional[List[int]]

Inclusive [min, max] home value range, in US dollars. Values must be between 0 and 1,000,000.

income_range: Optional[List[int]]

Inclusive [min, max] annual household income range, in US dollars. Values must be between 0 and 200,000.

num_children_range: Optional[List[int]]

Inclusive [min, max] number of children in the household. Values must be between 0 and 8.

occupations: Optional[List[Literal["professional_technical", "administration_management", "sales_service", 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"

zip_codes: Optional[List[str]]

A list of five-digit US ZIP codes to target.

zip_codes_around: Optional[UsConsumersZipCodesAround]

A geographic filter that selects all ZIP codes within a given radius of a center ZIP code.

radius_in_miles: float

The radius in miles around zipCode to include. Between 0.1 and 100.

formatfloat

minimum0.1

maximum100

zip_code: str

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

Targeted List BuildsFilters

Beta: the targeted list builds API is in beta and is subject to breaking changes. Endpoint shapes, status values, and filter fields may change without notice.

The targeted list builds API lets you programmatically build mailing lists of US consumers (B2C) or US companies (B2B) that match a set of demographic, geographic, and firmographic filters.

The lifecycle of a list build is:

1. Create a list build by supplying either usConsumers or usCompanies filters. A quote is generated asynchronously — poll the resource or wait for its status to become quote_ready.
2. Review the quote (total count and price per contact) and masked previewRecords. Adjust the filters with an update call if needed — this will regenerate the quote.
3. Confirm the build. This deducts the appropriate amount of list build credits from your organization (in live mode) and begins constructing the mailing list. buildProgressPercent reflects progress from 0 to 100.
4. Once status is completed, the ID of the resulting mailing list is available in the mailingList field and can be used like any other mailing list in the PostGrid API.

Targeted list builds must be enabled on your organization before they can be used. Contact PostGrid support to request access.

Autocomplete Filter Values

print_mail.targeted_list_builds.filters.autocomplete(FilterAutocompleteParams**kwargs) -> FilterAutocompleteResponse

POST/print-mail/v1/targeted_list_builds/filters/autocomplete

ModelsExpand Collapse

class FilterAutocompleteResponse: …

The list of suggestions returned by an autocomplete query.

data: List[Data]

type: Literal["industry"]

A field that can be autocompleted when configuring list build filters.

value: str

The suggested value (e.g., an industry name).

object: Literal["list"]