Ocean.io

Ocean.io Segmentation API

The Segmentation API from Ocean.io — 4 operation(s) for segmentation.

GitHub OpenAPI
Business capability
Customer Segmentation Management BC-420.20

Operations 4

GET /v2/segmentation/{segmentation_id} Get segmentation #
POST /v2/segmentation Create segmentation #
POST /v2/segmentation/{segmentation_id}/markDomains Add domains to the positive or negative list of a segmentation #
POST /v2/segmentation/{segmentation_id}/attribute-domains Attribute domains to segments #

Documentation

📖
Documentation
https://app.ocean.io/docs
📖
APIReference
https://app.ocean.io/docs
📖
GettingStarted
https://app.ocean.io/docs/getting-started/quickstart

Specifications

⚙
OpenAPI
https://artifacts.apis.io/ocean-io/openapi/ocean-io-segmentation-api-openapi.yml

Other Resources

🔗
ToolCrosswalk
https://artifacts.apis.io/ocean-io/mcp/ocean-io-tool-crosswalk.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/ocean-io:ocean-io-segmentation-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

ocean-io-segmentation-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Ocean.io API Documentation Segmentation API
  summary: Welcome to Ocean.io's API.
  description: Welcome to Ocean.io's API.
  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: Segmentation
paths:
  /v2/segmentation/{segmentation_id}:
    get:
      tags:
      - Segmentation
      summary: Get segmentation
      description: Retrieve a segmentation by its id, including its segments, traits, and CRM metrics once `status` is `SUCCESSFUL`.
      operationId: getSegmentation
      parameters:
      - name: segmentation_id
        in: path
        required: true
        schema:
          type: integer
          title: Segmentation Id
      - 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
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Segmentation'
        '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/segmentation:
    post:
      tags:
      - Segmentation
      summary: Create segmentation
      description: Create a new segmentation from a list of company domains. Runs asynchronously — poll Get Segmentation until `status` is `SUCCESSFUL` to read the resulting segments.
      operationId: createSegmentation
      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/SegmentationInput'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentationId'
        '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
                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/segmentation/{segmentation_id}/markDomains:
    post:
      tags:
      - Segmentation
      summary: Add domains to the positive or negative list of a segmentation
      description: Append domains to the positive or negative list of an existing segmentation to steer future results toward good-fit companies and away from poor-fit ones.
      operationId: addMarkedDomains
      parameters:
      - name: segmentation_id
        in: path
        required: true
        schema:
          type: integer
          title: Segmentation Id
      - 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/AddMarkedDomainsInput'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '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':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - Segmentation not found
                required:
                - detail
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v2/segmentation/{segmentation_id}/attribute-domains:
    post:
      tags:
      - Segmentation
      summary: Attribute domains to segments
      description: Assign each input domain to the closest segment in a segmentation, with a 0-1 match score. The segmentation must have completed successfully first.
      operationId: attributeSegmentationDomains
      parameters:
      - name: segmentation_id
        in: path
        required: true
        schema:
          type: integer
          title: Segmentation Id
      - 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/AttributeSegmentationDomainsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeSegmentationDomainsResponse'
        '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':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                required:
                - detail
          description: Not Found
        '412':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - Segmentation must be re-run to enable attribution.
                required:
                - detail
          description: Precondition Failed
        '502':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    enum:
                    - Clustering service error
                required:
                - detail
          description: Bad Gateway
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AttributeSegmentationDomainsRequest:
      properties:
        domains:
          items:
            type: string
          type: array
          maxItems: 1000
          minItems: 1
          title: Domains
          description: Domains to attribute (max 1000).
          examples:
          - - domain1.com
            - domain2.com
      type: object
      required:
      - domains
      title: AttributeSegmentationDomainsRequest
    SegmentCrmMetrics:
      properties:
        averageDealValue:
          type: number
          nullable: true
          title: Averagedealvalue
          description: Average deal value for the segment, from your connected CRM.
          examples:
          - 48000
        averageTimeToClose:
          type: number
          nullable: true
          title: Averagetimetoclose
          description: Average time to close in days, from your connected CRM.
          examples:
          - 64
        winRate:
          type: number
          nullable: true
          title: Winrate
          description: Win rate for the segment (0-1), from your connected CRM.
          examples:
          - 0.31
        untouchedCount:
          type: integer
          nullable: true
          title: Untouchedcount
          description: Companies in the segment you have no CRM activity with yet.
          examples:
          - 12
      type: object
      required:
      - averageDealValue
      - averageTimeToClose
      - winRate
      - untouchedCount
      title: SegmentCrmMetrics
    Segment:
      properties:
        segmentId:
          type: integer
          title: Segmentid
          description: Unique id of the segment within the segmentation.
          examples:
          - 1
        name:
          type: string
          title: Name
          description: Human-readable label describing the segment.
          examples:
          - Enterprise data platforms
        domains:
          items:
            type: string
          type: array
          title: Domains
          description: Domains of the companies assigned to this segment.
          examples:
          - - snowflake.com
            - datadoghq.com
        companyCount:
          type: integer
          title: Companycount
          description: Number of companies in the segment.
          examples:
          - 2
        traits:
          items:
            $ref: '#/components/schemas/ScoringFeature'
          type: array
          nullable: true
          title: Traits
          description: Company attributes that most define the segment, each with the matched value and a relative score. Present when the segmentation was run with scoring features.
        crmMetrics:
          $ref: '#/components/schemas/SegmentCrmMetrics'
          nullable: true
          description: Deal performance for the segment, from your connected CRM. `null` when CRM metrics aren't available.
        lookalikeCount:
          type: integer
          nullable: true
          title: Lookalikecount
          description: Estimated number of lookalike companies for this segment.
          examples:
          - 1840
      type: object
      required:
      - segmentId
      - name
      - domains
      - companyCount
      title: Segment
    AttributeSegmentationDomainsResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/AttributedDomain'
          type: array
          title: Results
          description: One result per input domain, in the same order.
        totalRequested:
          type: integer
          title: Totalrequested
          description: Total number of domains requested.
          examples:
          - 3
        totalAttributed:
          type: integer
          title: Totalattributed
          description: Number of domains attributed to a segment. Excludes unmatched domains and domains that couldn't be evaluated.
          examples:
          - 2
      type: object
      required:
      - results
      - totalRequested
      - totalAttributed
      title: AttributeSegmentationDomainsResponse
    StatusResponse:
      properties:
        status:
          type: string
          title: Status
      type: object
      required:
      - status
      title: StatusResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AttributedDomain:
      properties:
        domain:
          type: string
          title: Domain
          description: The domain that was attributed.
          examples:
          - domain1.com
        segmentId:
          type: integer
          nullable: true
          title: Segmentid
          description: ID of the matching segment, or `null` if the domain didn't match any segment closely enough (the unattributed bucket).
          examples:
          - 42
        score:
          type: number
          maximum: 1.0
          minimum: 0.0
          nullable: true
          title: Score
          description: Match score (0-1). Higher means a stronger match to the assigned segment. `null` when the domain didn't match any segment closely enough or couldn't be evaluated.
          examples:
          - 0.91
      type: object
      required:
      - domain
      - segmentId
      title: AttributedDomain
    SegmentationStatus:
      type: string
      enum:
      - IN_PROGRESS
      - SUCCESSFUL
      - FAILED
      title: SegmentationStatus
    SegmentationId:
      properties:
        segmentationId:
          type: integer
          title: Segmentationid
          description: Unique id of the segmentation. Use it to poll for results with the get segmentation endpoint.
          examples:
          - 12345
      type: object
      required:
      - segmentationId
      title: SegmentationId
    AddMarkedDomainsInput:
      properties:
        domains:
          items:
            type: string
          type: array
          title: Domains
          description: Domains to add to the positive or negative list.
          examples:
          - - stripe.com
            - twilio.com
        type:
          type: string
          enum:
          - positive
          - negative
          title: Type
          description: Whether these domains are a good fit (`positive`) or a poor fit (`negative`).
          examples:
          - positive
      type: object
      required:
      - domains
      - type
      title: AddMarkedDomainsInput
    SegmentationInput:
      properties:
        domains:
          items:
            type: string
          type: array
          title: Domains
          description: Company domains to segment. Provide a representative set of the companies you want to group, typically your customers or best-fit accounts.
          examples:
          - - stripe.com
            - twilio.com
            - datadoghq.com
            - snowflake.com
        leadScoringFeatures:
          items:
            type: string
            enum:
            - company_size
            - industry_categories
            - industries
            - linkedin_industry
            - countries
            - primary_country
            - ecommerce
            - is_small_site
            - technologies
            - technology_categories
            - keywords
            - year_founded
            - international_presence
            - multiple_locations
            - web_traffic_visits
            - revenue
            - headcount_growth_3m
            - headcount_growth_6m
            - headcount_growth_12m
            - headcount_growth_3m_percentage
            - headcount_growth_6m_percentage
            - headcount_growth_12m_percentage
          type: array
          nullable: true
          title: Leadscoringfeatures
          description: Company attributes to consider when grouping and scoring companies (for example `industries`, `technologies`, `company_size`). Omit to use the default feature set.
          examples:
          - - industries
            - technologies
            - company_size
        numberOfSegmentsMode:
          type: integer
          nullable: true
          title: Numberofsegmentsmode
          description: Bias toward fewer or more segments. Omit to let the service choose the number that best fits the data.
        positiveDomains:
          items:
            type: string
          type: array
          nullable: true
          title: Positivedomains
          description: Companies that are a good fit. The segmentation leans toward similar companies.
          examples:
          - - stripe.com
        negativeDomains:
          items:
            type: string
          type: array
          nullable: true
          title: Negativedomains
          description: Companies that are a poor fit. The segmentation leans away from similar companies.
          examples:
          - - tinyunknown.io
      type: object
      required:
      - domains
      title: SegmentationInput
    ScoringFeature:
      properties:
        featureName:
          type: string
          title: Featurename
          description: Feature that contributed to score
        featureValue:
          type: string
          title: Featurevalue
          description: Specific value that matched
        score:
          type: number
          title: Score
          description: Boost contribution
      type: object
      required:
      - featureName
      - featureValue
      - score
      title: ScoringFeature
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Segmentation:
      properties:
        segmentationId:
          type: integer
          title: Segmentationid
          description: Unique id of the segmentation.
          examples:
          - 12345
        segments:
          items:
            $ref: '#/components/schemas/Segment'
          type: array
          title: Segments
          description: Resulting segments. Empty while `status` is `IN_PROGRESS`.
        status:
          $ref: '#/components/schemas/SegmentationStatus'
          description: '`IN_PROGRESS` while running, `SUCCESSFUL` when segments are ready, or `FAILED` if it could not be completed.'
          examples:
          - SUCCESSFUL
        totalAddressableMarket:
          type: integer
          nullable: true
          title: Totaladdressablemarket
          description: Estimated number of lookalike companies across all segments.
          examples:
          - 3200
        totalUntouched:
          type: integer
          nullable: true
          title: Totaluntouched
          description: Companies in the addressable market you have no CRM activity with yet.
          examples:
          - 27
      type: object
      required:
      - segmentationId
      - segments
      - status
      title: Segmentation