--- updatedAt: 2026-10-08T14:27:46.000Z agentTools: projectIndex: https://docs.rocketreach.co/llms.txt --- # Tools Reference Most tools are read-only and consume no credits. Four tools consume credits: `person_lookup`, `profile_company_lookup`, `company_lookup`, and `email_verify`. The first three also add resolved contacts and companies to your My Contacts list. *** ## person\_search Search RocketReach's database of 700M+ professional profiles by professional attributes. Returns matching profile summaries — name, current title, current employer, location, and profile ID. Does **not** return contact info (emails, phones); use `person_lookup` for that. **No credits consumed.** ### Input | Parameter | Type | Description | | ----------- | ------- | -------------------------------------------------------------------- | | `query` | object | One or more facets to filter by (see facets table below) | | `exclude` | object | Same facets as `query` — matching profiles are excluded from results | | `start` | integer | Pagination offset, 1-based (default: 1) | | `page_size` | integer | Results per page, max 100 (default: 10) | | `order_by` | string | `relevance` (default), `popularity`, or `score` | ### Facets **Identity & job** | Facet | Description | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | RocketReach profile ID(s) | | `name` | Person name. Wrap in quotes for exact match: `"Jane Doe"` | | `current_title` | Current job title | | `previous_title` | A job title the person held previously | | `current_or_previous_title` | Match either a current or previous title | | `current_employer` | Current employer / company name | | `previous_employer` | A company the person worked at previously | | `employer` | Match either a current or previous employer | | `department` | Work department, e.g. `engineering`, `sales` | | `management_levels` | Seniority level: `cxo`, `vp`, `director`, `manager`, `non_manager` | | `years_experience` | Total years of experience. Supports operators: `10+`, `<5`, `3-7` | | `job_change_signal` | Person who recently changed jobs. Value is `Company Change::` or `Promotion::`, e.g. `Company Change::one_month`. See [Search signals](#search-signals) | **Skills & education** | Facet | Description | | ------------ | ------------------------------------------------- | | `skills` | Skills — OR logic, any listed skill matches | | `all_skills` | Skills — AND logic, every listed skill must match | | `major` | Education major / field of study | | `degree` | Education degree level | | `school` | School or university name | **Location** | Facet | Description | | ------------- | -------------------------------------------------------------------------------------- | | `location` | City, state, or country. Optional radius: `"San Francisco"::~50mi` or `"Paris"::~50km` | | `country` | Country | | `state` | State / region | | `city` | City | | `postal_code` | Postal / ZIP code | **Contact** | Facet | Description | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `email` | Known email address | | `email_grade` | Email confidence grade: `A`, `A-`, or `B`. Optional modifier: `A::professional only` or `A::personal only`. Requires email-grade search enabled on your account | | `phone` | Known phone number | | `phone_grade` | Specifies the minimum phone confidence grade that a profile must have. Allowed grades: `A`, `A-`, or `B` | | `link` | LinkedIn profile URL | | `handle` | Social-media handle | | `contact_method` | Include profiles with these contact methods Options are: `mobile`, `direct dial`, `office phone`, `personal email`, and `work email`. Available with both AND and OR logic. | **Current employer attributes** | Facet | Description | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `company_id` | Current company's RocketReach ID | | `previous_company_id` | A previous company's RocketReach ID | | `company_domain` | Current company domain, e.g. `acme.com` | | `company_size` | Current company employee count. Supports operators: `1000+`, `<5000`, `100-500` | | `company_revenue` | Current company annual revenue. Supports operators | | `company_industry` | Current company industry | | `company_sic_code` | Current company SIC code | | `company_naics_code` | Current company NAICS code | | `company_tag` | Tag applied to the current company | | `company_list` | Current company's saved-list membership, by list name | | `company_list_id` | Current company's saved-list membership, by list ID | | `company_competitors` | Companies named as competitors of the current company | | `company_intent` | Current company's purchase-intent signals | | `company_industry_keywords` | Keywords associated with the current company's industry | | `company_news_signal` | News event at the person's current company. Value is `::`, e.g. `Funding::one_month`. See [Search signals](#search-signals) | | `company_job_posting_signal` | Hiring activity at the person's current company. Value is ` Roles::`, e.g. `Engineering Roles::one_month`. See [Search signals](#search-signals) | **Healthcare** | Facet | Description | | ----------------------- | ---------------------- | | `health_npi` | NPI number | | `health_license` | Medical license | | `health_specialization` | Medical specialization | | `health_credentials` | Medical credentials | **Other** | Facet | Description | | ------------- | --------------------------------------------------- | | `keyword` | Free-text keyword matched across all profile fields | | `profile_tag` | Tag applied to the profile | | `connections` | LinkedIn connection count | | `update_time` | Last profile update (ISO 8601). Supports operators | ### Response ```json { "pagination": { "start": 1, "next": 11, "total": 4242 }, "profiles": [ { "id": 101, "name": "Ada Lovelace", "current_title": "Engineer", "current_employer": "Acme", "location": "London, UK" } ] } ``` Each entry in `profiles` includes `id`, `name`, `current_title`, `current_employer`, and `location`. The `id` is the RocketReach profile ID — pass it to `person_lookup` to retrieve contact information. *** ## company\_search Search RocketReach's company database. Returns matching company summaries — name, domain, industry, employee count, and company ID. **No credits consumed.** ### Input | Parameter | Type | Description | | ----------- | ------- | -------------------------------------------------------- | | `query` | object | One or more facets to filter by (see facets table below) | | `exclude` | object | Same facets as `query` — matching companies are excluded | | `start` | integer | Pagination offset, 1-based (default: 1) | | `page_size` | integer | Results per page, max 100 (default: 10) | | `order_by` | string | `relevance` (default), `popularity`, or `score` | ### Facets **Identity** | Facet | Description | | -------------- | --------------------------------------- | | `id` | RocketReach company ID(s) | | `name` | Company name | | `domain` | Company website domain, e.g. `acme.com` | | `website_url` | Full company website URL | | `email_domain` | Email domain the company uses | | `link` | Company social links (LinkedIn, etc.) | | `phone` | Company phone number | **Classification** | Facet | Description | | ------------------- | ----------------------------------------------- | | `industry` | Industry classification | | `primary_industry` | Primary industry (when a company spans several) | | `industry_tags` | Industry tags | | `industry_keywords` | Industry-related keywords | | `sic_code` | SIC code(s) | | `naics_code` | NAICS code(s) | | `website_category` | Website-category classification | **Size & financials** | Facet | Description | | ----------------- | --------------------------------------------------------------- | | `employees` | Employee count. Supports operators: `1000+`, `<5000`, `100-500` | | `revenue` | Annual revenue. Supports operators | | `total_funding` | Total funding raised. Supports operators | | `growth` | Company growth metric | | `publicly_traded` | Public-company indicator | **Location** | Facet | Description | | ---------- | ---------------------------------------------------------------------------------------- | | `location` | HQ location, e.g. `"San Francisco, California"`. Optional radius: `::~50mi` or `::~50km` | **Technology** | Facet | Description | | ----------- | ----------------------------- | | `techstack` | Technologies the company uses | **Other** | Facet | Description | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `keyword` | Free-text keyword matched across all fields | | `description` | Match terms in the company description | | `company_tag` | Tag applied to the company | | `news_signal` | Company news event. Value is `::`, e.g. `Funding::one_month`. See [Search signals](#search-signals) | | `job_posting_signal` | Company hiring activity. Value is ` Roles::`, e.g. `Engineering Roles::one_month`. See [Search signals](#search-signals) | | `intent` | Purchase-intent signals | | `competitors` | Companies named as competitors | ### Response ```json { "pagination": { "start": 1, "next": 11, "total": 87 }, "companies": [ { "id": 9001, "name": "Acme Corp", "domain": "acme.com", "industry_str": "Software", "employee_count": 250 } ] } ``` Each entry in `companies` includes `id`, `name`, `domain`, `industry_str`, and `employee_count`. *** ## Search signals A few search facets filter by **recent activity signals** rather than static attributes. Each takes a value of the form `Category::time_window` — an exact category string, then `::`, then exactly one time window. Pass an array to match any of several signals. **Time windows** * News and job-posting signals: `one_week`, `one_month`, `three_months`, `six_months`, `one_year` * Job-change signals: `one_week`, `one_month`, `three_months` (job-change data only goes back three months) ### `job_change_signal` — `person_search` A person who recently changed jobs. Categories: `Company Change`, `Promotion`. Example: `Company Change::one_month`. ### `company_news_signal` / `news_signal` — news event A news event at the company (the person's current employer for `person_search`, the company itself for `company_search`). Example: `Funding::one_month`. Categories: `Attends Event`, `Award`, `Closes Offices`, `Competitor Identified`, `Decreases Headcount`, `Developing Product`, `Executive Departure`, `Executive Hire`, `Executive Promotion`, `Executive Retirement`, `Expands Facilities`, `Files Lawsuit`, `Funding`, `Increases Headcount`, `Integration`, `Invests Into`, `IPO`, `Launches Product`, `Mergers & Acquisitions`, `New Customer`, `Partnership`, `Purchases Assets`, `Recognition`, `Sells Assets`, `Vulnerability`. ### `company_job_posting_signal` / `job_posting_signal` — hiring activity The company is actively hiring for a department. Example: `Engineering Roles::one_month`. Categories: `Accounting Roles`, `Administration Roles`, `Business Development Roles`, `Corporate Communications Roles`, `Customer Services Roles`, `Engineering Roles`, `Facilities Management Roles`, `Finance Roles`, `Human Resources Roles`, `Information Technology Roles`, `Legal Roles`, `Logistics Roles`, `Machine Learning Roles`, `Marketing Roles`, `Operations Roles`, `Procurement Roles`, `Production or Manufacturing Roles`, `Public Relations Roles`, `Quality Assurance Roles`, `Recruiting Roles`, `Research and Development Roles`, `Sales Roles`, `Strategy Roles`. *** ## person\_lookup Look up contact information for a specific person. Returns emails, phone numbers, and profile metadata. Charges credits and adds the contact to your My Contacts list with default tags (`MCP Lookups` plus the AI client name) and any `tags` you pass. **Consumes 1 lookup credit, plus 1 person export credit**. The lookup is asynchronous. If the result is not yet ready, the tool returns `status: "pending"` with a `profile_id` to poll via `check_person_status`. Polling is free. ### Input Provide at least one identifier: `id`, `email`, `linkedin_url`, `npi_number`, or `name` + `current_employer`. | Parameter | Type | Description | | ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | integer | RocketReach profile ID | | `email` | string | Known email address | | `linkedin_url` | string | LinkedIn profile URL | | `name` | string | Person's name. Requires `current_employer` | | `current_employer` | string | Current company name. Used with `name` | | `title` | string | Job title — disambiguates when name + employer match multiple people | | `npi_number` | integer | NPI number (US healthcare). Standalone identifier | | `lookup_type` | string | Force a specific credit type: `standard_lookup` (email only), `premium_lookup` (email + phone), `phone_lookup` (email + phone), or `person_enrich` (profile metadata only, no contact info). Omit to use your configured order | | `tags` | string\[] | Additional tags to apply to the contact | | `metadata` | object | Key/value metadata stored with the lookup. Values: strings or integers | ### Response — complete ```json { "profile_id": 101, "status": "complete", "name": "Ada Lovelace", "current_title": "Engineer", "current_employer": "Acme", "emails": [{ "email": "ada@acme.com", "grade": "A" }], "phones": [{ "number": "+1-555-0101", "type": "direct" }] } ``` ### Response — pending ```json { "status": "pending", "profile_id": 101, "retry_after_seconds": 3, "name": "Ada Lovelace", "current_title": "Engineer", "current_employer": "Acme" } ``` Call `check_person_status` with the `profile_id` once a few seconds have passed. Average resolution time is \~5 seconds. *** ## profile\_company\_lookup Retrieve contact information for a person **and** full details for their current company in a single call. The person side is asynchronous (returns pending/complete like `person_lookup`); the company side resolves immediately. **Consumes 1 lookup credit + 1 person export credit + 1 company export credit.** Adds the resolved contact and company to your My Contacts list. ### Input Same parameters as `person_lookup`: one of `id`, `email`, `linkedin_url`, `npi_number`, or `name` + `current_employer` as identifier, plus optional `title`, `lookup_type`, `tags`, and `metadata`. ### Response — complete ```json { "profile_id": 101, "status": "complete", "name": "Ada Lovelace", "emails": [{ "email": "ada@acme.com", "grade": "A" }], "phones": [{ "number": "+1-555-0101", "type": "direct" }], "company": { "id": 9001, "name": "Acme Corp", "domain": "acme.com", "industry_str": "Software", "employee_count": 250 } } ``` ### Response — pending The company data is already present in the pending response. Call `check_person_status` with the `profile_id` to retrieve the contact details. ```json { "status": "pending", "profile_id": 101, "retry_after_seconds": 3, "name": "Ada Lovelace", "company": { "id": 9001, "name": "Acme Corp", "domain": "acme.com" } } ``` *** ## company\_lookup Retrieve full details for a specific company: description, industry, employee count, revenue, founded year, tech stack, social links, and more. Adds the company to your My Contacts list. **Consumes 1 company export credit.** ### Input Provide at least one identifier. | Parameter | Type | Description | | -------------- | --------- | --------------------------------------- | | `domain` | string | Company website domain, e.g. `acme.com` | | `id` | integer | RocketReach company ID | | `name` | string | Company name | | `ticker` | string | Stock ticker symbol | | `linkedin_url` | string | Company LinkedIn URL | | `tags` | string\[] | Additional tags to apply to the company | ### Response — complete Full company profile: `id`, `name`, `domain`, `industry_str`, `employee_count`, `revenue`, `founded`, `description`, `techstack`, social links, and more. *** ## email\_verify Verify whether a single email address can receive mail. Checks the address's format, confirms the domain accepts mail, and probes the mailbox on the receiving mail server. **Consumes 1 email verification credit.** `valid`, `invalid` and `catchall` all charge — knowing an address is undeliverable is the answer you paid for. Only `unknown` and malformed emails are refunded, and it comes back with `credits_charged: 0`. Email verification credits are a separate pool from lookup and export credits. The `account` tool reports the balance as `email_verification`. ### Input | Parameter | Type | Description | | --------- | ------ | ----------------------------------- | | `email` | string | The address to verify. One per call | ### Response ```json { "email": "ada@acme.com", "status": "valid", "credits_charged": 1, "mx_record": "aspmx.l.google.com", "checks": { "format_valid": true, "domain_valid": true, "disposable": false, "catchall": false } } ``` | `status` | Meaning | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `valid` | The mailbox exists and accepts mail | | `invalid` | The mailbox does not exist, the domain rejects mail, or the address is malformed. Don't send to it | | `catchall` | The domain accepts mail for any address, so this mailbox can't be confirmed either way. `person_lookup` reports the same state as `accept-all` in an email's `smtp_valid` | | `unknown` | The receiving server gave no usable answer. The credit is refunded | `catchall` as a **status** and `catchall` inside **checks** answer different questions. `checks.catchall` says the domain accepts mail at any address; `status` says whether we could still confirm this particular mailbox. On a catch-all domain where we verified the mailbox anyway you get `"status": "valid"` with `"catchall": true`. The status is only `catchall` when mailbox-level deliverability can't be determined. `mx_record` is the domain's primary MX host, or `null` when the domain publishes none. Each value in `checks` is `true`, `false`, or `null` when that signal couldn't be determined: `format_valid` (syntactically well-formed), `domain_valid` (the domain exists and accepts mail), `disposable` (a throwaway or temporary provider), and `catchall` (the domain accepts any address). An `unknown` result won't resolve on an immediate retry. One retry later is worth attempting; retrying in a loop spends credits without improving the answer. ### Verifying several addresses There's no bulk verification. Ask an assistant to verify a list and it calls `email_verify` once per address, charging one credit each. Twenty-five addresses means twenty-five calls and twenty-five credits, bounded by the 300-per-minute rate limit. *** ## account Retrieve the authenticated user's RocketReach account information: plan name, credit balances, rate-limit status, and daily API call usage. **No credits consumed.** ### Input None. ### Response | Field | Type | Description | | ------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | integer | RocketReach user ID | | `first_name` / `last_name` | string | Account holder name | | `email` | string | Account email | | `state` | string | Account state: `registered`, `test_user`, or `anonymous` | | `plan` | object | Plan name and lookup/export limits | | `api_key` | string | The account's RocketReach API key | | `api_key_domain` | string | Domain the API key is bound to, if any | | `lookup_credit_balance` | number \| `"inf"` | Rollup lookup-credit balance. `"inf"` means the credit type is not tracked on this account, not that it is unlimited | | `person_export_credit_balance` | number \| `"inf"` | Rollup person-export balance. `"inf"` means the credit type is not tracked on this account, not that it is unlimited | | `company_export_credit_balance` | number \| `"inf"` | Rollup company-export balance. `"inf"` means the credit type is not tracked on this account, not that it is unlimited | | `lifetime_credits_spent` | integer | Total credits spent over the account's lifetime | | `lifetime_api_num_calls` | integer | Total API calls over the account's lifetime | | `daily_api_num_calls` | integer | API calls made today — MCP tool calls and direct API calls combined | | `daily_api_limit` | integer | Daily API call limit | | `credit_usage` | array | Per-type breakdown: `allocated`, `used`, `remaining` for each of `standard_lookup`, `premium_lookup`, `phone_lookup`, `person_enrich`, `person_export`, `company_export` | | `rate_limits` | array | Per-action rate limits: `action`, `duration`, `limit`, `used`, `remaining` | *** ## check\_person\_status Poll the status of one or more in-progress person lookups. Use this after `person_lookup` returns `status: "pending"` to retrieve results once the lookup completes. Wait at least **3 seconds** between polls for the same `profile_id`. Lookups typically resolve within \~5 seconds. **No credits consumed.** ### Input | Parameter | Type | Description | | ------------ | --------------------- | ---------------------------------------------------- | | `profile_id` | integer \| integer\[] | Single profile ID or array of up to 100 IDs to check | ### Response Array of status records, one per `profile_id`: | `status` | Description | | ---------- | ------------------------------------------------------------------------------- | | `complete` | Lookup finished. Full contact data included (emails, phones, job history, etc.) | | `pending` | Still in progress. Returns profile metadata only (name, title, employer) | | `failed` | Lookup ran to completion but no contact information was found | *** ## ping Liveness check. Returns the server name and version. Useful for verifying connectivity and auth before making tool calls. ### Input None. ### Response ```json { "name": "rr-mcp-server", "version": "1.0.0", "message": "pong" } ```