---
updatedAt: 2026-04-23T14:43:46.000Z
agentTools:
projectIndex: https://docs.rocketreach.co/llms.txt
---
# ⭐ Universal Bulk People Lookup API
Bulk People Lookup by Criteria
Universal Credits are not currently available for Essentials, Pro, Ultimate plans. Please instead use: [Bulk People Lookup API](bulk-person-lookup-person-lookup-api)
Using this endpoint consumes **export credits**. You can check your current usage via the [Account Endpoint](get_universal_account).
### 🚨Universal Credits - Updates 🚨
The new Universal Credit system is now live. Account Managers will reach out with more details. You can find more information here: [Universal Credits Overview](/reference/universal-credits-overview)
If you have any questions, please reach out to our team at .
Reminders:
* You must specify at least 1 enrichment type per query to get a response.
* These query parameters are only available to customers that have access to the new universal credit system. If you try to use these without access, you'll receive a 403 Forbidden error.
| Credit Action | Credit Cost | Enrichment Type Query Parameters |
| :----------------------------- | :------------------------------------------------------------ | :----------------------------------------- |
| **Professional Email** | **2 credits / person profile** with verified (A or A-) emails | `reveal_professional_email`=`true` |
| **Personal Email** | **3 credits / person profile** with verified (A or A-) emails | `reveal_personal_email`=`true` |
| **Phone** | **6 credits / person profile** with phones | `reveal_phone`=`true` |
| **Detailed Person Enrichment** | **1 credit / person profile** with enriched information | `reveal_detailed_person_enrichment`=`true` |
| **Healthcare Enrichment** | **1 credit / person profile** with enriched information | `reveal_healthcare_enrichment`=`true` |
***
This endpoint is suited for large numbers of simultaneous lookups. This endpoint requires for at least one webhook URL enabled for this endpoint, or a webhook ID specified. Up to 100 lookups can be performedper batch. There must be at least 10 lookups in a batch. If you need fewer than 10 lookups, please use the Lookup Person endpoint.
## Bulk Lookup Queries
Each query in the queries list has the following parameters. For each query, at least one of the following is required:
* linkedin\_url
* profile\_id
* company and name
* email (warning: lower success rate than other options)
# 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": {
"/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."
}
}
}
}
},
"components": {
"schemas": {
"UniversalCreditAPIBulkLookupQuery": {
"type": "object",
"properties": {
"queries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UniversalCreditPersonLookupInput"
},
"description": "Specify the lookup criteria for up to 100 people."
},
"profile_list": {
"type": "string",
"default": "API Bulk Lookup",
"description": "Add specified contacts to this profile list."
},
"webhook_id": {
"type": "integer",
"description": "ID of the webhook to post lookup results upon completion."
}
}
},
"UniversalCreditPersonLookupInput": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "RocketReach internal unique profile ID"
},
"name": {
"type": "string",
"description": "Name of the desired profile. Must specify along with `current_employer`"
},
"current_employer": {
"type": "string",
"description": "Current employer of the desired profile. Must specify along with `name`"
},
"title": {
"type": "string",
"description": "Job title of the desired profile"
},
"linkedin_ext_url": {
"type": "string",
"description": "linkedin_ext_url deprecated, please use `linkedin_url`",
"pattern": "",
"deprecated": true
},
"linkedin_url": {
"type": "string",
"description": "LinkedIn URL of the desired profile",
"pattern": ""
},
"email": {
"type": "string",
"format": "email",
"description": "An email address for the desired profile"
},
"phone": {
"type": "string",
"description": "A phone number for the desired profile in either E.164 format or international format.\n- Example: `+15555555555`"
},
"npi_number": {
"type": "integer",
"description": "An NPI number for the desired profile (US healthcare professional)"
},
"reveal_phone": {
"type": "boolean",
"default": false,
"description": "Whether to reveal the phone enrichment data for the desired profile"
},
"reveal_professional_email": {
"type": "boolean",
"default": false,
"description": "Whether to reveal the professional email enrichment data for the desired profile"
},
"reveal_personal_email": {
"type": "boolean",
"default": false,
"description": "Whether to reveal the personal email enrichment data for the desired profile"
},
"reveal_detailed_person_enrichment": {
"type": "boolean",
"default": false,
"description": "Whether to reveal the detailed person enrichment data for the desired profile"
},
"reveal_healthcare_enrichment": {
"type": "boolean",
"default": false,
"description": "Whether to reveal the healthcare enrichment data for the desired profile"
},
"metadata": {
"type": [
"object",
"null"
],
"additionalProperties": {},
"description": "User metadata about the profile, such as external ids, tags, notes, etc."
}
}
}
},
"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"
}
]
}
```