Search RocketReach's 700M+ professional profiles using filters such as name, current employer, title, location, skills, industry, and education. Returns paginated lists of profile summaries that can then be passed to the People Lookup API for full contact enrichment.
openapi: 3.1.0
info:
title: RocketReach People Search API
version: 1.0.0
description: Search RocketReach's 700M+ professional profiles using filters such as name, current employer, title, location,
and skills.
contact:
name: RocketReach Support
email: api@rocketreach.co
license:
name: Proprietary
termsOfService: https://rocketreach.co/legal/terms-of-use
servers:
- url: https://api.rocketreach.co/api/v2
description: RocketReach v2 API
- url: https://api.rocketreach.co/v1/api
description: RocketReach v1 API
security:
- RocketReachAPIKey: []
paths:
/person/search:
post:
operationId: create_person_search
description: Search People by Criteria
summary: People Search API
tags:
- People Data API
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/APISearchInput'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/APISearchInput'
multipart/form-data:
schema:
$ref: '#/components/schemas/APISearchInput'
required: true
security:
- RocketReachAPIKey: []
responses:
'201':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ProfileSearchResultSerializerBase'
description: Success. People search request accepted
'400':
description: Bad Request. The request is malformed or missing required parameters.
'401':
description: Unauthorized. API Key is missing or invalid.
'403':
description: Forbidden. API Key lacks permission to perform this action.
'404':
description: Not Found. The requested resource (e.g., profile) does not exist.
'429':
description: Too Many Requests. API request limit reached -- slow down requests.
'500':
description: Internal Server Error. Unexpected error on RocketReach servers. Try again later.
x-code-samples:
- lang: bash
source: "\n curl --request 'POST' --location 'https://api.rocketreach.co/api/v2/person/search'\\\n\
\ --header 'Content-Type: application/json'\\\n --data '{\"query\":{\"keyword\"\
:[\"Marc Benioff\"]},\"order_by\":\"popularity\"}'\n "
- lang: Python
source: "\n search = rr.person.search()\n search = search.filter(current_title='Software\
\ Engineer')\n search = search.options(order_by='popularity')\n result = search.execute()\n\
\ result.people\n "
- lang: Javascript
source: "\n let search = rr.people.search()\n search = search.include({name: \"John\
\ Smith\"})\n search = search.include({currentTitle: \"CEO\"})\n const results = \
\ await search.execute()\n "
/universal/person/search:
post:
operationId: create_universal_person_search
description: Search People by Criteria
summary: ⭐ Universal People Search API
tags:
- People Data API
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/APIUniversalCreditsSearchInput'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/APIUniversalCreditsSearchInput'
multipart/form-data:
schema:
$ref: '#/components/schemas/APIUniversalCreditsSearchInput'
required: true
security:
- RocketReachAPIKey: []
responses:
'201':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UniversalCreditPersonSearchOutput'
description: Success. People search request accepted
'400':
description: Bad Request. The request is malformed or missing required parameters.
'401':
description: Unauthorized. API Key is missing or invalid.
'403':
description: Forbidden. API Key lacks permission to perform this action.
'404':
description: Not Found. The requested resource (e.g., profile) does not exist.
'429':
description: Too Many Requests. API request limit reached -- slow down requests.
'500':
description: Internal Server Error. Unexpected error on RocketReach servers. Try again later.
x-code-samples:
- lang: bash
source: "\n curl --request 'POST' --location 'https://api.rocketreach.co/api/v2/universal/person/search'\\\
\n --header 'Content-Type: application/json'\\\n --data '{\"query\":{\"keyword\"\
:[\"Marc Benioff\"]},\"order_by\":\"popularity\"}'\n "
components:
securitySchemes:
RocketReachAPIKey:
type: apiKey
name: Api-Key
in: header
description: RocketReach account API key. You can locate your API Key from the "My API Key" section of the [API account
page](https://rocketreach.co/account?section=nav_gen_api). Requests to the API are authenticated using the Api-Key
request header. Older clients may use an `api_key` query parameter, but this behavior is deprecated.
schemas:
APISearchInput:
type: object
properties:
start:
type: integer
maximum: 10000
minimum: 1
default: 1
description: Start index of the request results (counting from 1)
page_size:
type: integer
maximum: 100
minimum: 1
default: 10
description: Maximum number of results to return per page [1-100]
query:
$ref: '#/components/schemas/PersonQuery'
description: Search query object for the request
order_by:
allOf:
- $ref: '#/components/schemas/OrderByEnum'
default: relevance
description: Specifies the ordering of search results. "popularity" matches the default ordering of the Search web
app.
example: popularity
OrderByEnum:
enum:
- relevance
- popularity
- score
type: string
PersonQuery:
type: object
properties:
all_skills:
type: array
items:
type: string
description: 'Include profiles with all of these skills (Uses `AND` logic).
- Example: `[''python'', ''sql'', ''machine learning'']`'
example:
- python
- sql
- machine learning
company_competitors:
type: array
items:
type: string
description: 'Include profiles with employers who have these competitors
- Example: `[''homedepot.com'']`'
example:
- homedepot.com
company_country_code:
type: array
items:
type: string
description: 'Include profiles with employers located in these country codes
- Example: `[''US'']`'
example:
- US
company_domain:
type: array
items:
type: string
description: 'Include profiles with employers who have these company domains
- Example: `[''rocketreach.co'']`'
example:
- rocketreach.co
company_email:
type: array
items:
type: string
description: 'Include profiles with employers who have these company emails
- Example: `[''info@rocketreach.co'']`'
example:
- info@rocketreach.co
company_funding_max:
type: array
items:
type: string
description: 'Include profiles with employers below this amount of funding
- Example: `[''50000000'']`'
example:
- '50000000'
company_funding_min:
type: array
items:
type: string
description: 'Include profiles with employers above this amount of funding
- Example: `[''1000000'']`'
example:
- '1000000'
company_geo:
type: array
items:
type: string
description: Include results matching company_geo.
company_id:
type: array
items:
type: string
description: 'Include profiles with employed by these company IDs
- Example: `[''123456'']`'
example:
- '123456'
company_industry:
type: array
items:
type: string
description: 'Include profiles with employers in these industries. See the full list of industries [here](https://docs.google.com/spreadsheets/d/1cYz3FwtNEWW7z9otNNZRIILQ63_hM1LQ9SgsXWayaaI/edit?gid=0#gid=0).
- Example: `[''Software Engineering'']`'
example:
- Software Engineering
company_industry_keywords:
type: array
items:
type: string
description: 'Include profiles with employers with these industry keywords
- Example: `[''SaaS'', ''B2B'']`'
example:
- SaaS
- B2B
company_intent:
type: array
items:
type: string
description: 'Search across 37,000 intent topics found [here](https://docs.google.com/spreadsheets/d/1nnk8ZOLr9GUzrPNy1pG_N_gVIhDpkc5XjE3Hh4J8M00/edit?gid=761283207#gid=761283207).
Intent is only available on certain plans. Please reach out to our team to learn more..
- Example: `[''hiring'']`'
example:
- hiring
company_job_posting_signal:
type: array
items:
type: string
description: 'Hiring signals that identify companies that are actively building out specific departments. Full list
of categories [here](https://docs.google.com/spreadsheets/d/1EZPVnOftbHNwDm0aXjiJ79dSpqcZ4JLnrNJPZxKXi5Q/edit?gid=2100271042#gid=2100271042).
- Example: `[''Accounting Roles::one_month'']`'
example:
- Accounting Roles::one_month
company_list:
type: array
items:
type: string
description: 'Transforms [ company_list ] search terms into a list of [ company_id ] search terms.
- Example: `[''Example Company List'']`'
example:
- Example Company List
company_list_id:
type: array
items:
type: string
description: 'Include results matching company_list_id.
- Example: `[''12345'']`'
example:
- '12345'
company_naics_code:
type: array
items:
type: string
description: 'Include profiles with employers with these NAICS codes
- Example: `[''541330'', ''541512'']`'
example:
- '541330'
- '541512'
company_name:
type: array
items:
type: string
description: 'Include profiles employed by these company names
- Example: `[''RocketReach'']`'
example:
- RocketReach
company_news_signal:
type: array
items:
type: string
description: 'Search on news events within the 25 categories listed [here](https://docs.google.com/spreadsheets/d/1EZPVnOftbHNwDm0aXjiJ79dSpqcZ4JLnrNJPZxKXi5Q/edit?gid=577464958#gid=577464958").
- Example: `[''Funding::one_month'']`'
example:
- Funding::one_month
company_news_timestamp:
type: array
items:
type: string
description: company_news_timestamp deprecated, please use `company_news_signal`
deprecated: true
example:
- mergers & acquisitions::one_month
company_publicly_traded:
type: array
items:
type: string
description: 'Include results matching company_publicly_traded.
- Example: `[''true'']`'
example:
- 'true'
company_revenue:
type: array
items:
type: string
description: 'Include profiles with employers with these revenue values.
- Example: `[''10000000-50000000'']`'
example:
- 10000000-50000000
company_sic_code:
type: array
items:
type: string
description: 'Include profiles with employers with these SIC codes.
- Example: `[''7372'']`'
example:
- '7372'
company_size:
type: array
items:
type: string
description: 'Include profiles with employers with these sizes.
- Example: `[''51-200'']`'
example:
- 51-200
company_tag:
type: array
items:
type: string
description: 'Include profiles with employers with these company tags.
- Example: `[''unicorn'']`'
example:
- unicorn
company_website_url:
type: array
items:
type: string
description: 'Include profiles with employers with these website URLs.
- Example: `[''rocketreach.co'']`'
example:
- rocketreach.co
connections:
type: array
items:
type: string
description: 'Include profiles with these connections.
- Example: `[''500+'']`'
example:
- 500+
contact_method:
type: array
items:
type: string
description: 'Include profiles with these contact methods Options are: `mobile`, `phone`, `personal email`, and
`work email`. Available with both AND and OR logic.
- Example: `["work email OR personal email"]` or `["mobile AND personal email"]`'
example:
- work email
current_or_previous_title:
type: array
items:
type: string
description: 'Include results matching current or previous job titles.
- Example: `[''VP of Sales'']`'
example:
- VP of Sales
current_title:
type: array
items:
type: string
description: 'Include profiles with these current job titles.
- Example: `[''Product Manager'']`'
example:
- Product Manager
degree:
type: array
items:
type: string
description: 'Include profiles with these degrees.
- Example: `[''Bachelors'']`'
example:
- Bachelors
department:
type: array
items:
type: string
description: 'Include profiles in these company departments. See the full list of departments [here](https://docs.google.com/spreadsheets/d/1EZPVnOftbHNwDm0aXjiJ79dSpqcZ4JLnrNJPZxKXi5Q/edit?gid=0#gid=0).
- Example: `[''Product Management'']`'
example:
- Product Management
description:
type: array
items:
type: string
description: 'Include profiles with these descriptions.
- Example: `[''Experienced software engineer with a focus on backend development'']`'
example:
- Experienced software engineer with a focus on backend development
domain:
type: array
items:
type: string
description: 'Include profiles with these domains.
- Example: `[''rocketreach.co'']`'
example:
- rocketreach.co
email:
type: array
items:
type: string
description: 'Include profiles with these emails.
- Example: `[''john.doe@rocketreach.co'']`'
example:
- john.doe@rocketreach.co
email_grade:
type:
- string
- 'null'
description: 'Specifies the minimum email confidence grade that a profile must have. Note: Email grades may be revalidated
during lookup. As a result, you may occasionally see profiles whose email grade no longer matches the grade filter
used in your search. Use the following format to specify personal or professional email grades: `<grade>::<modifier>`
- Allowed Grades: A, A-, or B.
- Allowed Modifiers: professional only, personal only
- Example: `''A-''` or `''A-::professional only''`'
example: A-
employer:
type: array
items:
type: string
description: 'Include profiles employed by these companies.
- Example: `[''RocketReach'']`'
example:
- RocketReach
geo:
type: array
items:
type: string
description: 'Include profiles located in these geographies.
- Example: `[''North America'']`'
example:
- North America
growth:
type: array
items:
type: string
description: 'Include growth numbers for specific departments and time ranges.
<b>Format:</b> `min_percentage_growth-max_percentage_growth::Department,TimeRange`
* min_percentage_growth: Minimum growth percentage to filter profiles
* max_percentage_growth: Maximum growth percentage to filter profiles
* Department: Name of the company department (e.g., Engineering, Sales)
* TimeRange: Duration for the growth metric (e.g., six_months, one_year)
- Example: `[''5-30::Engineering,six_months'']`
- Example: `[''-10--20::Sales,one_year'']`'
example:
- 5-30::Engineering,six_months
handle:
type: array
items:
type: string
description: 'Include results matching handle.
- Example: `[''johndoe'']`'
example:
- johndoe
health_credentials:
type: array
items:
type: string
description: 'Include profiles with these health credentials. Only available on certain plans. Please reach out
to our team to learn more.
- Example: `[''MD'', ''RN'', ''PhD'']`'
example:
- MD
- RN
- PhD
health_license:
type: array
items:
type: string
description: 'Include profiles with these health licenses. Only available on certain plans. Please reach out to
our team to learn more.
- Example: `[''MA12345'']`'
example:
- MA12345
health_npi:
type: array
items:
type: string
description: 'Include profiles with these health NPIs. Only available on certain plans. Please reach out to our
team to learn more.
- Example: `[''1234567890'']`'
example:
- '1234567890'
health_specialization:
type: array
items:
type: string
description: 'Include profiles with these health specializations. Only available on certain plans. Please reach
out to our team to learn more.
- Example: `[''Cardiology'']`'
example:
- Cardiology
id:
type: array
items:
type: string
description: 'Include profiles with these RocketReach Profile IDs.
- Example: `[''123456'']`'
example:
- '123456'
job_change_range_days:
type: array
items:
type: string
description: job_change_range_days deprecated, please use `job_change_signal`
deprecated: true
example:
- '30'
job_change_signal:
type: array
items:
type: string
description: 'Detect when a contact changes companies or gets promoted (Time window options: one_week, one_month,
three_months)
- Example: `[''Company Change::one_month'']`
- Example: `[''Promotion::one_week'']`
- Example: `[''Company Change AND Promotion::three_months'']`'
example:
- Company Change::one_month
keyword:
type:
- string
- 'null'
description: 'Include results matching keyword.
- Example: `[''data enrichment'']`'
example:
- data enrichment
keywords:
type:
- string
- 'null'
description: 'Include results matching keywords.
- Example: `[''sales prospecting'', ''data enrichment'']`'
example:
- sales prospecting
- data enrichment
link:
type: array
items:
type: string
description: 'Include results matching link.
- Example: `[''https://linkedin.com/in/johndoe'']`'
example:
- https://linkedin.com/in/johndoe
major:
type: array
items:
type: string
description: 'Include profiles with these majors.
- Example: `[''Computer Science'', ''Biology'']`'
example:
- Computer Science
- Biology
management_levels:
type: array
items:
type: string
description: 'Include profiles at these management levels. See the full list of management levels [here](https://docs.google.com/spreadsheets/d/1EZPVnOftbHNwDm0aXjiJ79dSpqcZ4JLnrNJPZxKXi5Q/edit?gid=0#gid=0).
- Example: `[''Director'']`'
example:
- Director
name:
type: array
items:
type: string
description: 'Include profiles with these names.
- Example: `[''John Doe'']`'
example:
- John Doe
phone:
type: array
items:
type: string
description: 'Include profiles with these phone numbers.
- Example: `[''+15555555555'']`'
example:
- '+15555555555'
previous_company_id:
type: array
items:
type: string
description: 'Include profiles who were previously employed at these RocketReach
company IDs.
- Example: `[''123456'']`'
example:
- '123456'
previous_employer:
type: array
items:
type: string
description: 'Include profiles who were previously employed at these companies.
- Example: `[''Google'']`'
example:
- Google
previous_title:
type: array
items:
type: string
description: 'Include results matching previous_title.
- Example: `[''Software Engineer'']`'
example:
- Software Engineer
school:
type: array
items:
type: string
description: 'Include profiles who attended these schools.
- Example: `[''Stanford University'']`'
example:
- Stanford University
skills:
type: array
items:
type: string
description: 'Include profiles listed with any of these skills (Uses `OR` logic).
- Example: `[''Python'', ''SQL'']`'
example:
- Python
- SQL
state:
type: array
items:
type: string
description: 'Include profiles located in these states.
- Example: `[''MA'']`'
example:
- MA
update_time:
type: array
items:
type: string
description: 'Include results that have been updated since the specified date.
- Example: `[''2025-01-01'']`'
example:
- '2025-01-01'
years_experience:
type: array
items:
type: string
description: 'Include profiles with this many years of experience.
- Example: `[''10'']`'
example:
- '10'
ProfileSearchResultSerializerBase:
type: object
properties:
id:
type: integer
readOnly: true
description: RocketReach internal unique profile ID
status:
allOf:
- $ref: '#/components/schemas/StatusEnum'
readOnly: true
description: Status of the profile lookup
name:
type:
- string
- 'null'
maxLength: 128
description: Name of the profile
profile_pic:
type:
- string
- 'null'
readOnly: true
description: URL containing this profile's picture (if available).
links:
type: object
additionalProperties: {}
description: Social media links for the profile
linkedin_url:
type:
- string
- 'null'
readOnly: true
description: LinkedIn URL of the profile
connections:
type: integer
description: Number of LinkedIn connections for this profile
location:
type:
- string
- 'null'
maxLength: 256
description: Location of the profile
city:
type:
- string
- 'null'
maxLength: 128
description: City of the profile
region:
type:
- string
- 'null'
maxLength: 3
description: Region of the profile
country:
type: string
readOnly: true
description: Country code of the profile
country_code:
type:
- string
- 'null'
maxLength: 2
description: Country code of the profile
current_title:
type:
- string
- 'null'
readOnly: true
description: Current job title of the profile
current_employer:
type:
- string
- 'null'
readOnly: true
description: Current employer of the profile
current_employer_domain:
type:
- string
- 'null'
description: Domain for the employer of the profile
current_employer_website:
type:
- string
- 'null'
description: Website for the employer of the profile
teaser:
type:
- object
- 'null'
properties:
emails:
type: array
items:
type: string
phones:
type: array
items:
type: object
properties:
number:
type: string
is_premium:
type: boolean
required:
- is_premium
- number
office_phones:
type: array
items:
type: string
preview:
type: array
items:
type: string
is_premium_phone_available:
type: boolean
personal_emails:
type: array
items:
type: string
professional_emails:
type: array
items:
type: string
readOnly: true
description: Preview contact data for the profile
birth_year:
type: integer
description: Year of birth of the profile
current_employer_id:
type: integer
description: RocketReach internal unique company ID
current_employer_linkedin_url:
type:
- string
- 'null'
description: LinkedIn URL for the employer of the profile
region_latitude:
type:
- number
- 'null'
format: double
description: Latitude of the region of the profile
region_longitude:
type:
- number
- 'null'
format: double
description: Longitude of the region of the profile
suppressed:
type: string
readOnly: true
description: Returns True if this profile is blocked by a suppression list filter
npi_data:
allOf:
- $ref: '#/components/schemas/TypedDict'
readOnly: true
description: List of NPI data objects for the profile
update_time:
type: string
format: date-time
readOnly: true
description: Timestamp of the last update for the profile
example: '2023-10-01T12:00:00Z'
StatusEnum:
enum:
- complete
- progress
- searching
- not queued
type: string
TypedDict:
type: object
properties:
npi_number:
type: string
readOnly: true
description: NPI number of the healthcare provider. An NPI is a unique 10-digit number used to identify health care
providers
example: 1234567890
credentials:
type: string
readOnly: true
description: Professional qualifications or designations earned by a healthcare provider, such as MD, DO, NP, or
RN.
license_number:
type: string
readOnly: true
description: A state-issued number that authorizes a healthcare provider to practice in a specific state or field.
specialization:
type: string
readOnly: true
description: The specific area of medicine or healthcare in which a provider focuses, such as cardiology, pediatrics,
or dermatology.
APIUniversalCreditsSearchInput:
type: object
properties:
start:
type: integer
maximum: 10000
minimum: 1
default: 1
description: Paginate through search results by returning results starting from this value (counting from 1).
page_size:
type: integer
maximum: 100
minimum: 1
default: 100
description: Maximum number of search results to return per page.
query:
$ref: '#/components/schemas/PersonQuery'
order_by:
allOf:
- $ref: '#/components/schemas/OrderByEnum'
default: relevance
description: 'Specifies the ordering of search results. "popularity" matches the default ordering of the Search
web app.
* `relevance` - relevance
* `popularity` - popularity
* `score` - score'
UniversalCreditPersonSearchOutput:
type: object
properties:
id:
type: integer
readOnly: true
description: RocketReach internal unique profile ID
name:
type:
- string
- 'null'
maxLength: 128
description: Name of the profile
profile_pic:
type:
- string
- 'null'
readOnly: true
description: URL containing this profile's picture (if available).
linkedin_url:
type:
- string
- 'null'
readOnly: true
description: LinkedIn URL of the profile
connections:
type: integer
description: Number of LinkedIn connections for this profile
location:
type:
- string
- 'null'
maxLength: 256
description: Location of the profile
city:
type:
- string
- 'null'
maxLength: 128
description: City of the profile
region:
type:
- string
- 'null'
maxLength: 3
description: Region of the profile
country:
type: string
rea
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/rocketreach/refs/heads/main/openapi/rocketreach-people-search-api-openapi.yml