RocketReach People Search API

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