How do I Perform Bulk Lookups Using the RocketReach API?

Bulk lookups allow you to retrieve contact information for multiple people in a single API request, reducing the number of API calls and improving efficiency. This guide explains how to use the bulk lookup feature, set up webhook notifications, and troubleshoot common issues.

Key Takeaways

Bulk lookups allow up to 100 profile lookups per request.
A minimum of 10 lookups per request is required.
You must enable webhooks to receive results for bulk lookups.
Bulk lookup results are sent asynchronously to your webhook URL.
If a lookup fails, you will not be charged a lookup or export credit.
API rate limits apply—ensure you do not exceed them.

What is a Bulk Lookup in RocketReach API?

A bulk lookup is an API request that retrieves contact details for multiple people at once. Instead of making separate requests for each person, you can send a batch request containing multiple queries and receive results in a single response.

Why use bulk lookup?

Improves efficiency by reducing API calls
Reduces request latency compared to multiple individual lookups
Minimizes rate limit impact by grouping lookups into a single request

How to Perform a Bulk Lookup

Step 1: Enable a Webhook

RocketReach sends bulk lookup results asynchronously via webhooks. You must configure a webhook before using bulk lookup.

Go to RocketReach API Usage & Settings from your Account Settings
Navigate to the Webhooks section
Click Create Webhook
Enter the URL of your server where webhook notifications should be sent
Click Create

Learn More: How Do I Use Webhooks in the RocketReach API?

Step 2: Send a Bulk Lookup Request

Your bulk lookup request must include a list of people to search for, using at least one of the following parameters:

LinkedIn URL
RocketReach Profile ID
Full name and current employer
Email address (lower success rate)

Example: Bulk Lookup API Request (cURL)

curl --request POST --location 'https://api.rocketreach.co/api/v2/person/bulkLookup' \
     --header 'Api-Key: YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
         "queries": [
             {"name": "John Doe", "current_employer": "Google"},
             {"linkedin_url": "https://www.linkedin.com/in/janedoe"},
             {"profile_id": 123456}
         ],
         "profile_list": "API Bulk Lookup",
         "webhook_id": 98765
     }'

🚀 Once the lookup is complete, the results will be sent to your webhook URL.

Step 3: Process Webhook Response

When the bulk lookup completes, RocketReach sends the results to your webhook as a JSON payload. Your server should parse this response to extract contact information.

Example Webhook Response:

{
  "bulk_lookup_id": "abc123",
  "results": [
    {
      "id": 9876,
      "name": "John Doe",
      "current_title": "Software Engineer",
      "current_employer": "Google",
      "emails": [{"email": "johndoe@gmail.com", "type": "personal"}],
      "linkedin_url": "https://www.linkedin.com/in/johndoe"
    },
    {
      "id": 6543,
      "name": "Jane Doe",
      "current_title": "Marketing Manager",
      "current_employer": "Microsoft",
      "emails": [{"email": "janedoe@microsoft.com", "type": "work"}],
      "linkedin_url": "https://www.linkedin.com/in/janedoe"
    }
  ]
}

✅ Your system should store or process this data accordingly.

Best Practices for Bulk Lookups

To optimize bulk lookup performance, follow these recommendations:

Batch similar lookups together – Try to group searches by industry, company, or region.
Use LinkedIn URLs for higher accuracy – Lookups using LinkedIn profiles have a better match rate than name-based searches.
Ensure your webhook is active – If RocketReach cannot send results, your bulk lookup may fail.
Monitor your API rate limits – Exceeding limits may result in throttling (HTTP 429 errors).

Common Bulk Lookup Errors and Solutions

Error Code	Description	Solution
400 Bad Request	Missing required parameters.	Ensure your request includes a minimum of 10 lookups and at least one valid query parameter.
403 Forbidden	API key is invalid or lacks permissions.	Verify that your API key is correct and has bulk lookup access.
404 Not Found	Webhook ID not found.	Ensure you have created and enabled a webhook before submitting a bulk lookup request.
429 Too Many Requests	Rate limit exceeded.	Reduce request frequency or upgrade to a higher API plan.
500 Internal Server Error	Issue with RocketReach API.	Retry the request after a few minutes or contact support@rocketreach.co.