Package Exports
- @thecompaniesapi/sdk
- @thecompaniesapi/sdk/package.json
Readme
The Companies API SDK for TypeScript
A fully-featured TypeScript SDK for The Companies API, providing type-safe access to company data, locations, industries, technologies, job titles, lists, and more.
If you need more details about a specific endpoint, you can find the corresponding documentation in the API reference.
You can also contact us on our livechat if you have any questions.
🚀 Features
- Type-safe API client with full TypeScript support from our OpenAPI schema
- Powerful search capabilities with filters, sorting and pagination
- Real-time company enrichment with both synchronous and asynchronous options
- Create and manage your company lists
- Track and monitor enrichment actions and requests
- Generate detailed analytics and insights for searches and lists
- Natural language querying for structured company information
- Lightweight with minimal dependencies
- Promise-based async/await interface
📦 Installation
# with npm
npm install @thecompaniesapi/sdk
# with yarn
yarn add @thecompaniesapi/sdk
# with pnpm
pnpm add @thecompaniesapi/sdk🔑 Initialize the client
Get your API token from your settings page and initialize our client with createClient.
The API token is required to authenticate your requests and should be kept secure. Never commit your API token to version control or share it publicly.
import createClient from '@thecompaniesapi/sdk'
const tca = createClient({
apiKey: 'your-api-token',
})🏬 Companies
Search companies
🔍 To learn more about our query system, please read our use case documentation.
// Search companies by industry and size
await tca.searchCompanies({
query: [
{ attribute: 'about.industries', operator: 'or', sign: 'equals', values: ['computer-software'] },
{ attribute: 'about.totalEmployees', operator: 'or', sign: 'equals', values: ['10-50'] }
],
size: 25
})
const companies = response.data.companies // Companies that match the query
const meta = response.data.meta // Meta informationSearch companies by name
const response = await tca.searchCompaniesByName({
name: 'The Companies API',
size: 2
})
const companies = response.data.companies // Companies that match the name
const meta = response.data.meta // Meta informationSearch companies using a prompt
// Search 25 companies for a specific prompt
const response = await tca.searchCompaniesByPrompt({
prompt: 'SaaS Companies in the United States with more than 100 employees',
size: 25
})
const companies = response.data.companies // Companies that match the prompt
const meta = response.data.meta // Meta informationSearch similar companies
// Search 25 companies that are similar to Crisp and Intercom
const response = await tca.searchSimilarCompanies({
domains: ['crisp.chat', 'intercom.com'],
size: 25
})
const companies = response.data.companies // Companies that are similar to the domains
const meta = response.data.meta // Meta informationCount companies matching your query
// Count how many companies are in the computer-software industry
const response = await tca.countCompanies({
query: [
{
attribute: 'about.industries',
operator: 'or',
sign: 'equals',
values: ['computer-software']
}
]
})
const count = response.data // Number of companies that match the queryEnrich a company from a domain name
// Fetch company data from our database without enrichment (faster response)
const response = await tca.fetchCompany({
domain: 'microsoft.com'
})
const company = response.data // The company profile
// Fetch company data and re-analyze it in real-time to get fresh, up-to-date information (slower but more accurate)
const response = await tca.fetchCompany({
domain: 'microsoft.com',
refresh: true
})
const company = response.data // The company profileEnrich a company from an email
// Fetch the company profile behind a professional email address
const response = await tca.fetchCompanyByEmail({
email: 'jack@openai.com'
})
const company = response.data // The company profileEnrich a company from a social network URL
// Fetch the company profile behind a social network URL
const response = await tca.fetchCompanyBySocial({
linkedin: 'https://www.linkedin.com/company/apple'
})
const company = response.data // The company profileFind a company email patterns
// Fetch the company email patterns for a specific domain
const response = await tca.fetchCompanyEmailPatterns({
domain: 'apple.com'
})
const patterns = response.data // The company email patternsAsk a question about a company
// Ask what products a company offers using its domain
const response = await tca.askCompany({
domain: 'microsoft.com',
question: 'What products does this company offer?',
model: 'large', // 'small' is also available
fields: [
{
key: 'products',
type: 'array|string',
description: 'The products that the company offers'
}
]
})
const answer = response.data.answer // Structured AI response
const meta = response.data.meta // Meta informationFetch the context of a company
// Get AI-generated strategic insights about a company
const response = await tca.fetchCompanyContext({
domain: 'microsoft.com'
})
const context = response.data.context // Includes market, model, differentiators, etc.
const meta = response.data.meta // Meta informationFetch analytics data for a query or your lists
// Analyze company distribution by business type
const response = await tca.fetchCompaniesAnalytics({
attribute: 'about.businessType',
query: [
{
attribute: 'locations.headquarters.country.code',
operator: 'or',
sign: 'equals',
values: ['us', 'gb', 'fr']
}
]
})
const analytics = response.data.data // Aggregated values
const meta = response.data.meta // Meta informationExport analytics data in multiple formats for a search
// Export analytics to CSV
const response = await tca.exportCompaniesAnalytics({
format: 'csv',
attributes: ['about.industries', 'about.totalEmployees'],
query: [
{
attribute: 'technologies.active',
operator: 'or',
sign: 'equals',
values: ['shopify']
}
]
})
const analytics = response.data.data // Aggregated values
const meta = response.data.meta // Meta information🎯 Actions
Request an action on one or more companies
// Request an enrichment job on multiple companies
const response = await tca.requestAction({
domains: ['microsoft.com', 'apple.com'],
job: 'enrich-companies',
estimate: false
})
const actions = response.data.actions // Track this via fetchActions
const meta = response.data.meta // Meta informationFetch the actions for your actions
// Fetch recent actions
const response = await tca.fetchActions({
status: 'completed',
page: 1,
size: 5
})
const actions = response.data.actions // Actions that match the query
const meta = response.data.meta // Meta information🏭 Industries
Search industries
// Search industries by keyword
const response = await tca.searchIndustries({
search: 'software',
size: 10
})
const industries = response.data.industries // Industries that match the keyword
const meta = response.data.meta // Meta informationFind similar industries
// Find industries similar to given ones
const response = await tca.searchIndustriesSimilar({
industries: ['saas', 'fintech']
})
const similar = response.data.industries // Industries that are similar to the given ones
const meta = response.data.meta // Meta information⚛️ Technologies
Search technologies
// Search technologies by keyword
const response = await tca.searchTechnologies({
search: 'shopify',
size: 10
})
const technologies = response.data.technologies // Technologies that match the keyword
const meta = response.data.meta // Meta information🌍 Locations
Search cities
// Search cities by name
const response = await tca.searchCities({
search: 'new york',
size: 5
})
const cities = response.data.cities // Cities that match the name
const meta = response.data.meta // Meta informationSearch counties
// Search counties by name
const response = await tca.searchCounties({
search: 'orange',
size: 5
})
const counties = response.data.counties // Counties that match the name
const meta = response.data.meta // Meta informationSearch states
// Search states by name
const response = await tca.searchStates({
search: 'california',
size: 5
})
const states = response.data.states // States that match the name
const meta = response.data.meta // Meta informationSearch countries
// Search countries by name
const response = await tca.searchCountries({
search: 'france',
size: 5
})
const countries = response.data.countries // Countries that match the name
const meta = response.data.meta // Meta informationSearch continents
// Search continents by name
const response = await tca.searchContinents({
search: 'asia',
size: 5
})
const continents = response.data.continents // Continents that match the name
const meta = response.data.meta // Meta information💼 Job titles
Enrich a job title from its name
// Enrich "chief marketing officer"
const response = await tca.enrichJobTitles({
name: 'chief marketing officer'
})
const jobTitle = response.data // Contains department, seniority, etc.📋 Lists
Fetch your lists
// Fetch your lists
const response = await tca.fetchLists()
const lists = response.data.lists // Lists that match the query
const meta = response.data.meta // Meta informationCreate a list of companies
// Create a list of companies
const response = await tca.createList({
name: 'My SaaS List',
type: 'companies'
})
const newList = response.data // The new listFetch companies in your list
// Fetch companies in a list
const response = await tca.fetchCompaniesInList({
listId: 1234
})
const companies = response.data.companies // Companies that match the list
const meta = response.data.meta // Meta informationAdd or remove companies in your list
// Add companies to a list
const response = await tca.addCompaniesToList({
listId: 1234,
companies: ['apple.com', 'stripe.com']
})
const list = response.data // The updated list👥 Teams
Fetch your team
// Fetch your team details
const response = await tca.fetchTeam()
const team = response.data // Your team details🔧 Utilities
Fetch the health of the API
// Check API health status
const response = await tca.fetchApiHealth()
const health = response.data // The health of the APIFetch the OpenAPI schema
// Fetch OpenAPI schema
const response = await tca.fetchOpenApi()
const schema = response.data // The OpenAPI schemaLicense
MIT License © TheCompaniesAPI