Skip to main content

​
Reference & Standards

Endpoint index, country codes, data logic, and performance details.
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.
This section covers technical standards and logic details to help you build reliable integrations with BlitzAPI.

​
📋 Endpoint Index

All v2 endpoints at a glance. Base URL: https://api.blitz-api.ai. All endpoints use POST except key-info.
EndpointMethodDescriptionPlan
/v2/account/key-infoGETCheck API key validity and rate limitAny
/v2/search/waterfall-icp-keywordPOSTFind decision-makers via cascade hierarchy (cached data, <600ms)Leads+
/v2/search/employee-finderPOSTSearch employees at one company by role and seniority levelLeads+
/v2/search/peoplePOSTSearch people across many companies (company + person filters)Leads+
/v2/search/companiesPOSTFind companies by filters (industry, size, location, keywords)Leads+
/v2/enrichment/emailPOSTLinkedIn profile URL → verified work emailEmail+
/v2/enrichment/phonePOSTLinkedIn profile URL → phone number (US only)Phone
/v2/enrichment/email-to-personPOSTWork email → full person profileLeads+
/v2/enrichment/phone-to-personPOSTPhone number → full person profileLeads+
/v2/enrichment/companyPOSTCompany LinkedIn URL → full company profileLeads+
/v2/enrichment/domain-to-linkedinPOSTWebsite domain → Company LinkedIn URLLeads+
/v2/enrichment/linkedin-to-domainPOSTCompany LinkedIn URL → verified email domainLeads+
/v2/enrichment/company-distribution-by-countryPOSTCompany LinkedIn URL → employee distribution by countryLeads+
/v2/enrichment/company-distribution-by-departmentPOSTCompany LinkedIn URL → employee distribution by departmentLeads+
/v2/utils/current-datePOSTGet current server date/time for a timezoneAny
Search endpoints require a Company LinkedIn URL as input (not a domain). If you only have a domain, use /v2/enrichment/domain-to-linkedin first.

​
🌍 Country Codes (LinkedIn)

All BlitzAPI search endpoints use 2-letter country codes following the ISO 3166-1 alpha-2 standard (consistent with LinkedIn). Using the wrong format (e.g., USA instead of US) will return 0 results. See the Field Normalization reference for the full list.
Use "WORLD" to search globally without geographic restriction.
CountryCode
United StatesUS
United KingdomGB
FranceFR
CanadaCA
GermanyDE
AustraliaAU
IndiaIN
BrazilBR
SingaporeSG
For a full list of supported codes, refer to the Microsoft LinkedIn Documentation.

​
📧 Email Logic: Matching vs. Guessing

A common misconception is that enrichment APIs “guess” emails (permutations like first.last@domain.com). BlitzAPI does not do this.

​
How we work

  1. Identity Matching: We match the LinkedIn profile against a massive dataset of known, verified identities.
  2. No Permutations: We only return an email if we have a concrete record of it linked to that specific individual.
  3. Freshness Guarantee:
  • We do not serve stale data.
  • Every email in our database is re-validated at least once every 30 days.
  • If an email bounces during our internal checks, it is immediately removed from the circulation.
This approach ensures a significantly lower bounce rate compared to “pattern-matching” tools.

​
🚦 Rate Limits & Latency

To ensure stability for all users:
  • Rate limit: All plans include 5 requests per second, per endpoint (RPS) — each endpoint has its own independent budget, so calls to /enrichment/email and /enrichment/phone don’t compete. Use the max_requests_per_seconds field from /v2/account/key-info to get your exact per-endpoint limit.
  • Burst: Short bursts above the limit may be queued, but sustained overage returns 429 Too Many Requests.
  • Retry on 429: Wait at least 60 seconds before retrying after a server-side 429. Client-side rate limiting should prevent this.
Recommended Client Timeouts:
Endpoint TypeRecommended Timeout
Waterfall ICP, Employee Finder, Find People, Company Search10 seconds
Email/Phone Validation20 seconds
Enrichment (email, phone, company)10 seconds
Error Codes:
CodeMeaningSolution
401UnauthorizedMissing or invalid x-api-key header.
402Payment RequiredAccount limit reached. Upgrade your plan.
404Not FoundAPI key does not exist.
429Too Many RequestsExceeded an endpoint’s rate limit. Implement client-side rate limiting (max 5 RPS per endpoint).
500Internal Server ErrorTransient server error. Retry with exponential backoff.