Quickstart
Your first API call in under five minutes: create a key, test it, search, then reveal.
1. Create a key
Open API keys in your account and create a key. It is shown once, so copy it straight away. If your plan does not include the API, the page tells you which plans do.
2. Test the key
This call spends nothing and tells you your plan and limits. Replace the example key with your own.
curl "https://findbytown.com/api/v1/quota" \
-H "Authorization: Bearer fbt_EXAMPLE_not_a_real_key_0000"const res = await fetch("https://findbytown.com/api/v1/quota", {
headers: { Authorization: "Bearer fbt_EXAMPLE_not_a_real_key_0000" },
});
const body = await res.json();
if (!res.ok) throw new Error(body.error);
console.log(body);import requests
res = requests.get(
"https://findbytown.com/api/v1/quota",
headers={"Authorization": "Bearer fbt_EXAMPLE_not_a_real_key_0000"},
)
body = res.json()
if not res.ok:
raise RuntimeError(body["error"])
print(body)3. Search
Find plumbers in France. Use /countries, /zones and /categories to find the values filters accept.
curl "https://findbytown.com/api/v1/businesses?country=FR&trade=plumber&perPage=1" \
-H "Authorization: Bearer fbt_EXAMPLE_not_a_real_key_0000"const res = await fetch("https://findbytown.com/api/v1/businesses?country=FR&trade=plumber&perPage=1", {
headers: { Authorization: "Bearer fbt_EXAMPLE_not_a_real_key_0000" },
});
const body = await res.json();
if (!res.ok) throw new Error(body.error);
console.log(body);import requests
res = requests.get(
"https://findbytown.com/api/v1/businesses?country=FR&trade=plumber&perPage=1",
headers={"Authorization": "Bearer fbt_EXAMPLE_not_a_real_key_0000"},
)
body = res.json()
if not res.ok:
raise RuntimeError(body["error"])
print(body)Rows come back with domain, website and contact set to null. This spends your daily budget of companies and no reveal quota.
4. Reveal a company
This call spends one reveal from your monthly quota. Check the cost first with GET /businesses/{id}/reveal if you are unsure.
curl -X POST "https://findbytown.com/api/v1/businesses/1001/reveal" \
-H "Authorization: Bearer fbt_EXAMPLE_not_a_real_key_0000"const res = await fetch("https://findbytown.com/api/v1/businesses/1001/reveal", {
method: "POST",
headers: { Authorization: "Bearer fbt_EXAMPLE_not_a_real_key_0000" },
});
const body = await res.json();
if (!res.ok) throw new Error(body.error);
console.log(body);import requests
res = requests.post(
"https://findbytown.com/api/v1/businesses/1001/reveal",
headers={"Authorization": "Bearer fbt_EXAMPLE_not_a_real_key_0000"},
)
body = res.json()
if not res.ok:
raise RuntimeError(body["error"])
print(body)The response holds the contacts and "charged": true. Run it again and you get the same data with "charged": false: nothing more is spent in the same period.
Next
- Handle errors by their stable
errorcode. - Respect the limits using the response headers.
- Use the same key from an MCP client.