TypeScript / JavaScript SDK for Node.js

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 BlitzAPI. 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. Retries, client-side rate limiting per endpoint and auto-pagination are built in.

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 BlitzAPI 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 seven list methods (search.people, search.companies, search.employee_finder, jobs.search, jobs.company, company.tam_by_jobs, company.tam_by_people) 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);
}

// Best-fit decision-makers (up to `max_results`) via a priority cascade (returned directly).
const match = await client.search.waterfall_icp({
  company_linkedin_url: "https://www.linkedin.com/company/openai",
  cascade: [
    // No `location`: both tiers search the whole world.
    { include_title: ["CTO", "VP Engineering"], include_headline_search: false },
    { include_title: ["Engineering Director", "Engineering Manager"], 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);
}

// Companies whose current employees match a persona (deduplicated), each with `matched_people`, its count of matching current positions.
for await (const match of client.company.tam_by_people({
  people: { job_level: ["VP", "Director"], job_function: ["Engineering"], min_per_company: 2 },
  company: { industry: { include: ["Software Development"] } },
  max_results: 50,
  max_items: 200,
})) {
  console.log(match.company?.name, match.matched_people);
}

`client.enrichment`

// LinkedIn profile URL -> full person profile with the whole career (1 record when found).
const profile = await client.enrichment.person({ person_linkedin_url: "https://www.linkedin.com/in/example-person" });
if (profile.found && profile.person) {
  for (const job of profile.person.experiences) {
    console.log(job.job_title, job.company_name, job.job_is_current);
  }
}

// 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 -> mobile or 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, company.tam_by_people) 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, with 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 how each result counts as a record.

Usage & rate limit

Every metered /v2 response carries a fair_usage block reporting the records the request used 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);                 // records left until the next reset
console.log(usage?.next_reset_at);                     // when the record count resets
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);

Only the public changelog.list(), which is not metered, doesn’t return the block. account.key_info() returns it with records_used at 0 and no rate_limit, since that endpoint is not rate limited. 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,
  InsufficientRecordsError,
  NotFoundError,
  RateLimitError,
  ServerError,
} from "blitz-api-js";

try {
  await client.enrichment.email({ person_linkedin_url: "..." });
} catch (err) {
  if (err instanceof InsufficientRecordsError) {
    // 402: Fair Use record limit reached; err.fair_usage?.next_reset_at
  } else if (err instanceof AuthenticationError) {
    // 401: missing or invalid key, or an endpoint outside the key's allowed_apis
  } 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). A 401 with a valid key means the endpoint is not in the key’s allowed_apis (“You do not have access to this route”); read allowed_apis from client.account.key_info(). FairUsageLimitError is still exported as a deprecated alias of InsufficientRecordsError (the same class, not a subclass) and is scheduled for removal in 4.0.0, so existing instanceof checks keep working for now; err.name is already "InsufficientRecordsError". 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