lusha

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=[e-mail]

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:

1. Get available filters
2. Search with filters
3. 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=[e-mail]"

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.