The The Companies API connector lets your AI agent act in each user's The Companies API account. Each user connects their own The Companies API API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 34 tools.
- Tools
- 34
- What they doRead · write · destructive
- 26 · 7 · 126 read7 write1 destructive
- Users sign in with
- API key
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the The Companies API connection
In AgentKit > Connections, create a The Companies API connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'thecompaniesapi'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize The Companies API:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'thecompaniesapi_get_current_user',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "thecompaniesapi"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize The Companies API:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="thecompaniesapi_get_current_user",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their The Companies API credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolthecompaniesapi_count_companiesCount the companies that match filter conditions and an optional name or domain text search, without returning them.Read-onlyCount Companies
Count the companies that match filter conditions and an optional name or domain text search, without returning them. Returns the number of matching companies. Use this to size a segment before paying for results with thecompaniesapi_search_companies. Use thecompaniesapi_get_companies_analytics to break a segment down by an attribute.
Inputs
queryarray- Filter conditions; a company must match every condition. Each condition names an attribute (for example about.industries, about.totalEmployees, locations.headquarters.country.code, technologies.active, finances.revenue or ai.search), a sign (equals, exactEquals, notEquals, greater or lower), the values to compare against, and an operator (or / and) that decides whether a company must match any or all of those values. Industry, technology and location values are the slugs and codes returned by the industry, technology and location search tools; thecompaniesapi_generate_search_query turns a plain-English description into these conditions. Example: [{"attribute": "about.industries", "operator": "or", "sign": "equals", "values": ["computer-software"]}, {"attribute": "locations.headquarters.country.code", "operator": "or", "sign": "equals", "values": ["us", "gb"]}]
searchstring- Optional text matched against company names or domains (see search_fields). Example: pay
search_fieldsarray- Which fields the search text matches against: about.name (company name), domain.domain (website domain), or both. Example: ["about.name"]
thecompaniesapi_enrich_job_titleClassify a job title into its department and seniority level.Read-onlyEnrich Job Title
Classify a job title into its department and seniority level. Returns the normalized job title with its department, secondary department, seniority level and how common it is on LinkedIn. Use this to segment contacts by role, for example to tell a VP of Sales from a sales intern.
Inputs
namestringrequired- The job title to classify. Example: Head of Growth Marketing
thecompaniesapi_get_companies_analyticsBreak down a company segment or one of your lists by one attribute, such as industry, employee range or headquarters country.Read-onlyGet Companies Analytics
Break down a company segment or one of your lists by one attribute, such as industry, employee range or headquarters country. Returns each value of that attribute with its company count and its share of the segment, plus totals. Use this to profile a segment or list. Use thecompaniesapi_count_companies for a single total.
Inputs
attributestringrequired- The company attribute to break down by. Example: about.industriesone of
about.businessTypeabout.industriesabout.industryabout.totalEmployeesabout.yearFoundedanalytics.monthlyVisitorsappscodes.naicscodes.siccontactsdomain.tldfinances.revenuefinances.stockExchangelocations.headquarters.city.codelocations.headquarters.continent.codelocations.headquarters.country.codelocations.headquarters.county.codelocations.headquarters.state.codemeta.scoremeta.syncedAtsocialstechnologies.activetechnologies.categories list_idinteger- Analyze the companies in this list instead of a search segment. thecompaniesapi_list_lists returns list IDs. Example: 4210
querystring- Optional filter conditions defining the segment, as a JSON array encoded as a string (the same condition objects thecompaniesapi_search_companies takes). Example: [{"attribute":"locations.headquarters.country.code","operator":"or","sign":"equals","values":["us","gb"]}]
sizeinteger- Maximum number of attribute values to return, from 1 to 10000. Example: 20
sort_orderstring- Sort values by company count, asc or desc. Example: descone of
ascdesc
thecompaniesapi_get_companyEnrich one company from its website domain.Read-onlyGet Company by Domain
Enrich one company from its website domain. Returns the company profile: name and descriptions, industries, employee range, founding year, revenue range, headquarters location, social profiles, technologies, phone and email contacts, NAICS and SIC codes, and website traffic. Use this when you know the domain. Use thecompaniesapi_get_company_by_email for a work email, thecompaniesapi_get_company_by_social for a LinkedIn or other social URL, and thecompaniesapi_search_companies_by_name when you only know the name.
Inputs
domainstringrequired- Company website domain, without protocol or path. Example: stripe.com
refreshboolean- Set to true to re-analyze the company in real time instead of returning the stored profile. Slower, but returns the freshest data. Defaults to false.
simplifiedboolean- Set to true to return a reduced company profile that costs no credits (the free plan limits how many). Defaults to false, which returns the full profile.
thecompaniesapi_get_company_by_emailEnrich the company behind a work email address.Read-onlyGet Company by Email
Enrich the company behind a work email address. Returns the company profile plus an analysis of the email: whether it is valid, from a free or disposable provider, and which address pattern it follows. Use this to enrich a signup or lead from their email. Use thecompaniesapi_get_company when you already have the domain.
Inputs
emailstringrequired- Work email address of someone at the company. Free-mail addresses such as gmail.com return no company. Example: jane@stripe.com
refreshboolean- Set to true to re-analyze the company in real time instead of returning the stored profile. Slower, but returns the freshest data. Defaults to false.
simplifiedboolean- Set to true to return a reduced company profile that costs no credits (the free plan limits how many). Defaults to false, which returns the full profile.
thecompaniesapi_get_company_contextGet an AI-written briefing on a company from its domain: its market, business model, products, customers and differentiators.Read-onlyGet Company Context
Get an AI-written briefing on a company from its domain: its market, business model, products, customers and differentiators. Returns the context object with the company summary and the sources it was built from, plus the cost. Use this for a narrative overview before outreach or research. Use thecompaniesapi_ask_company to answer one specific question, and thecompaniesapi_get_company for structured profile data.
Inputs
domainstringrequired- Company website domain, without protocol or path. Example: stripe.com
thecompaniesapi_get_company_email_patternsFind the email address patterns a company uses, such as {first}.{last}@domain.Read-onlyGet Company Email Patterns
Find the email address patterns a company uses, such as {first}.{last}@domain. Returns each pattern with how often it is used across the company's known addresses. Use this to guess a person's work email at a company. Use thecompaniesapi_get_company for the full company profile.
Inputs
domainstringrequired- Company website domain, without protocol or path. Example: stripe.com
emails_countboolean- Set to true to include how many known email addresses match each pattern. Defaults to false.
precisioninteger- Minimum usage percentage, from 0 to 100, a pattern needs to be returned. Example: 10
thecompaniesapi_get_company_in_listGet one company from one of your lists by its domain.Read-onlyGet Company in List
Get one company from one of your lists by its domain. Returns the company profile as stored in the list, or a 404 error when the company is not in the list. Use this to check whether a company is in a list. Use thecompaniesapi_list_companies_in_list to read the whole list.
Inputs
domainstringrequired- Company website domain, without protocol or path. Example: stripe.com
list_idintegerrequired- ID of the list. thecompaniesapi_list_lists returns list IDs. Example: 4210
thecompaniesapi_get_current_userGet the user that owns the API token.Read-onlyGet Current User
Get the user that owns the API token. Returns the user's ID, email, name, role and current team ID. Use this to check which account the connection uses, or to get the team ID for thecompaniesapi_get_team.
Inputs
This tool takes no inputs.
thecompaniesapi_get_teamGet a team's details, including its remaining credits.Read-onlyGet Team
Get a team's details, including its remaining credits. Returns the team's ID, name, country, website, credit balance and subscription status. Use this to check the credit balance before large searches or bulk jobs. Get the team ID from currentTeamId in thecompaniesapi_get_current_user.
Inputs
team_idintegerrequired- ID of the team. thecompaniesapi_get_current_user returns it as currentTeamId. Example: 1234
thecompaniesapi_list_actionsList your team's asynchronous actions, such as bulk enrichment jobs, and check their progress.Read-onlyList Actions
List your team's asynchronous actions, such as bulk enrichment jobs, and check their progress. Returns each action's ID, type, status (pending, active, completed or failed), cost, job data and results, with pagination info. Use this to poll a job started with thecompaniesapi_request_action. Use thecompaniesapi_retry_action to rerun a failed one.
Inputs
list_idinteger- Only return actions for this list. Example: 4210
pageinteger- Page of results to return, starting at 1. Defaults to 1. Example: 2
searchstring- Text to match against actions. Example: enrich
sizeinteger- Number of actions per page. Example: 10
statusstring- Only return actions with this status. Example: completedone of
activecompletedfailedpending typestring- Only return actions of this type: jobs:request (requested jobs) or companies:added (companies added to a list). Example: jobs:requestone of
jobs:requestcompanies:added
thecompaniesapi_list_companies_in_listList the companies in one of your lists, optionally narrowed by filter conditions.Read-onlyList Companies in List
List the companies in one of your lists, optionally narrowed by filter conditions. Returns a page of company profiles with pagination info. Use this to read a saved list. Use thecompaniesapi_get_company_in_list to check one company, and thecompaniesapi_search_companies to search the whole database.
Inputs
list_idintegerrequired- ID of the list. thecompaniesapi_list_lists returns list IDs. Example: 4210
pageinteger- Page of results to return, starting at 1. Defaults to 1. Example: 2
queryarray- Filter conditions; a company must match every condition. Each condition names an attribute (for example about.industries, about.totalEmployees, locations.headquarters.country.code, technologies.active, finances.revenue or ai.search), a sign (equals, exactEquals, notEquals, greater or lower), the values to compare against, and an operator (or / and) that decides whether a company must match any or all of those values. Industry, technology and location values are the slugs and codes returned by the industry, technology and location search tools; thecompaniesapi_generate_search_query turns a plain-English description into these conditions. Example: [{"attribute": "about.industries", "operator": "or", "sign": "equals", "values": ["computer-software"]}, {"attribute": "locations.headquarters.country.code", "operator": "or", "sign": "equals", "values": ["us", "gb"]}]
simplifiedboolean- Set to true to return a reduced company profile that costs no credits (the free plan limits how many). Defaults to false, which returns the full profile.
sizeinteger- Number of results per page, from 1 to 100. Defaults to 10. Example: 25
sort_bystring- Company field to sort results by, such as meta.score (relevance score), about.totalEmployees, about.yearFounded, analytics.monthlyVisitors or finances.revenue. Use with sort_order. Example: about.totalEmployeesone of
about.businessTypeabout.industriesabout.industryabout.nameabout.totalEmployeesabout.yearFoundedanalytics.monthlyVisitorsappscodes.naicscodes.siccontactsdomain.domaindomain.tldfinances.revenuelocations.headquarters.city.codelocations.headquarters.country.codelocations.headquarters.county.codelocations.headquarters.state.codemeta.scoremeta.syncedAtsocialstechnologies.activeurls sort_orderstring- Sort direction for sort_by: asc or desc. Example: descone of
ascdesc
thecompaniesapi_list_listsList your team's company lists.Read-onlyList Lists
List your team's company lists. Returns each list's ID, name, dynamic flag, filter conditions, company count and processing status, with pagination info. Use this to find a list ID. Use thecompaniesapi_list_companies_in_list to read the companies in a list.
Inputs
pageinteger- Page of results to return, starting at 1. Defaults to 1. Example: 2
sizeinteger- Number of results per page, from 1 to 500. Defaults to 25. Example: 25
thecompaniesapi_search_citiesSearch cities by name in The Companies API's location data.Read-onlySearch Cities
Search cities by name in The Companies API's location data. Returns cities with their name, code, coordinates, postcode, and the number of companies headquartered there, with pagination info. Use this to find the city code for a locations.headquarters.city.code condition in thecompaniesapi_search_companies. Use thecompaniesapi_search_states or thecompaniesapi_search_countries for larger areas.
Inputs
pageinteger- Page of results to return, starting at 1. Defaults to 1. Example: 2
searchstring- Text to match against city names. Example: San Francisco
sizeinteger- Number of results per page, from 1 to 20. Defaults to 20. Example: 20
sort_bystring- Sort results by the number of companies in each place (counts.companies). Use with sort_order. Example: counts.companiesone of
counts.companies sort_orderstring- Sort direction for sort_by: asc or desc. Example: descone of
ascdesc
thecompaniesapi_search_companiesSearch the company database with filter conditions on industry, size, location, technologies, revenue and more, optionally combined with a name or domain text search.Read-onlySearch Companies
Search the company database with filter conditions on industry, size, location, technologies, revenue and more, optionally combined with a name or domain text search. Returns a page of matching company profiles, pagination info (total, current and last page) and the credit cost. Each returned company costs 1 credit unless simplified is true. Use this for structured filters. Use thecompaniesapi_search_companies_by_prompt for a plain-English description, thecompaniesapi_search_companies_by_name for a name lookup, and thecompaniesapi_count_companies to size a segment without paying for results.
Inputs
domains_to_excludestring- Comma-separated domains to leave out of the results. Example: amazon.com,pearson.com
linkedin_to_excludestring- Comma-separated LinkedIn company URLs to leave out of the results. Example: https://www.linkedin.com/company/amazon
pageinteger- Page of results to return, starting at 1. Defaults to 1. Example: 2
queryarray- Filter conditions; a company must match every condition. Each condition names an attribute (for example about.industries, about.totalEmployees, locations.headquarters.country.code, technologies.active, finances.revenue or ai.search), a sign (equals, exactEquals, notEquals, greater or lower), the values to compare against, and an operator (or / and) that decides whether a company must match any or all of those values. Industry, technology and location values are the slugs and codes returned by the industry, technology and location search tools; thecompaniesapi_generate_search_query turns a plain-English description into these conditions. Example: [{"attribute": "about.industries", "operator": "or", "sign": "equals", "values": ["computer-software"]}, {"attribute": "locations.headquarters.country.code", "operator": "or", "sign": "equals", "values": ["us", "gb"]}]
searchstring- Optional text matched against company names or domains (see search_fields). Example: pay
search_fieldsarray- Which fields the search text matches against: about.name (company name), domain.domain (website domain), or both. Example: ["about.name"]
simplifiedboolean- Set to true to return a reduced company profile that costs no credits (the free plan limits how many). Defaults to false, which returns the full profile.
sizeinteger- Number of results per page, from 1 to 100. Defaults to 10. Example: 25
sort_bystring- Company field to sort results by, such as meta.score (relevance score), about.totalEmployees, about.yearFounded, analytics.monthlyVisitors or finances.revenue. Use with sort_order. Example: about.totalEmployeesone of
about.businessTypeabout.industriesabout.industryabout.nameabout.totalEmployeesabout.yearFoundedanalytics.monthlyVisitorsappscodes.naicscodes.siccontactsdomain.domaindomain.tldfinances.revenuelocations.headquarters.city.codelocations.headquarters.country.codelocations.headquarters.county.codelocations.headquarters.state.codemeta.scoremeta.syncedAtsocialstechnologies.activeurls sort_orderstring- Sort direction for sort_by: asc or desc. Example: descone of
ascdesc
thecompaniesapi_search_companies_by_nameFind companies by name, optionally limited to some countries.Read-onlySearch Companies by Name
Find companies by name, optionally limited to some countries. Returns matching company profiles with pagination info. Several companies can share a name, so check the domain and location of each result. Each returned company costs 1 credit unless simplified is true. Use this to resolve a company name to its domain and profile. Use thecompaniesapi_get_company when you already have the domain, and thecompaniesapi_search_companies for filter-based search.
Inputs
namestringrequired- Company name to search for. Example: Stripe
countriesstring- Comma-separated two-letter country codes, in lowercase, to limit results to. Example: us,gb,fr
exact_words_matchboolean- When true (the API default), every searched word must appear in the name: 'Bank of' matches Bank of America but 'Bank of A' does not. Set to false for looser matching.
lists_to_excludestring- Comma-separated IDs of your lists whose companies should be left out of the results. Example: 3920,3925
pageinteger- Page of results to return, starting at 1. Defaults to 1. Example: 2
simplifiedboolean- Set to true to return a reduced company profile that costs no credits (the free plan limits how many). Defaults to false, which returns the full profile.
sizeinteger- Number of results per page, from 1 to 25. Defaults to 1. Example: 25
sort_bystring- Company field to sort results by, such as meta.score (relevance score), about.totalEmployees, about.yearFounded, analytics.monthlyVisitors or finances.revenue. Use with sort_order. Example: about.totalEmployeesone of
about.businessTypeabout.industriesabout.industryabout.nameabout.totalEmployeesabout.yearFoundedanalytics.monthlyVisitorsappscodes.naicscodes.siccontactsdomain.domaindomain.tldfinances.revenuelocations.headquarters.city.codelocations.headquarters.country.codelocations.headquarters.county.codelocations.headquarters.state.codemeta.scoremeta.syncedAtsocialstechnologies.activeurls sort_orderstring- Sort direction for sort_by: asc or desc. Example: descone of
ascdesc
thecompaniesapi_search_companies_by_promptSearch companies with a plain-English description, such as 'SaaS companies in the United States with more than 100 employees'.Read-onlySearch Companies by Prompt
Search companies with a plain-English description, such as 'SaaS companies in the United States with more than 100 employees'. Returns matching company profiles with pagination info. Each returned company costs 1 credit unless simplified is true. Use this when the user describes the companies in words. Use thecompaniesapi_search_companies for exact filter conditions, and thecompaniesapi_generate_search_query to see or reuse the conditions a description maps to.
Inputs
promptstringrequired- Plain-English description of the companies to find. Example: SaaS companies in the United States with more than 100 employees
lists_to_excludestring- Comma-separated IDs of your lists whose companies should be left out of the results. Example: 3920,3925
pageinteger- Page of results to return, starting at 1. Defaults to 1. Example: 2
similaritynumber- Similarity threshold from 0 to 2 (API default 1.875). Higher values keep only closer matches. Example: 1.875
simplifiedboolean- Set to true to return a reduced company profile that costs no credits (the free plan limits how many). Defaults to false, which returns the full profile.
sizeinteger- Number of results per page, from 1 to 50. Defaults to 10. Example: 25
sort_bystring- Company field to sort results by, such as meta.score (relevance score), about.totalEmployees, about.yearFounded, analytics.monthlyVisitors or finances.revenue. Use with sort_order. Example: about.totalEmployeesone of
about.businessTypeabout.industriesabout.industryabout.nameabout.totalEmployeesabout.yearFoundedanalytics.monthlyVisitorsappscodes.naicscodes.siccontactsdomain.domaindomain.tldfinances.revenuelocations.headquarters.city.codelocations.headquarters.country.codelocations.headquarters.county.codelocations.headquarters.state.codemeta.scoremeta.syncedAtsocialstechnologies.activeurls sort_orderstring- Sort direction for sort_by: asc or desc. Example: descone of
ascdesc
thecompaniesapi_search_continentsSearch continents by name in The Companies API's location data.Read-onlySearch Continents
Search continents by name in The Companies API's location data. Returns continents with their name and code, and the number of companies headquartered there, with pagination info. Use this to find the continent code for a locations.headquarters.continent.code condition in thecompaniesapi_search_companies. Use thecompaniesapi_search_countries for a country.
Inputs
pageinteger- Page of results to return, starting at 1. Defaults to 1. Example: 2
searchstring- Text to match against continent names. Example: Europe
sizeinteger- Number of results per page, from 1 to 20. Defaults to 20. Example: 20
sort_bystring- Sort results by the number of companies in each place (counts.companies). Use with sort_order. Example: counts.companiesone of
counts.companies sort_orderstring- Sort direction for sort_by: asc or desc. Example: descone of
ascdesc
thecompaniesapi_search_countiesSearch counties by name in The Companies API's location data.Read-onlySearch Counties
Search counties by name in The Companies API's location data. Returns counties with their name and code, and the number of companies headquartered there, with pagination info. Use this to find the county code for a locations.headquarters.county.code condition in thecompaniesapi_search_companies. Use thecompaniesapi_search_cities for a city.
Inputs
pageinteger- Page of results to return, starting at 1. Defaults to 1. Example: 2
searchstring- Text to match against county names. Example: Santa Clara
sizeinteger- Number of results per page, from 1 to 20. Defaults to 20. Example: 20
sort_bystring- Sort results by the number of companies in each place (counts.companies). Use with sort_order. Example: counts.companiesone of
counts.companies sort_orderstring- Sort direction for sort_by: asc or desc. Example: descone of
ascdesc
thecompaniesapi_search_countriesSearch countries by name in The Companies API's location data.Read-onlySearch Countries
Search countries by name in The Companies API's location data. Returns countries with their name and code, and the number of companies headquartered there, with pagination info. Use this to find the country code for a locations.headquarters.country.code condition in thecompaniesapi_search_companies. Use thecompaniesapi_search_states for a state or region.
Inputs
pageinteger- Page of results to return, starting at 1. Defaults to 1. Example: 2
searchstring- Text to match against country names. Example: France
sizeinteger- Number of results per page, from 1 to 20. Defaults to 20. Example: 20
sort_bystring- Sort results by the number of companies in each place (counts.companies). Use with sort_order. Example: counts.companiesone of
counts.companies sort_orderstring- Sort direction for sort_by: asc or desc. Example: descone of
ascdesc
thecompaniesapi_search_industriesSearch the industries companies are tagged with, by name.Read-onlySearch Industries
Search the industries companies are tagged with, by name. Returns industries with their name, slug and number of companies, sorted by company count, with pagination info. Free. Use this to find the industry slug for an about.industries condition in thecompaniesapi_search_companies. Use thecompaniesapi_search_similar_industries to widen a set of industries.
Inputs
pageinteger- Page of results to return, starting at 1. Defaults to 1. Example: 2
searchstring- Text to match against industry names. Omit to list all industries. Example: software
sizeinteger- Number of results per page, from 1 to 100. Defaults to 25. Example: 25
thecompaniesapi_search_similar_companiesFind companies similar to one or more companies you name by domain, such as lookalikes of your best customers or a competitor set.Read-onlySearch Similar Companies
Find companies similar to one or more companies you name by domain, such as lookalikes of your best customers or a competitor set. Returns similar company profiles with pagination info. Each returned company costs 1 credit unless simplified is true. Use this to build a lookalike list from example domains. Use thecompaniesapi_search_companies for filter-based search.
Inputs
domainsarrayrequired- Domains of up to 100 example companies to find lookalikes of. Example: ["crisp.chat", "intercom.com"]
pageinteger- Page of results to return, starting at 1. Defaults to 1. Example: 2
proximitystring- How close the results must be to the examples: close, near or far. Example: closeone of
closenearfar simplifiedboolean- Set to true to return a reduced company profile that costs no credits (the free plan limits how many). Defaults to false, which returns the full profile.
sizeinteger- Number of results per page, from 1 to 100. Defaults to 10. Example: 25
sort_bystring- Company field to sort results by, such as meta.score (relevance score), about.totalEmployees, about.yearFounded, analytics.monthlyVisitors or finances.revenue. Use with sort_order. Example: about.totalEmployeesone of
about.businessTypeabout.industriesabout.industryabout.nameabout.totalEmployeesabout.yearFoundedanalytics.monthlyVisitorsappscodes.naicscodes.siccontactsdomain.domaindomain.tldfinances.revenuelocations.headquarters.city.codelocations.headquarters.country.codelocations.headquarters.county.codelocations.headquarters.state.codemeta.scoremeta.syncedAtsocialstechnologies.activeurls sort_orderstring- Sort direction for sort_by: asc or desc. Example: descone of
ascdesc
thecompaniesapi_search_similar_industriesFind industries related to one or more industries you name.Read-onlySearch Similar Industries
Find industries related to one or more industries you name. Returns related industries with their name, slug and number of companies, with pagination info. Use this to widen an industry filter. Use thecompaniesapi_search_industries to look up an industry by name.
Inputs
industriesarrayrequired- Industry names or slugs to find related industries for. Example: ["saas", "fintech"]
pageinteger- Page of results to return, starting at 1. Defaults to 1. Example: 2
sizeinteger- Number of results per page, from 1 to 100. Defaults to 25. Example: 25
thecompaniesapi_search_statesSearch states by name in The Companies API's location data.Read-onlySearch States
Search states by name in The Companies API's location data. Returns states with their name and code, and the number of companies headquartered there, with pagination info. Use this to find the state or region code for a locations.headquarters.state.code condition in thecompaniesapi_search_companies. Use thecompaniesapi_search_cities for a city.
Inputs
pageinteger- Page of results to return, starting at 1. Defaults to 1. Example: 2
searchstring- Text to match against state or region names. Example: California
sizeinteger- Number of results per page, from 1 to 20. Defaults to 20. Example: 20
sort_bystring- Sort results by the number of companies in each place (counts.companies). Use with sort_order. Example: counts.companiesone of
counts.companies sort_orderstring- Sort direction for sort_by: asc or desc. Example: descone of
ascdesc
thecompaniesapi_search_technologiesSearch the technologies detected on company websites, such as Shopify, HubSpot or Stripe, by name.Read-onlySearch Technologies
Search the technologies detected on company websites, such as Shopify, HubSpot or Stripe, by name. Returns technologies with their name, slug, categories, vendor, website and number of companies using them, with pagination info. Use this to find the technology slug for a technologies.active condition in thecompaniesapi_search_companies.
Inputs
pageinteger- Page of results to return, starting at 1. Defaults to 1. Example: 2
searchstring- Text to match against technology names. Example: shopify
sizeinteger- Number of results per page, from 1 to 100. Defaults to 25. Example: 25
thecompaniesapi_ask_companyAsk an AI question about a company, identified by its domain, and get a structured answer.WriteAsk About Company
Ask an AI question about a company, identified by its domain, and get a structured answer. Returns the answer (output values, explanation and confidence score) inside the prompt object, plus the model used and the credit cost. Use this for a specific fact that is not in the standard profile, such as which products a company sells. Use thecompaniesapi_get_company_context for a general overview.
Inputs
domainstringrequired- Company website domain, without protocol or path. Example: stripe.com
questionstringrequired- The question to answer about the company. Example: What products does this company sell?
explainboolean- Set to true to include an explanation of how the answer was reached. Defaults to false.
fieldsarray- Structured fields the answer must fill. Each field needs a key and a type (string, number, boolean, or array|string, array|number, array|boolean), and can add a description and a fixed set of allowed values. Omit to get a free-form answer. Example: [{"key": "products", "type": "array|string", "description": "The products the company sells"}]
modelstring- AI model size: small (cheaper, faster) or large (more capable). Example: largeone of
smalllarge
thecompaniesapi_create_listCreate a company list, either empty, filled from filter conditions, or filled with lookalikes of example domains.WriteCreate List
Create a company list, either empty, filled from filter conditions, or filled with lookalikes of example domains. Returns the new list with its ID. Use this to save a segment. Add or remove specific companies afterwards with thecompaniesapi_toggle_companies_in_list.
Inputs
namestringrequired- Name of the list, up to 255 characters. Example: EU fintech prospects
dynamicboolean- Set to true to keep adding new companies that match the conditions over time. Defaults to false.
mail_frequencystring- How often The Companies API emails you about new companies in the list: disabled, daily, weekly or monthly. Example: weeklyone of
disableddailyweeklymonthly max_companiesinteger- Maximum number of companies the list may hold. Example: 500
queryarray- Filter conditions; a company must match every condition. Each condition names an attribute (for example about.industries, about.totalEmployees, locations.headquarters.country.code, technologies.active, finances.revenue or ai.search), a sign (equals, exactEquals, notEquals, greater or lower), the values to compare against, and an operator (or / and) that decides whether a company must match any or all of those values. Industry, technology and location values are the slugs and codes returned by the industry, technology and location search tools; thecompaniesapi_generate_search_query turns a plain-English description into these conditions. Example: [{"attribute": "about.industries", "operator": "or", "sign": "equals", "values": ["computer-software"]}, {"attribute": "locations.headquarters.country.code", "operator": "or", "sign": "equals", "values": ["us", "gb"]}] When set, the list is filled with matching companies.
similar_domainsarray- Domains of example companies; the list is filled with lookalikes of them. Example: ["stripe.com", "adyen.com"]
thecompaniesapi_generate_search_queryTurn a plain-English description of companies into the filter conditions the search tools take.WriteGenerate Search Query
Turn a plain-English description of companies into the filter conditions the search tools take. Returns the generated conditions (in response.query), the number of matching companies and the credit cost, inside a prompt record. Use this to build or inspect conditions for thecompaniesapi_search_companies, thecompaniesapi_count_companies or thecompaniesapi_create_list. Use thecompaniesapi_search_companies_by_prompt to search directly from a description.
Inputs
promptstringrequired- Plain-English description of the companies. Example: Fintech startups in France with 10 to 50 employees
modelstring- AI model size: small (cheaper, faster) or large (more capable). Example: largeone of
smalllarge
thecompaniesapi_request_actionStart an asynchronous job, such as enriching many domains at once or enriching or asking a question across a list, or estimate its credit cost first.WriteRequest Action
Start an asynchronous job, such as enriching many domains at once or enriching or asking a question across a list, or estimate its credit cost first. Returns the created actions with their IDs and status (or the estimate when estimate is true). Use this for bulk work that is too large for one call. Poll progress with thecompaniesapi_list_actions; for single companies use thecompaniesapi_get_company or thecompaniesapi_ask_company.
Inputs
domainsarray- Domains to process, for enrich-companies and ask-domain. Example: ["pearson.com", "united.com"]
estimateboolean- Set to true to get the credit cost without running the job. Defaults to false.
fieldsarray- Structured fields the answer must fill. Each field needs a key and a type (string, number, boolean, or array|string, array|number, array|boolean), and can add a description and a fixed set of allowed values. Omit to get a free-form answer. Example: [{"key": "products", "type": "array|string", "description": "The products the company sells"}]
jobstring- The job to run: enrich-companies (enrich the given domains), enrich-list (enrich every company in list_id), ask-domain (answer question for the given domains), ask-list (answer question for every company in list_id) or cleanup-list (clean up list_id). Example: enrich-companiesone of
enrich-companiesenrich-listask-domainask-listcleanup-list list_idinteger- List to process, for enrich-list, ask-list and cleanup-list. Example: 4210
questionstring- Question to answer for each company, for ask-domain and ask-list. Example: Does this company sell to enterprises?
typestring- Action type. Leave as jobs:request (the default) to request a job. Example: jobs:requestone of
jobs:requestcompanies:addeddefaultjobs:request
thecompaniesapi_retry_actionRetry an asynchronous action that failed.WriteRetry Action
Retry an asynchronous action that failed. Returns the action with its new status. Use this after thecompaniesapi_list_actions shows a failed action.
Inputs
action_idintegerrequired- ID of the failed action. thecompaniesapi_list_actions returns action IDs. Example: 98765
thecompaniesapi_toggle_companies_in_listAdd companies to or remove companies from one of your lists, by domain or company ID.WriteAdd or Remove Companies in List
Add companies to or remove companies from one of your lists, by domain or company ID. Returns the updated list. Use this to curate a list by hand. Use thecompaniesapi_update_list to change the list's conditions.
- Idempotent
Inputs
actionstringrequired- attach adds the companies to the list; detach removes them. Example: attachone of
attachdetach list_idintegerrequired- ID of the list. thecompaniesapi_list_lists returns list IDs. Example: 4210
company_idsarray- Numeric The Companies API company IDs to add or remove. Provide domains or company_ids. Example: [123456]
domainsarray- Domains of the companies to add or remove. Provide domains or company_ids. Example: ["apple.com", "stripe.com"]
refreshboolean- Set to true to re-enrich the companies as they are added.
thecompaniesapi_update_listUpdate a company list's name, filter conditions, size cap, dynamic flag or email frequency, or resync its companies.WriteUpdate List
Update a company list's name, filter conditions, size cap, dynamic flag or email frequency, or resync its companies. Returns the updated list. Use this to change a list's settings. Use thecompaniesapi_toggle_companies_in_list to add or remove specific companies.
- Idempotent
Inputs
list_idintegerrequired- ID of the list. thecompaniesapi_list_lists returns list IDs. Example: 4210
dynamicboolean- Set to true to keep adding new matching companies over time, or false to stop.
mail_frequencystring- How often The Companies API emails you about new companies in the list: disabled, daily, weekly or monthly. Example: weeklyone of
disableddailyweeklymonthly max_companiesinteger- Maximum number of companies the list may hold, from 0 to 1000000. Example: 500
namestring- New name for the list, up to 255 characters. Example: EU fintech prospects
queryarray- Filter conditions; a company must match every condition. Each condition names an attribute (for example about.industries, about.totalEmployees, locations.headquarters.country.code, technologies.active, finances.revenue or ai.search), a sign (equals, exactEquals, notEquals, greater or lower), the values to compare against, and an operator (or / and) that decides whether a company must match any or all of those values. Industry, technology and location values are the slugs and codes returned by the industry, technology and location search tools; thecompaniesapi_generate_search_query turns a plain-English description into these conditions. Example: [{"attribute": "about.industries", "operator": "or", "sign": "equals", "values": ["computer-software"]}, {"attribute": "locations.headquarters.country.code", "operator": "or", "sign": "equals", "values": ["us", "gb"]}]
resyncboolean- Set to true to re-run the list's conditions and refresh its companies.
thecompaniesapi_delete_listDelete one of your company lists.DestructiveDelete List
Delete one of your company lists. This cannot be undone. Returns the deleted list. Use thecompaniesapi_toggle_companies_in_list instead to remove only some companies.
- Idempotent
Inputs
list_idintegerrequired- ID of the list. thecompaniesapi_list_lists returns list IDs. Example: 4210
No tools match.
