Ocean.io Search API

openapi: 3.2.0
info:
  title: Ocean.io API Documentation Search API
  summary: Welcome to Ocean.io's API.
  description: "\n            Welcome to Ocean.io's API.\n            The API can be used to access all our API endpoints, such as our enrich API to look up company information, or our discover API to identify companies based on specific search criteria such as semantic similarity, technologies or industries.\n            Ocean.io's APIs are a set of HTTPS endpoints that you can use to retrieve and integrate Ocean.io's data into your existing workflows.\n            All requests should be made through https and the request and response bodies should be formatted in JSON.\n        "
  version: 2.0.0
  x-logo:
    url: https://cdn2.ocean.io/assets/images/logo/256x92_ocean-logo.svg
servers:
- url: https://api.ocean.io
tags:
- name: Search
paths:
  /v2/search/companies:
    post:
      tags:
      - Search
      summary: Lookalike companies search (deprecated)
      description: Search companies using filters.
      operationId: searchCompanies
      deprecated: true
      parameters:
      - name: apiToken
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Apitoken
      - name: x-api-token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicSearchCompaniesBodyV1'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSearchCompaniesResult'
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - API token should be provided in headers or query parameters
                    - Current API token is not registered in our database
                required:
                - detail
          description: Forbidden
        '402':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - Insufficient credits
                required:
                - detail
          description: Payment Required
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - Conflicting API tokens provided in query parameters and headers
                    - Plan version not supported for this endpoint
                required:
                - detail
          description: Bad Request
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v3/search/companies:
    post:
      tags:
      - Search
      summary: Lookalike companies search
      description: 'Search companies using filters.


        Looking for the legacy endpoint? [Access it here](/docs/searchCompanies)'
      operationId: searchCompaniesV3
      parameters:
      - name: apiToken
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Apitoken
      - name: x-api-token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicSearchCompaniesBodyV3'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSearchCompaniesResultWithRelevance'
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - API token should be provided in headers or query parameters
                    - Current API token is not registered in our database
                required:
                - detail
          description: Forbidden
        '402':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - Insufficient credits
                required:
                - detail
          description: Payment Required
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - Conflicting API tokens provided in query parameters and headers
                required:
                - detail
          description: Bad Request
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/search/people:
    post:
      tags:
      - Search
      summary: Search people (deprecated)
      description: Search people using filters and/or people Ids
      operationId: searchPeople
      parameters:
      - name: apiToken
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Apitoken
      - name: x-api-token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicSearchPeopleBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSearchPeopleResult'
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - API token should be provided in headers or query parameters
                    - Current API token is not registered in our database
                required:
                - detail
          description: Forbidden
        '402':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - Insufficient standard credits
                required:
                - detail
          description: Payment Required
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - Conflicting API tokens provided in query parameters and headers
                    - Plan version not supported for this endpoint
                required:
                - detail
          description: Bad Request
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v3/search/people:
    post:
      tags:
      - Search
      summary: Lookalike people search
      description: 'Search people using filters and/or people Ids


        Looking for the legacy endpoint? [Access it here](/docs/searchPeople)


        **Webhook result:**

        [Email results](/docs/webhooks/people_search_emails)

        [Phone results](/docs/webhooks/people_search_phones)'
      operationId: searchPeopleV3
      parameters:
      - name: apiToken
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Apitoken
      - name: x-api-token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicSearchPeopleBodyV3'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookalikePeopleResultV3'
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - API token should be provided in headers or query parameters
                    - Current API token is not registered in our database
                required:
                - detail
          description: Forbidden
        '402':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - Insufficient credits
                required:
                - detail
          description: Payment Required
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - Conflicting API tokens provided in query parameters and headers
                required:
                - detail
          description: Bad Request
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v3/search/people/preview:
    post:
      tags:
      - Search
      summary: Preview - Lookalike people
      description: "Preview search people with company information. \n **Only available for enterprise API customers.**"
      operationId: searchPeopleV3Preview
      parameters:
      - name: apiToken
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Apitoken
      - name: x-api-token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicSearchPeopleBodyV3PreviewV3'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSearchPeopleResultPreviewV3'
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - API token should be provided in headers or query parameters
                    - Current API token is not registered in our database
                required:
                - detail
          description: Forbidden
        '402':
          content:
            application/json:
              schema:
                title: ''
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - Insufficient email credits
                    - Some email verifications are already in progress and might use all your remaining email credits. Please try again later.
                    - Insufficient phone credits
                    - Some phone verifications are already in progress and might use all your remaining phone credits. Please try again later.
                    - Insufficient credits
                required:
                - detail
          description: Payment Required
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - Conflicting API tokens provided in query parameters and headers
                required:
                - detail
          description: Bad Request
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v3/search/companies/preview:
    post:
      tags:
      - Search
      summary: Preview - Lookalike companies
      description: "Preview search companies using filters. \n **Only available for enterprise API customers.**"
      operationId: previewSearchCompaniesV3
      parameters:
      - name: apiToken
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Apitoken
      - name: x-api-token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicPreviewSearchCompaniesV3Body'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPreviewSearchCompaniesV3Response'
        '403':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - API token should be provided in headers or query parameters
                    - Current API token is not registered in our database
                    - You are not allowed to access this feature
                required:
                - detail
          description: Forbidden
        '402':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - Insufficient credits
                required:
                - detail
          description: Payment Required
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - Conflicting API tokens provided in query parameters and headers
                required:
                - detail
          description: Bad Request
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    FundingRoundFilter:
      properties:
        raised:
          $ref: '#/components/schemas/FromTo'
          nullable: true
          title: Raised amount
          description: 'Amount of money raised in funding round. Valid range: 0-100,000,000,000'
          examples:
          - from: 1000000
            to: 5000000
        types:
          items:
            $ref: '#/components/schemas/FundingRoundType'
          type: array
          nullable: true
          title: Funding round types
          description: List of funding round types
          examples:
          - - Seed
            - Series A
        date:
          $ref: '#/components/schemas/FromToStringDate'
          nullable: true
          title: Funding date
          description: 'Date range of the funding round. Valid range: 1800-01-01 to 2100-12-31'
          examples:
          - from: '2023-01-01'
            to: '2024-01-01'
      additionalProperties: false
      type: object
      title: FundingRoundFilter
    PublicPreviewCompanyV3:
      properties:
        name:
          type: string
          title: Company name
          description: Name of the company
          examples:
          - Google
          - Apple
          - Microsoft
        logo:
          type: string
          title: Company logo
          description: URL to the company logo
          examples:
          - https://cdn2.ocean.io/logos/ocean.io/b162ddc061a4ca67e8aacbbf747dc8e62cce7496.png
        topIndustries:
          items:
            type: string
          type: array
          title: Top industries
          description: Array of top 3 industries
          examples:
          - - Analytics
            - B2B
            - Software
          - - Analytics
            - B2B
            - Lead Generation
        size:
          type: string
          nullable: true
          title: Company size
          description: Company size in brackets
          examples:
          - 501-1000
          - 1001-5000
        description:
          type: string
          title: Company description
          description: Company description
          examples:
          - B2B Sales and Marketing teams use Ocean.io's prospecting data platform to find accounts and contacts no one else can.
        primaryCountry:
          type: string
          nullable: true
          title: Primary country
          description: 'Primary country code of the company '
          examples:
          - us
          - gb
          - dk
        primaryRegion:
          type: string
          nullable: true
          title: Primary region
          description: Primary region code of the company
          examples:
          - CA
          - UKE
          - WA
        linkedinHandle:
          type: string
          nullable: true
          title: LinkedIn handle
          description: LinkedIn company handle/username
          examples:
          - zoominfo
          - ocean-io
      type: object
      required:
      - name
      - logo
      - topIndustries
      - size
      - description
      - primaryCountry
      - primaryRegion
      title: PublicPreviewCompanyV3
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PersonCompany:
      properties:
        companySize:
          $ref: '#/components/schemas/PublicCompanySize'
          nullable: true
          title: Company size range
          description: Company size range
          examples:
          - 2-10
        logo:
          type: string
          nullable: true
          title: Logo
          description: Logo of the company (URL)
          examples:
          - https://cdn2.ocean.io/companies-logos-v1/domain.com/020539e284d9318e805301b672ad23047c30818a.png
        name:
          type: string
          nullable: true
          title: Name
          description: Name of the company
          examples:
          - Dunder Mifflin Paper Company
        revenue:
          $ref: '#/components/schemas/Revenue'
          nullable: true
          title: Revenue range
          description: Revenue range
          examples:
          - 1-10M
        employeeCountOcean:
          type: integer
          nullable: true
          title: Employeecountocean
          description: Number of people working at the company in our database.
          examples:
          - 57
        industries:
          items:
            type: string
          type: array
          nullable: true
          title: Industries
          description: Industries of the company<br>Available values can be found at /v2/data-fields endpoint.
          examples:
          - - Audio
            - Electronics
        technologies:
          items:
            type: string
          type: array
          nullable: true
          title: Technologies
          description: Software technologies used by the company
          examples:
          - - Accesso
            - Adcash
            - Atlassian Jira
        fundingRound:
          $ref: '#/components/schemas/FundingRound'
          nullable: true
          title: Funding round
          description: Funding round of the company
          examples:
          - cbUrl: https://www.crunchbase.com/funding_round/5c26b0c0
            date: '2020-01-01'
            moneyRaisedInUsd: 1000000
            type: Seed
      type: object
      title: PersonCompany
    LocationsFilter:
      properties:
        includeCountries:
          items:
            type: string
          type: array
          nullable: true
          title: Include countries
          description: Filter by all countries where the company has presence.<br>Must be provided as alpha-2 ISO 3166 country codes.
          examples:
          - - es
        excludeCountries:
          items:
            type: string
          type: array
          nullable: true
          title: Exclude countries
          description: Exclude companies that are present in the specified countries.<br>Must be provided as alpha-2 ISO 3166 country codes.
          examples:
          - - br
            - de
        includeRegions:
          items:
            $ref: '#/components/schemas/State'
          type: array
          nullable: true
          title: Include regions (states / provinces)
          description: Filter by country regions — US states, Canadian provinces, etc. (if applicable). Available values are located at /v2/data-fields endpoint.
          examples:
          - - abbreviation: CA
              country: us
            - abbreviation: YT
              country: ca
        excludeRegions:
          items:
            $ref: '#/components/schemas/State'
          type: array
          nullable: true
          title: Exclude regions (states / provinces)
          description: Exclude companies present in the specified regions — US states, Canadian provinces, etc. (if applicable). Available values are located at /v2/data-fields endpoint.
          examples:
          - - abbreviation: CA
              country: us
            - abbreviation: YT
              country: ca
        includeCities:
          items:
            $ref: '#/components/schemas/CompaniesCityFilter'
          type: array
          nullable: true
          title: Include cities
          description: Filter by cities
          examples:
          - - city: New York
              country: us
            - city: Los Angeles
              country: us
        excludeCities:
          items:
            $ref: '#/components/schemas/CompaniesCityFilter'
          type: array
          nullable: true
          title: Exclude cities
          description: Exclude companies that are present in the specified cities
          examples:
          - - city: New York
              country: us
            - city: Los Angeles
              country: us
        geolocation:
          $ref: '#/components/schemas/GeolocationFilter'
          nullable: true
          title: Geographical location
          description: Filter by latitude and longitude
          examples:
          - latitude: 38.880817
            longitude: -77.10216
            radius: 1000
      additionalProperties: false
      type: object
      title: LocationsFilter
    PublicPreviewSearchCompaniesV3Response:
      properties:
        totalHits:
          type: integer
          title: Total hits
          description: Total number of companies found
          examples:
          - 5173
        redirectMap:
          additionalProperties:
            type: string
          type: object
          nullable: true
          title: Domain redirection mapping
          description: Mapping of original domains passed in filters to their redirected domains.
          examples:
          - given_local_domain.uk: original.com
            ikea.nl: ikea.com
        creditsUsed:
          type: number
          title: Creditsused
          description: Number of credits charged for this request.
          examples:
          - 1.0
        companies:
          items:
            $ref: '#/components/schemas/PublicPreviewCompanyV3Result'
          type: array
          title: Companies found
          description: Array of found companies. Returns empty array if no results
      additionalProperties: false
      type: object
      required:
      - totalHits
      - creditsUsed
      - companies
      title: PublicPreviewSearchCompaniesV3Response
    DepartmentGrowthAllAnyFilter:
      properties:
        anyOf:
          items:
            $ref: '#/components/schemas/DepartmentGrowthFilter'
          type: array
          nullable: true
          title: Any of department headcount growth filters
          description: The result should match **any** of the department headcount growth filters.
          examples:
          - - asPercentage: false
              department: Accounting and Finance
              growthRange:
                from: -1.0
                to: 3.0
              months: Three months
        allOf:
          items:
            $ref: '#/components/schemas/DepartmentGrowthFilter'
          type: array
          nullable: true
          title: All values
          description: The result should match **all** of the he department headcount growth filters.
          examples:
          - - asPercentage: false
              department: Accounting and Finance
              growthRange:
                from: -1.0
                to: 3.0
              months: Three months
      additionalProperties: false
      type: object
      title: DepartmentGrowthAllAnyFilter
    PublicPreviewSearchCompaniesV3Body:
      properties:
        size:
          type: integer
          maximum: 50.0
          minimum: 5.0
          title: Maximum number of results
          description: Number of companies to return. The maximum value is 50 and the minimum is 5
          default: 50
          examples:
          - 50
        companiesFilters:
          $ref: '#/components/schemas/CompaniesFiltersV3'
          nullable: true
          title: Companies filters
          description: Collection of companies filters to be applied to the search
        peopleFilters:
          $ref: '#/components/schemas/PeopleFiltersV3'
          nullable: true
          title: People filters
          description: Collection of people filters to be applied to the search
      additionalProperties: false
      type: object
      title: PublicPreviewSearchCompaniesV3Body
    Revenue:
      type: string
      enum:
      - 0-1M
      - 1-10M
      - 10-50M
      - 50-100M
      - 100-500M
      - 500-1000M
      - '>1000M'
      title: Revenue
    KeywordsFilterV1:
      properties:
        keywords:
          items:
            type: string
          type: array
          title: Keywords
          description: Array of the keywords
        mode:
          type: string
          enum:
          - anyOf
          - allOf
          - noneOf
          title: Search mode
          description: '[default] anyOf - match at least one of the keywords<br>allOf - match all of the keywords<br>noneOf - match none of the keywords'
          default: anyOf
      additionalProperties: false
      type: object
      required:
      - keywords
      title: KeywordsFilterV1
    PublicPerson:
      properties:
        id:
          type: string
          title: Id
          description: Internal ocean id of the person
          examples:
          - e9447c74eafa8a19
        domain:
          type: string
          title: Domain
          description: Domain of the company the person is working for
          examples:
          - google.com
        name:
          type: string
          nullable: true
          title: Name
          description: Full name of the person
          examples:
          - John Doe
        firstName:
          type: string
          nullable: true
          title: Firstname
          description: First name of the person
          examples:
          - John
        lastName:
          type: string
          nullable: true
          title: Lastname
          description: Last name of the person
          examples:
          - Doe
        country:
          type: string
          nullable: true
          title: Country
          description: Country code of the person
          examples:
          - us
          - dk
        state:
          type: string
          nullable: true
          title: State
          description: State code of the person
          examples:
          - CA
          - NY
        location:
          type: string
          nullable: true
          title: Location
          description: Location of the person
          examples:
          - Copenhagen, Capital Region, Denmark
        linkedinUrl:
          type: string
          nullable: true
          title: Linkedinurl
          description: Link to the linkedin profile of the person
          examples:
          - https://www.linkedin.com/in/someone
        seniorities:
          items:
            $ref: '#/components/schemas/Seniority'
          type: array
          nullable: true
          title: Seniorities
          description: List of seniorities computed from the job title of the person
          examples:
          - - C-Level
            - Manager
        departments:
          items:
            $ref: '#/components/schemas/Department'
          type: array
          nullable: true
          title: Departments
          description: List of departments computed from the job title of the person
          examples:
          - - Management
            - Marketing and Advertising
        photo:
          type: string
          nullable: true
          title: Photo
          description: Link to the person's profile picture on LinkedIn
          examples:
          - http://media.licdn.com/dms/image/somelink
        jobTitle:
          type: string
          nullable: true
          title: Jobtitle
          description: Job title of the person
          examples:
          - Professeur
        jobTitleEnglish:
          type: string
          nullable: true
          title: Jobtitleenglish
          description: English translation of the person's job title
          examples:
          - Teacher
        currentJobDescription:
          type: string
          nullable: true
          title: Currentjobdescription
          description: Current job description of the person
          examples:
          - Software Engineer specializing in cloud infrastructure
        experiences:
          items:
            $ref: '#/components/schemas/Experience'
          type: array
          nullable: true
          title: Experiences
          description: List of experiences of the person
          examples:
          - - dateFrom: '2020-01-01'
              dateTo: '2021-01-01'
              description: Software Engineer specializing in cloud infrastructure
              domain: domain.com
              jobTitle: Software Engineer
        summary

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