openapi: 3.1.0
info:
title: RocketReach People Lookup API
version: 1.0.0
description: Look up an individual professional's email, phone, social, and full profile from name + employer, LinkedIn
URL, or RocketReach profile ID. Supports single, bulk, and combined person+company lookups, with status polling and webhook
delivery.
contact:
name: RocketReach Support
email: [email protected]
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/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: `[email protected]`'
- 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: `[email protected]`'
- 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
- Company 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: `[email protected]`'
- 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.
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:
EducationAPI:
type: object
properties:
major:
type:
- string
- 'null'
description: Primary field of study of the educational experience
school:
type:
- string
- 'null'
description: School/University of the educational experience
degree:
type:
- string
- 'null'
description: Degree obtained through the educational experience
start:
type:
- integer
- 'null'
description: Start date of the educational experience
end:
type:
- integer
- 'null'
description: End date of the educational experience
JobHistoryAPICompiledCompany:
type: object
properties:
start_date:
type:
- string
- 'null'
description: Start date of the work experience
end_date:
type: string
default: Present
description: End date of the work experience (Present if experience is current)
company:
type:
- string
- 'null'
description: Name of the company
company_name:
type: string
description: Name of the company
company_id:
type:
- integer
- 'null'
description: RocketReach internal unique company ID
company_linkedin_url:
type: string
readOnly: true
description: Linkedin URL of the company
company_city:
type: string
readOnly: true
description: City of the company's location
company_region:
type: string
readOnly: true
description: Region of the company's location
company_country_code:
type: string
readOnly: true
description: Country code of the company's location
department:
type: string
description: Department of the work experience
title:
type: string
description: Job title of the work experience
highest_level:
type: string
description: Highest level of the work experience
description:
type: string
description: Description of the work experience
last_updated:
type: string
format: date-time
description: Timestamp of the last update of this work experience
sub_department:
type:
- string
- 'null'
description: Sub-department of the work experience
is_current:
type: boolean
default: false
description: True if the experience is the profile's current role, False otherwise
ProfileAPICompiledCompany:
type: object
properties:
profile_list:
allOf:
- $ref: '#/components/schemas/ProfileListAPI'
readOnly: true
description: Profile List this contact was added to.
id:
type: integer
readOnly: true
description: RocketReach internal unique profile ID
status:
type: string
readOnly: true
description: Status of the profile lookup. Either "complete", "progress", "searching" or "not queued"
example: progress
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
links:
type: object
additionalProperties: {}
description: Social media links for the profile
location:
type:
- stri
# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/rocketreach/refs/heads/main/openapi/rocketreach-people-lookup-api-openapi.yml