# GoodLeads — capabilities reference (generated)

> Generated from the code by `tools/build_capability_manifest.py` — do not edit. The same data as JSON: `GET /api/v1/manifest`.
> Short guide: /llms.txt

## Which door fits which client
- **MCP address** (Clients that can add a remote MCP server): Claude, Cursor, VS Code, Gemini Spark, Perplexity and Grok accept the address directly. ChatGPT needs one more step. A person must turn on Developer mode in the ChatGPT settings. This takes about one minute and happens one time. An agent in a chat cannot do this step. `https://mcp.goodleads.club/mcp` — Paste the address where your client asks for a remote MCP server. You need no key and no account.
- **Plain web addresses** (Any agent that can fetch a web address): A ChatGPT chat without the connector, a script, a notebook, or any tool that can make a GET request. `https://app.goodleads.club/api/v1/counts` — `GET /api/v1/counts` sizes a market. It takes states, filters as JSON, and `group_by` with up to two fields. `GET /api/v1/crosswalk?q=MCC%205812` translates an industry between code systems. You need no key. Contact details stay masked.
- **The buy page** (A person): Use this way if you want a list and prefer to click, not connect or code. `https://app.goodleads.club/buy.html` — Say who you sell to. See the count and the price. Pay on a hosted page.

## Definitions
- Universe: Every list starts from 'Just started' businesses — a brand-new business with no prior filing. Widen it by filtering filing_kind (or lead_class), or pass include_existing.
- Refresh: Counts and quotes refresh once a day at 06:00 America/Denver with the overnight load; a quote holds until the next refresh.
- Speed: Records appear the morning after the state posts them. Speed is measured from the state's publication, never from the date of filing.
- Billing: only `sellable` records are billed or delivered. Free preview shows what the state publishes; what GoodLeads adds is for key holders.

## Live states
CO (Colorado), CT (Connecticut), FL (Florida), NY (New York), TX (Texas), VA (Virginia)

## Prices
name and address $0.25 per record · plus one verified phone or email $0.50 · plus both $0.70 (price rule v1; live prices always come from the summary call's `prices` block)

## Limits
- /v1 calls per minute: Live key 120 calls a minute, test key 60, no key 30.
- /v1 page size: default 25, max 100 (25 without a key)
- Filter size: 4000 characters, depth 4, 25 conditions
- Website API without a key: 30 calls a minute, 25 records a page
- Checkout: 5 calls a minute
- Over the limit: HTTP 429 with a Retry-After header (seconds to wait)

## What is live
- standing orders set up on the website: live
- standing orders from your code: coming next
- notifications to your server when new records land: coming next
- practice orders with made-up records: coming next
- billing to an account: coming next
- an agent buying on its own through the MCP door: live
- standing-order deliveries to a buyer: coming next
- filter values that forgive case, spacing, plurals and everyday words: live

## Endpoints
door | method path | key | calls/min | what it does
v1 | GET /v1 | no key | 30 | Describe the API
v1 | GET /v1/answers | no key | 30 | Answer a buyer's intent, in plain words
v1 | GET /v1/feedback | key | 120 | Your reports, newest first
v1 | POST /v1/feedback | key | 120 | Report on a record you bought
v1 | GET /v1/feedback/{feedback_id} | key | 120 | One report
v1 | GET /v1/fields | no key | 30 | Every field you can filter on
v1 | GET /v1/jobs | no key | 30 | Buyer jobs: why GoodLeads fits, and ready filters
v1 | GET /v1/jobs/{job_id} | no key | 30 | One buyer job
v1 | POST /v1/keys | no key | 30 | Get API keys — we email you a one-time link
v1 | POST /v1/keys/claim | no key | 30 | Exchange your key link for a test key and a live key (shown once)
v1 | GET /v1/leads | no key | 30 | Find leads
v1 | GET /v1/leads/new | no key | 30 | New leads — today's run, the last few days, or since your last poll
v1 | GET /v1/leads/{lead_id} | no key | 30 | Get one lead by its Lead ID
v1 | GET /v1/me | key | 120 | The key you are calling with
v1 | POST /v1/orders | key | 120 | Order a list
v1 | GET /v1/orders/{order_id} | key | 120 | Get one of your orders
v1 | GET /v1/orders/{order_id}/records | key | 120 | The records an order bought
v1 | GET /v1/pricing | no key | 30 | Current per-record prices
v1 | POST /v1/quotes | key | 120 | Price a list
v1 | GET /v1/states | no key | 30 | The states we carry, and when each last loaded
website_api | GET /api/v1/manifest | no key | - | This manifest: every field, limit, price, state and live feature
website_api | GET /api/v1/schema/attributes | no key | - | Every filterable field, with operators and allowed values
website_api | GET /api/v1/schema/concepts | no key | - | Map a buyer's own word to the fields we carry
website_api | GET /api/v1/schema/recipes | no key | - | Buyer jobs: ready filters and what each score means for that job
website_api | GET /api/v1/taxonomy | no key | - | The industry sectors and subsectors
website_api | GET /api/v1/crosswalk | no key | 30 | One industry in NAICS, SIC, Google category and MCC
website_api | GET /api/v1/counts | no key | 30 | Free counts for a filter, as one GET (optional group_by cross-tab)
website_api | POST /api/v1/leads/summary | no key | 30 | Free counts, facets, prices and a quote for a filter
website_api | POST /api/v1/lists/interpret | no key | 30 | Turn a buyer's words into filters
website_api | GET /api/v1/leads | no key | 30 | Browse leads (owner contact masked without a key)
website_api | GET /api/v1/leads/states | no key | - | The live states
website_api | POST /api/v1/lists | no key | 30 | Save a filter as a shareable list
website_api | GET /api/v1/lists/{list_id} | no key | 30 | Read a saved list
website_api | GET /api/v1/lists/{list_id}/summary | no key | 30 | Counts for a saved list
website_api | POST /api/v1/commerce/checkout | no key | 5 | Open a hosted checkout for a list

## MCP tools
browse_leads, checkout_list, create_checkout, data_quality_scorecard, describe_surface, explain_concept, find_lead_by_glid, interpret_list, list_filterable_fields, list_live_states, list_products, list_starters, quote_list

## Glossary
- **Entity** — A business pulled from a Secretary of State filing.
- **Contact** — The person who can authorize a purchase for that business.
- **Lead** — A business plus its owner, scores and attributes. The unit you buy.
- **Lead ID** — A permanent reference like GL-CO-00042 (GL-<STATE>-<number>); the lead_ref field. It never changes.
- **sellable** — A matching record whose filing names a person. Only sellable records are ever billed or delivered.
- **matching** — Every record that fits your filter, named owner or not. Counts show it; you are never billed on it.

## Rank-ordered sort fields (sorting by a tier sorts by its rank, not alphabetically)
reachability_tier: On Fire > Very Hot > Hot > Warm > Cold; contact_relevance_tier: Decision Maker > Likely Decision Maker > Probable Contact > Uncertain Contact > Unlikely Decision Maker; contact_confidence_tier: Verified Contact > Likely Contact > Possible Contact > Uncertain Contact; industry_confidence_tier: confirmed > likely > possible > unknown; new_business_tier: Confirmed new > Likely new > Uncertain > Likely established > Established

## Narrower pseudo-fields (a field with its own operator set)
`run_manifest_id` (`eq`), `cluster_ref` (`eq`), `missing_stage` (`eq`), `created_at` (`gt` `gte` `lt` `lte` `between`), `geo_polygon` (`within`), `geo_radius` (`within`), `has_phone_or_email` (`eq`), `filing_kind` (`eq` `neq` `in` `not_in`), `new_business_tier` (`eq` `neq` `in` `not_in`)

## Fields
85 on the website schema; 49 on /v1 (52 with a key); 50 in the free preview; 64 in the purchased file. /v1/fields lists the fields that the public API lets you filter on. The owner's name, phone and email are never filterable. /api/v1/schema/attributes lists the full website schema. The website schema is wider. It also has fields that the public API does not filter on, and the owner contact fields (masked without a key). Where both list a field, the names, operators and values are the same.

field | type | doors | operators | allowed values | also called
entity_id | text | preview | eq neq in not_in contains does_not_contain exists missing | - | internal id, row id
lead_ref | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | lead id, glid, record key, permalink id, lead number
state | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | CO, CT, FL, NY, TX, VA | filing state, formation state, registration state, state code
entity_name | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | registered name, corporate name, organization name
trade_name | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | trading name, dba name
entity_type | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | LLC, PLLC, CORP, PC, LP, LLP, LLLP, NONPROFIT, COOP, PARTNERSHIP, SOLE_PROP, OTHER | business structure, company type, entity form
entity_type_raw | text | website | eq neq in not_in contains does_not_contain exists missing | - | original entity type, raw filing type, state's entity type
entity_is_foreign | boolean | preview,v1_filter,v1_filter_with_key,export | eq neq | - | foreign registration, non-domestic, registered from elsewhere
business_origin | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | newly_formed, new_location, formed_out_of_state, institutional | opening a location here, new location, expanding into the state, formed out of state, registration vs formation, why it is on the list
filing_kind | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in | formation, registration, conversion, name_change, reinstatement, address_change, dissolution | -
home_state | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | AL, AK, AZ, AR, CA, CO, CT, DE, DC, FL, GA, HI (+40 more) | state of origin, formed in, where it was first formed, domestic state
has_federal_tax_id | boolean | preview,v1_filter,v1_filter_with_key,export | eq neq | - | ein on file, has an ein, tax id present
entity_is_professional | boolean | preview,v1_filter,v1_filter_with_key,export | eq neq | - | professional entity, pllc, licensed professional entity, professional corporation
entity_is_nonprofit | boolean | preview,v1_filter,v1_filter_with_key,export | eq neq | - | non-commercial entity, nonprofit flag
entity_is_public_benefit | boolean | preview,v1_filter,v1_filter_with_key,export | eq neq | - | benefit corporation, b-corp, public benefit corp, social enterprise filing
formation_date | date | preview,v1_filter,v1_filter_with_key,export | eq neq gt gte lt lte between in not_in exists missing | - | start date, date of formation
status | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | active, dissolved, withdrawn, merged, delinquent, converted, noncompliant, unknown | filing status, standing, registration status
status_raw | text | website | eq neq in not_in contains does_not_contain exists missing | - | original status, raw status, state's status wording
created_at | date | website | gt gte lt lte between | - | record added date, load date, ingested at, date added to database, first seen in dataset
contact_name | text | export | eq neq in not_in contains does_not_contain exists missing | - | principal name, key contact, buyer name
contact_ref | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | glc, contact reference number
role_title | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | designation, officer designation, capacity
role_is_decision_maker | boolean | preview,v1_filter,v1_filter_with_key,export | eq neq | - | decision maker flag, authority flag, signing authority, owner-level role
email_primary | text | export | eq neq in not_in contains does_not_contain exists missing | - | primary email, best email
phone_primary | text | export | eq neq in not_in contains does_not_contain exists missing | - | primary phone, telephone, dial number
reachability_score | number | export | eq neq gt gte lt lte between in not_in exists missing | - | reach score, contactability score, connectivity score
reachability_tier | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | On Fire, Very Hot, Hot, Warm, Cold | priority tier, lead temperature, reach band, call priority
contact_relevance_score | number | export | eq neq gt gte lt lte between in not_in exists missing | - | decision-maker score, relevance score
contact_relevance_tier | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | Decision Maker, Likely Decision Maker, Probable Contact, Uncertain Contact, Unlikely Decision Maker | decision-maker tier, relevance band, person-fit tier
contact_confidence_score | number | export | eq neq gt gte lt lte between in not_in exists missing | - | contact quality score, realness score, person confidence score
contact_confidence_tier | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | Verified Contact, Likely Contact, Possible Contact, Uncertain Contact | confidence band, contact quality tier
new_business_tier | text | export | eq neq in not_in | Confirmed new, Likely new, Uncertain, Likely established, Established | how new, newness, confirmed new, genuinely new, brand new business, new business score tier
industry_sector | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | healthcare, legal, accounting, engineering, construction, real_estate, food_and_beverage, transportation, technology, retail, finance_and_holdings, consulting (+3 more) | market segment, top-level industry
industry_name | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | specific industry, sub-industry, detailed category, specialty
industry_confidence_tier | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | confirmed, likely, possible, unknown | classification confidence, industry certainty
sic_2_digit | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | sic major group, 2-digit sic
sic_3_digit | text | preview,v1_filter,v1_filter_with_key | eq neq in not_in contains does_not_contain exists missing | - | 3-digit sic, sic industry group
sic_4_digit | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | sic industry code, full sic code
naics_2_digit | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | naics sector, 2-digit naics
naics_3_digit | text | preview,v1_filter,v1_filter_with_key | eq neq in not_in contains does_not_contain exists missing | - | naics subsector, 3-digit naics
naics_4_digit | text | preview,v1_filter,v1_filter_with_key | eq neq in not_in contains does_not_contain exists missing | - | 4-digit naics, naics industry group
naics_5_digit | text | preview,v1_filter,v1_filter_with_key | eq neq in not_in contains does_not_contain exists missing | - | 5-digit naics, naics industry
naics_6_digit | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | national industry code, full naics
gmb_category | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | google business profile category, gbp category, google maps category
mcc | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | mcc code, card network code, payment processor category
gtm_segment | text | export | eq neq in not_in contains does_not_contain exists missing | owner_operator, budget_formation, midmarket_formation, premium_established, suspicious_exclude, unclassified | buyer profile, outreach segment, sales segment
ra_market_tier | text | export | eq neq in not_in contains does_not_contain exists missing | - | filing service tier, ra tier, agent tier, agent market segment
ra_is_commercial | boolean | export | eq neq | - | commercial agent, professional ra, ra service, third-party agent
ra_self_represented | boolean | export | eq neq | - | own agent, owner is agent, acts as own agent
ra_is_attorney | boolean | export | eq neq | - | attorney agent, lawyer as agent
has_phone | boolean | preview,v1_filter,v1_filter_with_key,export | eq neq | - | phone available, phone found, phone fill flag
has_email | boolean | preview,v1_filter,v1_filter_with_key,export | eq neq | - | email available, email found, email fill flag
has_phone_or_email | boolean | v1_filter,v1_filter_with_key | eq | - | any channel, either channel present
email_deliverability_status | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | abuse, catch-all, do_not_mail, invalid, spamtrap, unknown, valid | email validation status, bounce risk, send safety, deliverability verdict
skip_trace_attempts | number | website | eq neq gt gte lt lte between in not_in exists missing | - | -
gapfill_attempts | number | website | eq neq gt gte lt lte between in not_in exists missing | - | -
phone_type | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | landline, mobile, unknown, voip | mobile or landline, phone kind, number type
property_classification | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | RESIDENTIAL, COMMERCIAL, INDUSTRIAL, AGRICULTURAL, EXEMPT, VACANT, UNKNOWN | property type, real estate type, residential or commercial, land use
property_is_vacant | boolean | export | eq neq | - | vacant land, empty lot, undeveloped parcel
property_assessed_value | number | export | eq neq gt gte lt lte between in not_in exists missing | - | assessed value, property value, home value, real estate value
principal_address | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | main address, primary address
county_fips | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | county code, fips code, county identifier
principal_city | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | municipality, business city
principal_zip | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | five-digit zip, postal code of record
address_source | text | export | eq neq in not_in contains does_not_contain exists missing | Mailing Address, Officer of Record, Organizer of Record, Registered Agent (Self), State Filing | address provenance, which address we display, working address origin, address origin
neighborhood | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | neighbourhood, district, part of town, side of town, community, area of the city, barrio
time_zone | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | -
msa_code | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | cbsa code, metro code
msa_name | text | preview,v1_filter,v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | - | metro name, city region
tract_income_band | text | preview,export | eq neq in not_in contains does_not_contain exists missing | Under $50K, $50K-$75K, $75K-$100K, $100K-$150K, $150K+ | income band, household income, neighborhood income, affluence, buying power, wealth band
tract_median_income | number | preview,v1_filter,v1_filter_with_key,export | eq neq gt gte lt lte between in not_in exists missing | - | median income, median household income, area income, census income
area_code | text | export | eq neq in not_in contains does_not_contain exists missing | - | phone prefix, npa, dialing code, phone area
geocode_status | text | website | eq neq in not_in contains does_not_contain exists missing | Match, No_Match, Tie | geocoding result, address match status, geolocation status
run_manifest_id | text | website | eq | - | run id, cohort id, pipeline run id, processing run
cluster_ref | text | v1_filter_with_key | eq | - | same owner, owner group, same-owner group, one owner
missing_stage | text | website | eq | - | coverage gap, never processed, unstamped records, stage never ran, unprocessed by brain
enrichment_strategy | text | website | eq neq in not_in contains does_not_contain exists missing | name_and_address, address_only, mailing_fallback, name_with_state, operating_business, hold | routing decision, enrichment plan, lookup strategy, trace mode
name_density | number | website | eq neq gt gte lt lte between in not_in exists missing | - | shared-name count, same-name entities in corpus, name frequency in corpus
name_rarity | text | website | eq neq in not_in contains does_not_contain exists missing | very_common, common, uncommon, rare | surname rarity, rare last name, how common is the last name in the us
address_density | number | website | eq neq gt gte lt lte between in not_in exists missing | - | same-address count, shared address count, address crowding, entities at this address
entity_archetype | text | export | eq neq in not_in contains does_not_contain exists missing | operating_business, mail_drop_or_formation_suite, asset_protection_holding, single_asset_property_llc | business kind, operating vs holding, entity category
cluster_size | number | v1_filter_with_key,export | eq neq gt gte lt lte between in not_in exists missing | - | businesses under one owner, portfolio owner, serial founder, related filings, filed more than one
cluster_code | text | v1_filter_with_key,export | eq neq in not_in contains does_not_contain exists missing | XF-O, XF-V, XP-O, XP-V, XV-V, XM-O, XM-V | owner group role, holding company or operating business, portfolio role, group type
geo_polygon | geo | website | within | - | territory boundary, map area, draw-to-select region, custom territory, polygon filter
geo_radius | geo | website | within | - | within miles of, mile radius, near a zip, around a city, radius filter, service area radius