Get Started

The RocketReach API allows you to programatically search & lookup contact info over 430 million professionals, and 20 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 }}

Search for prospects

The /search endpoint behaves similarly 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, and more. See the full list of search parameters.

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

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"]]) }}

Matches anyone with the exact name 'Marc Benioff'. To specify exact matches, add quotes around your search term /{{ version }}/api/search?name="Marc Benioff" {{ getCURL("search",[["name" ,"\"Marc Benioff\""]]) }}

Request Body

Name Description Schema Minimum Maximum
query JSON object containing a query. object - -
start The index of the 1st element to return integer 1 100
page_size The number of profiles to return integer 1 100

The query inside the search request body contains a list of search terms. Each search term must contain a list of keywords to search against that term. If any of the keywords for a given search term match a profile, it will be included in the results. If multiple filters are specified at least one keyword from each must match a profile.

You can also ensure a search excludes a certain matching phrase by prefixing the filter with exclude_ (see examples below).

Methods

  • POST: Queries are executed by posting to the search endpoint a query body with the request format.

Query Format

Name Description Schema
city Profiles from this city. string
company_domain Profiles working for companies with the given domain. string
company_funding_min Profiles working for companies matching the given criteria. Integer
company_funding_max Profiles working for companies matching the given criteria. Integer
company_industry_tags Profiles working for companies matching the given criteria. Integer
company_revenue_min Profiles working for companies matching the given criteria. Integer
company_revenue_max Profiles working for companies matching the given criteria. Integer
company_size_min Profiles working for companies matching the given criteria. Integer
company_size_max Profiles working for companies matching the given criteria. Integer
company_website_category Profiles working for companies matching the given criteria. Integer
company_website_url Profiles working for companies matching the given criteria. Integer
country Profiles from the given country. String
current_employer Profiles currently working for the given company. String
current_title Profiles with the given title. String
degree Profiles with the given degree. String
keyword Keyword: Any keywords in a person's profile String
location Location: (e.g. 'San Francisco', 'San Francisco Bay Area') String
major Profiles with the given major. String
naics_codes_min Profiles working for companies matching the given criteria. Integer
naics_codes_max Profiles working for companies matching the given criteria.
school Profiles with the given school. Strin
sic_codes_min Profiles working for companies matching the given criteria.
sic_codes_max Profiles working for companies matching the given criteria.
state Profiles with the given state. String.

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'

{ "query": { "current_title": ["Founder", "CEO"] } }

Excluding search terms

You can omit results matching any of the search terms listed in the table above. Prepend exclude_ before the field name to change the field parameter to exclude all matching documents. In this specific example, we will return the best results that match title: 'Software Engineer' and title: 'Software Developer' but not title: 'Senior' or title: 'Sr'

Basically, this should match Software Engineers and Software Developers that don't have senior anywhere in their job title.

{ "query": { "current_title": ["Software Engineer", "Software Developer"], "exclude_current_title": ["Senior", "Sr"] } }

Response Body

The search response contains pagination metadata, which indicate how many results can be retrieved for this query, as well as a list of profiles that matched the search terms. The search results contain profile metadata, but exclude contact information. The included teaser indicates the email domains and partial phone numbers for any contact information that has already been discovered. Keep in mind that contact information is searched in real-time, so the results may change during a lookup from what is indicated in the teaser.

{ "pagination": { "start": 1, "next": 11, "total": 10 }, "profiles": [ { "id": 1430548, "status": "complete", "name": "Amit Shanbhag", "profile_pic": "https://d1hbpr09pwz0sk.cloudfront.net/profile_pic/amit-shanbhag-5fd199dd", "links": { "github": "https://github.com/ashanbh", "linkedin": "https://www.linkedin.com/in/amitshanbhag" }, "linkedin_url": "https://www.linkedin.com/in/amitshanbhag", "location": "United States", "city": null, "region": null, "country_code": "US", "current_title": "Founder", "current_employer": "RocketReach.co", "teaser": { "emails": [ "rocketreach.co", "yahoo.com", "gmail.com", "shocase.com" ], "phones": [ { "number": "+1 (833) 212-XXXX", "is_premium": false } ], "office_phones": [ "+1 833-212-XXXX" ], "preview": [], "is_premium_phone_available": false } } {...}, {...}, ] }

The profile status is deprecated and doesn't serve a useful purpose. It will be removed in future API versions.

Pagination

You can retrieve up to the first 100 results of your search using start and page_size.

{ "query": { "current_title": ["Founder", "CEO"], }, "start": 1, "page_size": 100 }

If you try to paginate further than this, you will get an error with status code 400 and the following response body.

For performance reasons, searches are truncated after 100 results, so please be sure to stay within the pagination boundaries.

{ "start": [ "cannot exceed 100" ], "page_size": [ "cannot exceed 100" ] }

Errors

If you JSON is not well formated you will get an error with status 400 and a brief description of the problem and how to correct it.

For example, the following request is not formatted correctly since JSON does not allow trailing commas.

{ "query": { "location": ["San Francisco"] }, }

Please follow the instructions in the response to fix the formatting issue.

{ "detail": "JSON parse error - Expecting property name enclosed in double quotes: line 5 column 1 (char 50)" }

Another common error is including a non-existent search term.

{ "query": { "oops": ["😤"], "nope": ["😱"] } }

The resulting error will explain which fields are invalid.

{ "query": { "non_field_errors": [ "invalid fields: oops, nope" ] } }

Examples

curl -X POST -H "Api-Key: 3e7k0123456789abcdef0123456789abcdef" -H "Content-Type: application/json" -d '{"query": {"name": ["john smith"]}, "page_size": 1}' https://api.rocketreach.co/api/v2/person/search

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)

Examples

More detailed examples are listed below.

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