RocketReach People Search API

Search RocketReach's 700M+ professional profiles using filters such as name, current employer, title, location, skills, industry, and education. Returns paginated lists of profile summaries that can then be passed to the People Lookup API for full contact enrichment.

RocketReach People Search API is one of 5 APIs that RocketReach publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

Tagged areas include People Search, Sales Intelligence, and Prospecting. The published artifact set on APIs.io includes API documentation and an OpenAPI specification.

OpenAPI Specification

rocketreach-people-search-api-openapi.yml Raw ↑
openapi: 3.1.0
info:
  title: RocketReach People Search API
  version: 1.0.0
  description: Search RocketReach's 700M+ professional profiles using filters such as name, current employer, title, location,
    and skills.
  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/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:
  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:
    APISearchInput:
      type: object
      properties:
        start:
          type: integer
          maximum: 10000
          minimum: 1
          default: 1
          description: Start index of the request results (counting from 1)
        page_size:
          type: integer
          maximum: 100
          minimum: 1
          default: 10
          description: Maximum number of results to return per page [1-100]
        query:
          $ref: '#/components/schemas/PersonQuery'
          description: Search query object for the request
        order_by:
          allOf:
          - $ref: '#/components/schemas/OrderByEnum'
          default: relevance
          description: Specifies the ordering of search results. "popularity" matches the default ordering of the Search web
            app.
          example: popularity
    OrderByEnum:
      enum:
      - relevance
      - popularity
      - score
      type: string
    PersonQuery:
      type: object
      properties:
        all_skills:
          type: array
          items:
            type: string
          description: 'Include profiles with all of these skills (Uses `AND` logic).

            - Example: `[''python'', ''sql'', ''machine learning'']`'
          example:
          - python
          - sql
          - machine learning
        company_competitors:
          type: array
          items:
            type: string
          description: 'Include profiles with employers who have these competitors

            - Example: `[''homedepot.com'']`'
          example:
          - homedepot.com
        company_country_code:
          type: array
          items:
            type: string
          description: 'Include profiles with employers located in these country codes

            - Example: `[''US'']`'
          example:
          - US
        company_domain:
          type: array
          items:
            type: string
          description: 'Include profiles with employers who have these company domains

            - Example: `[''rocketreach.co'']`'
          example:
          - rocketreach.co
        company_email:
          type: array
          items:
            type: string
          description: 'Include profiles with employers who have these company emails

            - Example: `[''[email protected]'']`'
          example:
          - [email protected]
        company_funding_max:
          type: array
          items:
            type: string
          description: 'Include profiles with employers below this amount of funding

            - Example: `[''50000000'']`'
          example:
          - '50000000'
        company_funding_min:
          type: array
          items:
            type: string
          description: 'Include profiles with employers above this amount of funding

            - Example: `[''1000000'']`'
          example:
          - '1000000'
        company_geo:
          type: array
          items:
            type: string
          description: Include results matching company_geo.
        company_id:
          type: array
          items:
            type: string
          description: 'Include profiles with employed by these company IDs

            - Example: `[''123456'']`'
          example:
          - '123456'
        company_industry:
          type: array
          items:
            type: string
          description: 'Include profiles with employers in these industries. See the full list of industries [here](https://docs.google.com/spreadsheets/d/1cYz3FwtNEWW7z9otNNZRIILQ63_hM1LQ9SgsXWayaaI/edit?gid=0#gid=0).

            - Example: `[''Software Engineering'']`'
          example:
          - Software Engineering
        company_industry_keywords:
          type: array
          items:
            type: string
          description: 'Include profiles with employers with these industry keywords

            - Example: `[''SaaS'', ''B2B'']`'
          example:
          - SaaS
          - B2B
        company_intent:
          type: array
          items:
            type: string
          description: 'Search across 37,000 intent topics found [here](https://docs.google.com/spreadsheets/d/1nnk8ZOLr9GUzrPNy1pG_N_gVIhDpkc5XjE3Hh4J8M00/edit?gid=761283207#gid=761283207).
            Intent is only available on certain plans. Please reach out to our team to learn more..

            - Example: `[''hiring'']`'
          example:
          - hiring
        company_job_posting_signal:
          type: array
          items:
            type: string
          description: 'Hiring signals that identify companies that are actively building out specific departments. Full list
            of categories [here](https://docs.google.com/spreadsheets/d/1EZPVnOftbHNwDm0aXjiJ79dSpqcZ4JLnrNJPZxKXi5Q/edit?gid=2100271042#gid=2100271042).

            - Example: `[''Accounting Roles::one_month'']`'
          example:
          - Accounting Roles::one_month
        company_list:
          type: array
          items:
            type: string
          description: 'Transforms [ company_list ] search terms into a list of [ company_id ] search terms.

            - Example: `[''Example Company List'']`'
          example:
          - Example Company List
        company_list_id:
          type: array
          items:
            type: string
          description: 'Include results matching company_list_id.

            - Example: `[''12345'']`'
          example:
          - '12345'
        company_naics_code:
          type: array
          items:
            type: string
          description: 'Include profiles with employers with these NAICS codes

            - Example: `[''541330'', ''541512'']`'
          example:
          - '541330'
          - '541512'
        company_name:
          type: array
          items:
            type: string
          description: 'Include profiles employed by these company names

            - Example: `[''RocketReach'']`'
          example:
          - RocketReach
        company_news_signal:
          type: array
          items:
            type: string
          description: 'Search on news events within the 25 categories listed [here](https://docs.google.com/spreadsheets/d/1EZPVnOftbHNwDm0aXjiJ79dSpqcZ4JLnrNJPZxKXi5Q/edit?gid=577464958#gid=577464958").

            - Example: `[''Funding::one_month'']`'
          example:
          - Funding::one_month
        company_news_timestamp:
          type: array
          items:
            type: string
          description: company_news_timestamp deprecated, please use `company_news_signal`
          deprecated: true
          example:
          - mergers & acquisitions::one_month
        company_publicly_traded:
          type: array
          items:
            type: string
          description: 'Include results matching company_publicly_traded.

            - Example: `[''true'']`'
          example:
          - 'true'
        company_revenue:
          type: array
          items:
            type: string
          description: 'Include profiles with employers with these revenue values.

            - Example: `[''10000000-50000000'']`'
          example:
          - 10000000-50000000
        company_sic_code:
          type: array
          items:
            type: string
          description: 'Include profiles with employers with these SIC codes.

            - Example: `[''7372'']`'
          example:
          - '7372'
        company_size:
          type: array
          items:
            type: string
          description: 'Include profiles with employers with these sizes.

            - Example: `[''51-200'']`'
          example:
          - 51-200
        company_tag:
          type: array
          items:
            type: string
          description: 'Include profiles with employers with these company tags.

            - Example: `[''unicorn'']`'
          example:
          - unicorn
        company_website_url:
          type: array
          items:
            type: string
          description: 'Include profiles with employers with these website URLs.

            - Example: `[''rocketreach.co'']`'
          example:
          - rocketreach.co
        connections:
          type: array
          items:
            type: string
          description: 'Include profiles with these connections.

            - Example: `[''500+'']`'
          example:
          - 500+
        contact_method:
          type: array
          items:
            type: string
          description: 'Include profiles with these contact methods Options are: `mobile`, `phone`, `personal email`, and
            `work email`. Available with both AND and OR logic.

            - Example: `["work email OR personal email"]` or `["mobile AND personal email"]`'
          example:
          - work email
        current_or_previous_title:
          type: array
          items:
            type: string
          description: 'Include results matching current or previous job titles.

            - Example: `[''VP of Sales'']`'
          example:
          - VP of Sales
        current_title:
          type: array
          items:
            type: string
          description: 'Include profiles with these current job titles.

            - Example: `[''Product Manager'']`'
          example:
          - Product Manager
        degree:
          type: array
          items:
            type: string
          description: 'Include profiles with these degrees.

            - Example: `[''Bachelors'']`'
          example:
          - Bachelors
        department:
          type: array
          items:
            type: string
          description: 'Include profiles in these company departments. See the full list of departments [here](https://docs.google.com/spreadsheets/d/1EZPVnOftbHNwDm0aXjiJ79dSpqcZ4JLnrNJPZxKXi5Q/edit?gid=0#gid=0).

            - Example: `[''Product Management'']`'
          example:
          - Product Management
        description:
          type: array
          items:
            type: string
          description: 'Include profiles with these descriptions.

            - Example: `[''Experienced software engineer with a focus on backend development'']`'
          example:
          - Experienced software engineer with a focus on backend development
        domain:
          type: array
          items:
            type: string
          description: 'Include profiles with these domains.

            - Example: `[''rocketreach.co'']`'
          example:
          - rocketreach.co
        email:
          type: array
          items:
            type: string
          description: 'Include profiles with these emails.

            - Example: `[''[email protected]'']`'
          example:
          - [email protected]
        email_grade:
          type:
          - string
          - 'null'
          description: 'Specifies the minimum email confidence grade that a profile must have. Note: Email grades may be revalidated
            during lookup. As a result, you may occasionally see profiles whose email grade no longer matches the grade filter
            used in your search. Use the following format to specify personal or professional email grades: `<grade>::<modifier>`

            - Allowed Grades: A, A-, or B.

            - Allowed Modifiers: professional only, personal only

            - Example: `''A-''` or `''A-::professional only''`'
          example: A-
        employer:
          type: array
          items:
            type: string
          description: 'Include profiles employed by these companies.

            - Example: `[''RocketReach'']`'
          example:
          - RocketReach
        geo:
          type: array
          items:
            type: string
          description: 'Include profiles located in these geographies.

            - Example: `[''North America'']`'
          example:
          - North America
        growth:
          type: array
          items:
            type: string
          description: 'Include growth numbers for specific departments and time ranges.

            <b>Format:</b> `min_percentage_growth-max_percentage_growth::Department,TimeRange`

            * min_percentage_growth: Minimum growth percentage to filter profiles

            * max_percentage_growth: Maximum growth percentage to filter profiles

            * Department: Name of the company department (e.g., Engineering, Sales)

            * TimeRange: Duration for the growth metric (e.g., six_months, one_year)

            - Example: `[''5-30::Engineering,six_months'']`

            - Example: `[''-10--20::Sales,one_year'']`'
          example:
          - 5-30::Engineering,six_months
        handle:
          type: array
          items:
            type: string
          description: 'Include results matching handle.

            - Example: `[''johndoe'']`'
          example:
          - johndoe
        health_credentials:
          type: array
          items:
            type: string
          description: 'Include profiles with these health credentials. Only available on certain plans. Please reach out
            to our team to learn more.

            - Example: `[''MD'', ''RN'', ''PhD'']`'
          example:
          - MD
          - RN
          - PhD
        health_license:
          type: array
          items:
            type: string
          description: 'Include profiles with these health licenses. Only available on certain plans. Please reach out to
            our team to learn more.

            - Example: `[''MA12345'']`'
          example:
          - MA12345
        health_npi:
          type: array
          items:
            type: string
          description: 'Include profiles with these health NPIs. Only available on certain plans. Please reach out to our
            team to learn more.

            - Example: `[''1234567890'']`'
          example:
          - '1234567890'
        health_specialization:
          type: array
          items:
            type: string
          description: 'Include profiles with these health specializations. Only available on certain plans. Please reach
            out to our team to learn more.

            - Example: `[''Cardiology'']`'
          example:
          - Cardiology
        id:
          type: array
          items:
            type: string
          description: 'Include profiles with these RocketReach Profile IDs.

            - Example: `[''123456'']`'
          example:
          - '123456'
        job_change_range_days:
          type: array
          items:
            type: string
          description: job_change_range_days deprecated, please use `job_change_signal`
          deprecated: true
          example:
          - '30'
        job_change_signal:
          type: array
          items:
            type: string
          description: 'Detect when a contact changes companies or gets promoted (Time window options: one_week, one_month,
            three_months)

            - Example: `[''Company Change::one_month'']`

            - Example: `[''Promotion::one_week'']`

            - Example: `[''Company Change AND Promotion::three_months'']`'
          example:
          - Company Change::one_month
        keyword:
          type:
          - string
          - 'null'
          description: 'Include results matching keyword.

            - Example: `[''data enrichment'']`'
          example:
          - data enrichment
        keywords:
          type:
          - string
          - 'null'
          description: 'Include results matching keywords.

            - Example: `[''sales prospecting'', ''data enrichment'']`'
          example:
          - sales prospecting
          - data enrichment
        link:
          type: array
          items:
            type: string
          description: 'Include results matching link.

            - Example: `[''https://linkedin.com/in/johndoe'']`'
          example:
          - https://linkedin.com/in/johndoe
        major:
          type: array
          items:
            type: string
          description: 'Include profiles with these majors.

            - Example: `[''Computer Science'', ''Biology'']`'
          example:
          - Computer Science
          - Biology
        management_levels:
          type: array
          items:
            type: string
          description: 'Include profiles at these management levels. See the full list of management levels [here](https://docs.google.com/spreadsheets/d/1EZPVnOftbHNwDm0aXjiJ79dSpqcZ4JLnrNJPZxKXi5Q/edit?gid=0#gid=0).

            - Example: `[''Director'']`'
          example:
          - Director
        name:
          type: array
          items:
            type: string
          description: 'Include profiles with these names.

            - Example: `[''John Doe'']`'
          example:
          - John Doe
        phone:
          type: array
          items:
            type: string
          description: 'Include profiles with these phone numbers.

            - Example: `[''+15555555555'']`'
          example:
          - '+15555555555'
        previous_company_id:
          type: array
          items:
            type: string
          description: 'Include profiles who were previously employed at these RocketReach

            company IDs.

            - Example: `[''123456'']`'
          example:
          - '123456'
        previous_employer:
          type: array
          items:
            type: string
          description: 'Include profiles who were previously employed at these companies.

            - Example: `[''Google'']`'
          example:
          - Google
        previous_title:
          type: array
          items:
            type: string
          description: 'Include results matching previous_title.

            - Example: `[''Software Engineer'']`'
          example:
          - Software Engineer
        school:
          type: array
          items:
            type: string
          description: 'Include profiles who attended these schools.

            - Example: `[''Stanford University'']`'
          example:
          - Stanford University
        skills:
          type: array
          items:
            type: string
          description: 'Include profiles listed with any of these skills (Uses `OR` logic).

            - Example: `[''Python'', ''SQL'']`'
          example:
          - Python
          - SQL
        state:
          type: array
          items:
            type: string
          description: 'Include profiles located in these states.

            - Example: `[''MA'']`'
          example:
          - MA
        update_time:
          type: array
          items:
            type: string
          description: 'Include results that have been updated since the specified date.

            - Example: `[''2025-01-01'']`'
          example:
          - '2025-01-01'
        years_experience:
          type: array
          items:
            type: string
          description: 'Include profiles with this many years of experience.

            - Example: `[''10'']`'
          example:
          - '10'
    ProfileSearchResultSerializerBase:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          description: RocketReach internal unique profile ID
        status:
          allOf:
          - $ref: '#/components/schemas/StatusEnum'
          readOnly: true
          description: Status of the profile lookup
        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).
        links:
          type: object
          additionalProperties: {}
          description: Social media links for the profile
        linkedin_url:
          type:
          - string
          - 'null'
          readOnly: true
          description: LinkedIn URL of the profile
        connections:
          type: integer
          description: Number of LinkedIn connections for this profile
        location:
          type:
          - string
          - 'null'
          maxLength: 256
          description: Location of the profile
        city:
          type:
          - string
          - 'null'
          maxLength: 128
          description: City of the profile
        region:
          type:
          - string
          - 'null'
          maxLength: 3
          description: Region of the profile
        country:
          type: string
          readOnly: true
          description: Country code of the profile
        country_code:
          type:
          - string
          - 'null'
          maxLength: 2
          description: Country code of the profile
        current_title:
          type:
          - string
          - 'null'
          readOnly: true
          description: Current job title of the profile
        current_employer:
          type:
          - string
          - 'null'
          readOnly: true
          description: Current employer of the profile
        current_employer_domain:
          type:
          - string
          - 'null'
          description: Domain for the employer of the profile
        current_employer_website:
          type:
          - string
          - 'null'
          description: Website for the employer of the profile
        teaser:
          type:
          - object
          - 'null'
          properties:
            emails:
              type: array
              items:
                type: string
            phones:
              type: array
              items:
                type: object
                properties:
                  number:
                    type: string
                  is_premium:
                    type: boolean
                required:
                - is_premium
                - number
            office_phones:
              type: array
              items:
                type: string
            preview:
              type: array
              items:
                type: string
            is_premium_phone_available:
              type: boolean
            personal_emails:
              type: array
              items:
                type: string
            professional_emails:
              type: array
              items:
                type: string
          readOnly: true
          description: Preview contact data for the profile
        birth_year:
          type: integer
          description: Year of birth of the profile
        current_employer_id:
          type: integer
          description: RocketReach internal unique company ID
        current_employer_linkedin_url:
          type:
          - string
          - 'null'
          description: LinkedIn URL for the employer of the profile
        region_latitude:
          type:
          - number
          - 'null'
          format: double
          description: Latitude of the region of the profile
        region_longitude:
          type:
          - number
          - 'null'
          format: double
          description: Longitude of the region of the profile
        suppressed:
          type: string
          readOnly: true
          description: Returns True if this profile is blocked by a suppression list filter
        npi_data:
          allOf:
          - $ref: '#/components/schemas/TypedDict'
          readOnly: true
          description: List of NPI data objects for the profile
        update_time:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp of the last update for the profile
          example: '2023-10-01T12:00:00Z'
    StatusEnum:
      enum:
      - complete
      - progress
      - searching
      - not queued
      type: string
    TypedDict:
      type: object
      properties:
        npi_number:
          type: string
          readOnly: true
          description: NPI number of the healthcare provider. An NPI is a unique 10-digit number used to identify health care
            providers
          example: 1234567890
        credentials:
          type: string
          readOnly: true
          description: Professional qualifications or designations earned by a healthcare provider, such as MD, DO, NP, or
            RN.
        license_number:
          type: string
          readOnly: true
          description: A state-issued number that authorizes a healthcare provider to practice in a specific state or field.
        specialization:
          type: string
          readOnly: true
          description: The specific area of medicine or healthcare in which a provider focuses, such as cardiology, pediatrics,
            or dermatology.
    APIUniversalCreditsSearchInput:
      type: object
      properties:
        start:
          type: integer
          maximum: 10000
          minimum: 1
          default: 1
          description: Paginate through search results by returning results starting from this value (counting from 1).
        page_size:
          type: integer
          maximum: 100
          minimum: 1
          default: 100
          description: Maximum number of search results to return per page.
        query:
          $ref: '#/components/schemas/PersonQuery'
        order_by:
          allOf:
          - $ref: '#/components/schemas/OrderByEnum'
          default: relevance
          description: 'Specifies the ordering of search results. "popularity" matches the default ordering of the Search
            web app.


            * `relevance` - relevance

            * `popularity` - popularity

            * `score` - score'
    UniversalCreditPersonSearchOutput:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          description: RocketReach internal unique profile ID
        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
        location:
          type:
          - string
          - 'null'
          maxLength: 256
          description: Location of the profile
        city:
          type:
          - string
          - 'null'
          maxLength: 128
          description: City of the profile
        region:
          type:
          - string
          - 'null'
          maxLength: 3
          description: Region of the profile
        country:
          type: string
          rea

# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/rocketreach/refs/heads/main/openapi/rocketreach-people-search-api-openapi.yml