GoodLeads API

Which API for what

GoodLeads has two read surfaces over the same records. Pick the one that fits your job.

Why /v1 lists fewer fields: /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.

Which way in fits which client

There are three ways in. They give the same records and the same counts. Do you want to set up an AI agent, not write code? Read the setup guide.

Start from your job

• Pick a job: GET /v1/jobs lists the jobs. Each job says why GoodLeads fits, with ready filters and a link to the new businesses that fit. For web design, use GET /v1/jobs/web_design.
• Or say it in your words: GET /v1/answers?q=businesses that need insurance returns the answer, ready filters and a free count.
• Why it works: These businesses are days old. Most have no website, bank account or insurance yet. They are in no directory or sales database. You can be the first to reach them.

Start in four calls

1. Get your keys

   Enter your email. You get a test key and a live key. Get your keys.

2. See today’s new businesses

   You need no key. Owner details stay hidden until you buy.

3. Price it

   A free quote shows the count, the total, and the most the order can cost.

4. Buy it

   Use your live key and a new Idempotency-Key. You get a checkout link. After you pay, read the records with GET /v1/orders/{order_id}/records.

Get API keys

Send it as

Add Authorization: Bearer gl_live_… to every call.

Keep it

Keep it on your server. Never put it in a browser, an app, a web address or a log.

Limits

Live key 120 calls a minute, test key 60, no key 30. A 429 response says how long to wait.

Allowed uses

You can use the data for sales, marketing, CRM, research, and building it into a product. We refuse credit, employment, insurance and tenant screening.

Lost a key?

Ask for a new link above. To switch off an old key, email hello@goodleads.club.

What you bought

A read of a record you bought shows the owner’s details as your purchase shipped them. You can download your records again at any time.

What you can do

Coming next: standing orders from your code, notifications to your server when new records land, practice orders with made-up records and billing to an account.

Standing orders on the website. Set it up from your first order's receipt. The first delivery goes out when delivery opens.

Do you prefer to click, not code? Buy a list on the website. You get the same records at the same prices.

Size a market by industry and place

This is free. You need no key, and contact details stay masked. Counts start from just-started businesses and show when we computed them. Widen the filter to widen the market.

• By industry. Look up the same industry in four code systems: NAICS, SIC, Google category and MCC. Start from the system your buyer uses. The crosswalk does this. GET /api/v1/crosswalk?q=MCC%205812 returns the codes in the other three systems, our own industry, a ready filter for each, and a live count.
• By place. You can also size a market by place: metro, county, city, ZIP, neighborhood, time zone and tract income.
• Both at once. group_by takes up to two fields. One call can split industry by place, or by address type. Address type has more than two values: residential, commercial and others. Each value has its own count.
• Read the answer. “Records that fit” is every record that matches your filters, and the reply field matching counts them. “Named-owner records” are the ones whose filing names a person. You pay only for those, and the reply field sellable counts them. The industry lookup and the main count run separately, so they can differ by a few records. Use the main count when you give a number.
• Classification. Our pipeline builds the industry label from the filing, and the label improves with every run. A record that we have not classified yet reads Unclassified and appears last. A count by industry, NAICS or MCC is a minimum. It can only grow.

Two calls. First translate an industry. Then count it and split it by residential or commercial address:

curl -G "https://app.goodleads.club/api/v1/crosswalk" --data-urlencode "q=MCC 5812"

curl -G "https://app.goodleads.club/api/v1/counts" \
  --data-urlencode 'filters=[{"field":"mcc","op":"eq","value":"5812"}]' \
  --data-urlencode "group_by=property_classification"

The same group_by works in a JSON body with POST /api/v1/leads/summary. Read the guides: /counts.llms.txt and /crosswalk.llms.txt.

Filter values are forgiving. Case, spacing and plurals do not matter. Everyday words work: cell means mobile, CST means every Central time-zone zone, and Texas means TX. Working from home means a residential address. Every answer carries interpreted_values, the values we understood. For a value we could not place, the answer also carries value_hints, the closest real values.

Keep a daily sync

• First pull: Send window=today, or 5d, 7d, 15d, 30d or 60d. “Today” means each state’s latest finished run.
• More pages: Follow next_cursor until has_more is false.
• Next morning: Send the next_since you saved as since. Each new business arrives one time only.
• What “new” means: A business formed in the last 60 days. The runs field in every answer shows which run each state’s records came from.

Filters

A filter is a JSON list of {"field", "op", "value"}. Every item in the list must match. To group items, use {"op": "or", "filters": [...]}.

[
  {"field": "industry_sector", "op": "eq", "value": "construction"},
  {"field": "has_phone", "op": "eq", "value": true},
  {"op": "or", "filters": [
    {"field": "principal_city", "op": "eq", "value": "Tampa"},
    {"field": "principal_city", "op": "eq", "value": "Orlando"}
  ]}
]

• Find every field, operator and allowed value with GET /v1/fields or in the data dictionary. GET /v1/states lists the live states and their latest run.
• Not sure which filters fit? Describe what you sell in plain words. Send POST /api/v1/lists/interpret with {"text": "I sell payroll software to new restaurants in Florida"} and you get the filters back.
• You can filter on 49 fields here (52 with a key). The website schema (GET /api/v1/schema/attributes) lists 85. The public API leaves out the owner's name, phone and email. These stay hidden until you buy. Where both list a field, the name, operators and values are the same. The full list, with the ways in for each field, is at /capabilities.json.
• You cannot filter on the owner’s name, phone or email. They stay hidden until you buy.
• A misspelled field or value gives an error that names the closest match. We never drop a filter silently.

Limits

• Calls a minute. Live key 120 calls a minute, test key 60, no key 30. Over the limit, you get a 429 response with a Retry-After header. The header gives the seconds to wait.
• Page size. The default is 25. The maximum is 100 (25 without a key). Follow next_cursor for more.
• Filter size. A filter can have up to 4000 characters, 4 levels of nesting and 25 conditions.
• Time. The server stops a read after 10 seconds. It stops a count over the website API after 8. Narrow the filter and ask again.
• Without a key on the website API. You get 30 calls a minute and 25 records a page.
• Checkout. The limit is 5 calls a minute.
• Wrong keys. The limit is 20 failed attempts a minute.
• The source of truth. We generate these numbers from the code that enforces them. Read /capabilities.llms.txt, or the JSON file /capabilities.json.

Partners and resellers

This section is for CRMs, directories, marketplaces and agents that want every new business on the day it exists. It describes what is in place today.

• Say what you are building. When you get keys, choose “Building it into a product” (platform_integration). We refuse these uses for every key: credit eligibility, employment screening, insurance underwriting, tenant screening.
• The terms. The site terms (§10 API terms) are the API terms. API access is for your own internal use. Do not resell or proxy API responses. Do not build a competing client. Do not exceed the rate limits.
• Partnering beyond that. Anything past your own internal use needs an agreement. This includes reselling records, redistributing them, and embedding them for your customers. Write to hello@goodleads.club.
• Plans. We agree terms for each account.

Errors

Every error has a stable code and a request_id to quote to us. Many errors also have a next_step. Use code in your logic, not the wording.

New codes can appear. If you do not know a code, use its HTTP status.

Versions

• Choose a version with the header GoodLeads-Version: 2026-10-01. Without the header, your key stays on the version it first used.
• We only add: new fields, new values and new optional inputs. Ignore what you do not recognize.
• A change that could break your code ships as a new dated version, with advance notice.

For AI agents

• No-key tools: https://mcp.goodleads.club/mcp gives search, count, price and a payment link from Claude, ChatGPT, Cursor and more.
• Quick start: /llms.txt lists the calls, in order.
• Spend safely: Prices and quotes are free to read. max_cost_cents caps any order.
• Recover from errors: Read code and follow next_step.

API reference

The full contract is /v1/openapi.json (OpenAPI 3.1). Import it into Postman or generate a client.

Every endpoint:

Try it