# 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. ### Header Parameters - `"idempotency-key": optional string` ### Body Parameters - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `limit: optional number` Maximum number of contacts to include in the built mailing list. If omitted, all matching contacts are included. - `metadata: optional map[unknown]` See the section on Metadata. - `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. ### 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 \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### 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: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": [] } ``` ## 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 - `limit: optional number` - `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` ### Returns - `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. - `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. - `limit: number` - `object: "list"` - `"list"` - `skip: number` - `totalCount: number` ### Example ```http curl https://api.postgrid.com/print-mail/v1/targeted_list_builds \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "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": [] } ] } ``` ## Get Targeted List Build **get** `/print-mail/v1/targeted_list_builds/{id}` Retrieve a specific targeted list build by its ID. ### 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 \ -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: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": [] } ``` ## Update Targeted List Build **post** `/print-mail/v1/targeted_list_builds/{id}` Update an existing targeted list build. Only builds that have not yet been confirmed may be updated. Updating the filters or `limit` will reset the build's status back to `generating_quote` and a new quote will be generated. ### Path Parameters - `id: string` ### Body Parameters - `description: optional string` An optional string describing this resource. Will be visible in the API and the dashboard. - `limit: optional number` Maximum number of contacts to include in the built mailing list. If omitted, all matching contacts are included. - `metadata: optional map[unknown]` See the section on Metadata. - `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. ### 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 \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{}' ``` #### 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: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": [] } ``` ## Delete Targeted List Build **delete** `/print-mail/v1/targeted_list_builds/{id}` Delete a targeted list build. List builds can only be deleted before they have been confirmed — once a build has transitioned to `creating_list` or `completed` it cannot be deleted. ### Path Parameters - `id: string` ### Returns - `id: string` A unique ID prefixed with targeted_list_build_ - `deleted: true` - `true` ### Example ```http curl https://api.postgrid.com/print-mail/v1/targeted_list_builds/$ID \ -X DELETE \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" ``` #### Response ```json { "id": "targeted_list_build_123", "deleted": true } ``` ## 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": [] } ``` ## Domain Types ### Targeted List Build Create Response - `TargetedListBuildCreateResponse object { id, createdAt, live, 15 more }` 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` 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. ### Targeted List Build List Response - `TargetedListBuildListResponse object { id, createdAt, live, 15 more }` 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` 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. ### Targeted List Build Retrieve Response - `TargetedListBuildRetrieveResponse object { id, createdAt, live, 15 more }` 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` 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. ### Targeted List Build Update Response - `TargetedListBuildUpdateResponse object { id, createdAt, live, 15 more }` 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` 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. ### Targeted List Build Delete Response - `TargetedListBuildDeleteResponse object { id, deleted }` - `id: string` A unique ID prefixed with targeted_list_build_ - `deleted: true` - `true` ### Targeted List Build Confirm Response - `TargetedListBuildConfirmResponse object { id, createdAt, live, 15 more }` 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` 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. # Filters ## Autocomplete Filter Values **post** `/print-mail/v1/targeted_list_builds/filters/autocomplete` Return a list of autocomplete suggestions for a given filter field (currently only `industry` is supported). Useful when building a UI around the `industries` company filter. ### Body Parameters - `field: "industry"` A field that can be autocompleted when configuring list build filters. - `"industry"` - `size: optional number` Maximum number of suggestions to return. Between 1 and 100. Defaults to 25 if omitted. - `text: optional string` Optional text prefix to narrow the autocomplete suggestions. ### Returns - `data: array of object { type, value }` - `type: "industry"` A field that can be autocompleted when configuring list build filters. - `"industry"` - `value: string` The suggested value (e.g., an industry name). - `object: "list"` - `"list"` ### Example ```http curl https://api.postgrid.com/print-mail/v1/targeted_list_builds/filters/autocomplete \ -H 'Content-Type: application/json' \ -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \ -d '{ "field": "industry" }' ``` #### Response ```json { "object": "list", "data": [ { "value": "software", "type": "industry" }, { "value": "software development", "type": "industry" } ] } ``` ## Domain Types ### Filter Autocomplete Response - `FilterAutocompleteResponse object { data, object }` The list of suggestions returned by an autocomplete query. - `data: array of object { type, value }` - `type: "industry"` A field that can be autocompleted when configuring list build filters. - `"industry"` - `value: string` The suggested value (e.g., an industry name). - `object: "list"` - `"list"`