Reference & Standards
Endpoint index, country codes, data logic, and performance details.
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.
Endpoint Method Description Plan /v2/account/key-infoGETCheck API key validity and rate limit Any /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 level Leads+ /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 email Email+ /v2/enrichment/phonePOSTLinkedIn profile URL → phone number (US only ) Phone /v2/enrichment/email-to-personPOSTWork email → full person profile Leads+ /v2/enrichment/phone-to-personPOSTPhone number → full person profile Leads+ /v2/enrichment/companyPOSTCompany LinkedIn URL → full company profile Leads+ /v2/enrichment/domain-to-linkedinPOSTWebsite domain → Company LinkedIn URL Leads+ /v2/enrichment/linkedin-to-domainPOSTCompany LinkedIn URL → verified email domain Leads+ /v2/utils/current-datePOSTGet current server date/time for a timezone Any
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.
Common Country Codes List
📧 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
Identity Matching : We match the LinkedIn profile against a massive dataset of known, verified identities.No Permutations : We only return an email if we have a concrete record of it linked to that specific individual.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:
Concurrency : All plans include 5 concurrent requests per second (RPS). Use the max_requests_per_seconds field from /v2/account/key-info to get your exact 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 Type Recommended Timeout Waterfall ICP, Employee Finder, Find People, Company Search 10 seconds Email/Phone Validation 20 seconds Enrichment (email, phone, company) 10 seconds
Error Codes: Code Meaning Solution 401Unauthorized Missing or invalid x-api-key header. 402Payment Required Account limit reached. Upgrade your plan. 404Not Found API key does not exist. 429Too Many Requests Exceeded rate limit. Implement client-side rate limiting (max 5 RPS). 500Internal Server Error Transient server error. Retry with exponential backoff.
