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 {{ user.apiKey }} You can always visit the account page to view api usage or manage RocketReach api settings.

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 … {{ getCURL("lookupProfile", docJSON.markBenioffNameCompany) }} This actually works. (Try it)

Base URL

All URLs referenced in the documentation have the following base: https://api.rocketreach.co/v1/api/ and follow the following general format https://api.rocketreach.co/v1/api/<$END_POINT>?api_key=$api_key&param_name=param_value..

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. https://api.rocketreach.co/v1/api/<$END_POINT>?api_key={{ user.apiKey }}…

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. Status: 404 Not Found Content-Type: 'application/json; charset=utf-8' Response: { "error": "object not found", "detail": "Could not find profile with name/current_employer specified" }

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". In general, do not make 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.
Status: '429 TOO MANY REQUESTS' Content-Type: 'application/json; charset=utf-8' Response:{ "error_code": 208, "error": "Usage has exceeded quota" }

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.
Status: '403: EXECUTE ACCESS FORBIDDEN' Content-Type: 'application/json; charset=utf-8' Response: { "error":"Request is valid, but will not be fulfilled", detail:"Insufficient Credits" }

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 {{ getCURL("lookupProfile", docJSON.markBenioffNameCompany) }} This actually works. (Try it)

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. {{ getCURL("lookupProfile", docJSON.markBenioffNameCompany) }} This actually works. (Try it)

Example: Lookup Profile by LinkedIn URL

This example shows you how to lookup information for a person using their Linkedln URL. {{ getCURL("lookupProfile", docJSON.markBenioffLIURL) }} This actually works. (Try it)

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: {{ docJSON.markBenioffSampleSuccessResponse|json }}

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. {{ docJSON.multipleResults|json }}

You can then call lookupProfile using the right Id: {{ getCURL("lookupProfile", docJSON.markBenioffID) }}

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: status:"complete" //The search for contact information finished successfully status:"failed" //Search is complete, but there were errors. status:"waiting" //The request is waiting in an internal queue. status:"searching" //The search for contact information is in progress. status:"progress" //In progress, and partial data may be available. If the value is not "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 {{ docJSON.markBenioffStatusSearching|json }}

You can now poll the status for this profile by calling: {{ getCURL("checkStatus",[["ids","5244"]]) }}

Which in turn will initially return: {{ docJSON.mBIDSearchingResponse|json }}

And after a while... will return status:"complete", along with the complete data. {{ docJSON.markBenioffStatusComplete|json }}

Check status for multiple profiles

You can also club together multiple profile Ids in one call. E.g. {{ getCURL("checkStatus",[["ids","5244,1234,5678"]]) }} will return {{ docJSON.checkStatusMultipleResponse|json }}

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: {{ docJSON.checkStatusTypicalResponse|json }}

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. {{ getCURL("search",docJSON.benioffSearch) }} This actually works. (Try it)

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 {{ docJSON.elonMustSearchResult|json }}

You can then make a call to /lookupProfile to get the contact information for Elon Musk. {{ getCURL("lookupProfile",[["id" ,"5254"]]) }} This actually works. (Try it)

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'. {{ getCURL("search",[["name" ,"Marc"]]) }} This actually works. (Try it)

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" {{ getCURL("search",[["name" ,"\"Marc Benioff\""]]) }} This actually works. (Try it)

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' {{ getCURL("search",docJSON.benioffSearchMultiple) }} This actually works. (Try it)

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: {{ docJSON.searchTypicalResponse|json }}

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. {{ getCURL("lookupProfile",docJSON.markBenioffNameCompany) }} This actually works. (Try it)

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. {{ getCURL("checkStatus",[["ids" ,"5262"]]) }}

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.

<script src="https://api.rocketreach.co/v1/api.min.js"></script> <script> var API_KEY = "{{ user.apiKey }}"; //RocketReach has initialized var doLookup = function (account) { //Lookup Profile RocketReachAPI.lookupProfile({ name: "Marc Benioff", current_employer: "Salesforce" }).then(function (profiles) { //Print Result console.log(profiles[0] ); },handleFailure); } //Generic function to handle failure. var handleFailure = function () { console.error("Error:", arguments); } //Initialise RocketReachAPI.init({ "api_key":API_KEY, "success":doLookup, "error": handleFailure }); </script>

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.

{{ getCURL("lookupProfile",docJSON.markBenioffLIURL) }} This actually works. (Try it)

A fully functional application

The following example demonstrates a fully functional application, using the RocketReach API. <script src="//api.rocketreach.co/v1/api.min.js"></script> <script> var API_KEY = "{{ user.apiKey }}"; ... RocketReachAPI.lookupProfile({ li_url: "https://www.linkedin.com/in/marcbenioff", } ... </script>

( 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. {{ getCURL("search",[["name" ,"Marc Benioff"],["company","Salesforce"],["title","CEO"]]) }} This actually works. (Try it)

Assuming that the id for Marc's profile is 5262, you then call /lookupProfile {{ getCURL("lookupProfile",[["id","5262"]]) }}

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". {{ getCURL("checkStatus",[["ids","5262"]]) }}

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 )

<script src="//api.rocketreach.co/v1/api.min.js"></script> <script> var API_KEY = "{{ apiKey }}"; //Once RocketReach has initialized, perform a search follwed by a lookup var searchAndLookup = function (account) { RocketReachAPI.search({ name: "Marc Benioff", title: "CEO", company: "SalesForce" } ).then(function (searchResult) { //Print Results for (var i = 0; searchResult && searchResult.profiles && i < searchResult.profiles.length; i++) { console.log("Profile:" + i + ": [id:" + searchResult.profiles[i].id + ",name:" + searchResult.profiles[i].name +"]", "pre") } //Retrieve the first Profile RocketReachAPI.lookupProfile({ id: searchResult.profiles[0].id }).then(function success(profiles) { //Print Results console.log(profiles[0]); }, handleFailure); }, handleFailure); } //Generic function to handle failure. var handleFailure = function () { console.error("Error:", arguments); } //Initialise RocketReachAPI.init({ "api_key": API_KEY, "success": searchAndLookup, "error": handleFailure }); </script>

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.

<script src="//api.rocketreach.co/v1/api.min.js"></script> <script> //Initialise RocketReachAPI.init({ "api_key":"{{ user.apiKey }}", "success": mySuccessFunction, "error": myErrorHandler }); </script>

Call lookupProfile() or search() etc.

Once the library has been initialized you can call any of our methods. E.g. here we call lookupProfile().

<script src="//api.rocketreach.co/v1/api.min.js"></script> <script> var API_KEY = "{{ apiKey }}"; //Call lookup var mySuccessFunction = function (account) { //Lookup Profile RocketReachAPI.lookupProfile({ name: "Marc Benioff", current_employer: "Salesforce" }).then(function (profiles) { //Print Result console.log(profiles[0] ); }); } //Initialise RocketReachAPI.init({ "api_key":API_KEY, "success": mySuccessFunction, "error": myErrorHander }); </script>

This actually works.(Try it)

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. <script src="//api.rocketreach.co/v1/api.min.js"></script> <script> var API_KEY = "{{ user.apiKey }}"; //Initialise RocketReachAPI.init({ "api_key":API_KEY, "success": mySuccessFunction, "error": myErrorHander }); </script>

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.