# Reverse lookup API

Turn an email address or a website into the people and product behind it: founder names, their other emails, socials, the product, its launches (Product Hunt, BetaList, AppSumo and more) and verified contact emails. Plain HTTPS, JSON out.

Available on the Pro and Ultimate plans.

## 1. Create an API key

Open **[API keys](https://founderdb.co/app/api)** in the app, name the key (e.g. "CRM enrichment") and copy it. It starts with `fdb_` and is shown **once** — only a hash is stored. Lost it? Revoke it and make another.

Keep keys server-side. Anyone with the key can spend your quota.

## 2. Send the key with every request

Either header works:

```
Authorization: Bearer fdb_your_key
x-api-key: fdb_your_key
```

Base URL: `https://founderdb.co/api/v1`

## Look up an email

`GET /lookup/email?email=jane@acme.com`

```bash
curl -s "https://founderdb.co/api/v1/lookup/email?email=jane@acme.com" \
  -H "Authorization: Bearer $FOUNDERDB_KEY"
```

```json
{
  "data": {
    "email": "jane@acme.com",
    "found": true,
    "people": [
      {
        "id": "…",
        "name": "Jane Doe",
        "username": "janedoe",
        "avatar": "https://…",
        "bio": "Building Acme",
        "emails": [{ "email": "jane@acme.com", "source": "website", "status": "safe", "safeToSend": true }],
        "socials": [{ "type": "linkedin", "url": "https://linkedin.com/in/janedoe" }],
        "productIds": ["…"]
      }
    ],
    "products": [
      {
        "id": "…",
        "name": "Acme",
        "tagline": "Invoices that chase themselves",
        "website": "https://acme.com",
        "emails": [{ "email": "hello@acme.com", "source": "website", "status": "safe", "safeToSend": true }],
        "socials": [{ "type": "twitter", "url": "https://x.com/acme" }],
        "launches": [{ "platform": "producthunt", "launchedAt": "2026-10-24T00:00:00.000Z", "url": "https://www.producthunt.com/posts/acme", "upvotes": 312 }],
        "makers": [{ "name": "Jane Doe", "role": "maker", "emails": [], "socials": [] }]
      }
    ]
  }
}
```

`found: false` with empty lists means we don't know that address.

## Look up a domain

`GET /lookup/domain?domain=acme.com` — a bare domain or any URL (`?domain=https://www.acme.com/pricing` works too).

```bash
curl -s "https://founderdb.co/api/v1/lookup/domain?domain=acme.com" \
  -H "x-api-key: $FOUNDERDB_KEY"
```

Returns `{ "data": { "domain": "acme.com", "found": true, "products": [ … ] } }` — the same product shape as above, with its makers and contact emails.

## Email status

Each email carries `status` from verification: `safe` (deliverable), `catch_all`, `role_account` (info@, hello@), `unknown`, `invalid`, `disabled`, or `unverified`. `safeToSend` is the short answer.

## Usage and limits

- 60 requests a minute and 5,000 a day per key.
- `GET /usage` shows a key's calls in the last minute and 24 hours.
- Over a limit you get `429` with `Retry-After` (seconds).

## Errors

Errors are JSON: `{ "error": { "code": "invalid_email", "message": "…" } }`.

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `invalid_email` / `invalid_domain` | The parameter is missing or malformed. |
| 401 | `missing_api_key` / `invalid_api_key` | No key, a wrong key, or a revoked one. |
| 403 | `plan_required` | The account isn't on Pro or Ultimate. |
| 429 | `rate_limited` / `daily_limit` | Slow down; see `Retry-After`. |
| 500 | `internal_error` | Our side — retry shortly. |

## Examples

JavaScript:

```js
const res = await fetch(
  `https://founderdb.co/api/v1/lookup/email?email=${encodeURIComponent(email)}`,
  { headers: { Authorization: `Bearer ${process.env.FOUNDERDB_KEY}` } }
);
const { data } = await res.json();
```

Python:

```python
import os, requests
r = requests.get(
    "https://founderdb.co/api/v1/lookup/domain",
    params={"domain": "acme.com"},
    headers={"x-api-key": os.environ["FOUNDERDB_KEY"]},
)
print(r.json()["data"])
```