Get Started
The RocketReach API allows you to programatically search & lookup contact info over 400 million professionals, and 6 million companies. We constantly work on improving functionality and accuracy of our data. RocketReach is free to try for individual use.
To get started, signup for a free account and create your own API Key absolutely free.
For all calls to the RocketReach API, you will need the an API key. Your unique API key is
Try it out!
Before we get any further, lets try a quick example.
E.g. To get Mark Benioff's contact info, you can call the /lookupProfile
endpoint …
Base URL
All URLs referenced in the documentation have the following base:
The RocketReach API is served over HTTPS. Unencrypted HTTP is currently supported, but highly discouraged, and maybe deprecated in the future.
Authentication
All API calls require an API key.
I.e when using your API key, your calls will always look as follows.
Your API key must be kept secret, and never exposed in publicly exposed source code, (or used directly in HTML/javascript within a browser). Anyone with access to your API key can make API calls on your behalf. If your API key has been compromised, please regenrate a new API key by going to the API section of your account page.
Need Help?
Need help? Have feedback/questions about usage, pricing? Talk to us live or Email us: support@rocketreach.co
Handling Errors
Normal responses are returned with HTTP status HTTP: 200
. Error responses return HTTP: 4xx/5xx
error codes.
E.g If the profile being searched for cannot be found, we will return a 404
.
Rate Limits (HTTP:429)
If we start receiving unusually heavy call volumes on your API key,
you may receive responses with HTTP: 429 "Too Many Requests"
more than 5 calls per second
using your API key.
There are two possible solutions to this.
- If you are not on a paid plan, you will generally need to upgrade to a paid API plan. Please email support@rocketreach.co and we can set you up with an API plan.
- If you are already on a paid API plan, please slow down and retry your requests. If you're still seeing this, please email support@rocketreach.co or contact our live support.
You can visit the account page to review your RocketReach API limits and daily usage
In general calls to all end points are rate limited to protect against abuse/attacks. However calls to /checkStatus
do not count against your daily rate limits.
Out of Credits
If you have hit some sort of rate limit, you'll see a HTTP: 429
.
But, if you are out of credits, you will see a HTTP: 403
.
- Free plans are allowed a limited number of lookups per month, and this error is most commonly returned to free plans.
- If you are on a paid plan, you should almost never see this error, paid plans are allowed to exceed their allocation. However, if you've disabled overages, you may see this errors. Please contact support@rocketreach.co and we can set you up with an API plan.
Lookup Contact information for a prospect
The /lookupProfile
API is used to lookup contact information for a prospect(profile).
You can identify the profile using parameters like name, current employer, LinkedIn URL, or profile id (returned
from /search).
The call is pretty straightforward – you provide information about the person you are looking for
i.e name, employer etc. and RocketReach searches for a person matching this information.
Lookup Profile Quickstart
Let's try a simple example. Say you want to lookup contact info for Mark Benioff, who works at Salesforce. You
would call
A deeper look
Most of the time, the contact info will be returned immediately, along with "status":"complete"
or
"status":"failed"
.
However, in certain cases, the lookup can take longer.
If the system is busy doing a lookup, the
call to /lookupProfile
will return "status:
as
"waiting","searching" or "progress"
. In these cases,
you must poll the /checkStatus endpoint
till the status changes to "complete"
or "failed"
.
When polling /checkStatus, please make sure that your rate limit does not exceed one call/second .
A detailed flowchart for this webservice call, is shown below.
Example: Lookup Profile by 'name' and 'current_employer'
This example shows you how to lookup information for a person using name & current employer.
Example: Lookup Profile by LinkedIn URL
This example shows you how to lookup information for a person using their Linkedln URL.
Parameters
This enpoint accepts the following parameters.
Name | Description | Schema |
---|---|---|
api_key | User's API Key | string |
name | Name of the person you are looking for | string |
current_employer | Current employer name (e.g. 'Google', 'General Electric') | string |
title | Job Title (e.g. 'VP of Marketing', 'CEO') | string |
li_url | LinkedIn URL e.g. 'https://www.linkedin.com/in/markbenioff' | string |
id | RocketReach specific Id of the person you are looking for (see /search ) | string |
Response
A typical response to this endpoint will look as follows:Phone numbers are only available on +Phone plans.
Multiple Matches
In certain cases, you may find that the lookup returns multiple matches. In such cases,
you can select one of the matching profiles, and then
call /lookupProfile
again, with a specific Id.
You can then call lookupProfile
using the right Id:
Checking the status of active lookups
The /checkStatus
API call is used, primarily, to poll the status of active lookups initiated by the
/lookupProfile
endpoint.
When you make a call to /lookupProfile
, the response can contain one of the following 5 values:
"complete"
or "failed"
, the client must poll this endpoint till it returns
either "complete"
or "failed"
.
Example Usage
Assume that you made a call to lookup contact info for 'Mark Benioff' and the response was
You can now poll the status for this profile by calling:
Which in turn will initially return:
And after a while... will return status:"complete"
, along with the complete data.
Check status for multiple profiles
You can also club together multiple profile Ids
in one call. E.g.
Rate limits
Calls to this endpoint do not count against your daily rate
limits.
However, calling it too aggressively, at rates higher than once per second, may trigger HTTP 429
Parameters
Name | Description | Schema |
---|---|---|
api_key | User's API Key | string |
ids | Comma separated list of profile Ids, for which you need the status returned. | string |
Response
A typical response to this endpoint will look as follows:Search for prospects
The /search
endpoint behaves very similar to the search in our UI. When you provide certain keywords, or facets as inputs,
this endpoint returns a list of people. The result is always a list of possible matches, without any contact info.
You can search by name, keyword, title, company or location. The behaviour is similar to what you see in our UI.
Search Quickstart
Lets look at a simple example. In this example, we will search for 'Amit Shanbhag',
who works at 'RocketReach.co',
using his name, company and title.
Retrieving contact information for profiles
A call to /search
does not return contact information in the result.
In order to retrieve contact information for someone in the list,
please make a separate call to /lookupProfile?id=$id
A detailed flowchart for this webservice call, is shown below.
E.g. You may perform a search for Elon Musk, which returns
You can then make a call to /lookupProfile
to get the contact information for Elon Musk.
Specifying exact matches
You can specify exact matches for all your search terms. E.g name:'Marc'
will match anyone named Marc.
If you wish to match only 'Marc Benioff', you can quote your search.
Matches anyone named 'Marc'.
Matches anyone with the exact name 'Marc Benioff'. To specify exact matches,
add quotes around your search term /{{ version }}/api/search?api_key=123456789&name="Marc Benioff"
Specifying multiple search parameters
You can specify multiple keywords or titles etc. Our search system will try and find
results that match closest to your query. In this specific example, we will return the best results that match
either title:'Founder'
or title:'CEO'
Parameters
Name | Description | Schema |
---|---|---|
api_key | User's API Key | string |
name | Name of the person you are looking for | string |
keyword | Keyword: Any keywords in a person's profile | string |
title | Title: (e.g. 'VP of Marketing', 'CEO') | string |
company | Company: (e.g. 'Google', 'General Electric') | string |
location | Location: (e.g. 'San Francisco', 'San Francisco Bay Area') | string |
Response
A typical response to this endpoint will look as follows:Retrieve Account Info
The /account
API allows you to retrieve your account information. The response will
return your basic usage and profile information.
Parameters
Name | Description | Schema |
---|---|---|
api_key | User's API Key | string |
Response
A typical response to this endpoint will look as follows:Example: Lookup contact info by name, company
If you are calling the RocketReach API endpoints directly, you will essentially need to use 2 calls.
First call /lookupProfile
with 3 params api_key
,name
and current_employer
.
If the status
returned by the call is not "complete"
or "failed"
,
then you will need to poll /checkStatus
till it returns either "complete"
or "failed"
.
If the status is "complete"
, then the response will also contain contact info data.
Putting it all together
The following example demonstrates a fully functional application, using the RocketReach API. Here, we lookup contact info of a person, by name and current_employer.
( Edit in plunker )
The source code shown below uses the RocketReach Javascript Library. We start by calling init. This checks to make sure that the
api_key
is valid, and that the user has sufficient credits to perform lookups. Under the
covers, the JS library is simply calling the /account
endpoint.
If everything looks good, we now call /lookupProfile
to
lookup contact info. The library also polls /checkStatus
for you, when necessary.
You can use the javascript library in a backend environment over node.js. We do not, however, recommend using the JS library in a browser, since your API key will be visible in plaintext, and hence vulnerable to being copied and mis-used.
Example: Lookup contact info by LinkedIn URL
This is very similar to the previous example, except for one difference.
The call to /lookupProfile
is made using the li_url
parameter.
A fully functional application
The following example demonstrates a fully functional application, using the RocketReach API.
( Edit in plunker )
Example: Search Title (role) at Company
If you are calling the RocketReach API endpoints directly, you will essentially need to use 3 calls.
First call the /search
endpoint.
Assuming that the id
for Marc's profile is 5262
, you then call
/lookupProfile
If the status
returned by the call is not "complete"
or "failed"
,
then you will need to poll /checkStatus
till it returns either "complete"
or "failed"
.
Fully functional prototype app
In this example, we will search for people with a specific name, title, at a company. We will then lookup contact info for one of the search results.
( Edit in plunker )
Javascript Library
The Javascript library allows you to find anyone's emails, social media and complete contact data, using only a few lines of code.
The Javscript library is ideal for use in backend (node.js) environments, or to quickly prototype applications in a browser.
We do not recommend using the JS library in a publicly accessible application
(i.e. in an environment where the browser directly makes the API calls), since your API key will passed around in plaintext.
Initialize the Library
The first step is to initialize the library. To initialize the library, call init()
using your API
key.
Call lookupProfile()
or search()
etc.
Once the library has been initialized you can call any of our methods.
E.g. here we call lookupProfile().
Examples
More detailed examples are listed below.
RocketReach API: Javascript Library Reference
All the methods of the Javascript Library, and their parameters are listed below. All methods receive an
object as input. All methods (except for init()
) return a jQuery promise to listen for
success/errors
E.g. init()
is invoked as follows.
init()
Name | Description | Schema |
---|---|---|
api_key | User's API Key | string |
success | Callback for succesful initialization of RocketReach. Recieves account information. | function |
error | Callback function invoked on error during initialization. Receives error information. | function |
lookupProfile()
Name | Description | Schema |
---|---|---|
id | id returned by any of the other methods. | int |
name | Name of the person you are looking for | string |
current_employer | Current employer name (e.g. 'Google', 'General Electric') | string |
title | Job Title (e.g. 'VP of Marketing', 'CEO') | string |
li_url | LinkedIn URL e.g. 'https://www.linkedin.com/in/marcbenioff' | string |
twitter_handle | Twitter Handle (e.g. use 'joandoe' instead of '@joandoe') | string |
twitter_url | Twitter Handle (e.g. 'https://twitter.com/joandoe') | string |
search()
Name | Description | Schema |
---|---|---|
name | Name of the person you are looking for | string |
keyword | Keyword: Any keywords in a person's profile | string |
title | Title: (e.g. 'VP of Marketing', 'CEO') | string |
company | Company: (e.g. 'Google', 'General Electric') | string |
location | Location: (e.g. 'San Francisco', 'San Francisco Bay Area') | string |
account()
This method takes no arguments. On success, the callback receives account information.