Lusha

Lusha

This connector calls the Lusha API v3 (https://api.lusha.com) with the user's own API key: contact and company search by identifier, prospecting with ICP filters, enrichment of chosen records, contact and company signals, enrichment jobs and account usage. It never changes data in Lusha.

Personal data: B2B use only. Contact records describe real people: names, job titles, employers, work and private email addresses and mobile or direct phone numbers. Use them only for a legitimate business purpose the user can justify (for example B2B sales or recruiting under legitimate interest), in line with the GDPR, CAN-SPAM and similar laws, and with Lusha's terms. Keep only what is needed, respect doNotCall on phone numbers and isEuContact, and never pull contact data in bulk or build a mass mailing list. Do not look up private individuals. Lusha itself withholds some records for legal reasons (COMPLIANCE_RESTRICTED, HTTP 451).

Credits: look first, reveal only what the user picked. Every Lusha call that returns records spends credits from the account's pool; only the helpers are free. Prices depend on the plan: lusha_get_account_usage returns the balance and a pricing map (credits per action, for example api_search, reveal_company, email, phone).

• Free: lusha_get_account_usage (at most 5 calls a minute), lusha_list_filters, lusha_get_filter_values, lusha_list_signal_types, lusha_get_enrich_job.
• Small charge per result found (api_search, nothing for NOT_FOUND): lusha_search_contacts, lusha_search_companies, lusha_prospect_contacts, lusha_prospect_companies. They return previews without emails or phones, plus canReveal with the credit cost of each field. Keep size small.
• Costs more credits: lusha_enrich_contacts (per revealed email and per revealed phone; a phone is usually the most expensive), lusha_enrich_companies (per company), lusha_get_contact_signals and lusha_get_company_signals (per matched signal). Before any call that costs credits, tell the user what you will run, for how many records, and what it can cost, and wait for their yes. Reveal only the fields the user needs (reveal: ["emails"] is cheaper than emails and phones).

Setup (about 2 minutes)

1. Sign in to Lusha with an account that has API access. Only account admins and managers with API access can see the API page.
2. Open API, Manage API Keys (https://dashboard.lusha.com/api/manage-api-keys) and create or copy a key.
3. Paste it into LUSHA_API_KEY. It is sent as the api_key header and only to api.lusha.com.

Workflow

• Known people: lusha_search_contacts with ids, LinkedIn URLs, emails or first name, last name and company; known companies: lusha_search_companies with names or domains.
• New prospects: lusha_list_filters and lusha_get_filter_values for valid values (seniority ids, departments, industries, sizes, locations, technologies), then lusha_prospect_contacts or lusha_prospect_companies.
• After the user picks records: lusha_enrich_contacts or lusha_enrich_companies with the Lusha id values (up to 100). If an enrichment returns a job, wait job.retryAfter seconds and read it with lusha_get_enrich_job.
• Timing: lusha_list_signal_types, then lusha_get_contact_signals (promotions, company changes) or lusha_get_company_signals (hiring surges, headcount, traffic, news, intent).

Rate limits: 25 requests a second per account by default, plus hourly and daily quotas by plan; the usage endpoint allows 5 a minute. On 429 wait and retry once.

Common errors (statusCode, message, errors)

• 401: the API key is wrong, revoked or missing.
• 402: the account has no credits left.
• 403: the account is inactive or the plan lacks a feature (for example excludeDnc).
• 400: a filter value or parameter is invalid; errors names it.
• 451: Lusha cannot return this person for legal reasons.
• 429: rate limit. Wait and retry once.
• Per record, a 200 can still carry error.code NOT_FOUND, COMPLIANCE_RESTRICTED or ENRICH_FAILED.

Out of scope here: search-and-enrich in one call (it skips the user's confirmation step), lookalikes, buying groups, scoring, website visits, tables, webhooks, CRM export, conversations and the legacy v2 endpoints (/v2/person, /prospecting/...).