RocketReach API

{{menu.title}}

Get my Free API Key

The RocketReach API is free for individual use. Create your API Key absolutely free - Signup Now!

My API Key

{{apiKey}}

Use this API key for all your API calls.

Try it out!

E.g. Get Travis Kalanick's contact info, by calling… {{getCURL("lookupProfile",[["name" ,"Travis Kalanick"],["current_employer","Uber"]])}} This actually works. ( Try it now )

Learn more about the API

The RocketReach API allows you retrieve rich contact info and social data for people and companies. Our APIs are powered by the same search engine, data and algorithms that power our website.

The RocketReach API is very consistent in the way it accepts parameters and returns responses/errors. Please take a moment to read Using the API to learn more about common patterns of interaction with our API.

Need Help?

We're constantly working to improve and expand our API. We can't wait to see what you do with it. Need help? Have Feedback?

Get in touch with us

URL Structure

The general structure of all API calls is shown below. https://api.rocketreach.co/v1/api/<$END_POINT>?api_key=$api_key&param_name=param_value..

All requests are made to api.rocketreach.co and require your API KEY as a URL parameter. Normal responses are returned with error code 200. Error responses return 4xx/5xx error codes. Read more about error responses below.

AJAX Applications

For use within an AJAX application, the API supports both CORS and JSONP. You can restrict the CORS headers to specific domains, by configuring your domains in API Settings.

If you'd like to use JSONP, and wrap our response with a callback, you can specify a callback parameter with any API call. E.g. curl --get 'https://api.rocketreach.co/v1/api/lookupProfile' \ --data-urlencode 'api_key={{apiKey}}' \ … --data-urlencode 'callback=myCallbackFunction' Would respond with: Status Code: 200 OK Content-Type: 'application/javascript; charset=utf-8' Response: myCallbackFunction([{ … }]);

Error Response

If there is an error, the API calls will return 4xx/5xx HTTP status. 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, you may receive responses with 429: Too Many Requests. { Status: '429 TOO MANY REQUESTS' Content-Type: 'application/json; charset=utf-8' Response:{ "error_code": 208, "error": "Usage has exceeded quota" } }

Which calls are rate limited?

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 limits.

Rate-limited vs. Out of Credits

If you have hit some sort of rate limit, you'll see a HTTP: 429. { Status: '429 TOO MANY REQUESTS' Content-Type: 'application/json; charset=utf-8' Response:{ "error_code": 208, "error": "Usage has exceeded quota" } } But, if you are out of credits, you will see a HTTP: 403. { 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" } }
















/lookupProfile

The /lookupProfile API is used to lookup contact information. 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.

Example: Lookup Profile by 'name' and 'current_employer'

{{getCURL("lookupProfile",[["name" ,"Travis Kalanick"],["current_employer","Uber"]])}} This actually works. ( Try it now )

Pending Results

The search for a persons's contact info can take a few seconds. If the info is immediately available, the status: "complete" will be returned by the API call. Status code can have one of the 4 possible values status:"complete" //The search for contact information finished successfully status:"failed" //Search is complete, but there were errors. status:"searching" //The search for contact information is in progress. status:"progress" //In progress, and partial data may be available.

E.g. If contact information wasn't immediately available for Travis Kalanick, you'd see {{pendingInfo|json}}

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
twitter_handle Twitter Handle (e.g. use 'joandoe' instead of '@joandoe') string
twitter_url Twitter Handle (e.g. 'https://twitter.com/joandoe') string

Parameters for Lookup by Id

If you already know the ID of the person, form a previous call to /search, you can call this end point with id.

Name Description Schema
api_key User's API Key string
id Id of the person you are looking for string

Response

A typical response to this endpoint will look as follows: {{lookupProfileResponse|json}}

Multiple Matches

In certain cases, you may find the the lookup returns multiple matches. In that case the response will contain a list of profiles. You can select one of the matching profiles, and then call /lookupProfile again, with a specific Id.

{ "error":"object not found", "detail":"Search resulted in multiple possible matches", "possible_matches":[{ "id": 1000, "profile_pic": "https://../54b9d4d0c87af0310770e21f3f2baaa1.jpeg", "name": "Travis Kalanick", "headline": "CEO, co-founder at Uber", ... },{ "id": 2034, "profile_pic": "https://../19d4d0c87af0310754b70e21f3f2baaa.jpeg", "name": "Kravit Salackin", "headline": "CTO at Foober", }, .. ] }

You can then call lookupProfile using the right Id: {{getCURL("lookupProfile",[["id" ,"1000"]])}}

/checkStatus

The /checkStatus API call retrieves the status of profiles returned by /lookupProfile. When you make a call to /lookupProfile, the response can contain one of the following 4 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 for status till it returns either complete or failed.

In a normal lookup request states transition from "waiting" to "completed" as shown in the state diagram below. If there is a unrecoverable error at any stage, the status becomes "failed" "waiting" -> "searching" -> "progress" -> "completed"

Example Usage

Assume that you made a call to lookup contact info for 'Travis Kalanick' and the response was {{pendingInfo|json}} You can now poll the status for this profile by calling: {{getCURL("checkStatus",[["ids" ,"1503"]])}} Which in turn will initially return: {{[checkStatusResponse[0]]|json}} And after a while... will return status:"complete", along with the complete data. {{checkStatusResponseAfterCompletion|json}}

You can also club together multiple profile Ids in one call. E.g. {{getCURL("checkStatus",[["ids" ,"1503,1504"]])}} will return {{checkStatusResponse|json}}

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: {{checkStatusResponseComplete|json}}

/search

The /search API is used to find people. The result is always a list of possible matches. You can search by name, keyword, title, company or location. The behaviour is similar to what you see in our UI.

Retrieving contact information for profiles

A call to /search does not return contact information in the result. In order to retreive contact information for someone in the list, please make a separate call to /lookupProfile?id=$id

Example: Search profiles by name, keyword and employer

{{getCURL("search",[["name" ,"Amit Shanbhag"],["keyword","Co-Founder"],["company","RocketReach"]])}} This actually works. ( Try it now )

Example: Multiple Parameters

You can specifiy multiple keywords or titles etc. Our search system will try and find results that match closest to your query.
E.g. in the search below, we have two keywords. {{getCURL("search",[["name" ,"Amit Shanbhag"],["keyword","Entrepreneur"],["keyword","Co-Founder"],["company","RocketReach"]])}} This actually works. ( Try it now )

Looking up contact information

When you make calls to /search, each item in the resulting array will contain an id You can then use this id to lookup contact information for the person.

E.g. You may perform a search for Elon Musk, which returns { profiles: [{ id: 5254, current_title: "Entrepreneur and Explorer", name: "Elon Musk", location: "Palo Alto, California", }, ... ] }

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 now )

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: {{searchResponse|json}}

Example: Lookup contact info by name, company

In this example, we will retrieve the full profile of a person, by name and current_employer

Using Javascript

<script src="//api.rocketreach.co/v1/api.min.js"></script> <script> var API_KEY = "{{ apiKey }}"; //RocketReach has initialized var doLookup = function (account) { //Lookup Profile RocketReachAPI.lookupProfile({ name: "Travis Kalanick", current_employer: "Uber" }).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>

( Edit in plunker )

Using the API directly

If you are calling the Web Services directly, you will essentially need to use 2 calls. First call /lookupProfile {{getCURL("lookupProfile",[["name" ,"Travis Kalanick"],["current_employer","Uber"]])}} This actually works. ( Try it now )

If the status returned by the call is not "complete" or "failed", then you will need to poll /checkStatus till it returns one of those values. E.g. Assuming that Travis Kalanick's profile Id is 5262

{{getCURL("checkStatus",[["ids" ,"5262"]])}} This actually works. ( Try it now )

Example: Search Title (role) at Company

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.

Using Javascript

<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: "Travis Kalanick", title:"CEO", company: "Uber"} ).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") } //Retreive 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>

( Edit in plunker )

Using the API directly

If you use the API directly, you will essentially need to use 3 calls. First call /search {{getCURL("search",[["name" ,"Travis Kalanick"],["company","Uber"]])}} This actually works. ( Try it now )

Assuming that the id for Travis's profile is 5262, you then call /lookupProfile {{getCURL("lookupProfile",[["id" ,"5262"]])}} This actually works. ( Try it now )

If the status returned by the call is not "complete" or "failed", then you will need to poll /checkStatus till it returns one of those values. {{getCURL("checkStatus",[["ids" ,"5262"]])}} This actually works. ( Try it now )

Javascript Library

If you're using the API in a browser, the Javascript Library allows you to get going very quickly. Lookup anyone's emails, social links and complete contact data, using only a few lines of code.

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":"{{ apiKey }}", "success": mySuccessFunction, "error": myErrorHandler }); </script>

Call lookupProfile(), 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: "Travis Kalanick", current_employer: "Uber" }).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 now )

Examples

More detailed examples are listed below.

API Reference

View the complete API reference.

RocketReach API: Javascript Library Reference

All the methods of the Javascript Library, and their parameters are listed below. All methods receive a settings 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 = "{{ apiKey }}"; //Initialise RocketReachAPI.init({ "api_key":API_KEY, "success": mySuccessFunction, "error": myErrorHander }); </script>

and lookupProfile() will be invoked as follows. <script src="//api.rocketreach.co/v1/api.min.js"></script> <script> ... RocketReachAPI.lookupProfile({ "name":"Travis Kalanick", "current_employer": "Uber" }).then( function successCallback() {...}, function errorCallback() {...} ); ... </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
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.

© 2016 RocketReach, All Rights Reserved.