Get Started

The RocketReach API allows you to programatically search & lookup contact info over 450 million professionals, and 17 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/v2/api/ and follow the following general format https://api.rocketreach.co/v2/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/v2/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: sales@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 sales@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 sales@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.
  • Because paid plans are allowed to exceed their allocation, you are unlikely to encounter this error. However, if you do, check that overages are enabled, and then contact sales@rocketreach.co to 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" }

Authorization

Requests to the API must be authenticated with your user credentials. There are several ways to pass your identity to the API.

Query Parameter

Callers may specify the api_key query parameter to any of the API endpoints to authenticate

For example, GET api.rocketreach.co/api/v2/account?api_key=

Request Body

API Requests with a request body can include the API Key in the body.

Request Header

Callers may specify their API Key in the Api-Key request header.

Webhooks

For the lookupProfileendpoint, we offer a webhook solution so that users do not need to poll the checkStatus endpoint until their results are available.

Setting Up a Webhook

To set up a webhook, go to your API settings. Enter your server's callback URL into the field, and hit "Create".

Options for Created Webhook URLs

For each URL created, you can perform some basic maintenance tasks:

  • Test the webhook - we will attempt to send a basic JSON payload to the URL.
  • Disable/enable - if you may use this URL in the future, this is an option to termporarily disable it.
  • Delete - if you no longer plan using this URL, it can be deleted.

Using Webhook-Enabled Endpoints

Currently, only lookupProfile has webhook functionality, but we anticipate supporting more in the future!
Once you call a webhook-enabled endpoint with a webhook set up in your settings, we will send back results to the provided URL.
The results returned to you should look the same as if they were queried through the REST API. In addition, the API will still respond to your REST call as normal.

Errors

If any errors occur, they will show up in the API settings page in the "Web Hook" section.
If the callback to the provided URL is unsuccessful after several attempts, the URL will be marked as disabled.

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 }}

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 }}

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.

The source code shown below uses the RocketReach Python SDK. We start by calling initializing the client. 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 SDK 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.

Code import rocketreach rr = rocketreach.Gateway(api_key='{{ user.apiKey }}') lookup = rr.person.lookup(extras={'name': 'Marc Benioff', 'current_employer': 'Salesforce'}) if lookup.is_success: print(repr(lookup.person))
Output {'current_employer': 'Salesforce', 'current_personal_email': 'benioff@gmail.com', 'current_title': 'Chairman and Co-CEO', 'current_work_email': 'marcb@salesforce.com', 'emails': [{'email': 'm.benioff@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'mbenioff@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'benioff@comcast.net', 'smtp_valid': 'valid', 'type': 'personal'}, {'email': 'marc@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'marc_benioff@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'benioff@gmail.com', 'smtp_valid': 'valid', 'type': 'personal'}, {'email': 'benioff@aol.com', 'smtp_valid': 'valid', 'type': 'personal'}, {'email': 'ceo@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'marcb@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'marc.benioff@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'marcbenioff@salesforce.com', 'smtp_valid': 'invalid', 'type': 'professional'}, {'email': 'benioff@frontiernet.net', 'smtp_valid': 'invalid', 'type': 'personal'}, {'email': 'cooldwj@chinaren.com', 'smtp_valid': 'invalid', 'type': 'professional'}, {'email': 'benioff@rcn.com', 'smtp_valid': 'invalid', 'type': 'professional'}], 'id': 5244, 'linkedin_url': 'https://www.linkedin.com/in/marcbenioff', 'links': {'aboutme': 'http://www.about.me/marcbenioff', 'amazon': 'http://www.amazon.com/gp/pdp/profile/AZGYQG724J6ON//190-5748375-2756131', 'angel': 'https://angel.co/benioff', 'angellist': 'http://www.angel.co/benioff', 'crunchbase': 'https://www.crunchbase.com/person/marc-benioff', 'facebook': 'http://www.facebook.com/benioff', 'google': 'https://plus.google.com/109586918294369333764', 'google+': 'https://plus.google.com/108172009599607363531/about', 'googleplus': 'https://plus.google.com/108172009599607363531', 'gravatar': 'http://www.gravatar.com/crmmaster', 'gravatar.com': 'http://gravatar.com/crmmaster', 'hi5': 'http://www.hi5.com/friend/p45336146--profile--html', 'instagram': 'http://www.instagram.com/benioff', 'klout': 'http://www.klout.com/benioff', 'linkedin': 'https://www.linkedin.com/in/marcbenioff', 'meetup': 'http://www.meetup.com/members/15867891', 'pinterest': 'http://www.pinterest.com/benioff', 'quora': 'http://www.quora.com/marc-benioff', 'salesforce.com': 'http://www.salesforce.com/company/leadership/executive-team/index.jsp#benioff', 'twicsy': 'http://twicsy.com/u/%40Benioff', 'twitter': 'http://www.twitter.com/benioff'}, 'location': 'San Francisco, California, United States', 'name': 'Marc Benioff', 'phones': [], 'profile_pic': 'https://d1hbpr09pwz0sk.cloudfront.net/profile_pic/marc-benioff-4492e698', 'status': 'complete'}

Example: Lookup contact info by LinkedIn URL

This is very similar to the previous example, but calls /lookupProfile with the li_url parameter.

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

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.

The source code shown below uses the RocketReach Python SDK. We start by calling initializing the client. 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 SDK 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.

Code import rocketreach rr = rocketreach.Gateway(api_key='{{ user.apiKey }}') lookup = rr.person.lookup(linkedin_url='https://www.linkedin.com/in/marcbenioff') if lookup.is_success: print(repr(lookup.person))
Output {'current_employer': 'Salesforce', 'current_personal_email': 'benioff@gmail.com', 'current_title': 'Chairman and Co-CEO', 'current_work_email': 'marcb@salesforce.com', 'emails': [{'email': 'm.benioff@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'mbenioff@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'benioff@comcast.net', 'smtp_valid': 'valid', 'type': 'personal'}, {'email': 'marc@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'marc_benioff@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'benioff@gmail.com', 'smtp_valid': 'valid', 'type': 'personal'}, {'email': 'benioff@aol.com', 'smtp_valid': 'valid', 'type': 'personal'}, {'email': 'ceo@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'marcb@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'marc.benioff@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'marcbenioff@salesforce.com', 'smtp_valid': 'invalid', 'type': 'professional'}, {'email': 'benioff@frontiernet.net', 'smtp_valid': 'invalid', 'type': 'personal'}, {'email': 'cooldwj@chinaren.com', 'smtp_valid': 'invalid', 'type': 'professional'}, {'email': 'benioff@rcn.com', 'smtp_valid': 'invalid', 'type': 'professional'}], 'id': 5244, 'linkedin_url': 'https://www.linkedin.com/in/marcbenioff', 'links': {'aboutme': 'http://www.about.me/marcbenioff', 'amazon': 'http://www.amazon.com/gp/pdp/profile/AZGYQG724J6ON//190-5748375-2756131', 'angel': 'https://angel.co/benioff', 'angellist': 'http://www.angel.co/benioff', 'crunchbase': 'https://www.crunchbase.com/person/marc-benioff', 'facebook': 'http://www.facebook.com/benioff', 'google': 'https://plus.google.com/109586918294369333764', 'google+': 'https://plus.google.com/108172009599607363531/about', 'googleplus': 'https://plus.google.com/108172009599607363531', 'gravatar': 'http://www.gravatar.com/crmmaster', 'gravatar.com': 'http://gravatar.com/crmmaster', 'hi5': 'http://www.hi5.com/friend/p45336146--profile--html', 'instagram': 'http://www.instagram.com/benioff', 'klout': 'http://www.klout.com/benioff', 'linkedin': 'https://www.linkedin.com/in/marcbenioff', 'meetup': 'http://www.meetup.com/members/15867891', 'pinterest': 'http://www.pinterest.com/benioff', 'quora': 'http://www.quora.com/marc-benioff', 'salesforce.com': 'http://www.salesforce.com/company/leadership/executive-team/index.jsp#benioff', 'twicsy': 'http://twicsy.com/u/%40Benioff', 'twitter': 'http://www.twitter.com/benioff'}, 'location': 'San Francisco, California, United States', 'name': 'Marc Benioff', 'phones': [], 'profile_pic': 'https://d1hbpr09pwz0sk.cloudfront.net/profile_pic/marc-benioff-4492e698', 'status': 'complete'}

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"],["current_employer","Salesforce"],["current_title","CEO"]]) }}

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 and title, at a company. We will then lookup contact info for one of the search results.

Code import rocketreach rr = rocketreach.Gateway(api_key='{{ user.apiKey }}') search = rr.person.search() # Build up our search query search = search.filter(name='Marc Benioff', current_title='CEO', current_employer='Salesforce') # Call the search endpoint with our query result = search.execute() if result.is_success: lookup = rr.person.lookup(result.people[0].id) if lookup.is_success: print(repr(lookup.person))
Output {'current_employer': 'Salesforce', 'current_personal_email': 'benioff@gmail.com', 'current_title': 'Chairman and Co-CEO', 'current_work_email': 'marcb@salesforce.com', 'emails': [{'email': 'm.benioff@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'mbenioff@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'benioff@comcast.net', 'smtp_valid': 'valid', 'type': 'personal'}, {'email': 'marc@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'marc_benioff@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'benioff@gmail.com', 'smtp_valid': 'valid', 'type': 'personal'}, {'email': 'benioff@aol.com', 'smtp_valid': 'valid', 'type': 'personal'}, {'email': 'ceo@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'marcb@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'marc.benioff@salesforce.com', 'smtp_valid': 'valid', 'type': 'professional'}, {'email': 'marcbenioff@salesforce.com', 'smtp_valid': 'invalid', 'type': 'professional'}, {'email': 'benioff@frontiernet.net', 'smtp_valid': 'invalid', 'type': 'personal'}, {'email': 'cooldwj@chinaren.com', 'smtp_valid': 'invalid', 'type': 'professional'}, {'email': 'benioff@rcn.com', 'smtp_valid': 'invalid', 'type': 'professional'}], 'id': 5244, 'linkedin_url': 'https://www.linkedin.com/in/marcbenioff', 'links': {'aboutme': 'http://www.about.me/marcbenioff', 'amazon': 'http://www.amazon.com/gp/pdp/profile/AZGYQG724J6ON//190-5748375-2756131', 'angel': 'https://angel.co/benioff', 'angellist': 'http://www.angel.co/benioff', 'crunchbase': 'https://www.crunchbase.com/person/marc-benioff', 'facebook': 'http://www.facebook.com/benioff', 'google': 'https://plus.google.com/109586918294369333764', 'google+': 'https://plus.google.com/108172009599607363531/about', 'googleplus': 'https://plus.google.com/108172009599607363531', 'gravatar': 'http://www.gravatar.com/crmmaster', 'gravatar.com': 'http://gravatar.com/crmmaster', 'hi5': 'http://www.hi5.com/friend/p45336146--profile--html', 'instagram': 'http://www.instagram.com/benioff', 'klout': 'http://www.klout.com/benioff', 'linkedin': 'https://www.linkedin.com/in/marcbenioff', 'meetup': 'http://www.meetup.com/members/15867891', 'pinterest': 'http://www.pinterest.com/benioff', 'quora': 'http://www.quora.com/marc-benioff', 'salesforce.com': 'http://www.salesforce.com/company/leadership/executive-team/index.jsp#benioff', 'twicsy': 'http://twicsy.com/u/%40Benioff', 'twitter': 'http://www.twitter.com/benioff'}, 'location': 'San Francisco, California, United States', 'name': 'Marc Benioff', 'phones': [], 'profile_pic': 'https://d1hbpr09pwz0sk.cloudfront.net/profile_pic/marc-benioff-4492e698', 'status': 'complete'}

Python SDK

The Python SDK allows you to find anyone's emails, social media and complete contact data, using only a few lines of code.

Install the SDK

Install with pip: pip install rocketreach

Manual installation:

# The requests v2.2 or higher is a required dependency wget https://pypi.python.org/packages/source/r/requests/requests-2.2.1.tar.gz tar xzvf requests-2.2.1.tar.gz cd requests-2.2.1 python setup.py install # Install the rocketreach SDK wget https://files.pythonhosted.org/packages/20/9d/5ba988d0b2f94a19fb8f86ae87ef1a2eb79b3fd7da7cce00998b7051d57f/rocketreach-2.1.0.tar.gz tar xzvf rocketreach-2.1.0.tar.gz cd rocketreach-2.1.0 python setup.py install

Use one of the installation methods above to install the rocketreach package into your project's virtual environment. The code is now ready to be integrated.

Initialize the SDK

Initialization is the first step to use the SDK. You will need you API key for this step. import rocketreach rr = rocketreach.Gateway(api_key='{{ user.apiKey }}') # Check that the SDK is working result = rr.account.get() if result.is_success: print(f'Success: {result.account}') else: print(f'Error: {result.message}!')

Call lookup() or search().

You can call any of our methods once the Gateway class is constructed. In this next example we will call lookup() using a name and current employer. Then, we'll do the same lookup using a LinkedIn URL.

lookup_result = rr.person.lookup(name='Marc Benioff', current_employer='Salesforce') if lookup_result.is_success: print(lookup_result.person) lookup_result = rr.person.lookup(linkedin_url='https://www.linkedin.com/in/marcbenioff') if lookup_result.is_success: print(lookup_result.person)

By default, the lookup method blocks until /checkStatus returns complete. The caller can override this behavior and call lookup in a non-blocking context.

import time # Lookup 2 profiles, non-blocking and checkStatus ourself. lookup1 = rr.person.lookup(linkedin_url='https://www.linkedin.com/in/marcbenioff', block=False) lookup2 = rr.person.lookup(linkedin_url='https://www.linkedin.com/in/reidhoffman', block=False) # Check if the lookups are complete. while True: lookup_ids = [lookup1.person.id, lookup2.person.id] cs_result = rr.person.check_status(lookup_ids) num_complete = 0 for p in cs_result.people: if p.status == 'complete': num_complete += 1 if num_complete == len(lookups): break time.sleep(10) # Wait a few seconds before checking status again # All the lookups are 'complete'.

check_status() can take either a single argument, or an array containing multiple IDs to lookup. Regardless of the number of arguments, the return value will always contain a person collection as an array (with 1 or more elements).

result = rr.person.check_status(5244) assert(len(result.people) == 1) result = rr.person.check_status([5244, 5234]) assert(len(result.people) == 2)

Reference

Calls are wrapped in a Result object. If the call was successful the Result object will encapsulate the return value.

Result object attributes

Name Description Type
request Request object sent to the server. requests.Request
response Response object received from the server. requests.Response
is_success Indicates if the call succeeded. bool
data (optional) Any data retrieved from the server response. dict
error (optional) Any error data retrieved from the server response. Returned if is_success is False dict
message (optional) A human readable message that explains what went wrong. str

Successful results will also contain an attribute containing a Python object representing the returned entity.

Gateway Initialization

Usage

result = rocketreach.Gateway(api_key='{{ user.apiKey }}') result.person result.account

Arguments

Name Description Type
config Gateway configuration object. rocketreach.GatewayConfig
api_key User's api key, str

Returns

Gateway
Name Description Type
person Access person functions, like lookup, check status and search. rocketreach.PersonGateway
account Access user account functions. rocketreach.AccountGateway

Account Information

Usage

result = rr.account.get() result.account

Arguments

None

Returns

Returns an Account within a result object.

Name Description Type
api_key User's api key. str
api_key_domain User's api key domain str
daily_api_limit Deprecated int
daily_api_num_calls Deprecated str
email User's email. str
first_name User's first name. str
id User's unique identifier. int
last_name User's last name. str
lifetime_api_num_calls Deprecated int
lifetime_credits_spent Deprecated int
lookup_credit_balance Deprecated int
plan Metadata about the user's current subscription plan. dict
state Either 'registered' or 'test_user'. str

Lookup

Usage

result = rr.person.lookup(5244) result.person

Aguments

Name Description Type
id The person's ID to lookup. Use the search result to find IDs. int
linkedin_url The person's linkedin URL (should be the full URL including https://wwww.linkedin.com). str
extras Wrapper for passing other parameters to lookup, such as name or current_employer. dict
block Indicate whether the call should block until the lookup status is complete. (Default: True) bool

Returns

Account

Name Description Type
current_employer Person's current employer name. str
current_personal_email Best guess at most up-to-date personal email for this contact. str
current_title Person's current job title. str
current_work_email Best guess at most up-to-date work email for this contact. str
emails List of emails for this contact. list
id Person's unique id. int
linkedin_url Person's linkedin url. str
links Social links for this contact. dict
location Person's current location. str
name Person's name. str
phones Phone numbers associated with this contact. list
profile_pic Link to a profile picture associated with this person. str
status The lookup status ('complete', 'progress', 'searching', 'not queued') str

Note: by default, the lookup status should be complete, since the lookup method polls check status and blocks until the lookup is finished.

Search

Usage

search = rr.person.search() search = search.filter(current_title='Software Engineer') result = search.execute() result.people

search() returns a search object which can be used to modify the current query. The search object supports filter and exclude. These methods have the same signature and return a copy of the search with the underlying query modified according to the method arguments. Use filter to match people with a given criteria, or exclude to remove them from the results.

filter and exclude can take multiple parameters in one call, or the calls can be chained together.

search = rr.person.search() # these 2 filters are functionally equivalent s1 = search.filter(current_title='Software Engineer', current_employer='Google') s2 = search.filter(current_title='Software Engineer').filter(current_employer='Google')

You can filter a parameter multiple times to "or" their results together.

search = rr.person.search() # search current title is "Software Engineer" or "Software Developer" search = search.filter(current_title='Software Engineer').filter('Software Developer')

Finally, when using exclude, you dont need to prefix the search parameter with exclude. The SDK handles this detail for you.

search = rr.person.search() search = search.filter(current_title='Software Engineer') search = search.exclude(current_title='Senior Software Engineer')

If you are unsure how your search is being interpreted, you can access the query as a dict.

Code search = rr.person.search() search = search.filter(current_title='Software Engineer') search = search.exclude(current_title='Senior Software Engineer') search.query
Output {'current_title': ['Software Engineer'], 'exclude_current_title': ['Senior Software Engineer']}

Arguments

See Search for a comprehensive list of arguments. The argument names will be the same.

Returns

PersonCollection, list of Person objects.

Pagination

Searches will only return 10 results at a time, but the API provides a pagination method that can be accessed through the Python SDK.

search = rr.person.search() # Add filters to your search start = 1 size = 10 result = search.execute() people = [] while result.is_success and result.people: start += size people.extend(result.people) search = search.params(start=start, size=size) result = search.execute()

The Python SDK provides iterators to handle paginating through results for you. These convenience iterators are accessed through the .iterator() method.

search = rr.person.search() # Add filters to your search for person in search.iterator(): print(person)

The search object also supports indexing and slicing to limit the range of results.

search = rr.person.search() # Add filters to your search list(search[:100]) # Retrieve the first 100 results list(search[10:20]) # Retrieve results 11 - 19 person = search[0] # Retrieve only the first result

Indexing causes the search to be immediately executed with the desired result returned.

Search object slices cannot contain steps.

Ordering

The RocketReach API provides 2 methods for ordering the search results. Results can be ordered by relevance (default) or popularity.

Relevance
Return results most closely matching the search query.
Popularity
Ensure matching decision makers, executives and managers are closer to the top of the search results when they match the search criteria.
search = rr.person.search() search = search.options(order_by='popularity') result = search.execute()