How do I Perform a Person Lookup Using the RocketReach API?

The RocketReach API allows you to retrieve contact details, including email addresses, phone numbers, and social media links, for professionals based on their name, company, LinkedIn URL, or other identifiers. This guide explains how to perform a person lookup and retrieve contact information.

Key Takeaways

Person Lookup returns verified contact details such as emails, phone numbers, and social media links.
Lookup credits are deducted only when contact information is successfully retrieved.
You can perform lookups using a name, company, LinkedIn URL, or profile ID.
Lookups may take time to process, so you may need to check the status before retrieving results.
API Lookups charge lookup/export credits for verified contact information retrieved.
Bulk lookups are available for retrieving multiple profiles at once.

What Is a Person Lookup?

A person lookup allows you to retrieve a professional’s contact information using one or more identifiers such as:

Name and company (e.g., "John Doe at Google")
LinkedIn URL (e.g., "https://www.linkedin.com/in/johndoe")
Profile ID (Returned from a previous search)

Once a lookup is requested, RocketReach will search for the best-matching contact details and return them.

How to Lookup a Person Using Name and Company

To perform a person lookup, send a request to the /api/v2/person/lookup endpoint with a name and current employer.

Example: Lookup by Name and Company

curl --request GET --location 'https://api.rocketreach.co/api/v2/person/lookup' \
     --header 'Api-Key: YOUR_API_KEY' \
     --data-urlencode 'name=John Doe' \
     --data-urlencode 'current_employer=Google'

✅ If the person exists in RocketReach's database, their contact information will be returned.
❌ If no matching profile is found, lookup credits are not deducted.

How to Lookup a Person Using LinkedIn URL

If you have a LinkedIn profile URL, you can perform a lookup directly.

Example: Lookup by LinkedIn URL

curl --request GET --location 'https://api.rocketreach.co/api/v2/person/lookup' \
     --header 'Api-Key: YOUR_API_KEY' \
     --data-urlencode 'linkedin_url=https://www.linkedin.com/in/johndoe'

This method is highly accurate and often returns better results than name-based lookups.

How to Lookup a Person Using Profile ID

If you previously performed a search query, you might already have a Profile ID. Using this ID allows for faster lookups.

Example: Lookup by Profile ID

curl --request GET --location 'https://api.rocketreach.co/api/v2/person/lookup' \
     --header 'Api-Key: YOUR_API_KEY' \
     --data-urlencode 'id=12345'

This will return full contact details for the profile with ID 12345.

Understanding Person Lookup Responses

If the lookup is successful, you’ll receive the following details:

Professional emails (e.g., johndoe@google.com)
Personal emails (e.g., johndoe@gmail.com)
Phone numbers (if available)
Social media links (LinkedIn, Twitter, etc.)

Example API Response

{
  "id": 12345,
  "name": "John Doe",
  "current_title": "Software Engineer",
  "current_employer": "Google",
  "linkedin_url": "https://www.linkedin.com/in/johndoe",
  "emails": [
    {
      "email": "johndoe@google.com",
      "type": "professional",
      "grade": "A",
      "last_validation_check": "2024-02-01"
    },
    {
      "email": "johndoe@gmail.com",
      "type": "personal",
      "grade": "A",
      "last_validation_check": "2024-02-01"
    }
  ],
  "phones": [
    {
      "number": "+1-555-123-4567",
      "type": "mobile"
    }
  ]
}

✔ Email Grades: Contact details come with a validation grade (A-F) to indicate their accuracy.
✔ Last Validation Date: Shows when the email was last verified.

How to Check the Status of a Person Lookup

If a lookup takes time to process, you can check its status before retrieving contact information.

Example: Check Lookup Status

curl --request GET --location 'https://api.rocketreach.co/api/v2/person/checkStatus' \
     --header 'Api-Key: YOUR_API_KEY' \
     --data-urlencode 'ids=12345'

Possible statuses include:

"complete" – The lookup is finished, and data is available.
"searching" – The lookup is still in progress.
"failed" – The lookup could not be completed.

Bulk Lookup: Retrieving Multiple Contacts at Once

If you need to retrieve contact details for multiple people, use the bulk lookup API.

Example: Bulk Lookup Request

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/janesmith" }
       ]
     }'

Bulk lookups require at least 10 profiles per request.
Up to 100 profiles can be retrieved in a single request.
You must set up a webhook to receive bulk lookup results.

Common Errors and Troubleshooting

Error Code	Description	Solution
401 Unauthorized	Missing or invalid API key.	Ensure your API key is correct.
404 Not Found	No matching profile found.	Try refining the search parameters.
429 Too Many Requests	Rate limit exceeded.	Reduce request frequency or upgrade your plan.
500 Internal Server Error	Unexpected API issue.	Retry after a few seconds.

Next Steps

Now that you know how to perform a Person Lookup, here’s what you can do next:

Webhooks– Automate lookup retrieval without polling the API.
Rate Limits – Understand usage restrictions and avoid throttling.
API Errors – Resolve common API issues.