The Segmentation API from Ocean.io — 4 operation(s) for segmentation.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/ocean-io-segmentation-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
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.
A second provider on the same verified email joins the account you already have.
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:
SegmentationStatus:
type: string
enum:
- IN_PROGRESS
- SUCCESSFUL
- FAILED
title: SegmentationStatus
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
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
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
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
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
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
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
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
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
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
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
StatusResponse:
properties:
status:
type: string
title: Status
type: object
required:
- status
title: StatusResponse