TypeScript / JavaScript SDK - BlitzAPI - The API Engine for every GTM Playbook

Agents & LLMs: a Markdown version of this page is available by appending .md to the URL, and the full documentation index is at llms.txt.

blitz-api-js is the official, typed TypeScript SDK for the Blitz API. It is fetch-based, Zod-validated, ships both ESM and CommonJS builds with .d.ts / .d.cts types, and uses snake_case request and response fields that match the API reference exactly.

npm

blitz-api-js on the npm registry.

GitHub

Source, changelog, and issues.

Install

npm install blitz-api-js
# or: pnpm add blitz-api-js  /  yarn add blitz-api-js

Requires Node.js 20+ (or any runtime with a global fetch). Ships both ESM and CommonJS builds.

Quickstart

import { BlitzAPI } from "blitz-api-js";

// api_key defaults to the BLITZ_API_KEY environment variable.
const client = new BlitzAPI();

// Health-check the key before a batch job.
const info = await client.account.key_info();
console.log(info.valid, info.records_remaining, info.max_requests_per_seconds);

// LinkedIn profile URL -> verified work email.
const email = await client.enrichment.email({
  person_linkedin_url: "https://www.linkedin.com/in/example-person",
});
if (email.found) console.log(email.email);

// Search people — list methods are paginated; one page's items live on `.data`.
const page = await client.search.people({
  company: { industry: { include: ["Software Development"] } },
  people: { job_level: ["VP"] },
  max_results: 10,
});
for (const person of page.data) {
  console.log(person.full_name, person.headline);
}

CommonJS works too:

const { BlitzAPI } = require("blitz-api-js");

Authentication

Pass the key explicitly or via the BLITZ_API_KEY environment variable. It is sent in the x-api-key header on every request.

const explicit = new BlitzAPI({ api_key: "sk_..." }); // explicit
const fromEnv = new BlitzAPI();                        // reads BLITZ_API_KEY

Never expose your API key in client-side code (browsers, mobile apps). Always call Blitz from your backend.

Endpoints

All methods are grouped into seven namespaces. Each takes a single options object (snake_case keys) and returns a typed, Zod-validated response. The six list methods (search.people, search.companies, search.employee_finder, jobs.search, jobs.company, company.tam_by_jobs) return a paginated PagePromise (see Pagination); waterfall_icp, changelog.list, and the enrichment / utils / account methods return their response directly.

`client.account`

const info = await client.account.key_info();
console.log(info.valid, info.records_remaining, info.max_requests_per_seconds);
console.log(info.allowed_apis);

`client.search`

// People across many companies (cursor-paginated — see Pagination below).
const people = await client.search.people({
  company: {
    industry: { include: ["IT Services and IT Consulting"] },
    employee_range: ["51-200", "201-500"],
    hq: { sales_region: ["EMEA"] },
  },
  people: {
    job_level: ["VP", "Director"],
    job_function: ["Sales & Business Development"],
    min_connections: 200,
  },
  max_results: 25,
});
for (const person of people.data) {
  console.log(person.full_name, person.headline, person.linkedin_url);
}

// Companies by ICP (cursor-paginated).
const companies = await client.search.companies({
  company: {
    keywords: { include: ["SaaS"] },
    industry: { include: ["Software Development"] },
    hq: { country_code: ["FR", "DE"] },
    employee_range: ["51-200", "201-500"],
  },
  max_results: 25,
});
for (const company of companies.data) {
  console.log(company.name, company.industry, company.employees_on_linkedin);
}

// All employees at one company (page-paginated).
const employees = await client.search.employee_finder({
  company_linkedin_url: "https://www.linkedin.com/company/openai",
  job_level: ["C-Team", "VP", "Director"],
  job_function: ["Sales & Business Development"],
  sales_region: ["NORAM"],
  max_results: 50,
});
console.log(`Page ${employees.response.page} of ${employees.response.total_pages}`);
for (const person of employees.data) {
  console.log(person.full_name, person.headline);
}

// Single best decision-maker via a priority cascade (returned directly).
const match = await client.search.waterfall_icp({
  company_linkedin_url: "https://www.linkedin.com/company/openai",
  cascade: [
    { include_title: ["CTO", "VP Engineering"], location: ["WORLD"], include_headline_search: false },
    { include_title: ["Engineering Director", "Engineering Manager"], location: ["WORLD"], include_headline_search: false },
  ],
  max_results: 5,
});
for (const item of match.results) {
  console.log(`[Tier ${item.icp} | Rank #${item.ranking}]`, item.person.full_name);
}

`client.jobs`

// Live job postings across companies (cursor-paginated — see Pagination below).
const jobs = await client.jobs.search({
  job: {
    title: { include: ["Head of Sales"] },
    seniority: { include: ["5-10"] },
    employment_type: { include: ["FULL_TIME"] },
    work_arrangement: { include: ["Hybrid", "Remote OK"] },
    date_posted: { last_days: 30 },
  },
  company: {
    industry: { include: ["Software Development"] },
    size: { include: ["51-200", "201-500"] },
  },
  max_results: 25,
});
for (const job of jobs.data) {
  console.log(job.company_name, job.title, job.location?.city);
}

// Postings at one company (cursor-paginated).
const companyJobs = await client.jobs.company({
  company_linkedin_url: "https://www.linkedin.com/company/openai",
  job: { field: { include: ["Software Engineering"] } },
  max_results: 25,
});
for (const job of companyJobs.data) {
  console.log(job.title, job.url);
}

`client.company`

// Companies hiring for a role (deduplicated), each with its matching-posting count.
for await (const match of client.company.tam_by_jobs({
  job: { title: { include: ["Account Executive"] }, min_per_company: 3 },
  company: { industry: { include: ["Software Development"] } },
  max_results: 50,
  max_items: 200,
})) {
  console.log(match.company?.name, match.matched_jobs);
}

`client.enrichment`

// LinkedIn profile URL -> verified work email.
const email = await client.enrichment.email({ person_linkedin_url: "https://www.linkedin.com/in/example-person" });
if (email.found) console.log(email.email);

// LinkedIn profile URL -> direct phone (US only).
const phone = await client.enrichment.phone({ person_linkedin_url: "https://www.linkedin.com/in/example-person" });
if (phone.found) console.log(phone.phone);

// Work email -> full person profile.
const byEmail = await client.enrichment.email_to_person({ email: "jane.doe@acme.com" });
if (byEmail.found) console.log(byEmail.person.full_name);

// Phone number -> full person profile (US only).
const byPhone = await client.enrichment.phone_to_person({ phone: "+14155551234" });
if (byPhone.found) console.log(byPhone.person.full_name);

// Company LinkedIn URL -> full company profile.
const company = await client.enrichment.company({ company_linkedin_url: "https://www.linkedin.com/company/openai" });
console.log(company.company.name, company.company.industry, company.company.employees_on_linkedin);

// Website domain -> Company LinkedIn URL.
const toLinkedin = await client.enrichment.domain_to_linkedin({ domain: "openai.com" });
if (toLinkedin.found) console.log(toLinkedin.company_linkedin_url);

// Company LinkedIn URL -> email domain.
const toDomain = await client.enrichment.linkedin_to_domain({ company_linkedin_url: "https://www.linkedin.com/company/openai" });
if (toDomain.found) console.log(toDomain.email_domain);

// Company employees grouped by country.
const byCountry = await client.enrichment.company_distribution_by_country({
  company_linkedin_url: "https://www.linkedin.com/company/openai",
});
for (const row of byCountry.distribution) {
  console.log(row.country, row.count, row.percentage_ratio);
}

// Company employees grouped by department.
const byDepartment = await client.enrichment.company_distribution_by_department({
  company_linkedin_url: "https://www.linkedin.com/company/openai",
});
for (const row of byDepartment.distribution) {
  console.log(row.department, row.count, row.percentage_ratio);
}

`client.utils`

// Current server date/time.
const now = await client.utils.current_date();

`client.changelog`

// Public API changelog, newest first. No API key required, and not paginated.
const entries = await client.changelog.list({ days: 30, limit: 10 });
for (const entry of entries) console.log(entry.date, entry.type, entry.title);

Pagination

The list methods (search.people, search.companies, search.employee_finder, jobs.search, jobs.company, company.tam_by_jobs) return a PagePromise — await it for the first page, or for await to stream every item across all pages (each fetched on demand).

// Stream every match across all pages — no cursor handling needed.
for await (const person of client.search.people({ people: { job_level: ["VP"] } })) {
  console.log(person.full_name);
}

See Pagination for max_items, .collect(), manual paging, page metadata, and the per-result billing caveat.

Usage & rate limit

Every metered /v2 response carries a fair_usage block reporting what the request cost and what is left, so you can meter a batch job without a second key_info() call.

const email = await client.enrichment.email({ person_linkedin_url: "https://www.linkedin.com/in/example-person" });
const usage = email.fair_usage;
console.log(usage?.records_used);                      // records this request consumed
console.log(usage?.records_remaining);                 // a number, or "unlimited"
console.log(usage?.next_reset_at);                     // null on an unlimited plan
console.log(usage?.rate_limit?.remaining_this_second); // calls left this second
console.log(usage?.request_id);                        // quote this id to support

// On a paginated method the block belongs to each page's raw body.
const page = await client.search.people({ people: { job_level: ["VP"] }, max_results: 50 });
console.log(page.response.fair_usage?.records_used);

Two endpoints don’t return the block: the public changelog.list(), which is not metered, and account.key_info(), which reports the balance in its own top-level records_remaining, next_reset_at, and max_requests_per_seconds fields. Every field is optional, so a response predating the block still parses.

Configuration

const client = new BlitzAPI({
  api_key: undefined,   // falls back to BLITZ_API_KEY
  base_url: "https://api.blitz-api.ai",
  timeout: 30,          // default per-request timeout, seconds (via AbortSignal.timeout)
  max_retries: 3,       // retries on 429 / 5xx / pre-response network errors
  rate_limit_rps: 5,    // client-side token bucket, per endpoint; null to disable
  fetch: undefined,     // custom fetch implementation (tests / runtimes)
});

// Override the timeout for a single call — pass an options object as the last argument:
await client.enrichment.email({ person_linkedin_url: "..." }, { timeout: 5 });

A single client instance stays under your per-endpoint request-per-second limit and retries automatically on 429; see Rate limits & retries. rate_limit_rps defaults to 5; set it to your key’s max_requests_per_seconds to use your plan’s full per-endpoint throughput.

Error handling

import {
  APIConnectionError,
  APIResponseValidationError,
  APIStatusError,
  APITimeoutError,
  AuthenticationError,
  BlitzError,
  FairUsageLimitError,
  NotFoundError,
  RateLimitError,
  ServerError,
} from "blitz-api-js";

try {
  await client.enrichment.email({ person_linkedin_url: "..." });
} catch (err) {
  if (err instanceof FairUsageLimitError) {
    // 402: Fair Use record limit reached; err.fair_usage?.next_reset_at
  } else if (err instanceof AuthenticationError) {
    // 401 — bad key
  } else if (err instanceof APIResponseValidationError) {
    // 2xx, but the body wasn't valid JSON or didn't match the schema
  } else if (err instanceof APIStatusError) {
    console.log(err.status_code, err.message, err.body, err.request_id);
  } else if (err instanceof BlitzError) {
    // base class for everything this SDK raises
  }
}

401 / 402 / 404 throw immediately; 429 and 5xx are retried automatically; timeouts surface as APITimeoutError (not retried). InsufficientCreditsError is still exported as a deprecated alias of FairUsageLimitError (the same class, not a subclass), so existing instanceof checks keep working. See Rate limits & retries for the full retry and timeout behavior. A 400 or 422 also throws immediately, as APIStatusError. For a 422, err.body.errors lists each invalid field as { field, message }; see Errors. The API rejects any field it does not define, so an extra key in a params object returns a 422 even when TypeScript does not flag it.

Types & enums

Response objects keep their snake_case wire keys and preserve unknown fields — if the API adds a property before this SDK models it, the value is still present (typed as unknown); known fields stay precisely typed.

import { INDUSTRY } from "blitz-api-js";              // the full value array (534 industries)
import type { CompanyFilter, Industry } from "blitz-api-js";

Enum-backed filter fields (e.g. industry, job_level, continent) accept a known value — autocompleted from a union like Industry — or any raw string, so a value missing from the vendored taxonomy never blocks you.

Next steps

Python SDK

The same API surface with sync + async clients.

Field Normalization

Accepted values for industry, job level, job function, and geography filters.

API reference

Full request/response schemas and an interactive try-it console.

Recipes

End-to-end workflows: build an ICP list, enrich it, and sync to your CRM.

npm

GitHub

​Install

​Quickstart

​Authentication

​Endpoints

​client.account

​client.search

​client.jobs

​client.company

​client.enrichment

​client.utils

​client.changelog

​Pagination

​Usage & rate limit

​Configuration

​Error handling

​Types & enums

​Next steps

Python SDK

Field Normalization

API reference

Recipes

Install

Quickstart

Authentication

Endpoints

`client.account`

`client.search`

`client.jobs`

`client.company`

`client.enrichment`

`client.utils`

`client.changelog`

Pagination

Usage & rate limit

Configuration

Error handling

Types & enums

Next steps