LeadVault Data API

Audience sizing for your own product. Ask how many people match a brief and show the number to your users. The API returns counts only: no names, emails, phones, companies or profiles ever come back through it. Anyone who wants the people themselves creates a LeadVault account and reveals them there.

Request a key

Keys are issued by the LeadVault team, usually within one working day. A key is shown once when it is created; keep it server-side and never in a browser or mobile app.

Count people

GET /v1/count?title=VP%20Finance&country=United%20States&employees=500%2B
Authorization: Bearer lv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
  "count": 38412,
  "filters": {"title": ["VP Finance"], "similar_titles": true, "location": ["United States"], "employees": ["501-1,000", "1,001-2,000", "2,001-5,000", "5,001-10,000", "10,001+"]},
  "contacts_included": false,
  "reveal_url": "https://leadvaultlabs.com/?signup=1",
  "took_ms": 212
}

Ask in plain English (Genie)

Skip the filter vocabulary: send the sentence your user typed and Genie works out the filters, counts, and returns both. Pass the previous answer's filters back with a follow-up ("only 500+ staff") to refine the same audience.

POST /v1/ask
{"question": "How many directors of marketing at software and technology companies in the US?"}

{
  "count": 61240,
  "summary": "Directors of Marketing at software and technology companies in the United States",
  "filters": {"title": "director of marketing", "industry": ["Computer software", "IT & services", "Internet"], "country": ["United States"]},
  "filters_readable": [{"label": "Titles", "value": "director of marketing"}, …],
  "contacts_included": false
}

GET /v1/ask?q=... works too. A sentence that does not describe an audience returns 422 with a hint.

Break a count down

The same filters, split by one dimension so you can draw a chart: by=seniority, department, employees or country.

GET /v1/breakdown?by=seniority&department=finance&country=United%20States&employees_min=501

{
  "count": 412903,
  "by": "seniority",
  "rows": [{"value": "vp", "label": "VP", "count": 38412}, {"value": "director", "label": "Director", "count": 91277}, …],
  "contacts_included": false
}

Filters

GET /v1/filters returns the full vocabulary, including every industry name, as JSON. GET /v1/me returns your key's allowance and usage today.

Errors

{"detail": {"code": "bad_filter", "message": "seniority 'boss' not recognised. See /v1/filters."}}

Examples

curl

curl -s "https://leadvaultlabs.com/v1/count?title=VP%20Finance&country=United%20States&employees=500%2B" \
  -H "Authorization: Bearer $LEADVAULT_KEY"

Python

import requests
r = requests.get("https://leadvaultlabs.com/v1/count",
                 params={"title": "VP Finance", "country": "United States", "employees": "500+"},
                 headers={"Authorization": f"Bearer {KEY}"})
print(r.json()["count"])

JavaScript (server side)

const u = new URL("https://leadvaultlabs.com/v1/count");
u.search = new URLSearchParams({title: "VP Finance", country: "United States", employees: "500+"});
const r = await fetch(u, {headers: {Authorization: `Bearer ${process.env.LEADVAULT_KEY}`}});
console.log((await r.json()).count);

Fair use

Keys are for building audience-sizing features into your own product. Do not share a key between companies, proxy the API publicly, or probe with thousands of narrow filter combinations to reconstruct records; keys that do are revoked. Usage is metered per key and visible to the administrator who issued it.