blitz-api

Blitz API

Base https://api.blitz-api.ai, header x-api-key. Spec: https://docs.blitz-api.ai/api-reference/v2.openapi.json (index at /llms.txt). Check your plan and allowed routes with GET /v2/account/key-info before a big run.

Endpoints worth knowing

Endpoint	Use
POST /v2/search/companies	Company search over ~66M companies
POST /v2/search/people	People search, filterable by company and person fields
POST /v2/search/employee-finder	Every employee at one company_linkedin_url
POST /v2/jobs/search	Job postings, filterable by recency (job.date_posted.last_days)
POST /v2/jobs/company	Postings at one company
POST /v2/company/tam-by-jobs	Companies sized by who is hiring for what
POST /v2/enrichment/email	person_linkedin_url to work email
POST /v2/enrichment/domain-to-linkedin	Domain to company LinkedIn URL (use for exact account matching)
POST /v2/enrichment/company-distribution-by-department	Headcount by department (how big is their GTM team, really)
POST /v2/search/waterfall-icp-keyword	Ordered title tiers; tier N+1 runs only if tier N is empty

The traps (each one cost us a day)

1. Unknown filter keys return 200 and filter nothing. A typo reads as a 66-million-company market. Real filters are nested under company, people, or job. Always compare the filtered total_results against the unfiltered total and fail loudly if it did not drop.
2. max_results is the page size. per_page, limit, and page_size are accepted and ignored (you get 10). The cap is 50; 100 is a 422. Pagination is cursor only. page, offset, and from are silently ignored, so a page loop re-fetches page 1 forever and reports success.
3. The filter shape is inconsistent. Most keys take {"include": [...], "exclude": [...]}. These take plain arrays: employee_range, hq.country_code, hq.continent, hq.sales_region, company.linkedin_url, people.job_function, people.job_level. These take {"min","max"}: founded_year, employee_count, revenue, web_traffic, ad_spend, total_funding.
4. To learn the real schema, send the wrong type, not the wrong key. A wrong key is silent; a wrong type 422s and names the expected shape.
5. industry is a strict enum that does not match returned labels. Some labels that appear on records are rejected as filters. One bad value 422s the whole request and names the index, not the string. Validate each industry value on its own before shipping a segment.
6. Name and title matching is full-text. company.name: "Check" returns Check Point employees; on one real run 64% of returned people worked at a company we never asked for. job_title: "President" matches "Vice President of Client Services". Bracket for exact match ("[CEO]"), and when you know the account, filter on company.linkedin_url (exact) instead of name. Re-check every returned person's company_linkedin_url against the account you requested.
7. Funding, revenue, traffic, and ad spend are filter-only. You can target on them but they never come back in the payload. Anything you need to store or cite has to come from another provider.
8. employee_count and size disagree. employee_count filters observed LinkedIn headcount; size is the self-reported band shown in results. Expect about 20% of a pull to sit outside the band you asked for.
9. Search returns the current role only. No tenure history. Education and skills do come back.
10. Email enrichment is not a job-change check. Recent leavers still resolve to their old employer's address with found: true, because the source is LinkedIn's current-company field.
11. Job posting counts lie. matched_jobs counts postings, not roles. One company showed 146 GTM roles that were two titles reposted across cities. Re-score on distinct titles before ranking anyone on hiring volume. Gate geography on company.hq, not job.location (job country codes are unreliable).
12. The waterfall catch-all leaks. With include_headline_search: true, a loose tier grabs whoever sounds senior. Bracket full titles in any tier that also searches headlines.

Minimal client

import json, os, subprocess

BASE = "https://api.blitz-api.ai"

def call(path, body, timeout=60):
    """Returns (status, parsed). Uses curl so an exception never prints the key."""
    cmd = ["curl", "-s", "--max-time", str(timeout), "-w", "\n%{http_code}",
           "-X", "POST", BASE + path,
           "-H", "x-api-key: " + os.environ["BLITZ_API_KEY"],
           "-H", "Content-Type: application/json", "-d", json.dumps(body)]
    out = subprocess.run(cmd, capture_output=True, text=True).stdout
    text, _, code = out.rpartition("\n")
    return int(code or 0), (json.loads(text) if text.strip() else {})

def search_all(path, body, limit=500):
    body = {**body, "max_results": 50}
    rows, cursor = [], None
    while len(rows) < limit:
        if cursor:
            body["cursor"] = cursor
        status, data = call(path, body)
        if status != 200:
            raise RuntimeError(f"{status}: {data}")
        batch = data.get("results") or []
        rows += batch
        cursor = data.get("cursor")
        if not batch or not cursor:
            break
    return rows[:limit]

Example: recent job postings for a title

rows = search_all("/v2/jobs/search", {
    "job": {"title": {"include": ["GTM Engineer"]}, "date_posted": {"last_days": 30}},
}, limit=1000)
# Dedupe on (company_linkedin_url, normalized title) before counting anything.

Before you trust a run

• The filtered total dropped versus the unfiltered baseline.
• The first page's records actually match the filters you sent (eyeball five).
• People were re-checked against the requested company_linkedin_url.
• Counts are on distinct roles or distinct companies, not raw postings.