openapi: 3.1.0
info:
title: RocketReach Account People Data API API
version: 1.0.0
description: Retrieve and manage RocketReach API account details, lookup quotas, plan usage, billing email, and webhook configuration.
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: []
tags:
- name: People Data API
paths:
/person/lookup:
get:
operationId: create_person_lookup
description: Person Enrichment API
summary: People Lookup API
parameters:
- in: query
name: current_employer
schema:
type: string
minLength: 1
description: 'Current employer of the desired profile. Must specify along with `name`.
- Example: `RocketReach`'
- in: query
name: email
schema:
type: string
format: email
minLength: 1
description: 'An email address for the desired profile.
- Example: `jamie@rocketreach.co`'
- in: query
name: id
schema:
type: integer
description: 'RocketReach internal unique profile ID.
- Example: `123456`'
- in: query
name: linkedin_ext_url
schema:
type: string
pattern: ''
minLength: 1
description: linkedin_ext_url deprecated, please use `linkedin_url` instead
deprecated: true
- in: query
name: linkedin_url
schema:
type: string
pattern: ''
minLength: 1
description: 'LinkedIn URL of the desired profile.
- Example: `www.linkedin.com/in/jamesgullbrand`'
- in: query
name: lookup_type
schema:
enum:
- standard
- premium
- premium (feeds disabled)
- bulk
- phone
- enrich
- ''
- null
type:
- string
- 'null'
description: 'Lookup type for the request
* `standard` - standard
* `premium` - premium
* `premium (feeds disabled)` - premium (feeds disabled)
* `bulk` - bulk
* `phone` - phone
* `enrich` - enrich'
- in: query
name: name
schema:
type: string
minLength: 1
description: 'Name of the desired profile. Must specify along with `current_employer`.
- Example: `Jamie Gullbrand`'
- in: query
name: npi_number
schema:
type: integer
description: 'An NPI number for the desired profile (US healthcare professional).
- Example: `1234567890`'
- in: query
name: return_cached_emails
schema:
type: boolean
default: true
description: 'Controls whether cached emails are included in the initial response when `lookup status = progress`. When set to `false`, all email fields will be null until the lookup is complete and all emails are fully verified. Use /checkStatus or Webhooks to retrieve the completed response with fully verified emails (`status = complete`). Defaults to `true`.
<b>NOTE: Default will change to false on September 1st, 2026. No cached emails will be returned in the initial response. Use /checkStatus or webhooks to retrieve fully verified emails.</b>'
- in: query
name: title
schema:
type: string
minLength: 1
description: 'Job title of the desired profile.
- Example: `Product Manager`'
- in: query
name: webhook_id
schema:
type: integer
description: Your webhook's unique ID number. Find it in your API Usage & Settings page.
tags:
- People Data API
security:
- RocketReachAPIKey: []
responses:
'200':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/ProfileAPICompiledCompany'
description: Success. Returns the profile data for the person lookup.
'400':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Bad Request. The request is malformed or missing required parameters.
'401':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Unauthorized. API Key is missing or invalid.
'403':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Forbidden. API Key lacks permission to perform this action.
'404':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Not Found. The requested resource (e.g., profile) does not exist.
'429':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Too Many Requests. API request limit reached -- slow down requests.
'500':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Internal Server Error. Unexpected error on RocketReach servers. Try again later.
/person/checkStatus:
get:
operationId: check_person_lookup_status
description: Check Person Lookup Status
summary: People Lookup Status API
parameters:
- in: query
name: ids
schema:
type: array
items:
type: integer
description: List of Profile IDs
tags:
- People Data API
security:
- RocketReachAPIKey: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ProfileAPICompiledCompany'
description: Success. Returns the status and profile data of the requested profiles.
'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.
/bulkLookup:
post:
operationId: create_person_bulk_lookup
description: Bulk People Lookup by Criteria
summary: Bulk People Lookup API
tags:
- People Data API
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/APIBulkLookupQuery'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/APIBulkLookupQuery'
multipart/form-data:
schema:
$ref: '#/components/schemas/APIBulkLookupQuery'
required: true
security:
- RocketReachAPIKey: []
responses:
'200':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Success. Bulk lookup request accepted
'400':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Bad Request. The request is malformed or missing required parameters.
'401':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Unauthorized. API Key is missing or invalid.
'403':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Forbidden. API Key lacks permission to perform this action.
'404':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Not Found. The requested resource (e.g., profile) does not exist.
'429':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Too Many Requests. API request limit reached -- slow down requests.
'500':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Internal Server Error. Unexpected error on RocketReach servers. Try again later.
/profile-company/lookup:
get:
operationId: create_person_and_company_lookup
description: Person and Company Lookup
summary: People and Company Lookup API
parameters:
- in: query
name: current_employer
schema:
type: string
minLength: 1
description: 'Current employer of the desired profile. Must specify along with `name`.
- Example: `RocketReach`'
- in: query
name: email
schema:
type: string
format: email
minLength: 1
description: 'An email address for the desired profile.
- Example: `jamie@rocketreach.co`'
- in: query
name: id
schema:
type: integer
description: 'RocketReach internal unique profile ID.
- Example: `123456`'
- in: query
name: linkedin_ext_url
schema:
type: string
pattern: ''
minLength: 1
description: linkedin_ext_url deprecated, please use `linkedin_url` instead
deprecated: true
- in: query
name: linkedin_url
schema:
type: string
pattern: ''
minLength: 1
description: 'LinkedIn URL of the desired profile.
- Example: `www.linkedin.com/in/jamesgullbrand`'
- in: query
name: lookup_type
schema:
enum:
- standard
- premium
- premium (feeds disabled)
- bulk
- phone
- enrich
- ''
- null
type:
- string
- 'null'
description: 'Lookup type for the request
* `standard` - standard
* `premium` - premium
* `premium (feeds disabled)` - premium (feeds disabled)
* `bulk` - bulk
* `phone` - phone
* `enrich` - enrich'
- in: query
name: name
schema:
type: string
minLength: 1
description: 'Name of the desired profile. Must specify along with `current_employer`.
- Example: `Jamie Gullbrand`'
- in: query
name: npi_number
schema:
type: integer
description: 'An NPI number for the desired profile (US healthcare professional).
- Example: `1234567890`'
- in: query
name: return_cached_emails
schema:
type: boolean
default: true
description: 'Controls whether cached emails are included in the initial response when `lookup status = progress`. When set to `false`, all email fields will be null until the lookup is complete and all emails are fully verified. Use /checkStatus or Webhooks to retrieve the completed response with fully verified emails (`status = complete`). Defaults to `true`.
<b>NOTE: Default will change to false on September 1st, 2026. No cached emails will be returned in the initial response. Use /checkStatus or webhooks to retrieve fully verified emails.</b>'
- in: query
name: title
schema:
type: string
minLength: 1
description: 'Job title of the desired profile.
- Example: `Product Manager`'
- in: query
name: webhook_id
schema:
type: integer
description: Your webhook's unique ID number. Find it in your API Usage & Settings page.
tags:
- People Data API
security:
- RocketReachAPIKey: []
responses:
'200':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/ProfileAPISerializerWithCompiledCompany'
description: Success. Returns the profile data and company data for the person / company lookup.
'400':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Bad Request. The request is malformed or missing required parameters.
'401':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Unauthorized. API Key is missing or invalid.
'403':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Forbidden. API Key lacks permission to perform this action.
'404':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Not Found. The requested resource (e.g., profile) does not exist.
'429':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Too Many Requests. API request limit reached -- slow down requests.
'500':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Internal Server Error. Unexpected error on RocketReach servers. Try again later.
/universal/person/lookup:
get:
operationId: create_universal_person_lookup
description: Person Enrichment API
summary: ⭐ Universal People Lookup API
parameters:
- in: query
name: current_employer
schema:
type: string
minLength: 1
description: 'Current employer of the desired profile. Must specify along with `name`.
- Example: `RocketReach`'
- in: query
name: email
schema:
type: string
format: email
minLength: 1
description: 'An email address for the desired profile.
- Example: `jamie@rocketreach.co`'
- in: query
name: id
schema:
type: integer
description: 'RocketReach internal unique profile ID.
- Example: `123456`'
- in: query
name: linkedin_ext_url
schema:
type: string
pattern: ''
minLength: 1
description: linkedin_ext_url deprecated, please use `linkedin_url` instead
deprecated: true
- in: query
name: linkedin_url
schema:
type: string
pattern: ''
minLength: 1
description: 'LinkedIn URL of the desired profile.
- Example: `www.linkedin.com/in/jamesgullbrand`'
- in: query
name: metadata
schema:
type:
- object
- 'null'
additionalProperties: {}
description: User metadata about the profile, such as external ids, tags, notes, etc.
- in: query
name: name
schema:
type: string
minLength: 1
description: 'Name of the desired profile. Must specify along with `current_employer`.
- Example: `Jamie Gullbrand`'
- in: query
name: npi_number
schema:
type: integer
description: 'An NPI number for the desired profile (US healthcare professional).
- Example: `1234567890`'
- in: query
name: return_cached_emails
schema:
type: boolean
default: true
description: 'Controls whether cached emails are included in the initial response when `lookup status = progress`. When set to `false`, all email fields will be null until the lookup is complete and all emails are fully verified. Use /checkStatus or Webhooks to retrieve the completed response with fully verified emails (`status = complete`). Defaults to `true`.
<b>NOTE: Default will change to false on September 1st, 2026. No cached emails will be returned in the initial response. Use /checkStatus or webhooks to retrieve fully verified emails.</b>'
- in: query
name: reveal_detailed_person_enrichment
schema:
type: boolean
default: false
description: Whether to reveal the detailed person enrichment data for the desired profile
- in: query
name: reveal_healthcare_enrichment
schema:
type: boolean
default: false
description: Whether to reveal the healthcare enrichment data for the desired profile
- in: query
name: reveal_personal_email
schema:
type: boolean
default: false
description: Whether to reveal the personal email enrichment data for the desired profile
- in: query
name: reveal_phone
schema:
type: boolean
default: false
description: Whether to reveal the phone enrichment data for the desired profile
- in: query
name: reveal_professional_email
schema:
type: boolean
default: false
description: Whether to reveal the professional email enrichment data for the desired profile
- in: query
name: title
schema:
type: string
minLength: 1
description: 'Job title of the desired profile.
- Example: `Product Manager`'
- in: query
name: webhook_id
schema:
type: integer
description: Your webhook's unique ID number. Find it in your API Usage & Settings page.
tags:
- People Data API
security:
- RocketReachAPIKey: []
responses:
'200':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/UniversalCreditPersonLookupOutputWithOptionalMetadata'
description: Success. Returns the profile data for the person lookup.
'400':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Bad Request. The request is malformed or missing required parameters.
'401':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Unauthorized. API Key is missing or invalid.
'403':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Forbidden. API Key lacks permission to perform this action.
'404':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Not Found. The requested resource (e.g., profile) does not exist.
'429':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Too Many Requests. API request limit reached -- slow down requests.
'500':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Internal Server Error. Unexpected error on RocketReach servers. Try again later.
/universal/person/bulk_lookup:
post:
operationId: create_universal_person_bulk_lookup
description: Bulk People Lookup by Criteria
summary: ⭐ Universal Bulk People Lookup API
tags:
- People Data API
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UniversalCreditAPIBulkLookupQuery'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/UniversalCreditAPIBulkLookupQuery'
multipart/form-data:
schema:
$ref: '#/components/schemas/UniversalCreditAPIBulkLookupQuery'
required: true
security:
- RocketReachAPIKey: []
responses:
'200':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Success. Bulk lookup request accepted
'400':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Bad Request. The request is malformed or missing required parameters.
'401':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Unauthorized. API Key is missing or invalid.
'403':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Forbidden. API Key lacks permission to perform this action.
'404':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Not Found. The requested resource (e.g., profile) does not exist.
'429':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Too Many Requests. API request limit reached -- slow down requests.
'500':
headers:
RR-Request-ID:
schema:
type: string
format: uuid
description: Lookup unique identifier, will also be sent in the header of webhook.
description: Internal Server Error. Unexpected error on RocketReach servers. Try again later.
/universal/person/check_status:
get:
operationId: check_universal_person_lookup_status
description: Check Universal Person Lookup Status
summary: ⭐ Universal People Lookup Status API
parameters:
- in: query
name: ids
schema:
type: array
items:
type: integer
description: List of Profile IDs
tags:
- People Data API
security:
- RocketReachAPIKey: []
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UniversalCreditPersonLookupOutput'
description: Success. Returns the status and profile data of the requested profiles.
'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.
/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:
schemas:
StatusEnum:
enum:
- complete
- progress
- searching
- not queued
type: string
ProfileAPICompiledCompany:
type: object
properties:
profile_list:
allOf:
- $ref: '#/components/schemas/ProfileListAPI'
readOnly: true
description: Profile List this contact was added to.
id:
# --- truncated at 32 KB (103 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/rocketreach/refs/heads/main/openapi/rocketreach-people-data-api-api-openapi.yml