{"openapi":"3.1.0","info":{"title":"GoodLeads API","description":"Owners of newly formed US businesses — by name, with a mailing address and, where verified, a phone or email — the morning after the state posts the filing. Every object carries `type`; every error is `application/problem+json` with a stable `code`; every response carries `GoodLeads-Request-Id` and the `GoodLeads-Version` it was rendered in. Additive-only: ignore fields you do not know and treat enum values you do not know as valid.","version":"2026-10-01"},"paths":{"/":{"get":{"tags":["meta"],"summary":"Describe the API","operationId":"api_root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiRoot"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/jobs":{"get":{"tags":["jobs"],"summary":"Buyer jobs: why GoodLeads fits, and ready filters","description":"Start here when you know what your buyer sells, not our fields: each job says\nwhy GoodLeads fits it and carries ready filters and next steps.","operationId":"list_jobs_jobs_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobList"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/jobs/{job_id}":{"get":{"tags":["jobs"],"summary":"One buyer job","operationId":"get_job_jobs__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"default":{"$ref":"#/components/responses/Problem"}}}},"/answers":{"get":{"tags":["jobs"],"summary":"Answer a buyer's intent, in plain words","description":"Any intent gets an answer, never a \"no\": what is true of a days-old business,\nready filters, a free count, and where to go next. Deterministic and fast.","operationId":"answer_answers_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":300,"description":"What your buyer wants, e.g. \"businesses that need insurance\".","title":"Q"},"description":"What your buyer wants, e.g. \"businesses that need insurance\"."},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":2},{"type":"null"}],"description":"Two-letter state code for the count.","title":"State"},"description":"Two-letter state code for the count."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntentAnswer"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"default":{"$ref":"#/components/responses/Problem"}}}},"/states":{"get":{"tags":["meta"],"summary":"The states we carry, and when each last loaded","description":"Every live state — what `state` on /v1/leads and `states` on /v1/quotes accept —\nwith the day its records last landed.","operationId":"list_states_states_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateList"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/fields":{"get":{"tags":["meta"],"summary":"Every field you can filter on","description":"The filter surface: each field's type, operators and, where the set is closed,\nits values. A key adds the fields only key holders may filter on. The owner's name,\nphone and email are never filterable — they are masked until you buy.","operationId":"list_fields_fields_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldList"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/pricing":{"get":{"tags":["pricing"],"summary":"Current per-record prices","operationId":"get_pricing_pricing_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pricing"}}}},"default":{"$ref":"#/components/responses/Problem"}}}},"/me":{"get":{"tags":["account"],"summary":"The key you are calling with","operationId":"get_me_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}]}},"/keys":{"post":{"tags":["account"],"summary":"Get API keys — we email you a one-time link","operationId":"request_keys_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyRequestBody"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyRequest"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"default":{"$ref":"#/components/responses/Problem"}}}},"/keys/claim":{"post":{"tags":["account"],"summary":"Exchange your key link for a test key and a live key (shown once)","operationId":"claim_keys_keys_claim_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimBody"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyPair"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"default":{"$ref":"#/components/responses/Problem"}}}},"/leads":{"get":{"tags":["leads"],"summary":"Find leads","operationId":"list_leads_leads_get","parameters":[{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":2},{"type":"null"}],"description":"Two-letter state code.","title":"State"},"description":"Two-letter state code."},{"name":"filters","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"JSON array of {\"field\", \"op\", \"value\"} leaves and and/or/not groups (the filter grammar).","title":"Filters"},"description":"JSON array of {\"field\", \"op\", \"value\"} leaves and and/or/not groups (the filter grammar)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"next_cursor from the previous page.","title":"Cursor"},"description":"next_cursor from the previous page."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadList"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"default":{"$ref":"#/components/responses/Problem"}}}},"/leads/new":{"get":{"tags":["leads"],"summary":"New leads — today's run, the last few days, or since your last poll","description":"Every new lead that matches your filter, as masked previews (records you\nbought show what you bought). New means: loaded by a state's run once that\nrun finished checking it, and formed within the last 60 days.","operationId":"new_leads_leads_new_get","parameters":[{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":2},{"type":"null"}],"description":"Two-letter state code. Default: every live state.","title":"State"},"description":"Two-letter state code. Default: every live state."},{"name":"filters","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"JSON array of {\"field\", \"op\", \"value\"} leaves and and/or/not groups (the filter grammar).","title":"Filters"},"description":"JSON array of {\"field\", \"op\", \"value\"} leaves and and/or/not groups (the filter grammar)."},{"name":"window","in":"query","required":false,"schema":{"anyOf":[{"enum":["today","5d","7d","15d","30d","60d"],"type":"string"},{"type":"null"}],"description":"For a first pull: today (each state's latest completed run) or the last 5 / 7 / 15 / 30 / 60 days of runs. Default: today.","title":"Window"},"description":"For a first pull: today (each state's latest completed run) or the last 5 / 7 / 15 / 30 / 60 days of runs. Default: today."},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"next_since from your previous poll: everything new since then, each record exactly once.","title":"Since"},"description":"next_since from your previous poll: everything new since then, each record exactly once."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"next_cursor from the previous page. It carries its window, state, filters and order: send it alone with limit.","title":"Cursor"},"description":"next_cursor from the previous page. It carries its window, state, filters and order: send it alone with limit."},{"name":"order","in":"query","required":false,"schema":{"anyOf":[{"enum":["newest","oldest"],"type":"string"},{"type":"null"}],"description":"newest (default): the latest Lead IDs first, so page one is the newest filings. oldest: the reverse.","title":"Order"},"description":"newest (default): the latest Lead IDs first, so page one is the newest filings. oldest: the reverse."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadFeed"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"default":{"$ref":"#/components/responses/Problem"}}}},"/leads/{lead_id}":{"get":{"tags":["leads"],"summary":"Get one lead by its Lead ID","operationId":"get_lead_leads__lead_id__get","parameters":[{"name":"lead_id","in":"path","required":true,"schema":{"type":"string","title":"Lead Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"default":{"$ref":"#/components/responses/Problem"}}}},"/feedback":{"post":{"tags":["feedback"],"summary":"Report on a record you bought","operationId":"create_feedback_feedback_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feedback"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}]},"get":{"tags":["feedback"],"summary":"Your reports, newest first","operationId":"list_feedback_feedback_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackList"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}]}},"/feedback/{feedback_id}":{"get":{"tags":["feedback"],"summary":"One report","operationId":"get_feedback_feedback__feedback_id__get","parameters":[{"name":"feedback_id","in":"path","required":true,"schema":{"type":"string","title":"Feedback Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feedback"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}]}},"/quotes":{"post":{"tags":["orders"],"summary":"Price a list","description":"What the list costs today, graded, with nothing written or reserved. Send the\nsame body to POST /v1/orders with `expected_total_cents` to buy exactly this.","operationId":"create_quote_quotes_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"402":{"description":"budget_exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"no_match · order_too_large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}]}},"/orders":{"post":{"tags":["orders"],"summary":"Order a list","description":"Freeze the list and open its payment page. The records are fixed now: the file\nis exactly these rows, at exactly this price. Requires `Idempotency-Key`.","operationId":"create_order_orders_post","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Required. A fresh random value (a UUID) per order, and the same value when you retry it."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"402":{"description":"budget_exceeded","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"quote_changed · idempotency_key_reused · idempotency_key_in_use","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"no_match · order_too_large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}]}},"/orders/{order_id}":{"get":{"tags":["orders"],"summary":"Get one of your orders","description":"Where an order is: awaiting payment, paid, delivered. Only your own orders — any\nother id is a 404.","operationId":"get_order_orders__order_id__get","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}]}},"/orders/{order_id}/records":{"get":{"tags":["orders"],"summary":"The records an order bought","description":"Every record a paid order bought, as Leads (`access: owned`), in Lead ID order —\nthe order's frozen list, so the set never changes after checkout. Owner details are\nshown as the purchase shipped them. Only your own orders; any other id is a 404.","operationId":"list_order_records_orders__order_id__records_get","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"next_cursor from the previous page.","title":"Cursor"},"description":"next_cursor from the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadList"}}}},"409":{"description":"order_not_paid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"default":{"$ref":"#/components/responses/Problem"}},"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}]}}},"components":{"schemas":{"ApiRoot":{"properties":{"type":{"type":"string","const":"api","title":"Type","default":"api"},"name":{"type":"string","title":"Name"},"version":{"type":"string","title":"Version","description":"The version this response was rendered in."},"latest_version":{"type":"string","title":"Latest Version"},"supported_versions":{"items":{"type":"string"},"type":"array","title":"Supported Versions"},"docs_url":{"type":"string","title":"Docs Url"},"openapi_url":{"type":"string","title":"Openapi Url"},"resources":{"items":{"type":"string"},"type":"array","title":"Resources"},"start_here":{"anyOf":[{"$ref":"#/components/schemas/NextStep"},{"type":"null"}],"description":"Where a new caller begins: the buyer jobs."}},"type":"object","required":["name","version","latest_version","supported_versions","docs_url","openapi_url","resources"],"title":"ApiRoot"},"Cap":{"properties":{"type":{"type":"string","enum":["count","budget"],"title":"Type","description":"count: at most `value` records. budget: at most `value` cents."},"value":{"type":"integer","minimum":0.0,"title":"Value"}},"additionalProperties":false,"type":"object","required":["type","value"],"title":"Cap"},"ClaimBody":{"properties":{"token":{"type":"string","maxLength":2000,"minLength":10,"title":"Token","description":"The token from your key link."}},"additionalProperties":false,"type":"object","required":["token"],"title":"ClaimBody"},"ExcludedFilter":{"properties":{"field":{"type":"string","title":"Field"},"reason":{"type":"string","title":"Reason"}},"type":"object","required":["field","reason"],"title":"ExcludedFilter","description":"A filter the job's recipe uses that /v1 does not take, and why."},"FeedRun":{"properties":{"type":{"type":"string","const":"state_run","title":"Type","default":"state_run"},"state":{"type":"string","title":"State"},"run_day":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Day","description":"The day the state's latest completed run finished (US Central date); null when it has none in 60 days."},"run_completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Completed At"},"window_start":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Window Start","description":"Records added after this instant (ISO 8601, UTC)…"},"window_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Window End","description":"…and at or before this one."},"status":{"type":"string","title":"Status","description":"ok · unavailable — this state did not answer in time; its records come on your next poll (next_since keeps its place). Extensible enum: new values may appear — treat unknown values as valid.","default":"ok"}},"type":"object","required":["state","run_day","run_completed_at","window_start","window_end"],"title":"FeedRun","description":"The run a state's part of the feed came from — so a caller can see when\na state's data last landed, and that a state is not silently a day behind."},"Feedback":{"properties":{"type":{"type":"string","const":"feedback","title":"Type","default":"feedback"},"id":{"type":"string","title":"Id"},"lead_id":{"type":"string","title":"Lead Id"},"outcome":{"type":"string","title":"Outcome","description":"connected · wrong_person · disconnected · bad_email · bought · not_a_fit. Extensible enum: new values may appear — treat unknown values as valid."},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"},"status":{"type":"string","title":"Status","description":"received. Extensible enum: new values may appear — treat unknown values as valid."},"replacement_eligible":{"type":"boolean","title":"Replacement Eligible"},"replacement_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Replacement Reason"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["id","lead_id","outcome","status","replacement_eligible"],"title":"Feedback","description":"What you told us about a record you bought, and whether it is replaced."},"FeedbackCreate":{"properties":{"lead_id":{"type":"string","maxLength":32,"minLength":4,"title":"Lead Id","description":"The Lead ID of a record you bought."},"outcome":{"type":"string","title":"Outcome","description":"One of: connected, wrong_person, disconnected, bad_email, bought, not_a_fit. Extensible enum: new values may appear — treat unknown values as valid."},"detail":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Detail"}},"additionalProperties":false,"type":"object","required":["lead_id","outcome"],"title":"FeedbackCreate"},"FeedbackList":{"properties":{"type":{"type":"string","const":"list","title":"Type","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Feedback"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data","has_more"],"title":"FeedbackList"},"FieldList":{"properties":{"type":{"type":"string","const":"list","title":"Type","default":"list"},"data":{"items":{"$ref":"#/components/schemas/FilterField"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","default":false},"next_step":{"anyOf":[{"$ref":"#/components/schemas/NextStep"},{"type":"null"}],"description":"Start from your buyer's job instead of the fields: GET /v1/jobs."}},"type":"object","required":["data"],"title":"FieldList"},"FilterField":{"properties":{"type":{"type":"string","const":"filter_field","title":"Type","default":"filter_field"},"name":{"type":"string","title":"Name"},"value_type":{"type":"string","title":"Value Type","description":"text · number · boolean · date. Extensible enum: new values may appear — treat unknown values as valid."},"operators":{"items":{"type":"string"},"type":"array","title":"Operators"},"allowed_values":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Values","description":"The only values eq / neq / in / not_in accept, when the field has a closed set."},"description":{"type":"string","title":"Description"},"audience":{"type":"string","title":"Audience","description":"anyone · key (filterable only with an API key). Extensible enum: new values may appear — treat unknown values as valid."}},"type":"object","required":["name","value_type","operators","description","audience"],"title":"FilterField","description":"One field you can filter on: a leaf is {\"field\": name, \"op\": one of `operators`, \"value\": ...}."},"IntentAnswer":{"properties":{"type":{"type":"string","const":"answer","title":"Type","default":"answer"},"query":{"type":"string","title":"Query"},"kind":{"type":"string","title":"Kind","description":"setup · not_yet · industry · field · general. Extensible enum: new values may appear — treat unknown values as valid."},"headline":{"type":"string","title":"Headline"},"answer":{"type":"string","title":"Answer"},"filters":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Filters","description":"Ready /v1 filter leaves (may be empty: every new business)."},"excluded_filters":{"items":{"$ref":"#/components/schemas/ExcludedFilter"},"type":"array","title":"Excluded Filters"},"window":{"type":"string","title":"Window"},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Id","description":"The matching buyer job: GET /v1/jobs/{job_id}."},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State","description":"The live state the count and next steps are for — from `state=` or named in `q`."},"count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Count","description":"Businesses formed in the last `window` that match `filters` (in `state` when one is named), free; null when it could not be counted in time."},"next_steps":{"items":{"$ref":"#/components/schemas/NextStep"},"type":"array","title":"Next Steps"}},"type":"object","required":["query","kind","headline","answer","filters","window","next_steps"],"title":"IntentAnswer","description":"The answer to a buyer's intent (\"businesses that need insurance\"). Never a\n\"no\": `kind` names the answer, and `next_steps` always lead somewhere."},"IssuedKey":{"properties":{"type":{"type":"string","const":"api_key","title":"Type","default":"api_key"},"key":{"type":"string","title":"Key"},"key_id":{"type":"string","title":"Key Id"},"mode":{"type":"string","title":"Mode","description":"test · live. Extensible enum: new values may appear — treat unknown values as valid."},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes","description":"What this key may do. Extensible enum: new values may appear — treat unknown values as valid."},"rate_limit_per_min":{"type":"integer","title":"Rate Limit Per Min"}},"type":"object","required":["key","key_id","mode","scopes","rate_limit_per_min"],"title":"IssuedKey","description":"One key, shown once. Store it on your server; it is never shown again."},"Job":{"properties":{"type":{"type":"string","const":"job","title":"Type","default":"job"},"id":{"type":"string","title":"Id","description":"Stable slug, e.g. web_design."},"job":{"type":"string","title":"Job","description":"The job, in the buyer's words."},"why_goodleads":{"type":"string","title":"Why Goodleads"},"phrasings":{"items":{"type":"string"},"type":"array","title":"Phrasings","description":"How buyers say this job."},"filters":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Filters","description":"Ready /v1 filter leaves. Recency is the feed's `window`, not a filter."},"refinements":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Refinements","description":"Optional narrower cuts: add them to `filters` where they fit."},"excluded_filters":{"items":{"$ref":"#/components/schemas/ExcludedFilter"},"type":"array","title":"Excluded Filters","description":"Parts of the recipe /v1 does not take, and why."},"window":{"type":"string","title":"Window","description":"The /v1/leads/new window the next step reads."},"score_interpretation":{"additionalProperties":{"type":"string"},"type":"object","title":"Score Interpretation","description":"What each tier means for THIS job."},"caveats":{"items":{"type":"string"},"type":"array","title":"Caveats"},"traps":{"items":{"type":"string"},"type":"array","title":"Traps"},"quote_request":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Quote Request","description":"A POST /v1/quotes body for this job (a key is free); null when the job needs no filter."},"next_steps":{"items":{"$ref":"#/components/schemas/NextStep"},"type":"array","title":"Next Steps"}},"type":"object","required":["id","job","why_goodleads","phrasings","filters","refinements","excluded_filters","window","score_interpretation","caveats","traps","quote_request","next_steps"],"title":"Job","description":"A buyer job: why GoodLeads, and ready /v1 filters. Send `filters` to\n/v1/leads/new (the `next_steps` carry the URL) or `quote_request` to\nPOST /v1/quotes for a free count and price."},"JobList":{"properties":{"type":{"type":"string","const":"list","title":"Type","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Job"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","default":false}},"type":"object","required":["data"],"title":"JobList"},"KeyPair":{"properties":{"type":{"type":"string","const":"key_pair","title":"Type","default":"key_pair"},"test":{"$ref":"#/components/schemas/IssuedKey"},"live":{"$ref":"#/components/schemas/IssuedKey"},"shown_once":{"type":"boolean","title":"Shown Once","default":true}},"type":"object","required":["test","live"],"title":"KeyPair","description":"Your test key (build with it — never charges, never real people) and your\nlive key (buy with it — every order is paid on its checkout page)."},"KeyRequest":{"properties":{"type":{"type":"string","const":"key_request","title":"Type","default":"key_request"},"status":{"type":"string","title":"Status","description":"sent. Extensible enum: new values may appear — treat unknown values as valid."},"email":{"type":"string","title":"Email"},"expires_in_minutes":{"type":"integer","title":"Expires In Minutes"},"next_step":{"anyOf":[{"$ref":"#/components/schemas/NextStep"},{"type":"null"}]}},"type":"object","required":["status","email","expires_in_minutes"],"title":"KeyRequest","description":"A key link is on its way to the email you gave."},"KeyRequestBody":{"properties":{"email":{"type":"string","maxLength":320,"minLength":3,"title":"Email","description":"Where the one-time link goes."},"declared_use":{"type":"string","maxLength":64,"title":"Declared Use","description":"What you will use the data for: b2b_sales_outreach, b2b_marketing, crm_enrichment, market_research, platform_integration."},"company":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Company"},"accept_terms":{"type":"boolean","title":"Accept Terms","description":"You accept the GoodLeads terms (https://goodleads.club/terms.html), including §10 API terms."}},"additionalProperties":false,"type":"object","required":["email","declared_use","accept_terms"],"title":"KeyRequestBody"},"Lead":{"properties":{"type":{"type":"string","const":"lead","title":"Type","default":"lead"},"id":{"type":"string","title":"Id","description":"The Lead ID (for example GL-FL-392995). Permanent; the only lead identifier."},"access":{"type":"string","title":"Access","description":"What this response shows. preview: no key — what the state publishes, owner details masked. keyed: a key — adds what GoodLeads resolves (the same-owner family); owner details still masked. owned: your account bought this record — the owner's name, phone and email in full. Extensible enum: new values may appear — treat unknown values as valid."},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State","description":"Two-letter code of the state that published the filing.","x-audience":"anyone","x-group":"business","x-stability":"ga"},"state_entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State Entity Id","description":"The state's own filing number for this business — look it up directly on the state registry.","x-audience":"anyone","x-group":"business","x-stability":"ga"},"entity_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Name","description":"Legal name of the business as filed with the state.","x-audience":"anyone","x-group":"business","x-stability":"ga"},"trade_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trade Name","description":"Market-facing DBA/trade name registered with the state — the name a customer recognizes, distinct from the legal entity name. Blank when the business operates under its legal name.","x-audience":"anyone","x-group":"business","x-stability":"ga"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Current filing status — standardized across states (active, dissolved, withdrawn, etc.).","x-audience":"anyone","x-group":"business","x-stability":"ga"},"entity_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Type","description":"Legal structure of the business — standardized across states (LLC, CORP, LP, LLP, NONPROFIT, etc.).","x-audience":"anyone","x-group":"business","x-stability":"ga"},"formation_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Formation Date","description":"Date the business was officially formed with the state.","x-audience":"anyone","x-group":"business","x-stability":"ga"},"entity_is_foreign":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Entity Is Foreign","description":"True when the business registered from out of state (a foreign filing).","x-audience":"anyone","x-group":"business","x-stability":"ga"},"entity_is_professional":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Entity Is Professional","description":"True for a licensed-professional entity (PLLC / PC).","x-audience":"anyone","x-group":"business","x-stability":"ga"},"entity_is_nonprofit":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Entity Is Nonprofit","description":"True for a not-for-profit entity.","x-audience":"anyone","x-group":"business","x-stability":"ga"},"entity_is_public_benefit":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Entity Is Public Benefit","description":"True for a public-benefit corporation (B-corp filing).","x-audience":"anyone","x-group":"business","x-stability":"ga"},"business_origin":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Business Origin","description":"Why this business is on the list: Newly formed in <state> (a brand-new business); New location of an existing business (registered here from an out-of-state address); New business, formed out of state (a local address, formed in another state); Holding or institutional vehicle (held at a custodian). A file sold as newly formed carries only the first; the others ship as their own list.","x-audience":"anyone","x-group":"business","x-stability":"ga"},"home_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Home State","description":"The state the business was first formed in, when it is not this one — from the filing. Blank on every newly formed business.","x-audience":"anyone","x-group":"business","x-stability":"ga"},"has_federal_tax_id":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Federal Tax Id","description":"True when the state filing lists a federal tax ID — the number itself is in Federal Tax ID (EIN). An existing business usually has one before it registers; a brand-new one rarely does. Blank where the state's feed has no such field.","x-audience":"anyone","x-group":"business","x-stability":"ga"},"filing_kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filing Kind","description":"What the state filing did: a brand-new business, an existing business registering in this state, a change of legal form, a new name, a reactivation, a move, or a closing. A file sold as new businesses carries only formations; the others ship as their own list.","x-audience":"anyone","x-group":"filing","x-stability":"ga"},"lead_class":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lead Class","description":"The same fact in the words you sell by — so a rep knows in one glance whether this is a first purchase (Just started — including a local owner who formed in another state, home-state paperwork) or a reason to call an operating business (New to <state>, the record's own state; Established business, new entity; New trade name; Back in business; Moved). Agrees with business_origin on every row.","x-audience":"anyone","x-group":"filing","x-stability":"ga"},"last_event":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Event","description":"The most recent thing the state published about this business, in plain words.","x-audience":"anyone","x-group":"filing","x-stability":"ga"},"last_event_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Last Event Date","description":"The day the state published that event — the day your clock starts.","x-audience":"anyone","x-group":"filing","x-stability":"ga"},"published_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Published Date","description":"The day the filing appeared on the state's public record. Freshness is measured from here, never from the filing date.","x-audience":"anyone","x-group":"filing","x-stability":"ga"},"prior_entity_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prior Entity Ref","description":"For a business that changed form, the record it came from: its Lead ID when we hold it, otherwise the state's document number.","x-audience":"anyone","x-group":"filing","x-stability":"ga"},"prior_entity_formation_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Prior Entity Formation Date","description":"When that prior business was first formed — how long this owner has been operating.","x-audience":"anyone","x-group":"filing","x-stability":"ga"},"industry_sector":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry Sector","description":"High-level industry classification, standardized across states.","x-audience":"anyone","x-group":"classification","x-stability":"ga"},"industry_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry Name","description":"Specific industry within the sector — more granular than industry_sector.","x-audience":"anyone","x-group":"classification","x-stability":"ga"},"industry_confidence_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry Confidence Tier","description":"How sure the classification is: confirmed, likely, possible, or unknown.","x-audience":"anyone","x-group":"classification","x-stability":"preview"},"naics_2_digit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Naics 2 Digit","description":"2017 NAICS 2-digit sector code.","x-audience":"anyone","x-group":"classification","x-stability":"ga"},"naics_3_digit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Naics 3 Digit","description":"2017 NAICS 3-digit subsector (e.g. '238' = Specialty Trade Contractors). May be NULL for ambiguous mappings.","x-audience":"anyone","x-group":"classification","x-stability":"ga"},"naics_4_digit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Naics 4 Digit","description":"2017 NAICS 4-digit industry group (e.g. '2381' = Foundation/Structure/Building Exterior). May be NULL for ambiguous mappings.","x-audience":"anyone","x-group":"classification","x-stability":"ga"},"naics_5_digit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Naics 5 Digit","description":"2017 NAICS 5-digit industry (e.g. '23816' = Roofing Contractors). May be NULL for ambiguous mappings.","x-audience":"anyone","x-group":"classification","x-stability":"ga"},"naics_6_digit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Naics 6 Digit","description":"2017 NAICS 6-digit national industry code — the deepest official NAICS depth.","x-audience":"anyone","x-group":"classification","x-stability":"ga"},"sic_2_digit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sic 2 Digit","description":"1987 SIC 2-digit major group code.","x-audience":"anyone","x-group":"classification","x-stability":"ga"},"sic_3_digit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sic 3 Digit","description":"1987 SIC 3-digit industry group (e.g. '176' = Roofing/Siding/Sheet Metal). May be NULL for ambiguous mappings.","x-audience":"anyone","x-group":"classification","x-stability":"ga"},"sic_4_digit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sic 4 Digit","description":"1987 SIC 4-digit industry code — the depth most B2B systems key on.","x-audience":"anyone","x-group":"classification","x-stability":"ga"},"gmb_category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gmb Category","description":"Google Business (GMB) category — the category local-marketing buyers target on Google.","x-audience":"anyone","x-group":"classification","x-stability":"ga"},"mcc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mcc","description":"ISO 18245 card-network MCC — the underwriting vocabulary of payment processors. Blank when the business type is not a card-accepting merchant category.","x-audience":"anyone","x-group":"classification","x-stability":"ga"},"principal_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Principal Address","description":"Principal business address exactly as filed with the state — always the filing address, on every file. Often a home address for brand-new businesses.","x-audience":"anyone","x-group":"place","x-stability":"ga"},"principal_city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Principal City","description":"City from the principal business address.","x-audience":"anyone","x-group":"place","x-stability":"ga"},"principal_zip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Principal Zip","description":"5-digit ZIP code from the principal business address.","x-audience":"anyone","x-group":"place","x-stability":"ga"},"county_fips":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"County Fips","description":"Federal county FIPS code — useful for territory mapping and geographic joins.","x-audience":"anyone","x-group":"place","x-stability":"ga"},"msa_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Msa Code","description":"OMB CBSA code for the business's metro area — joins cleanly to Census, BLS, and market datasets. Blank when the county sits outside every Metropolitan Statistical Area.","x-audience":"anyone","x-group":"place","x-stability":"ga"},"msa_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Msa Name","description":"Metropolitan Statistical Area the business sits in (for example 'Tampa-St. Petersburg-Clearwater, FL').","x-audience":"anyone","x-group":"place","x-stability":"ga"},"neighborhood":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Neighborhood","description":"Named neighborhood or unincorporated community around the business address (for example 'Capitol Hill', 'South Austin', 'Kendall'), Use it to route by territory inside a city and to open with a local reference. Blank when the address sits outside every named area.","x-audience":"anyone","x-group":"place","x-stability":"ga"},"time_zone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Time Zone","description":"Time zone of the business address, as the standard IANA name every dialer, CRM and scheduler accepts — 'America/New_York', 'America/Chicago', 'America/Denver', 'America/Los_Angeles', 'America/Phoenix'. Sort by it to work a list in local business hours. A name rather than a fixed offset on purpose: the offset moves with daylight saving, and Arizona never shifts. Taken from the address rather than the area code, so a ported number never moves a lead into the wrong calling window. Blank when the address could not be placed on the map.","x-audience":"anyone","x-group":"place","x-stability":"ga"},"tract_income_band":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tract Income Band","description":"Income band of the neighborhood around the business address (census-tract median household income, US Census Bureau ACS): 'Under $50K' through '$150K+'. New filings usually list the owner's home address, so this reads as the founder's neighborhood affluence — use it to pick the offer and the outreach order. An area statistic, not the contact's personal income. Blank when the tract has no reliable estimate.","x-audience":"anyone","x-group":"place","x-stability":"ga"},"tract_median_income":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Tract Median Income","description":"The neighborhood's median household income in dollars (census tract, ACS 5-year estimates) — the raw figure behind Neighborhood Income, for spreadsheet sorting and custom thresholds.","x-audience":"anyone","x-group":"place","x-stability":"ga"},"property_classification":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Property Classification","description":"Type of property at the business address (residential, commercial, industrial, and so on). Residential plus a single entity usually means an owner-operator.","x-audience":"anyone","x-group":"place","x-stability":"ga"},"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latitude","description":"Latitude of the business address, rounded to about a kilometre.","x-audience":"anyone","x-group":"place","x-stability":"preview"},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Longitude","description":"Longitude of the business address, rounded to about a kilometre.","x-audience":"anyone","x-group":"place","x-stability":"preview"},"registered_agent_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Registered Agent Name","description":"Name of the registered agent on the filing.","x-audience":"anyone","x-group":"filing","x-stability":"ga"},"contact_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Ref","description":"Persistent GoodLeads ID for the contact (for example GLC-00087) — the same person may appear on several businesses.","x-audience":"anyone","x-group":"owner","x-stability":"ga"},"contact_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Name","description":"Full name of the person who can authorize a buy for this business.","x-audience":"anyone","x-group":"owner","x-person":true,"x-stability":"ga"},"role_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role Title","description":"The contact's role on the filing — standardized (e.g. Manager, Managing Member, President, Director). Blank where the state does not publish titles.","x-audience":"anyone","x-group":"owner","x-stability":"ga"},"role_is_decision_maker":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Role Is Decision Maker","description":"True when the contact's role can bind the business (owner, manager, managing member, president, etc.) — the person who can authorize a purchase.","x-audience":"anyone","x-group":"owner","x-stability":"ga"},"has_phone":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Phone","description":"Whether the record carries at least one phone number.","x-audience":"anyone","x-group":"reach","x-stability":"ga"},"has_email":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Email","description":"Whether the record carries at least one email address.","x-audience":"anyone","x-group":"reach","x-stability":"ga"},"contact_on_order":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact On Order","description":"found: a phone and an email are on the record. partly_found: one is; we look for the other when you order. found_fresh_on_order: we look up the owner's phone and email the moment you order, so you get today's — has_phone and has_email are false until then. Extensible enum: treat unknown values as valid.","x-audience":"anyone","x-group":"reach","x-stability":"preview"},"phone_primary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Primary","description":"Best phone number for the contact, in +1 E.164 format — paste-ready for dialers and CRMs.","x-audience":"anyone","x-group":"reach","x-person":true,"x-stability":"ga"},"phone_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone Type","description":"Line type of the primary phone: mobile, landline, or voip. Mobile connects best.","x-audience":"anyone","x-group":"reach","x-stability":"ga"},"email_primary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email Primary","description":"Best email address for the contact, selected from every validated candidate.","x-audience":"anyone","x-group":"reach","x-person":true,"x-stability":"ga"},"email_deliverability_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email Deliverability Status","description":"Deliverability verdict for the primary email: valid means send-safe; catch-all means the domain accepts every address.","x-audience":"anyone","x-group":"reach","x-stability":"preview"},"email_inbox_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Email Inbox Active","description":"Whether recent activity was observed on the primary email.","x-audience":"anyone","x-group":"reach","x-stability":"preview"},"cluster_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cluster Ref","description":"Every business with the same owner (ADR-060): the group's reference (GLX-…) as stamped on each member. The record page's 'N businesses' link opens this cohort.","x-audience":"key","x-group":"family","x-stability":"preview"},"cluster_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cluster Code","description":"This record's place among the businesses under one owner, as a type and a role. The type: XF one operating business plus the holding companies built around it; XP several operating businesses under one owner; XV a structure (holding companies only, a deal being formed); XM the same across states. The role: O an operating business, V a holding company (a property LLC, a GP / LP). Blank for a business with no related filing. Every owner group has one owner; call the owner once and you reach the set.","x-audience":"key","x-group":"family","x-stability":"preview"},"cluster_size":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cluster Size","description":"How many businesses share this owner, counting this one (Same owner · 3 businesses). Blank for a business with no related filing.","x-audience":"key","x-group":"family","x-stability":"preview"},"cluster_owner_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cluster Owner Name","description":"The owner every business in this group shares — the one person to call. Blank for a business with no related filing.","x-audience":"key","x-group":"family","x-person":true,"x-stability":"preview"},"cluster_operating_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cluster Operating Name","description":"On a holding company (role V): the operating business it was built around — the one the owner runs. Blank on an operating business or a business with no related filing.","x-audience":"key","x-group":"family","x-stability":"preview"},"reachability_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reachability Tier","description":"Named reachability band: On Fire, Very Hot, Hot, Warm, Cold. Withheld marks records we recommend against dialing.","x-audience":"anyone","x-group":"scores","x-stability":"preview"},"contact_relevance_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Relevance Tier","description":"Named relevance band, from Decision Maker down to Unlikely Decision Maker.","x-audience":"anyone","x-group":"scores","x-stability":"preview"},"contact_confidence_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Confidence Tier","description":"Named confidence band: Verified Contact, Likely Contact, Possible Contact, Uncertain Contact.","x-audience":"anyone","x-group":"scores","x-stability":"preview"},"reachability_score_band":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reachability Score Band","description":"The reachability score as a ten-point band (for example 80–89).","x-audience":"anyone","x-group":"scores","x-stability":"preview"},"contact_relevance_score_band":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Relevance Score Band","description":"The contact relevance score as a ten-point band.","x-audience":"anyone","x-group":"scores","x-stability":"preview"},"contact_confidence_score_band":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact Confidence Score Band","description":"The contact confidence score as a ten-point band.","x-audience":"anyone","x-group":"scores","x-stability":"preview"}},"type":"object","required":["id","access"],"title":"Lead","description":"A newly formed business and its owner."},"LeadFeed":{"properties":{"type":{"type":"string","const":"list","title":"Type","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Lead"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"},"next_step":{"anyOf":[{"$ref":"#/components/schemas/NextStep"},{"type":"null"}],"description":"Present when the page is empty: where to go next."},"next_since":{"type":"string","title":"Next Since","description":"Pass as `since` on your next poll, once has_more is false."},"window":{"type":"string","title":"Window","description":"today · 5d · 7d · 15d · 30d · 60d · since · cursor. Extensible enum: new values may appear — treat unknown values as valid."},"runs":{"items":{"$ref":"#/components/schemas/FeedRun"},"type":"array","title":"Runs","description":"One entry per state: the run its records came from and the window read."},"on_order":{"anyOf":[{"$ref":"#/components/schemas/OnOrder"},{"type":"null"}],"description":"Found fresh when you order: we look up phones and emails at order time, and how many we expect to find on this page. Absent when every record on the page already carries a phone or an email."}},"type":"object","required":["data","has_more","next_since","window","runs"],"title":"LeadFeed","description":"New leads. Follow ``next_cursor`` until ``has_more`` is false, keep\n``next_since``, and pass it as ``since`` on your next poll."},"LeadList":{"properties":{"type":{"type":"string","const":"list","title":"Type","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Lead"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"},"next_step":{"anyOf":[{"$ref":"#/components/schemas/NextStep"},{"type":"null"}],"description":"Present when the page is empty: where to go next."},"on_order":{"anyOf":[{"$ref":"#/components/schemas/OnOrder"},{"type":"null"}],"description":"Found fresh when you order: we look up phones and emails at order time, and how many we expect to find on this page. Absent when every record on the page already carries a phone or an email."}},"type":"object","required":["data","has_more"],"title":"LeadList","description":"A page of leads. Follow ``next_cursor`` until ``has_more`` is false."},"ListRequest":{"properties":{"states":{"items":{"type":"string"},"type":"array","maxItems":10,"minItems":1,"title":"States","description":"Two-letter state codes."},"filters":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Filters","description":"The /v1/leads filter grammar. At least one filter: a whole state on its own is not a list."},"lane":{"type":"string","enum":["all","best","contact"],"title":"Lane","description":"all: every record that names a person. best: the best-reachable first. contact: only records with a phone or email."},"cap":{"anyOf":[{"$ref":"#/components/schemas/Cap"},{"type":"null"}],"description":"Buy fewer: a record count or a budget. None = the whole list."},"channel":{"anyOf":[{"type":"string","enum":["phone","email"]},{"type":"null"}],"title":"Channel","description":"Buy one way to reach the owner: a record counts as reachable only by this channel."},"include_existing":{"type":"boolean","title":"Include Existing","description":"Widen past businesses that just started (moved in, new trade names, ...).","default":false},"max_cost_cents":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Max Cost Cents","description":"Refuse (402 budget_exceeded) if this could charge more. Nothing is written."}},"additionalProperties":false,"type":"object","required":["states","lane"],"title":"ListRequest","description":"The list to price or buy: the same shape the buy page and /v1/leads use."},"LiveState":{"properties":{"type":{"type":"string","const":"state","title":"Type","default":"state"},"code":{"type":"string","title":"Code","description":"Two-letter code — what `state` and `states` take."},"name":{"type":"string","title":"Name"},"run_day":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Day","description":"The day its latest completed loading run finished (US Central date); null when none in 60 days."},"run_completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Completed At","description":"When that run finished (ISO 8601, UTC)."}},"type":"object","required":["code","name","run_day","run_completed_at"],"title":"LiveState","description":"A state we carry, and when its records last landed."},"Me":{"properties":{"type":{"type":"string","const":"api_key","title":"Type","default":"api_key"},"key_id":{"type":"string","title":"Key Id"},"mode":{"type":"string","title":"Mode","description":"live · test. Test keys never charge; until the synthetic sandbox opens they read the same masked previews as anonymous callers. Extensible enum: new values may appear — treat unknown values as valid."},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes","description":"What this key may do. Extensible enum: new values may appear — treat unknown values as valid."},"declared_use":{"type":"string","title":"Declared Use","description":"The permissible use declared when the key was issued. Extensible enum: new values may appear — treat unknown values as valid."},"rate_limit_per_min":{"type":"integer","title":"Rate Limit Per Min"},"version_pin":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version Pin","description":"The API version this key is pinned to, if any."}},"type":"object","required":["key_id","mode","scopes","declared_use","rate_limit_per_min","version_pin"],"title":"Me","description":"The calling key — never its secret."},"NextStep":{"properties":{"label":{"type":"string","title":"Label"},"action":{"type":"string","title":"Action","description":"What the step does. Extensible enum: new values may appear — treat unknown values as valid."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"}},"type":"object","required":["label","action"],"title":"NextStep","description":"What to do next — the list interpreter's ``{label, action, url}`` shape."},"OnOrder":{"properties":{"type":{"type":"string","const":"on_order","title":"Type","default":"on_order"},"headline":{"type":"string","title":"Headline"},"promise":{"type":"string","title":"Promise"},"records_to_look_up":{"type":"integer","title":"Records To Look Up","description":"Records on this page with no phone and no email yet — the ones the forecast covers."},"expected_found_share":{"type":"number","title":"Expected Found Share","description":"Share of those records we expect to find a phone or email for (0–1), measured on comparable records we have already looked up."},"expected":{"type":"string","title":"Expected","description":"The forecast in one sentence."},"basis":{"type":"string","title":"Basis","description":"Where the forecast comes from."},"billing":{"type":"string","title":"Billing","description":"What finding costs: the phone-or-email price only where one is found."}},"type":"object","required":["headline","promise","records_to_look_up","expected_found_share","expected","basis","billing"],"title":"OnOrder","description":"What happens to a page's phones and emails when you order: we look them up\nfresh, and this is how many we expect to find."},"Order":{"properties":{"type":{"type":"string","const":"order","title":"Type","default":"order"},"id":{"type":"string","title":"Id"},"status":{"type":"string","title":"Status","description":"awaiting_payment · paid · delivered · expired · failed · refunded. Extensible enum: new values may appear — treat unknown values as valid."},"checkout_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Checkout Url","description":"Where a person pays (Stripe). Present while the order awaits payment."},"quote":{"$ref":"#/components/schemas/Quote"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["id","status","quote"],"title":"Order","description":"An order for a list. Pay at `checkout_url`; the file is emailed and readable\nthrough /v1/leads (access `owned`) once it is paid."},"OrderRequest":{"properties":{"states":{"items":{"type":"string"},"type":"array","maxItems":10,"minItems":1,"title":"States","description":"Two-letter state codes."},"filters":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Filters","description":"The /v1/leads filter grammar. At least one filter: a whole state on its own is not a list."},"lane":{"type":"string","enum":["all","best","contact"],"title":"Lane","description":"all: every record that names a person. best: the best-reachable first. contact: only records with a phone or email."},"cap":{"anyOf":[{"$ref":"#/components/schemas/Cap"},{"type":"null"}],"description":"Buy fewer: a record count or a budget. None = the whole list."},"channel":{"anyOf":[{"type":"string","enum":["phone","email"]},{"type":"null"}],"title":"Channel","description":"Buy one way to reach the owner: a record counts as reachable only by this channel."},"include_existing":{"type":"boolean","title":"Include Existing","description":"Widen past businesses that just started (moved in, new trade names, ...).","default":false},"max_cost_cents":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Max Cost Cents","description":"Refuse (402 budget_exceeded) if this could charge more. Nothing is written."},"expected_total_cents":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Expected Total Cents","description":"The quote's total_cents. If the total has moved, 409 quote_changed — never a different charge."},"price_rule_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Price Rule Version","description":"The quote's price_rule_version, checked the same way."}},"additionalProperties":false,"type":"object","required":["states","lane"],"title":"OrderRequest"},"PriceGrade":{"properties":{"type":{"type":"string","const":"price_grade","title":"Type","default":"price_grade"},"grade":{"type":"string","title":"Grade","description":"name_address · one_channel · both. Extensible enum: new values may appear — treat unknown values as valid."},"label":{"type":"string","title":"Label"},"unit_cents":{"type":"integer","title":"Unit Cents"},"ships":{"items":{"type":"string"},"type":"array","title":"Ships","description":"What a record billed at this grade carries."}},"type":"object","required":["grade","label","unit_cents","ships"],"title":"PriceGrade"},"Pricing":{"properties":{"type":{"type":"string","const":"pricing","title":"Type","default":"pricing"},"currency":{"type":"string","title":"Currency"},"price_rule_version":{"type":"integer","title":"Price Rule Version"},"billing_rule":{"type":"string","title":"Billing Rule"},"grades":{"items":{"$ref":"#/components/schemas/PriceGrade"},"type":"array","title":"Grades"},"lanes":{"items":{"type":"string"},"type":"array","title":"Lanes","description":"How a capped list picks its records. Extensible enum: new values may appear — treat unknown values as valid."},"channel_scopes":{"items":{"type":"string"},"type":"array","title":"Channel Scopes","description":"Buy for one channel only. Extensible enum: new values may appear — treat unknown values as valid."}},"type":"object","required":["currency","price_rule_version","billing_rule","grades","lanes","channel_scopes"],"title":"Pricing"},"Quote":{"properties":{"type":{"type":"string","const":"quote","title":"Type","default":"quote"},"records":{"type":"integer","title":"Records","description":"Records you would buy — each names a person. Only these are billed."},"total_cents":{"type":"integer","title":"Total Cents","description":"Charged when you pay."},"max_charge_cents":{"type":"integer","title":"Max Charge Cents","description":"The most this order can charge. Above total_cents only when some records are checked for a phone or email after you pay; what is found is billed at grade, never above this."},"currency":{"type":"string","title":"Currency","default":"usd"},"lane":{"type":"string","title":"Lane","description":"all · best · contact. Extensible enum: new values may appear — treat unknown values as valid."},"channel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channel","description":"phone · email, when the order is for one way to reach the owner."},"price_rule_version":{"type":"integer","title":"Price Rule Version"},"lines":{"items":{"$ref":"#/components/schemas/QuoteLine"},"type":"array","title":"Lines"}},"type":"object","required":["records","total_cents","max_charge_cents","lane","price_rule_version","lines"],"title":"Quote","description":"What a list costs today. Counts and prices are live; send `expected_total_cents`\nwith the order to be refused rather than charged if either moves."},"QuoteLine":{"properties":{"grade":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Grade","description":"name_address · one_channel · both. Extensible enum: new values may appear — treat unknown values as valid."},"label":{"type":"string","title":"Label","description":"The grade in the buyer's words, as the file and receipt print it."},"count":{"type":"integer","title":"Count"},"unit_cents":{"type":"integer","title":"Unit Cents"},"total_cents":{"type":"integer","title":"Total Cents"},"ships":{"items":{"type":"string"},"type":"array","title":"Ships","description":"What a record at this grade carries."}},"type":"object","required":["grade","label","count","unit_cents","total_cents"],"title":"QuoteLine","description":"One grade on a quote: how many records, at what per-record price, and what each carries."},"StateList":{"properties":{"type":{"type":"string","const":"list","title":"Type","default":"list"},"data":{"items":{"$ref":"#/components/schemas/LiveState"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","default":false}},"type":"object","required":["data"],"title":"StateList"},"Problem":{"description":"RFC 9457 problem details, plus a stable ``code`` to branch on.","properties":{"type":{"title":"Type","type":"string"},"title":{"title":"Title","type":"string"},"status":{"title":"Status","type":"integer"},"detail":{"title":"Detail","type":"string"},"code":{"description":"Stable machine-readable error code. Extensible enum: new values may appear — treat unknown values as valid.","title":"Code","type":"string"},"param":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Param"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Request Id"},"next_step":{"anyOf":[{"$ref":"#/components/schemas/NextStep"},{"type":"null"}],"default":null}},"required":["type","title","status","detail","code"],"title":"Problem","type":"object"}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your API key (gl_live_… or gl_test_…) as `Authorization: Bearer <key>`."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"The same key in an `X-API-Key` header, for clients that cannot set Authorization."}},"responses":{"InvalidParameter":{"description":"invalid_parameter · invalid_version — `param` names what to fix.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Problem":{"description":"Any error, as problem+json — branch on `code`: invalid_parameter · invalid_version · unauthorized · invalid_api_key · budget_exceeded · forbidden_scope · not_found · method_not_allowed · idempotency_key_reused · rate_limited · internal_error · not_available · quote_changed · no_match · order_too_large · idempotency_key_in_use · live_key_required · order_not_paid · use_not_permitted · link_expired · link_used. A route without a key requirement still refuses a key that is not valid (401 invalid_api_key).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"servers":[{"url":"/v1"}]}