How to set up and use Lusha API for bulk contact enrichment

If you’re tired of manual data entry and want to actually use the contact info you’ve got, this guide’s for you. We’ll walk through setting up the Lusha API—warts and all—so you can enrich batches of contacts, not just one at a time. Whether you’re in sales ops, growth, or just sick of CSV hell, this is the no-fluff guide you need.

1. What is Lusha’s API (and why should you care)?

Lusha is a tool that fills in the blanks in your contact data—think work emails, phone numbers, company info. The Lusha API lets you automate this, instead of clicking around in their web app. If you want to enrich hundreds or thousands of leads at once, the API is the only way that doesn’t make you want to throw your laptop.

Use cases: - You’ve got a big list of LinkedIn URLs or work emails and want to fill in missing info. - You’re syncing data into a CRM and want it as complete as possible. - You’re running outbound campaigns and want to skip the “dear [first_name]” fails.

But here’s the catch: Lusha’s API is not unlimited. Their pricing and rate limits can get expensive fast. Don’t expect to build your own Clearbit overnight.

2. Get Access: Lusha API Key & Account Setup

Before you can make a single API call, you’ll need an account with API access—not all Lusha plans include this. Here’s what to do:

Step 1: Check Your Lusha Plan

  • Log in to your Lusha account.
  • Go to your account settings.
  • Look for an “API” or “Integrations” section.
  • If you don’t see it, you probably need to upgrade. Contact Lusha support for details. Don’t bother with workarounds; you’ll just waste time.

Step 2: Get Your API Key

  • In the API section, you’ll find your API key (sometimes called “API token”).
  • Copy it and keep it somewhere safe. Don’t share it. Anyone with this key can run up your bill or get you in compliance trouble.

Pro tip: You might only get one API key per account. Rotate it if you suspect it’s been compromised.

3. Understand Lusha’s API Limits (Before You Get Burned)

Before you start building, know what you’re working with. Lusha’s API is not built for massive, unlimited scraping.

  • Credits: Every API call costs credits. Bulk enrichment chews through them quickly.
  • Rate limits: Typically, Lusha limits you to a certain number of calls per minute/hour. Check their docs for your plan’s specifics.
  • Data coverage: Not every contact has a match. If you send 1,000 emails, don’t expect 1,000 results.

Bottom line: Always test with a small batch first. Don’t upload your entire database and hope for the best.

4. Set Up Your Environment

You’ll need some basics:

  • A tool to send HTTP requests (Postman, curl, or your own code).
  • A way to handle CSV or spreadsheet files.
  • Preferably, basic scripting skills (Python is a good bet).

You don’t need: A fancy integration platform or paid enrichment tools on top of Lusha. Keep it simple.

5. Make Your First Lusha API Call

Step 1: Read the API Docs

  • Lusha’s API docs are decent, but not perfect. Look for the “Person Enrichment” endpoint—that’s what you want for emails or LinkedIn URLs.
  • Bookmark the docs so you’re not constantly searching for field names.

Step 2: Test With a Single Contact (Don’t Skip This)

Here’s a basic example using Python and the requests library:

python import requests

API_KEY = 'YOUR_LUSHA_API_KEY' headers = { 'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json' }

payload = { "email": "someone@example.com" }

response = requests.post( 'https://api.lusha.com/person', headers=headers, json=payload )

print(response.json())

  • Replace YOUR_LUSHA_API_KEY and the email.
  • If you get a 200 OK and actual data, you’re set.
  • If you get an error, stop and fix it before moving on.

Common issues:

  • Wrong endpoint (double check the docs—Lusha changes URLs sometimes).
  • Missing or bad API key.
  • Invalid input (Lusha is picky about fields).

6. Prepare Your Contact List for Bulk Enrichment

You want a CSV or spreadsheet with a column for the identifier you’ll use—usually email, sometimes LinkedIn URL.

Format tips: - Stick to columns like email, linkedin_url, first_name, last_name (if you have them). - Clean up duplicates and junk data now. Lusha charges per API call—even for garbage.

Avoid: Uploading every field you can think of. Only enrich what you truly need.

7. Build a Simple Bulk Enrichment Script

You don’t need to build a whole web app. Here’s a basic approach in Python:

python import csv import requests import time

API_KEY = 'YOUR_LUSHA_API_KEY' headers = { 'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json' }

def enrich_contact(email): payload = {"email": email} r = requests.post('https://api.lusha.com/person', headers=headers, json=payload) if r.status_code == 200: return r.json() else: return {}

with open('input_contacts.csv', newline='') as infile, \ open('enriched_contacts.csv', 'w', newline='') as outfile: reader = csv.DictReader(infile) fieldnames = reader.fieldnames + ['lusha_phone', 'lusha_company'] writer = csv.DictWriter(outfile, fieldnames=fieldnames) writer.writeheader() for row in reader: data = enrich_contact(row['email']) row['lusha_phone'] = data.get('phone', '') row['lusha_company'] = data.get('company', '') writer.writerow(row) time.sleep(1) # Respect Lusha's rate limit

What this does: - Reads your input CSV row by row. - Calls Lusha’s API for each email. - Adds phone and company info (if found). - Writes out a new CSV.

A few warnings: - This code is dead simple—good for up to a few hundred contacts. - For thousands, you’ll need to add error handling, retries, and smarter rate limiting. - Don’t skip the time.sleep(1)—Lusha will ban you if you go too fast.

8. Handle Errors and Misses

Not every lookup will work. Lusha might return nothing, or partial data, or an error code.

What to do: - If you get a rate limit error (usually HTTP 429), pause and try again after a few minutes. - If you get empty results, don’t keep re-trying the same contact. It’s not going to magically appear. - Log failures separately so you can review them later.

9. Best Practices & What to Ignore

What works:

  • Start with a small batch—see what coverage you get before you burn through credits.
  • Enrich only what you need—don’t run every field “just in case.”
  • Always log your requests and results—so you can troubleshoot without guessing.

What doesn’t:

  • Don’t expect 100% match rates. Lusha’s coverage is good, but not magic.
  • Don’t build super complex automations before you know your real enrichment rates.
  • Don’t ignore privacy and compliance. You’re handling personal data—be smart.

What to ignore:

  • Ignore promises of “real-time” updates. Lusha’s data is as fresh as their sources; it’s not always up-to-the-minute.
  • Don’t get sucked into expensive add-ons you don’t need. The API is the main thing.

10. Wrapping Up: Keep It Simple, Iterate Fast

Bulk contact enrichment with Lusha’s API is more about process than tech wizardry. Start small, automate the boring stuff, and don’t outsmart yourself with over-engineering. The real value comes from getting reliable data, not from building the fanciest integration. Run a quick batch, see what works, and tweak as you go.

If you need more advanced features, try a few open-source libraries or simple workflow tools before shelling out for “premium” integrations. Most of the time, the basics get you 90% of the way there.

Good luck—and remember, sometimes the best automation is just a well-written script and a strong cup of coffee.