The Companies API lists API
The lists API from The Companies API — 5 operation(s) for lists.
OpenAPI Specification
openapi: 3.1.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: The 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:
User:
type: object
properties:
colorMode:
type: string
enum:
- dark
- light
- system
createdAt:
type:
- string
- 'null'
currentTeamId:
type:
- number
- 'null'
email:
type: string
emailFree:
type:
- boolean
- 'null'
emailVerified:
type:
- boolean
- 'null'
emailVerifiedResentAt:
type:
- string
- 'null'
fullName:
type:
- string
- 'null'
hasPassword:
type:
- boolean
- 'null'
id:
type: number
locale: {}
pictureUrl:
type:
- string
- 'null'
referral:
type:
- string
- 'null'
role:
type:
- string
- 'null'
enum:
- owner
- user
required:
- currentTeamId
- email
- emailFree
- emailVerified
- emailVerifiedResentAt
- fullName
- hasPassword
- id
- pictureUrl
description: A user of the platform.
PaginationMeta:
type: object
properties:
cost:
type: number
credits:
type: number
currentPage:
type: number
firstPage:
type: number
freeRequest:
type: boolean
lastPage:
type: number
maxScrollResultsReached:
type: boolean
perPage:
type: number
total:
type: number
required:
- cost
- credits
- currentPage
- firstPage
- freeRequest
- lastPage
- perPage
- total
description: Metadata about a paginated or billed response.
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
- operator
- sign
- values
description: A condition for our platform segmentation engine.
CompanyV2:
type: object
properties:
id:
type: string
about:
type: object
properties:
businessType:
type: string
enum:
- educational-institution
- government-agency
- nonprofit
- partnership
- privately-held
- public-company
- self-employed
- sole-proprietorship
description: The type of business the company is.
industries:
type: array
items:
type: string
description: The industries the company is in.
industry:
type: string
description: The main industry of the company.
languages:
type: array
items:
type: string
description: The languages the company supports.
name:
type: string
description: The name of the company.
nameAlts:
type: array
items:
type: string
description: The alternative names of the company.
nameLegal:
type: string
description: The legal name of the company.
totalEmployees:
type: string
enum:
- 1-10
- 10-50
- 50-200
- 200-500
- 500-1k
- 1k-5k
- 5k-10k
- over-10k
description: The total number of employees the company has.
totalEmployeesExact:
# --- 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