The Companies API lists API
The lists API from The Companies API — 5 operation(s) for lists.
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.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/thecompaniesapi-lists-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.2.0
info:
contact:
email: support@thecompaniesapi.com
name: The Companies API
url: https://www.thecompaniesapi.com
description: An enrichment platform to search and retrieve information about companies
termsOfService: https://www.thecompaniesapi.com/product/terms
title: Companies actions Lists API
version: 2.0.0
servers:
- description: Production server
url: https://api.thecompaniesapi.com
tags:
- name: lists
paths:
/v2/lists:
get:
description: Get and filter your lists.
operationId: fetchLists
tags:
- lists
security:
- apiKey: []
parameters:
- schema:
type: number
required: false
name: page
in: query
- schema:
type: number
minimum: 1
maximum: 500
required: false
name: size
in: query
responses:
'200':
description: Get and filter your lists.
content:
application/json:
schema:
type: object
properties:
lists:
type: array
items:
$ref: '#/components/schemas/List'
meta:
$ref: '#/components/schemas/PaginationMeta'
required:
- lists
- meta
'401':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- tokenNotFound
- invalidApiSecret
- missingApiSecret
- userNotAuthenticated
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
post:
description: Create a new list.
operationId: createList
tags:
- lists
security:
- apiKey: []
requestBody:
content:
application/json:
schema:
type: object
properties:
dynamic:
type: boolean
imported:
type: boolean
mailFrequency:
type: string
enum:
- disabled
- daily
- weekly
- monthly
maxCompanies:
type: number
name:
type: string
maxLength: 255
processInitialized:
type: boolean
query:
type: array
items:
$ref: '#/components/schemas/SegmentationCondition'
similarDomains:
type: array
items:
type: string
required:
- name
responses:
'200':
description: Create a new list.
content:
application/json:
schema:
$ref: '#/components/schemas/List'
'401':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- tokenNotFound
- invalidApiSecret
- missingApiSecret
- userNotAuthenticated
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
/v2/lists/{listId}:
patch:
description: Update a list.
operationId: updateList
tags:
- lists
security:
- apiKey: []
parameters:
- schema:
type: number
required: true
name: listId
in: path
requestBody:
content:
application/json:
schema:
type: object
properties:
dynamic:
type: boolean
lastSeen:
type: boolean
mailFrequency:
type: string
enum:
- disabled
- daily
- weekly
- monthly
maxCompanies:
type:
- number
- 'null'
minimum: 0
maximum: 1000000
name:
type: string
maxLength: 255
query:
type: array
items:
$ref: '#/components/schemas/SegmentationCondition'
resync:
type: boolean
responses:
'200':
description: Update a list.
content:
application/json:
schema:
$ref: '#/components/schemas/List'
'400':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- listNotFound
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
'401':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- tokenNotFound
- invalidApiSecret
- missingApiSecret
- userNotAuthenticated
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
'403':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- userCurrentTeamIsNotInstanceOwner
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
delete:
description: Delete a list.
operationId: deleteList
tags:
- lists
security:
- apiKey: []
parameters:
- schema:
type: number
required: true
name: listId
in: path
responses:
'200':
description: Delete a list.
content:
application/json:
schema:
$ref: '#/components/schemas/List'
'400':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- listNotFound
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
'401':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- tokenNotFound
- invalidApiSecret
- missingApiSecret
- userNotAuthenticated
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
'403':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- userCurrentTeamIsNotInstanceOwner
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
/v2/lists/{listId}/companies:
get:
description: Get companies in a list with a segmentation query.
operationId: fetchCompaniesInList
tags:
- lists
security:
- apiKey: []
parameters:
- schema:
type: number
required: true
name: listId
in: path
- schema:
type: number
required: false
name: actionId
in: query
- schema:
type: number
required: false
name: page
in: query
- schema:
type: array
items:
$ref: '#/components/schemas/SegmentationCondition'
required: false
name: query
in: query
- schema:
type: boolean
required: false
name: simplified
in: query
- schema:
type: number
minimum: 1
maximum: 100
required: false
name: size
in: query
- schema:
type: array
items:
type: object
properties:
key:
type: string
enum:
- about.businessType
- about.industries
- about.industry
- about.name
- about.totalEmployees
- about.yearFounded
- analytics.monthlyVisitors
- apps
- codes.naics
- codes.sic
- contacts
- domain.domain
- domain.tld
- finances.revenue
- locations.headquarters.city.code
- locations.headquarters.country.code
- locations.headquarters.county.code
- locations.headquarters.state.code
- meta.score
- meta.syncedAt
- socials
- technologies.active
- urls
missing:
type: string
enum:
- _first
- _last
order:
type: string
enum:
- asc
- desc
required:
- key
- order
required: false
name: sortFields
in: query
- schema:
type: string
enum:
- about.businessType
- about.industries
- about.industry
- about.name
- about.totalEmployees
- about.yearFounded
- analytics.monthlyVisitors
- apps
- codes.naics
- codes.sic
- contacts
- domain.domain
- domain.tld
- finances.revenue
- locations.headquarters.city.code
- locations.headquarters.country.code
- locations.headquarters.county.code
- locations.headquarters.state.code
- meta.score
- meta.syncedAt
- socials
- technologies.active
- urls
required: false
name: sortKey
in: query
- schema:
type: string
enum:
- asc
- desc
required: false
name: sortOrder
in: query
responses:
'200':
description: Get companies in a list with a segmentation query.
content:
application/json:
schema:
type: object
properties:
companies:
type: array
items:
$ref: '#/components/schemas/CompanyV2'
meta:
$ref: '#/components/schemas/PaginationMeta'
query:
type: array
items:
$ref: '#/components/schemas/SegmentationCondition'
required:
- companies
- meta
'400':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- listNotFound
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
'401':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- tokenNotFound
- invalidApiSecret
- missingApiSecret
- userNotAuthenticated
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
'403':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- userCurrentTeamIsNotInstanceOwner
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
post:
description: Get companies in a list with a segmentation body.
operationId: fetchCompaniesInListPost
tags:
- lists
security:
- apiKey: []
parameters:
- schema:
type: number
required: true
name: listId
in: path
requestBody:
content:
application/json:
schema:
type: object
properties:
actionId:
type: number
page:
type: number
query:
type: array
items:
$ref: '#/components/schemas/SegmentationCondition'
simplified:
type: boolean
size:
type: number
minimum: 1
maximum: 100
sortFields:
type: array
items:
type: object
properties:
key:
type: string
enum:
- about.businessType
- about.industries
- about.industry
- about.name
- about.totalEmployees
- about.yearFounded
- analytics.monthlyVisitors
- apps
- codes.naics
- codes.sic
- contacts
- domain.domain
- domain.tld
- finances.revenue
- locations.headquarters.city.code
- locations.headquarters.country.code
- locations.headquarters.county.code
- locations.headquarters.state.code
- meta.score
- meta.syncedAt
- socials
- technologies.active
- urls
missing:
type: string
enum:
- _first
- _last
order:
type: string
enum:
- asc
- desc
required:
- key
- order
sortKey:
type: string
enum:
- about.businessType
- about.industries
- about.industry
- about.name
- about.totalEmployees
- about.yearFounded
- analytics.monthlyVisitors
- apps
- codes.naics
- codes.sic
- contacts
- domain.domain
- domain.tld
- finances.revenue
- locations.headquarters.city.code
- locations.headquarters.country.code
- locations.headquarters.county.code
- locations.headquarters.state.code
- meta.score
- meta.syncedAt
- socials
- technologies.active
- urls
sortOrder:
type: string
enum:
- asc
- desc
responses:
'200':
description: Get companies in a list with a segmentation body.
content:
application/json:
schema:
type: object
properties:
companies:
type: array
items:
$ref: '#/components/schemas/CompanyV2'
meta:
$ref: '#/components/schemas/PaginationMeta'
query:
type: array
items:
$ref: '#/components/schemas/SegmentationCondition'
required:
- companies
- meta
'400':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- listNotFound
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
'401':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- tokenNotFound
- invalidApiSecret
- missingApiSecret
- userNotAuthenticated
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
'403':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- userCurrentTeamIsNotInstanceOwner
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
/v2/lists/{listId}/companies/{domain}:
get:
description: Get a company in a list.
operationId: fetchCompanyInList
tags:
- lists
security:
- apiKey: []
parameters:
- schema:
type: number
required: true
name: listId
in: path
- schema:
type: string
required: true
name: domain
in: path
responses:
'200':
description: Get a company in a list.
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyV2'
'400':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- listNotFound
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
'401':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- tokenNotFound
- invalidApiSecret
- missingApiSecret
- userNotAuthenticated
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
'403':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- userCurrentTeamIsNotInstanceOwner
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
'404':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- companyNotFound
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
/v2/lists/{listId}/companies/toggle:
patch:
description: Toggle one or more companies in a list.
operationId: toggleCompaniesInList
tags:
- lists
security:
- apiKey: []
parameters:
- schema:
type: number
required: true
name: listId
in: path
requestBody:
content:
application/json:
schema:
type: object
properties:
action:
type: string
enum:
- attach
- detach
companyIds:
type: array
items:
type: number
domains:
type: array
items:
type: string
refresh:
type: boolean
required:
- action
responses:
'200':
description: Toggle one or more companies in a list.
content:
application/json:
schema:
$ref: '#/components/schemas/List'
'400':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- listNotFound
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
'401':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- tokenNotFound
- invalidApiSecret
- missingApiSecret
- userNotAuthenticated
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
'403':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- userCurrentTeamIsNotInstanceOwner
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
'404':
description: The error message
content:
application/json:
schema:
type: object
properties:
details: {}
messages:
type: string
enum:
- companyNotFound
status:
type: number
minimum: 400
maximum: 511
required:
- messages
- status
components:
schemas:
Action:
type: object
properties:
attempts:
type: number
cost:
type:
- number
- 'null'
createdAt:
type:
- string
- 'null'
data:
type: object
properties:
cleanedUp:
type: number
completed:
type: array
items:
type: string
completedDomains:
type: number
completedDomainsSample:
type: array
items:
type: string
count:
type: number
domain:
type: string
domains:
type: array
items:
type: string
domainsSample:
type: array
items:
type: string
elasticQuery: {}
failed:
type: array
items:
type: string
failedDomains:
type: number
failedDomainsSample:
type: array
items:
type: string
fields:
type: array
items:
type: object
properties:
description:
type: string
key:
type: string
type:
type: string
enum:
- array|boolean
- array|number
- array|string
- boolean
- number
- string
values:
type: array
items:
type: string
required:
- key
- type
grounded:
type: boolean
job:
type: string
enum:
- ask-domain
- ask-list
- enrich-companies
- enrich-list
- cleanup-list
model:
type: string
enum:
- claude
- claude-mini
- cousteau
- cousteau2
- cousteau2-thinking
- gpt
- gpt-mini
- groq
- groq-mini
- llama4
query:
type: array
items:
$ref: '#/components/schemas/SegmentationCondition'
question:
type: string
team:
$ref: '#/components/schemas/Team'
totalDomains:
type: number
user:
$ref: '#/components/schemas/User'
id:
type: number
listId:
type: number
promptId:
type: number
result:
type: object
properties:
answers:
type: array
items:
$ref: '#/components/schemas/LLMAnswer'
cleanedUp:
type: number
domains:
type: array
items:
type: string
status:
type: string
enum:
- active
- completed
- failed
- pending
teamId:
type: number
type:
type: string
enum:
- companies:added
- jobs:request
updatedAt:
type:
- string
- 'null'
required:
- id
- status
description: An action tracks a request made to our job queue and its result.
SegmentationCondition:
type: object
properties:
attribute:
type: string
enum:
- about.businessType
- about.industries
- about.industry
- about.name
- about.totalEmployees
- about.yearFounded
- ai.search
- analytics.monthlyVisitors
- apps
- codes.naics
- codes.sic
- contacts
- domain.domain
- domain.tld
- finances.revenue
- finances.stockExchange
- locations.headquarters.city.code
- locations.headquarters.continent.code
- locations.headquarters.country.code
- locations.headquarters.county.code
- locations.headquarters.state.code
- meta.listIds
- meta.score
- meta.syncedAt
- socials
- socials.linkedin.id
- technologies.active
- technologies.categories
- urls
blockedOperator:
type: boolean
operator:
type: string
enum:
- and
- or
sign:
type: string
enum:
- equals
- exactEquals
- greater
- lower
- notEquals
values:
type: array
items:
anyOf:
- type: string
- type: number
required:
- attribute
# --- truncated at 32 KB (128 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/thecompaniesapi/refs/heads/main/openapi/thecompaniesapi-lists-api-openapi.yml