lusha - SKILL.md Agent Skill

name: lusha description: Comprehensive Lusha API integration for B2B contact and company data. Use when agents need to enrich contacts, search for prospects, get company information, track signals (job changes, promotions, company events), find lookalikes, or set up webhooks for real-time notifications. Covers all Lusha API endpoints including person/company enrichment, prospecting search, signals, lookalikes, webhooks, and account management.

Lusha API

Complete API integration for Lusha's B2B sales intelligence platform. Access contact enrichment, company data, prospecting search, signals tracking, lookalikes, and webhooks.

Authentication

All requests require an API key in the api_key header:

curl -H "api_key: YOUR_API_KEY" https://api.lusha.com/v2/person?email=example@company.com

Get your API key from: https://dashboard.lusha.com/enrich/api

Rate Limits

General: 25 requests/second per endpoint
Credit Usage API: 5 requests/minute
Monitor via response headers: x-rate-limit-*, x-*-requests-left, x-*-usage

Base URL

https://api.lusha.com

API Categories

1. Enrichment

Enrich existing contact or company records with missing data.

Endpoints:

GET /v2/person - Enrich single contact
POST /v2/person - Bulk enrich contacts (up to 100)
GET /v2/company - Enrich single company
POST /bulk/company/v2 - Bulk enrich companies (up to 100)

See: references/enrichment.md for full details and examples.

2. Prospecting - Search & Enrich

Query Lusha's database to find new contacts and companies matching your ICP.

Three-step process:

Get available filters
Search with filters
Enrich results

See: references/prospecting.md for filters, search, and enrichment.

3. Signals

Track job changes, promotions, company growth, and business events.

Available signal types:

Contact: promotion, companyChange, allSignals
Company: headcountGrowth, newJobsOpen, newsEvent, allSignals

See: references/signals.md for all signal endpoints.

4. Lookalikes

Find similar contacts and companies using AI recommendations.

Endpoints:

POST /api/recommendations/contacts - Similar contacts
POST /api/recommendations/companies - Similar companies

See: references/lookalikes.md for details.

5. Webhooks 🆕

Real-time notifications for contact and company signals.

Features:

HMAC-SHA256 signature verification
Bulk subscription management (up to 25/request)
Automatic URL verification

See: references/webhooks.md for setup and payload formats.

6. Filters

Get available filter values for prospecting searches.

See: references/filters.md for all filter endpoints.

7. Account Management

Endpoint:

GET /account/usage - Get credit usage stats

Error Handling

Standard HTTP codes:

200 - Success
400 - Bad request
401 - Invalid API key
402 - Payment required
403 - Forbidden / account inactive
404 - Not found
429 - Rate limit exceeded
451 - GDPR restriction
5XX - Server error

Error format:

{
  "error": {
    "code": 400,
    "message": "Invalid request parameters"
  }
}

Quick Examples

Enrich a contact:

curl -H "api_key: YOUR_KEY" \
  "https://api.lusha.com/v2/person?email=john@example.com"

Search for contacts:

curl -X POST -H "api_key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": {"jobTitle": "CEO"}, "limit": 10}' \
  "https://api.lusha.com/prospecting/contact/search"

Get contact signals:

curl -X POST -H "api_key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contactIds": ["123456"], "signalTypes": ["promotion", "companyChange"]}' \
  "https://api.lusha.com/api/signals/contacts"

Important Notes

Unified Credits Plan: revealEmails and revealPhones parameters only available on Unified Credits plan (403 error on other plans)
GDPR: EU contacts may return 451 error
Credits: Most endpoints charge credits per successful result
Bulk Operations: Max 100 items per request for bulk endpoints

Need More Details?

Read the appropriate reference file for comprehensive endpoint documentation, parameters, and response schemas.