Ocean.io Enrich API

openapi: 3.2.0
info:
  title: Ocean.io API Documentation Enrich 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: Enrich
paths:
  /v2/enrich/company:
    post:
      tags:
      - Enrich
      summary: Enrich company
      description: 'Match a company with our database and enrich it with additional information.



        **Webhook result:**

        [Documentation](/docs/webhooks/enrich_person_email)'
      operationId: enrichCompany
      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/MatchCompanyBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichCompanyResult'
        '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
                    - Empty body
                required:
                - detail
          description: Bad Request
        '404':
          description: Not found
        '201':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - Data gathering process has started. Please try again later.
                required:
                - detail
          description: Created
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/enrich/person:
    post:
      tags:
      - Enrich
      summary: Enrich person
      description: 'Match a person with our database and enrich it with additional information.



        **Webhook result:**

        [Documentation](/docs/webhooks/enrich_person_phone)'
      operationId: enrichPerson
      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/MatchPersonBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichPersonResult'
        '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
                    - Empty `person` body
                required:
                - detail
          description: Bad Request
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - No matching record found
                required:
                - detail
          description: Not Found
        '201':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - Data gathering process has started. Please try again later.
                required:
                - detail
          description: Created
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/enrich/companies:
    post:
      tags:
      - Enrich
      summary: Enrich companies
      description: 'Match companies with our database and enrich it with additional information.



        **Webhook result:**

        [Documentation](/docs/webhooks/enrich_companies)'
      operationId: enrichCompanies
      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/MatchCompaniesBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichCompaniesResult'
        '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'
  /v2/enrich/people:
    post:
      tags:
      - Enrich
      summary: Enrich people
      description: 'Match people with our database and enrich it with additional information.



        **Webhook result:**

        [Documentation](/docs/webhooks/enrich_people)'
      operationId: enrichPeople
      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/MatchPeopleBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichPeopleResult'
        '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'
components:
  schemas:
    ImpressumPerson:
      properties:
        name:
          type: string
          title: Name
          examples:
          - Michael Scott
        position:
          type: string
          nullable: true
          title: Position
          examples:
          - Regional Manager
      type: object
      required:
      - name
      title: ImpressumPerson
    Media:
      properties:
        url:
          type: string
          title: Media URL
          description: URL of the media
        handle:
          type: string
          nullable: true
          title: Handle
          description: ids extracted from social media urls
        name:
          type: string
          nullable: true
          title: Name
          description: Name of the company as it appears in the social media account
        specialties:
          items:
            type: string
          type: array
          nullable: true
          title: Specialties
          description: Specialties of the company as it appears in the social media account. Right now we only have this for LinkedIn.
          examples:
          - - artificial intelligence
            - machine learning
      type: object
      required:
      - url
      title: Media
    RevealEmails:
      properties:
        includeEmails:
          type: boolean
          title: Include emails
          description: Include the emails for all the results. One email credit will be charged for each verified email.
          default: false
          examples:
          - true
        webhookUrl:
          type: string
          nullable: true
          title: Webhook url
          description: Only relevant if `includeEmails` is True. Webhook url to get the reveal email results, if any email has to be processed in the background.
          examples:
          - https://url.com/webhook
      additionalProperties: false
      type: object
      title: RevealEmails
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Company:
      properties:
        name:
          type: string
          nullable: true
          title: Company name
          description: The name of the company
          examples:
          - Ocean ApS
        registrationNumber:
          type: string
          nullable: true
          title: Registration number
          description: The registration number of the company
          examples:
          - '123456789'
        email:
          type: string
          nullable: true
          title: Email
          description: The email of the company
          examples:
          - hello@ocean.io
        phone:
          type: string
          nullable: true
          title: Phone
          description: The phone number of the company
          examples:
          - +45 12345678
        countryCode:
          type: string
          nullable: true
          title: Country code
          description: Country code of the company's headquarters
          examples:
          - dk
        state:
          type: string
          nullable: true
          title: State
          description: Name of the state/region where the company is located
          examples:
          - Arkansas
        city:
          type: string
          nullable: true
          title: City
          description: The city where the company is located
          examples:
          - Copenhagen
        streetAddress:
          type: string
          nullable: true
          title: Street address
          description: Street address of the company
          examples:
          - Strandgade 6
        postalCode:
          type: string
          nullable: true
          title: Postal code
          description: The postal code of the company
          examples:
          - '1401'
        address:
          type: string
          nullable: true
          title: Address
          description: Full address of the company
          examples:
          - Strandgade 6, 1401 Copenhagen
        facebook:
          type: string
          nullable: true
          title: Facebook
          description: The Facebook page of the company
          examples:
          - https://www.facebook.com/oceanio
        twitter:
          type: string
          nullable: true
          title: Twitter
          description: Company's Twitter page
          examples:
          - https://twitter.com/oceanio
        linkedin:
          type: string
          nullable: true
          title: LinkedIn
          description: LinkedIn page of the company
          examples:
          - https://www.linkedin.com/company/oceanio
        instagram:
          type: string
          nullable: true
          title: Instagram
          description: Instagram page of the company
          examples:
          - https://www.instagram.com/oceanio
        xing:
          type: string
          nullable: true
          title: Xing
          description: The Xing page of the company
          examples:
          - https://www.xing.com/oceanio
        domain:
          type: string
          nullable: true
          title: Domain
          description: The domain name of the company's website
          examples:
          - ocean.io
        youtube:
          type: string
          nullable: true
          title: YouTube
          description: The YouTube page of the company
          examples:
          - https://www.youtube.com/oceanio
      additionalProperties: false
      type: object
      title: Company
    Medias:
      properties:
        linkedin:
          $ref: '#/components/schemas/Media'
          nullable: true
          description: LinkedIn page associated with the company
          examples:
          - handle: dunder-mifflin
            name: Dunder Mifflin Paper Company, Inc.
            url: https://www.linkedin.com/company/dunder-mifflin
        twitter:
          $ref: '#/components/schemas/Media'
          nullable: true
          description: Twitter page associated with the company
          examples:
          - handle: dunder-mifflin
            name: Dunder Mifflin Paper Company, Inc.
            url: https://twitter.com/dunder-mifflin
        youtube:
          $ref: '#/components/schemas/Media'
          nullable: true
          description: YouTube page associated with the company
          examples:
          - handle: dunder-mifflin
            name: Dunder Mifflin Paper Company, Inc.
            url: https://youtube.com/channel/dunder-mifflin
        facebook:
          $ref: '#/components/schemas/Media'
          nullable: true
          description: Facebook page associated with the company
          examples:
          - handle: dunder-mifflin
            name: Dunder Mifflin Paper Company, Inc.
            url: https://facebook.com/dunder-mifflin
        xing:
          $ref: '#/components/schemas/Media'
          nullable: true
          description: Xing page associated with the company
          examples:
          - handle: dunder-mifflin
            name: Dunder Mifflin Paper Company, Inc.
            url: https://xing.com/dunder-mifflin
        tiktok:
          $ref: '#/components/schemas/Media'
          nullable: true
          description: TikTok page associated with the company
          examples:
          - handle: dunder-mifflin
            name: Dunder Mifflin Paper Company, Inc.
            url: https://tiktok.com/dunder-mifflin
        instagram:
          $ref: '#/components/schemas/Media'
          nullable: true
          description: Instagram page associated with the company
          examples:
          - handle: dunder-mifflin
            name: Dunder Mifflin Paper Company, Inc.
            url: https://instagram.com/dunder-mifflin
      type: object
      title: Medias
    Department:
      type: string
      enum:
      - Accounting and Finance
      - Board
      - Business Support
      - Customer Relations
      - Design
      - Editorial Personnel
      - Engineering
      - Founder/Owner
      - Healthcare
      - HR
      - Legal
      - Management
      - Manufacturing
      - Marketing and Advertising
      - Operations
      - PR and Communications
      - Procurement
      - Product
      - Quality Control
      - R&D
      - Sales
      - Security
      - Supply Chain
      - Other
      title: Department
    PublicCompanySize:
      type: string
      enum:
      - 0-1
      - 2-10
      - 11-50
      - 51-200
      - 201-500
      - 501-1000
      - 1001-5000
      - 5001-10000
      - 10001-50000
      - 50001-100000
      - 100001-500000
      - 500000+
      title: PublicCompanySize
    EnrichCompanyResult:
      properties:
        domain:
          type: string
          title: Domain
          description: Domain of the company, used as a unique identifier
          examples:
          - dundermifflinpaper.com
        countries:
          items:
            type: string
          type: array
          nullable: true
          title: Countries
          description: List of all countries in which the company operates
          examples:
          - - us
            - ca
        primaryCountry:
          type: string
          nullable: true
          title: Primary country
          description: Main country of the company
          examples:
          - us
        companySize:
          $ref: '#/components/schemas/PublicCompanySize'
          nullable: true
          title: Company size range
          description: Company size range
          examples:
          - 2-10
        industryCategories:
          items:
            type: string
          type: array
          nullable: true
          title: Industrycategories
          description: Industry categories of the company<br>Available values can be found at /v2/data-fields endpoint.
          examples:
          - - Consumer Electronics
            - Hardware
        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
        linkedinIndustry:
          type: string
          nullable: true
          title: Linkedinindustry
          description: Linkedin industry of the company<br>Available values can be found at /v2/data-fields endpoint.
          examples:
          - Computer Software
        ecommerce:
          type: boolean
          nullable: true
          title: E-Commerce
          description: True if the company is an e-commerce company
          examples:
          - true
        keywords:
          items:
            type: string
          type: array
          nullable: true
          title: Keywords
          description: Keywords associated with the company
          examples:
          - - paper
            - premium copy paper
        employeeCountOcean:
          type: integer
          nullable: true
          title: Employeecountocean
          description: Number of people working at the company in our database.
          examples:
          - 57
        employeeCountLinkedin:
          type: integer
          nullable: true
          title: Employeecountlinkedin
          description: Number of people linked to the company page on Linkedin. This number might be higher than `employeeCountOcean` because of private profiles.
          examples:
          - 70
        revenue:
          $ref: '#/components/schemas/Revenue'
          nullable: true
          title: Revenue range
          description: Revenue range
          examples:
          - 1-10M
        yearFounded:
          type: integer
          nullable: true
          title: Yearfounded
          description: Year the company was founded
          examples:
          - 1999
        description:
          type: string
          nullable: true
          title: Description
          description: Company's description
          examples:
          - Dunder Mifflin Paper Company, Inc. is a fictional paper and office supplies wholesale company featured in the American television series The Office.
        emails:
          items:
            type: string
          type: array
          nullable: true
          title: Emails
          description: Emails of the company
          examples:
          - - email1@domain.com
            - email2@domain.com
        phones:
          items:
            $ref: '#/components/schemas/ContactNumber'
          type: array
          nullable: true
          title: Phones
          description: Phones of the company
          examples:
          - - country: us
              number: +1 212 456 7890
              primary: true
            - country: ca
              number: +1 250 555 0199
        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
        technologies:
          items:
            type: string
          type: array
          nullable: true
          title: Technologies
          description: Software technologies used by the company
          examples:
          - - Accesso
            - Adcash
            - Atlassian Jira
        technologyCategories:
          items:
            type: string
          type: array
          nullable: true
          title: Technology categories
          description: Technology categories of the company
          examples:
          - - Security
            - Analytics
            - Blogs
        mobileApps:
          items:
            $ref: '#/components/schemas/MobileApp'
          type: array
          nullable: true
          title: Mobile apps
          description: Mobile apps produced by the company
        webTraffic:
          $ref: '#/components/schemas/WebTraffic'
          nullable: true
          description: Web traffic of the domain
          examples:
          - bounceRate: 0.5227
            pageViews: 2155984
            pagesPerVisit: 4.88
            visits: 10000
        medias:
          $ref: '#/components/schemas/Medias'
          nullable: true
          title: Social medias
          description: Social medias of the company
        name:
          type: string
          nullable: true
          title: Name
          description: Name of the company
          examples:
          - Dunder Mifflin Paper Company
        legalName:
          type: string
          nullable: true
          title: Legalname
          description: Legal name of the company
          examples:
          - Dunder Mifflin Paper Company, Inc.
        locations:
          items:
            $ref: '#/components/schemas/public_api__models__company__Location'
          type: array
          nullable: true
          title: Locations
          description: Locations of the company
        departmentSizes:
          items:
            $ref: '#/components/schemas/DepartmentSize'
          type: array
          nullable: true
          title: Department sizes
          description: Number of employees per department
          examples:
          - - department: Accounting and Finance
              size: 10
            - department: Sales
              size: 15
        rootUrl:
          type: string
          nullable: true
          title: Rooturl
          description: Root url to access the website
          examples:
          - https://dundermifflinpaper.com/
        faxes:
          items:
            $ref: '#/components/schemas/ContactNumber'
          type: array
          nullable: true
          title: Faxes
          description: Faxes of the company
          examples:
          - - country: us
              number: '5709045026'
              primary: true
        impressum:
          $ref: '#/components/schemas/Impressum'
          nullable: true
          title: Impressum
          description: Impressum (Imprint) data of the company (only for Germany, Austria, Switzerland)
        fundingRound:
          $ref: '#/components/schemas/FundingRound'
          nullable: true
          title: Funding round
          description: Funding round of the company
          examples:
          - cbUrl: https://www.crunchbase.com/funding_round/orderyoyo-post-ipo-equity--5c26b0c0
            date: '2020-01-01'
            moneyRaisedInUsd: 1000000
            type: Seed
        redirectedFrom:
          items:
            type: string
          type: array
          nullable: true
          title: Redirected from
          description: Urls that redirects to this domain. We provide maximum 10 urls in this field.
          examples:
          - - pol.dk
            - pressen.nu
        updatedAt:
          type: string
          nullable: true
          title: Updated at
          description: When has the company data been updated for the last time
          examples:
          - '2022-08-22T12:09:37Z'
        headcountGrowth:
          $ref: '#/components/schemas/Growth'
          nullable: true
          title: Headcount growth
          description: Headcount growth of the company
          examples:
          - sixMonths: 10
            sixMonthsPercentage: 0.2
            threeMonths: 5
            threeMonthsPercentage: 0.1
            twelveMonths: 15
            twelveMonthsPercentage: 0.3
        headcountGrowthPerDepartment:
          items:
            $ref: '#/components/schemas/DepartmentSizesGrowth'
          type: array
          nullable: true
          title: Headcount growth per department
          description: Headcount growth per department
          examples:
          - - department: Accounting and Finance
              growth:
                sixMonths: 10
                sixMonthsPercentage: 0.2
                threeMonths: 5
                threeMonthsPercentage: 0.1
                twelveMonths: 15
                twelveMonthsPercentage: 0.3
        creditsUsed:
          type: number
          title: Creditsused
          description: Number of credits charged for this request.
          examples:
          - 0.1
      type: object
      required:
      - domain
      - creditsUsed
      title: EnrichCompanyResult
    Revenue:
      type: string
      enum:
      - 0-1M
      - 1-10M
      - 10-50M
      - 50-100M
      - 100-500M
      - 500-1000M
      - '>1000M'
      title: Revenue
    CompanyField:
      type: string
      enum:
      - domain
      - countries
      - primaryCountry
      - companySize
      - industryCategories
      - industries
      - linkedinIndustry
      - ecommerce
      - keywords
      - employeeCountOcean
      - employeeCountLinkedin
      - revenue
      - yearFounded
      - description
      - emails
      - phones
      - phones.number
      - phones.country
      - phones.primary
      - logo
      - technologies
      - technologyCategories
      - mobileApps
      - mobileApps.link
      - mobileApps.name
      - webTraffic
      - webTraffic.visits
      - webTraffic.pageViews
      - webTraffic.pagesPerVisit
      - medias
      - medias.linkedin
      - medias.twitter
      - medias.youtube
      - medias.facebook
      - medias.xing
      - medias.tiktok
      - medias.instagram
      - name
      - legalName
      - locations
      - locations.primary
      - locations.country
      - locations.locality
      - locations.region
      - locations.postalCode
      - locations.streetAddress
      - locations.state
      - locations.regionCode
      - departmentSizes
      - rootUrl
      - faxes
      - faxes.number
      - faxes.country
      - faxes.primary
      - impressum
      - impressum.company
      - impressum.address
      - impressum.email
      - impressum.phone
      - impressum.fax
      - impressum.vat
      - impressum.url
      - impressum.people
      - fundingRound
      - fundingRound.date
      - fundingRound.type
      - funding

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