---
updatedAt: 2026-04-23T14:43:46.000Z
agentTools:
projectIndex: https://docs.rocketreach.co/llms.txt
---
# People Lookup API
Person Enrichment API
Using this endpoint consumes **export credits**. You can check your current usage via the [Account Endpoint](rocketreach-api-account).
Provide identifiers such as name, employer, or location to the RocketReach People Lookup API to quickly retrieve matching professional profiles.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "RocketReach API",
"version": "1.0.0",
"description": "The RocketReach API lets you search and retrieve contact info for 700M+ professionals and 35M\n companies. Manage API settings, track usage, and find your API key on the account page.\n All API calls require authentication via API key.\n If you have any questions, please reach out to our team at api@rocketreach.co.\n Quickstart\n 1. Create an API key: Select “Generate New API Key” on your Account Settings page\n 2. Test API Key: You can test API endpoints directly in our documentation without writing a single line of code.\n - Select an endpoint (GET /person/lookup for example)\n - Select “Try It”\n - Enter your API Key to send the request\n 3. Create Webhook (optional, but recommended): We offer a webhook solution for person lookups so clients do not need to poll the check status endpoint until their results are available.\n - To set up a webhook, go to your API settings. Enter your server's callback URL into the field, and hit \"Create\".\n - For each URL created, you can perform some basic maintenance tasks:\n - Test the webhook - we will attempt to send a basic JSON payload to the URL.\n - Disable/enable - if you may use this URL in the future, this is an option to temporarily disable it.\n - Delete - if you no longer plan using this URL, it can be deleted.\n Rate Limits\n - [Rate Limits](../guides/rate-limits.md)\n FAQ\n - [FAQ](../guides/faq.md)\n ",
"contact": {
"name": "RocketReach Support",
"email": "api@rocketreach.co"
}
},
"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`.\n- Example: `RocketReach`"
},
{
"in": "query",
"name": "email",
"schema": {
"type": "string",
"format": "email",
"minLength": 1
},
"description": "An email address for the desired profile.\n- Example: `jamie@rocketreach.co`"
},
{
"in": "query",
"name": "id",
"schema": {
"type": "integer"
},
"description": "RocketReach internal unique profile ID.\n- 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.\n- 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\n\n* `standard` - standard\n* `premium` - premium\n* `premium (feeds disabled)` - premium (feeds disabled)\n* `bulk` - bulk\n* `phone` - phone\n* `enrich` - enrich"
},
{
"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`.\n- Example: `Jamie Gullbrand`"
},
{
"in": "query",
"name": "npi_number",
"schema": {
"type": "integer"
},
"description": "An NPI number for the desired profile (US healthcare professional).\n- Example: `1234567890`"
},
{
"in": "query",
"name": "phone",
"schema": {
"type": "string",
"minLength": 1
},
"description": "A phone number for the desired profile in either E.164 format or international format.\n- Example: `+15555555555`"
},
{
"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`."
},
{
"in": "query",
"name": "title",
"schema": {
"type": "string",
"minLength": 1
},
"description": "Job title of the desired profile.\n- 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/ProfileAPIWithMetadataCompiledCompany"
}
}
},
"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."
}
}
}
}
},
"components": {
"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"
}
}
},
"ProfileAPIWithMetadataCompiledCompany": {
"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
},
"status": {
"type": "string",
"readOnly": true,
"description": "Either \"complete\", \"progress\", \"searching\" or \"not queued\". A status other than \"complete\" indicates the lookup is not finished, and the contact info is not fully available yet."
},
"name": {
"type": [
"string",
"null"
],
"maxLength": 128
},
"profile_pic": {
"type": [
"string",
"null"
],
"readOnly": true,
"description": "profile_pic deprecated",
"deprecated": true
},
"linkedin_url": {
"type": [
"string",
"null"
],
"readOnly": true
},
"connections": {
"type": "integer",
"description": "Number of LinkedIn connections for this profile"
},
"links": {
"type": "object",
"additionalProperties": {}
},
"location": {
"type": [
"string",
"null"
],
"maxLength": 256
},
"current_title": {
"type": [
"string",
"null"
],
"readOnly": true
},
"current_employer": {
"type": [
"string",
"null"
],
"readOnly": true
},
"current_employer_id": {
"type": "integer"
},
"current_employer_domain": {
"type": [
"string",
"null"
],
"description": "This person's company's domain name."
},
"current_employer_website": {
"type": [
"string",
"null"
],
"description": "This person's company's website."
},
"current_employer_linkedin_url": {
"type": [
"string",
"null"
],
"description": "This person's company's LinkedIn URL."
},
"current_employer_industry": {
"type": [
"string",
"null"
],
"description": "This person's company's industry."
},
"job_history": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobHistoryAPICompiledCompany"
}
},
"education": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EducationAPI"
}
},
"skills": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
}
},
"birth_year": {
"type": "integer"
},
"region_latitude": {
"type": [
"number",
"null"
],
"format": "double"
},
"region_longitude": {
"type": [
"number",
"null"
],
"format": "double"
},
"city": {
"type": [
"string",
"null"
],
"maxLength": 128
},
"region": {
"type": [
"string",
"null"
],
"maxLength": 3
},
"country": {
"type": "string",
"readOnly": true
},
"country_code": {
"type": [
"string",
"null"
],
"maxLength": 2
},
"npi_data": {
"type": "object",
"description": "The format of the NPI data that is serialized to the UI on the search page.",
"properties": {
"npi_number": {
"type": "string"
},
"credentials": {
"type": "string"
},
"license_number": {
"type": "string"
},
"specialization": {
"type": "string"
}
},
"readOnly": true
},
"tags": {
"type": "string",
"readOnly": true
},
"return_cached_emails": {
"type": "boolean",
"readOnly": true,
"description": "Indicates if cached emails were returned in the initial synchronous response. If false, email fields will be null until the lookup is complete."
},
"linkedin_url_active": {
"type": "boolean",
"description": "Indicates if the LinkedIn profile exists or is no longer available.\"\n* `True` = Active (as of last update)\n* `False` = Unavailable (as of last update)",
"readOnly": true
},
"recommended_email": {
"type": [
"string",
"null"
],
"readOnly": true
},
"recommended_personal_email": {
"type": [
"string",
"null"
],
"readOnly": true
},
"recommended_professional_email": {
"type": [
"string",
"null"
],
"readOnly": true
},
"current_work_email": {
"type": [
"string",
"null"
],
"readOnly": true
},
"current_personal_email": {
"type": [
"string",
"null"
],
"readOnly": true
},
"emails": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProfileEmailAPI"
},
"readOnly": true
},
"phones": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProfilePhoneAPI"
},
"readOnly": true
},
"current_employer_phone": {
"allOf": [
{
"$ref": "#/components/schemas/ProfilePhoneAPI"
}
],
"readOnly": true,
"description": "Office phone number object for the profile's current employer. These are not direct lines to the person."
},
"metadata": {
"type": "object",
"additionalProperties": {},
"readOnly": true,
"description": "User metadata about the profile, such as external ids, tags, notes, etc."
}
}
},
"ProfileEmailAPI": {
"type": "object",
"properties": {
"email": {
"type": "string",
"readOnly": true,
"description": "The email address.\n- Example: `info@rocketreach.co`",
"example": "info@rocketreach.co"
},
"smtp_valid": {
"type": [
"string",
"null"
],
"readOnly": true,
"description": "SMTP validation result. Options are `valid`, `invalid`, `accept-all`, or `unknown`.\n- Example: `valid`",
"example": "valid"
},
"type": {
"type": [
"string",
"null"
],
"readOnly": true,
"description": "The type of email address. Options are `personal`, `professional`, `disposable`, or `role-based`.\n- Example: `professional`",
"example": "professional"
},
"last_validation_check": {
"type": [
"string",
"null"
],
"readOnly": true,
"description": "Timestamp of the last validation check of the email address.\n- Example: `2026-01-01T12:00:00Z`",
"example": "2026-01-01T12:00:00Z"
},
"grade": {
"type": "string",
"readOnly": true,
"description": "RocketReach internal grade for the email. See Email Grades for details.",
"example": "A-"
}
}
},
"ProfileListAPI": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"readOnly": true,
"description": "RocketReach internal unique profile list ID",
"example": 123456
},
"name": {
"type": "string",
"readOnly": true,
"description": "Name of the profile list",
"example": "Example List Name"
}
}
},
"ProfilePhoneAPI": {
"type": "object",
"properties": {
"number": {
"type": "string",
"description": "The phone number in international format\n- Example: `+1 234-555-6789`",
"example": "+1 234-555-6789"
},
"e164": {
"type": [
"string",
"null"
],
"description": "The phone number in E.164 format\n- Example: `+12345556789`",
"example": "+12345556789"
},
"country_code": {
"type": [
"string",
"null"
],
"description": "The country code associated with the phone number\n- Example: `1` for United States",
"example": "1"
},
"extension": {
"type": [
"string",
"null"
],
"description": "The phone extension, if applicable\n- Example: `123`",
"example": "123"
},
"type": {
"type": "string",
"default": "other",
"description": "The type of phone number. Options are `mobile`, `direct dial`, or `other`.\n- Example: `mobile`",
"example": "mobile"
},
"grade": {
"type": "string",
"description": "Phone confidence grade.\n- `A` = Best: Confirmed as valid phone and strong identity match signals.\n- `A-` = Likely: Confirmed as valid phone, but unable to confirm identity.\n- `B` = Possible: Worth trying, especially if better options are not available.",
"example": "A"
},
"validity": {
"type": "string",
"default": "unknown",
"description": "validity deprecated, please use `grade` instead.",
"deprecated": true,
"example": "valid"
},
"recommended": {
"type": "boolean",
"default": false,
"description": "Indicates whether this is the recommended phone number to use as the best option for connecting with the person.\n- Example: `true`",
"example": true
},
"premium": {
"type": "boolean",
"default": false,
"description": "`premium` deprecated",
"deprecated": true,
"example": true
},
"last_checked": {
"type": "string",
"format": "date-time",
"description": "`last_checked` deprecated",
"deprecated": true
}
}
}
},
"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."
}
}
},
"servers": [
{
"url": "https://api.rocketreach.co/api/v2",
"description": "v2 Production Server"
}
]
}
```