B2C Listgen Estimate Mcp Tool
b2c_listgen_estimateRead-onlyIdempotent
Estimate consumer audience sizes using Versium's Consumer Audience Builder (B2C Listgen) API. Supports the full configuration and demographic filter set
For fields with large, high-cardinality option sets (e.g. esthhldincome), use the Consumer Audience Options tool to retrieve available values
Any property restricted to `enum: ["Y"]` is enabled by sending `"Y"`. For example, pet owners who golf in Washington use `{"state":["WA"],"d_pets":"Y","d_golf":"Y"}`.
Call `b2c_listgen_options` with `field: "attribute_flags"` when you need the human-readable meanings of those flag names.
**Tips for Best Results:**
- Start with a single output type and add filters incrementally
- Combine geography with age, income, or lifestyle filters for precise targeting
- Leverage lifestyle and interest filters to reach specific consumer segmentsInput Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| d_age | No | Age range in years (single value or min-max, e.g., "35-45") | |
| d_lor | No | Length of residence in years (single value or range) | |
| d_zip | No | Array of 5-digit ZIP codes to filter by | |
| d_golf | No | ||
| d_news | No | ||
| d_pets | No | ||
| d_soho | No | ||
| d_state | No | Array of 2-letter state codes to filter by | |
| d_county | No | Array of county,state combinations (e.g., "King, WA") | |
| d_gender | No | Gender filter (M=Male, F=Female) | |
| d_travel | No | ||
| d_fishing | No | ||
| d_hunting | No | ||
| d_ownrent | No | Home ownership status codes (H=Owner, R=Renter, 9=Probable Owner) | |
| d_exercise | No | ||
| d_language | No | Language codes. See values in options tool | |
| d_networth | No | Estimated net worth range using codes. See values in options tool | |
| d_religion | No | Religion codes. See values in options tool | |
| d_shooting | No | ||
| d_auto_year | No | Automobile year range (single year or min-max) | |
| d_education | No | Education level codes: A=High School, B=College, C=Graduate, D=Technical/Vocational | |
| d_gardening | No | ||
| d_hhld_size | No | Household size range (1-9, e.g., "2-4"); 9 means 9 or more | |
| d_home_year | No | Year home was built (single year or range) | |
| d_magazines | No | ||
| d_refi_date | No | Refinance date or date range using YYYYMMDD format | |
| max_records | No | Cap the number of records returned by the eventual list build | |
| d_city_state | No | Array of city,state combinations (e.g., "Seattle, WA") | |
| d_home_value | No | Home value range. See values in options tool | |
| d_occupation | No | Occupation codes. See values in options tool | |
| d_weightloss | No | ||
| max_coverage | No | Request append processing for selected channels (must overlap required/optional fields) | |
| cfg_zipradius | No | Radius expansion (pseudo-miles) applied around supplied ZIP or city/state centers | |
| d_creditlines | No | Number of credit lines range (e.g. "0-5") | |
| d_electronics | No | ||
| d_ethnicgroup | No | Ethnic group codes. See values in options tool | |
| d_hhldveteran | No | ||
| d_loantovalue | No | Loan-to-value percentage as single value or range (0-100) | |
| d_motorcycles | No | ||
| d_refi_amount | No | Refinance amount in thousands (single value or range) | |
| d_senior_hhld | No | ||
| d_apparel_mens | No | ||
| d_creditrating | No | Credit rating range. See values in options tool | |
| d_donation_env | No | ||
| d_dwellingtype | No | Dwelling type codes (M=Multi Family, S=Single Family, U=Unknown) | |
| d_num_children | No | Number of children range (0-8, e.g., "2-3") | |
| d_singleparent | No | ||
| d_workingwoman | No | ||
| d_esthhldincome | No | Estimated household income range using codes. See values in options tool | |
| d_maritalstatus | No | Marital status codes (M=Married, S=Single, A=Married (Inferred), B=Single (Inferred)) | |
| d_mortgage_rate | No | Mortgage interest rate percentage (e.g., "6.75%", "10%") | |
| optional_fields | No | Optional contact fields to include when available | |
| required_fields | No | Required output contact fields. Must include at least one. Recommended to include address for estimate calls for geo info. IMPORTANT: Unlike the B2B Persona API, this field along with optional_fields are used to define output instead of the "output" parameter | |
| cfg_require_name | No | Set to true to require full names in the output | |
| d_apparel_womens | No | ||
| d_auto_makemodel | No | Auto make and model combo(s) (e.g. "Ford:Escape") | |
| d_mailorderbuyer | No | ||
| d_mortgage2_date | No | Second mortgage date in YYYYMMDD format | |
| d_mortgage2_rate | No | Second mortgage interest rate percentage | |
| d_refi_loan_type | No | Refinance loan type codes. See values in options tool | |
| d_refi_rate_type | No | Refinance rate type codes. A=Adjustable, B=Balloon, F=Fixed, U=Unknown | |
| cfg_require_email | No | Set to true to require email addresses in the output | |
| cfg_require_phone | No | Set to true to require phone numbers in the output | |
| contacts_per_addr | No | Maximum contacts per street address (0=unlimited, 1=one contact per address) | |
| d_cardholder_bank | No | ||
| d_donation_health | No | ||
| d_lifestyle_music | No | ||
| d_mortgage_amount | No | Mortgage amount in thousands (use values like "50" or "400") | |
| d_onlinepurchaser | No | ||
| d_political_party | No | Political party affiliation values | |
| d_youngadult_hhld | No | ||
| rcfg_phone_format | No | Set to 1 to prefix returned phone numbers with the country code | |
| d_donation_animals | No | ||
| d_home_improvement | No | ||
| d_investing_active | No | ||
| d_lifestyle_sports | No | ||
| d_military_history | No | ||
| d_mortgage2_amount | No | Second mortgage amount in thousands | |
| cfg_require_address | No | Set to true to require mailing addresses in the output | |
| cfg_zipradius_focus | No | Limits radius expansion to ZIP, city/state, or none | |
| d_donation_children | No | ||
| d_donation_intl_aid | No | ||
| d_donation_religion | No | ||
| d_donation_veterans | No | ||
| d_home_market_value | No | Home market value range. See values in options tool | |
| d_lifestyle_cooking | No | ||
| d_lifestyle_outdoor | No | ||
| d_lifestyle_reading | No | ||
| d_cardholder_upscale | No | ||
| d_donation_community | No | ||
| d_donation_political | No | ||
| d_home_purchase_date | No | Home purchase date in YYYYMMDD format | |
| d_lifestyle_antiques | No | ||
| d_mortgage_rate_type | No | Mortgage rate type codes. A=Adjustable, B=Balloon, F=Fixed, U=Unknown | |
| include_filter_attrs | No | Include selected filter attributes as columns in the final audience | |
| d_home_purchase_price | No | Home purchase price in thousands | |
| d_mortgage2_loan_type | No | Second mortgage loan type codes. See values in options tool | |
| d_mortgage2_rate_type | No | Second mortgage rate type codes. A=Adjustable, B=Balloon, F=Fixed, U=Unknown | |
| d_donation_unspecified | No | ||
| d_lifestyle_decorating | No | ||
| d_presence_of_children | No | ||
| d_donation_arts_culture | No | ||
| d_donation_env_wildlife | No | ||
| include_demo_categories | No | Demographic category summaries to include in the response. Recommended to include at least one with estimate calls for audience insights in the preview response | |
| d_lifestyle_arts_general | No | ||
| d_mortgage_purchase_date | No | Mortgage purchase date in YYYYMMDD format | |
| d_lifestyle_health_beauty | No | ||
| d_donation_political_liberal | No | ||
| d_donation_political_conservative | No | ||
| d_mortgage_purchase_loan_type_code | No | Mortgage purchase loan type codes. See values in options tool |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| results | No | ||
| query_id | No | ||
| warnings | No | ||
| input_query | No | ||
| num_matches | No | ||
| num_results | No | ||
| match_counts | No |