Reveal a company

Spends one reveal from your monthly quota and returns the card with domain, website and contacts. Revealing the same company again in the same period is free, and charged says so.

POSThttps://findbytown.com/api/v1/businesses/{id}/revealSpends quota

Path parameters

Name	Type	Description
id(required)	integer	Company id, an integer.

JSON body (optional)

Name	Type	Description
locale	en \| fr \| es	Language of labels and category names: en, fr or es. Defaults to the language of your account.

Examples

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)

Response

Example with fake values:

{
  "data": {
    "id": 1001,
    "domain": "plumbing.example",
    "name": "Example Plumbing",
    "website": "https://plumbing.example/",
    "zone": "fr_idf",
    "zoneLabels": {
      "en": "Example Region",
      "fr": "Région Exemple",
      "es": "Región Ejemplo"
    },
    "country": "FR",
    "precision": "exact",
    "address": "1 Example Street",
    "city": "Exampleville",
    "quality": 80,
    "provider": "google",
    "providerDetail": "Google Workspace",
    "hasPhone": true,
    "contactsCount": 1,
    "otherEmailsCount": 0,
    "description": "Plumbing and heating repairs.",
    "logoUrl": null,
    "social": {},
    "openingHours": null,
    "activity": "Plumber",
    "categories": [
      "Heating contractor"
    ],
    "websiteTitle": null,
    "postalCode": "00000",
    "adminArea": "Example Region",
    "fullAddress": "1 Example Street, 00000 Exampleville",
    "mapsUrl": null,
    "rating": 4.6,
    "reviews": 25,
    "facts": null,
    "extraPhonesCount": 0,
    "primaryEmailMasked": "c•••@•••",
    "phoneMasked": "+33 1 •• •• •• 00",
    "revealed": true,
    "contact": {
      "email": "contact@plumbing.example",
      "otherEmails": [],
      "phone": "+33100000000",
      "extraPhones": [],
      "contacts": [
        {
          "fullName": "Alex Example",
          "title": "Manager",
          "email": "alex@plumbing.example"
        }
      ]
    }
  },
  "charged": true,
  "quota": {
    "used": 13,
    "allowance": 10000,
    "remaining": 9987,
    "resetAt": "2030-01-01T00:00:00.000Z"
  }
}

Errors

Code	HTTP status	Meaning
validation_error	400	A parameter is missing or has the wrong form. details names it.
bad_id	400	The company id is not a positive integer.
missing_api_key	401	No Authorization header, or an empty one.
invalid_api_key	401	The key does not exist or has been revoked.
quota_exhausted	402	No reveals left this period. details holds the reset date. Reading stays available.
plan_without_api	403	The account's current plan does not include the API. Applies from the moment a plan ends.
suspended	403	The account is suspended. Its keys start working again if the suspension is lifted.
not_found	404	No such company, or it was removed at its owner's request.
email_invalid	409	This company's email is marked invalid, so it cannot be revealed. Nothing was spent.
rate_limited	429	Too many requests this minute. Wait for the number of seconds in Retry-After.
blocked	429	Access to company data is temporarily paused because of automated use, such as walking through ids. Retry-After gives the time left. Write to support if this is a mistake.
internal_error	500	Something went wrong on our side. Quote requestId when writing to support.
reveals_unavailable	503	Reveals are briefly unavailable and nothing was spent. Try again shortly.

Back to findbytown