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 like so: {{ getCURL("search",[["keyword" ,"Marc Benioff"], ["order_by", "popularity"]]) }}
which returns: {{ docJSON.marcBenioffSearchResult|json }}

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

Specifying Exact Matches

You can specify exact matches for all your search terms. E.g. The following query matches anyone with 'Marc Benioff' in their name. I.e it will match people named both “Marc Benioff”, “Benioff Marc” and also “Marc Anthony Benioff”. It will also ignore certain typos like “Marck benoiff” etc.

This query matches anyone named 'Marc Benioff'. {{ getCURL("search",[["name" ,"Marc Benioff"]]) }}

This query exact matches anyone with the exact name 'Marc Benioff'. To specify exact matches, add quotes around your search term {{ getCURL("search",[["name" ,"\"Marc Benioff\""]]) }}

This approach works for all other parameters that accept strings. E.g. If you wish to exact match people with current employer: “IBM”, you can use the following query. Note that this will exclude people who work e.g. for "IBM UK". {{ getCURL("search",[["current_employer" ,"\"IBM\""]]) }}

Exclude 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. {{ getCURL("search",[["current_title", "Software Engineer"], ["exclude_current_title", "Senior"], ["exclude_current_title", "Sr"]]) }}

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

If you have multiple parameters with multiple values, it’s interpreted as an “AND” between filters, and “OR” within the filters. E.g. {{ getCURL("search",[["current_employer", "IBM"], ["current_employer", "Google"], ["current_title", "Founder"], ["current_title", "CEO"]]) }} The values returned will satisfy the following logical condition:
(Profile.title == "IBM" OR Profile.title == "GOOGLE") AND (Profile.title == "Founder" OR Profile.title == "CEO")

Pagination

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

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.

Ordering Results

There is a parameter called order_by separate of the query, which takes either popularity or relevance, allowing you to sort results.

Request Body

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.

Numbers with Operators

Some fields, such as company_funding, take strings which are numbers with mathematical operators. For example, here are some valid values:

• "1000000+"
• "<90000000"
• "1000000>="
• "1000000-90000000"

Normalized Titles

A query should specify at most one of current_title and normalized_title. Normalized titles are a relatively new feature. They are intended to reduce the space of titles in a reliable way. As of 2022-04-21, half of person profiles have normalized titles. The full list of current normalized titles is available here. A normalized title must be specified exactly (see below) and will always be matched exactly.

Query Format

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.

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

Errors

If your JSON is not well formatted 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.

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

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

The resulting error will explain which fields are invalid.

Examples