Skip to main content

Blitz API Reference

Blitz API is the primary data source for attorney contact enrichment. It provides LinkedIn-based employee discovery, email lookup, and phone number retrieval across law firms.

API Configuration​

SettingValue
Base URLhttps://api.blitz-api.ai
Versionv2
Auth Headerx-api-key: {BLITZ_API_KEY}
Env VariableBLITZ_API_KEY (in .env)

Endpoints​

EndpointMethodCostPurpose
/v2/search/employee-finderPOST1 credit/resultFind employees by firm LinkedIn URL
/v2/enrichment/emailPOST1 credit if foundGet work email from personal LinkedIn URL
/v2/enrichment/phonePOST5 credits if foundGet mobile phone from personal LinkedIn URL
/api/blitz/key-infoGETFreeCheck remaining credits and plan details

Credit Costs Per Attorney​

StepCostCondition
Employee finder1 credit/resultAlways charged
Email enrichment1 creditOnly if email is found
Phone enrichment5 creditsOnly if phone is found
Typical total2--7 creditsPer attorney
Critical: Field Name Difference

Email and phone enrichment endpoints use person_linkedin_url (NOT linkedin_profile_url). Using the wrong field name causes 422 Unprocessable Entity errors with no helpful error message. This has been a recurring source of bugs.

Employee Finder​

Discovers employees at a company using the firm's LinkedIn company URL.

Request​

POST /v2/search/employee-finder
{
  "company_linkedin_url": "https://linkedin.com/company/kirkland-ellis",
  "job_function": ["Legal"],
  "limit": 100
}

Response Shape​

interface EmployeeFinderResponse {
  results: EmployeeResult[];
  total_results: number;
}

interface EmployeeResult {
  first_name: string;
  last_name: string;
  full_name: string;
  headline: string | null;
  about_me: string | null;
  location: {
    city: string;
    state_code: string;
    country_code: string;
    continent: string;
  };
  linkedin_url: string;
  connections_count: number | null;
  experiences: Experience[];
  education: Education[];
  skills: string[];
  certifications: string[];
}

interface Experience {
  job_title: string;
  company_linkedin_url: string;
  job_start_date: string | null;
  job_end_date: string | null;
  job_is_current: boolean;
  job_location: {
    city: string;
    state_code: string;
    country_code: string;
  } | null;
}

interface Education {
  degree: string | null;
  organization: string;
  end_date: string | null;
}

Key Notes​

  • job_function: ["Legal"] filters to legal staff, but results still include non-attorney roles (legal assistants, paralegals). Title filtering is required post-response.
  • limit maxes at 100. For large firms, multiple paginated calls may be needed.
  • The response includes full work history (experiences) and education, which the enrichment pipeline extracts into structured fields.

Email Enrichment​

Finds work email addresses from a LinkedIn profile URL.

Request​

POST /v2/enrichment/email
{
  "person_linkedin_url": "https://linkedin.com/in/john-doe"
}

Response​

{
  "success": true,
  "email": "[email protected]",
  "email_status": "valid",
  "source": "pattern_match"
}

Email Status Values​

The email_status field only accepts these values in the attorneys table:

StatusMeaning
validConfirmed deliverable
invalidBounced or known bad
catch_allDomain accepts all addresses (unverifiable)
unknownStatus could not be determined
No "unverified" Status

The email_status enum does not include "unverified". Attempting to insert this value causes a database constraint violation. Map any non-standard status values to unknown.

Phone Enrichment​

Finds mobile phone numbers from a LinkedIn profile URL.

Request​

POST /v2/enrichment/phone
{
  "person_linkedin_url": "https://linkedin.com/in/john-doe"
}

Response​

{
  "success": true,
  "phone": "+15551234567",
  "phone_type": "mobile"
}

Phone enrichment costs 5 credits per found number, making it the most expensive API call. The --skip-phone flag on the enrichment script omits this step.

Credit Check​

Request​

GET /api/blitz/key-info

Response​

{
  "remaining_credits": 4523,
  "plan": "pro",
  "rate_limit": "100/minute"
}

Always check credits before large enrichment runs. A full AmLaw 100 firm can consume 200--700 credits.

Error Handling​

HTTP StatusMeaningAction
200SuccessProcess response
400Bad requestCheck request body format
401UnauthorizedCheck BLITZ_API_KEY
422Unprocessable EntityLikely wrong field name (see warning above)
429Rate limitedBack off and retry
500Server errorRetry with exponential backoff

Usage in Client Portal​

Local Scripts​

The enrichment pipeline script (scripts/enrich-attorneys.ts) calls Blitz API directly using the BLITZ_API_KEY from .env. See Enrichment Pipeline for full details.

Edge Functions​

The blitz-enrich-attorney-contacts edge function provides on-demand enrichment of individual attorneys via the UI. It reads the API key from Supabase secrets.