> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to the TheirStack MCP server

The TheirStack MCP connector routes your AI agent's tool calls to TheirStack's own MCP server through Scalekit. Each user signs in to TheirStack once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 79 tools.

**Authentication:** OAuth 2.1/DCR
**Categories:** CRM & Sales
**Tools:** 79: 52 read, 10 write, 17 destructive
**Users sign in with:** OAuth
**OAuth app:** Your own TheirStack MCP server app
**Built by:** Vendor MCP
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=THEIRSTACKMCP)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the TheirStack MCP connection

   In **AgentKit > Connections**, create a TheirStack MCP connection and copy its redirect URI. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Register an OAuth app

   TheirStack MCP server connections use your own OAuth app. Register one with TheirStack MCP server and add the redirect URI you copied.

   Then enter the app's Client ID and Client Secret on the TheirStack MCP connection.

5. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   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.actions

   const connector = 'theirstackmcp'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize TheirStack MCP:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'theirstackmcp_count_companies_by_country',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_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.actions

   connection_name = "theirstackmcp"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize TheirStack MCP:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="theirstackmcp_count_companies_by_country",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user signs in once. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'theirstackmcp_count_companies_by_country',
  toolInput: {},
  connector: 'theirstackmcp',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="theirstackmcp_count_companies_by_country",
    tool_input={},
    connection_name="theirstackmcp",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `theirstackmcp_count_companies_by_country`

Count companies by country · Read-only

List every ISO country code with the number of companies headquartered in that country, for geographic distribution analysis. Free: it doesn't consume credits.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `country` (`string`, optional): Name of a country. Will return the country matching their name in English
- `limit` (`integer`, optional): Number of results per page. Default: `25`.
- `page` (`integer`, optional): Page number. Default: `0`.

Example input: `{}`

### `theirstackmcp_count_jobs_by_country`

Count jobs by country · Read-only

List every country code with the number of jobs located in that country and the number of companies hiring there. Search by country name in English.

Free: it doesn't consume credits.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `country` (`string`, optional): Name of a country. Will return the country matching their name in English
- `limit` (`integer`, optional): Number of results per page. Default: `25`.
- `page` (`integer`, optional): Page number. Default: `0`.

Example input: `{}`

### `theirstackmcp_count_webhook_events`

Count webhook events · Read-only

Count the events a webhook has triggered, optionally only those with a given delivery status. Use it when the number is all you need, such as how many deliveries failed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `webhook_id` (`integer`, required): ID of the webhook
- `status` (`string`, optional): Status of the webhook events to filter by. One of: `IN_PROGRESS`, `SUCCESS`, `FAILED`, `NOT_TRIGGERED`.

Example input: `{"webhook_id":1}`

### `theirstackmcp_count_webhook_events_per_day`

Count webhook events per day · Read-only

Count the team's webhook events per day over a date range (the last 30 days by default), with the credits they consumed, for one webhook or all of them. Optionally split each day by delivery status, webhook or event type, e.g. to chart delivery health over time.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end_datetime` (`string`, optional): End of the range, in ISO format (e.g. 2023-01-01T23:59:59). Defaults to now.
- `group_by` (`array`, optional): Dimensions to split each day's count by: delivery status, webhook or event type. Several can be combined.
- `start_datetime` (`string`, optional): Start of the range, in ISO format (e.g. 2023-01-01T00:00:00). Defaults to 30 days before the end.
- `timezone` (`string`, optional): IANA timezone string (e.g., 'Europe/Madrid', 'America/New_York'). Default: `UTC`.
- `webhook_id` (`integer`, optional): Webhook ID

Example input: `{}`

### `theirstackmcp_estimate_saved_search_volume`

Estimate a saved search's daily volume · Read-only

Returns how many records a saved search matched per day over the last 7 days, and what they would cost. Use it to size max_events_per_day: a cap below avg_records_per_day means the webhook will drop matches every day, and dropped matches are never sent later. A webhook whose events are companies (a company search, or trigger_once_per_company) has no daily estimate and returns nulls with an unavailable_reason.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `search_id` (`integer`, required): ID of the saved search to estimate
- `trigger_once_per_company` (`boolean`, optional): Whether the webhook fires once per company. A webhook that does has no daily estimate, because its events are companies rather than jobs and it only fires for companies it has not sent yet. Default: `false`.

Example input: `{"search_id":1}`

### `theirstackmcp_find_locations`

Find locations · Read-only

Search for geographic locations by name or ID to retrieve standardized location data including city, region, and country. Use the location IDs in the job_location_or and job_location_not filters of a job search to filter by city or region.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `country_code` (`string`, optional): The country code of the location, all the returned locations will be filtered by this country code
- `feature_code` (`array`, optional): GeoNames feature code(s) to filter by location type (e.g. PPL=populated place, ADM1=first-order admin division). See https://www.geonames.org/export/codes.html
- `id` (`array`, optional): The ids of the locations
- `limit` (`integer`, optional): The limit of the results. Default: `5`.
- `name` (`string`, optional): Search value for the location, this will be used to filter the locations by name
- `offset` (`integer`, optional): The offset of the results. Default: `0`.

Example input: `{}`

### `theirstackmcp_find_technologies_and_topics`

Find technologies and topics · Read-only

Find technologies and buying intent topics in TheirStack's keyword catalog, and the slugs the technology and keyword filters of the search tools take. Search by name with `q`; results are sorted by how many companies have each keyword. Pass `keyword_type=technology` for technologies only, or `keyword_type_not=technology` for buying intent topics only. There are about 42k keywords, so search rather than page through them. Free: it doesn't consume credits.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category_pattern` (`string`, optional): Case-insensitive text to search for in the keyword category. For example, `data` to find 'data tools'.
- `category_slug` (`string`, optional): Keyword category slug
- `include_metadata` (`boolean`, optional): Deprecated, metadata is always included now. Default: `false`.
- `keyword_type` (`string`, optional): Keyword type to filter by. One of: `technology`, `software_product`, `technology_concept`, `operational_activity`, `strategic_initiative`, `metric_or_concept`, `product_or_service_offered`, `regulation`, `threat_or_risk`, `event`, `commodity`, `industry_vertical`, `physical_equipment`, `medical_research`, `government_body`.
- `keyword_type_not` (`array`, optional): Exclude keywords of these types
- `limit` (`integer`, optional): Number of results per page. Default: `25`.
- `name_pattern` (`string`, optional): Case-insensitive text to search for in the keyword name
- `page` (`integer`, optional): Page number. Default: `0`.
- `parent_category_pattern` (`string`, optional): Case-insensitive text to search for in the keyword parent category name
- `parent_category_slug` (`string`, optional): Keyword parent category slug
- `q` (`string`, optional): General search query. Searches across keyword name, keyword type, category, and parent category (case-insensitive). Results where the keyword name starts with the query are ranked first.
- `slug` (`array`, optional): Keyword slug of a single keyword
- `slugs` (`array`, optional): Keyword slugs of one or many keywords
- `starts_with` (`string`, optional): Filter keywords whose name starts with this string (e.g. 'A' for glossary). Special value '__other__' selects keywords whose name does not start with letters A-Z.

Example input: `{}`

### `theirstackmcp_generate_app_url`

Generate app URL · Read-only

Build a deep link into the TheirStack app for a given resource and return it as `{"url": ...}`. Pick the resource with the `type` field: `company_list` (view a list), `job_search` / `company_search` (open a search from the same filters a job or company search takes), `saved_search` (open a saved search), or `webhook` (view a webhook). Search links (`job_search` / `company_search`) are workspace-independent — the encoded query opens against whoever's session loads it, so the link is portable when shared. The other types point at a workspace-specific resource and include the workspace, which is taken from the authenticated caller, so it is never passed in.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `filters` (`object`, optional): The same filters a job search takes (`search_jobs`, `POST /v1/jobs/search`). The URL opens the jobs search with these filters applied and runs the search automatically.
- `list_id` (`integer`, optional): ID of the company list to open
- `saved_search_id` (`integer`, optional): ID of the saved search to open
- `search_type` (`string`, optional): Whether the saved search is a jobs or a companies search. One of: `jobs`, `companies`.
- `type` (`string`, optional): Selects the variant. Accepted values: 'company_list', 'job_search', 'company_search', 'saved_search', 'webhook'. 'company_list' uses type, list_id; 'job_search' uses type, filters; 'company_search' uses type, filters; 'saved_search' uses type, saved_search_id, search_type; 'webhook' uses type, webhook_id. Send only the fields belonging to the selected variant. One of: `company_list`, `job_search`, `company_search`, `saved_search`, `webhook`.
- `webhook_id` (`integer`, optional): ID of the webhook to open

Example input: `{}`

### `theirstackmcp_get_brand_book`

Get the workspace brand book · Read-only

The workspace's own company profile, products and services, the problems
they solve (with the job titles that own them), ideal customer profiles (as
company search filters), customers cited in case studies and competitors.
Read it before researching sales signals for the workspace, and start from
it. Until the workspace saves its own, it may read one prepared for its
company, flagged `inherited`.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `theirstackmcp_get_companies_in_list`

Get companies in a list · Read-only

List the companies in one of the team's company lists, each with its company profile and the dates it was added and revealed. Paginated; sort by reveal date or name, or filter by part of the company name.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `list_id` (`integer`, required): No description.
- `company_name_partial` (`string`, optional): Pass a partial company name to filter the list of companies
- `limit` (`integer`, optional): Number of results per page. Default: `25`.
- `offset` (`integer`, optional): Number of results to skip. Required for [offset-based pagination](https://theirstack.com/en/docs/api-reference/pagination). Default: `0`.
- `order_by` (`string`, optional): Order by field. One of: `revealed_at`, `name`. Default: `revealed_at`.
- `order_direction` (`string`, optional): Order direction. One of: `asc`, `desc`. Default: `desc`.
- `page` (`integer`, optional): Page number. Required when using [page-based pagination](https://theirstack.com/en/docs/api-reference/pagination). Default: `0`.

Example input: `{"list_id":1}`

### `theirstackmcp_get_company_buying_intents`

Get company buying intents · Read-only

List the buying intent topics detected for a company. For each topic, it returns the confidence level (`low`, `medium`, `high`), the number of jobs that mention the topic, and the first and last dates it was mentioned.

You must specify at least one of `company_domain`, `company_name` or `company_linkedin_url`.

It consumes **3 API credits** per company lookup, regardless of the number of buying intent topics returned. It doesn't consume credits if there is no response.

Job, company, technographics and buying intent searches share one rate limit per user (10 per minute on the free plan).

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `company_domain` (`string`, optional): Only return companies that match this domain exactly. It accepts full urls (https://www.google.com/) and emails (andrew@stripe.com).
- `company_id` (`string`, optional): Only return companies that match this TheirStack Company ID exactly. This ID is temporary and internal and will change in the future and become stable. Until then, it is only meant to be used internally by our UI (app.theirstack.com). For deduplication logic, use company_domain or company_linkedin_url instead.
- `company_linkedin_url` (`string`, optional): Return companies whose LinkedIn URL matches this URL exactly.
- `company_name` (`string`, optional): Only return companies that match this name exactly, case-sensitively.
- `confidence_or` (`array`, optional): Only return keywords (technologies or buying intent topics) detected with any of these confidence levels. Available values: "high", "medium", "low"
- `first_date_found_gte` (`string`, optional): Only return keywords (technologies or buying intent topics) where the first time they were found was after or on this date. Format: "YYYY-MM-DD"
- `first_date_found_lte` (`string`, optional): Only return keywords (technologies or buying intent topics) where the first time they were found was before or on this date. Format: "YYYY-MM-DD"
- `include_total_results` (`boolean`, optional): When enabled, calculates and returns `total_results` and `total_companies` fields in the response. WARNING: This significantly slows down responses as it requires reading the entire dataset. Recommended usage: enable only for the initial request to get totals, then disable for subsequent pagination requests. Default: `false`.
- `keyword_category_slug_or` (`array`, optional): Only return keywords from any of these categories. Case sensitive. Pass slugs. Check out all keyword categories at [GET /v1/catalog/keywords/categories](https://theirstack.com/en/docs/api-reference/catalog/list_keyword_categories_v1)
- `keyword_parent_category_slug_or` (`array`, optional): Only return keywords from any of these parent categories. Case sensitive. Pass slugs. Check out all keyword categories at [GET /v1/catalog/keywords/categories](https://theirstack.com/en/docs/api-reference/catalog/list_keyword_categories_v1)
- `keyword_slug_or` (`array`, optional): Only return these keywords (technologies or buying intent topics). Case sensitive. Pass slugs. Check out all keywords at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0)
- `last_date_found_gte` (`string`, optional): Only return keywords (technologies or buying intent topics) where the last time they were found was after or on this date. Format: "YYYY-MM-DD"
- `last_date_found_lte` (`string`, optional): Only return keywords (technologies or buying intent topics) where the last time they were found was before or on this date. Format: "YYYY-MM-DD"
- `limit` (`integer`, optional): Number of results per page
- `max_jobs` (`integer`, optional): Maximum number of jobs in which each company mentions the keyword (technology or buying intent topic)
- `max_rank` (`integer`, optional): The rank measures how common a keyword (technology or buying intent topic) is within its category for a company. The keyword most mentioned among similar ones by a company has a rank of 1, the second 2, etc. Useful to keep only the primary technology or topic of each category.
- `min_jobs` (`integer`, optional): Minimum number of jobs in which each company mentions the keyword (technology or buying intent topic)
- `min_relative_occurrence` (`number`, optional): Minimum value of relative_occurrence_within_category for each keyword (technology or buying intent topic). Higher values increase the probability that the company actually uses the technology or cares about the topic, because a higher share of the mentions within that category are of this keyword.
- `offset` (`integer`, optional): Number of results to skip. Required for [offset-based pagination](https://theirstack.com/en/docs/api-reference/pagination).
- `page` (`integer`, optional): Page number. Required when using [page-based pagination](https://theirstack.com/en/docs/api-reference/pagination).

Example input: `{}`

### `theirstackmcp_get_company_list`

Get company list · Read-only

Get one of the team's company lists by ID: its name, owner, type, creation date and number of companies. The companies themselves are not included.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `list_id` (`integer`, required): No description.

Example input: `{"list_id":1}`

### `theirstackmcp_get_company_technographics`

Get company technographics · Read-only

List the technologies a company uses. For each technology, it returns the confidence level (`low`, `medium`, `high`), the number of jobs that mention the technology, and the first and last dates it was mentioned.

You must specify at least one of `company_domain`, `company_name` or `company_linkedin_url`.

It consumes **3 API credits** per company lookup, regardless of the number of technologies returned. It doesn't consume credits if there is no response.

Job, company, technographics and buying intent searches share one rate limit per user (10 per minute on the free plan).

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `company_domain` (`string`, optional): Only return companies that match this domain exactly. It accepts full urls (https://www.google.com/) and emails (andrew@stripe.com).
- `company_id` (`string`, optional): Only return companies that match this TheirStack Company ID exactly. This ID is temporary and internal and will change in the future and become stable. Until then, it is only meant to be used internally by our UI (app.theirstack.com). For deduplication logic, use company_domain or company_linkedin_url instead.
- `company_linkedin_url` (`string`, optional): Return companies whose LinkedIn URL matches this URL exactly.
- `company_name` (`string`, optional): Only return companies that match this name exactly, case-sensitively.
- `confidence_or` (`array`, optional): Only return keywords (technologies or buying intent topics) detected with any of these confidence levels. Available values: "high", "medium", "low"
- `first_date_found_gte` (`string`, optional): Only return keywords (technologies or buying intent topics) where the first time they were found was after or on this date. Format: "YYYY-MM-DD"
- `first_date_found_lte` (`string`, optional): Only return keywords (technologies or buying intent topics) where the first time they were found was before or on this date. Format: "YYYY-MM-DD"
- `include_total_results` (`boolean`, optional): When enabled, calculates and returns `total_results` and `total_companies` fields in the response. WARNING: This significantly slows down responses as it requires reading the entire dataset. Recommended usage: enable only for the initial request to get totals, then disable for subsequent pagination requests. Default: `false`.
- `keyword_category_slug_or` (`array`, optional): Only return keywords from any of these categories. Case sensitive. Pass slugs. Check out all keyword categories at [GET /v1/catalog/keywords/categories](https://theirstack.com/en/docs/api-reference/catalog/list_keyword_categories_v1)
- `keyword_parent_category_slug_or` (`array`, optional): Only return keywords from any of these parent categories. Case sensitive. Pass slugs. Check out all keyword categories at [GET /v1/catalog/keywords/categories](https://theirstack.com/en/docs/api-reference/catalog/list_keyword_categories_v1)
- `keyword_slug_or` (`array`, optional): Only return these keywords (technologies or buying intent topics). Case sensitive. Pass slugs. Check out all keywords at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0)
- `last_date_found_gte` (`string`, optional): Only return keywords (technologies or buying intent topics) where the last time they were found was after or on this date. Format: "YYYY-MM-DD"
- `last_date_found_lte` (`string`, optional): Only return keywords (technologies or buying intent topics) where the last time they were found was before or on this date. Format: "YYYY-MM-DD"
- `limit` (`integer`, optional): Number of results per page
- `max_jobs` (`integer`, optional): Maximum number of jobs in which each company mentions the keyword (technology or buying intent topic)
- `max_rank` (`integer`, optional): The rank measures how common a keyword (technology or buying intent topic) is within its category for a company. The keyword most mentioned among similar ones by a company has a rank of 1, the second 2, etc. Useful to keep only the primary technology or topic of each category.
- `min_jobs` (`integer`, optional): Minimum number of jobs in which each company mentions the keyword (technology or buying intent topic)
- `min_relative_occurrence` (`number`, optional): Minimum value of relative_occurrence_within_category for each keyword (technology or buying intent topic). Higher values increase the probability that the company actually uses the technology or cares about the topic, because a higher share of the mentions within that category are of this keyword.
- `offset` (`integer`, optional): Number of results to skip. Required for [offset-based pagination](https://theirstack.com/en/docs/api-reference/pagination).
- `page` (`integer`, optional): Page number. Required when using [page-based pagination](https://theirstack.com/en/docs/api-reference/pagination).

Example input: `{}`

### `theirstackmcp_get_credit_balance`

Get credit balance · Read-only

Retrieve your team's current credit balance including remaining credits available for API calls, searches, and data exports across all endpoints.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `theirstackmcp_get_crm_connection`

CRM connection status · Read-only

The CRM connected to the workspace (`provider`): whether its data is up to date, the running and last syncs, how many companies have each CRM status, and the status rules in the order they are checked. `connection` is null when no CRM is connected.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `theirstackmcp_get_crm_send`

A send to the CRM · Read-only

One send of companies to the CRM: whether it is still running and what the CRM did with each company, with the link to its record or the reason it was skipped or rejected. Take `run_id` from the `id` that `send_companies_to_crm` or `list_crm_sends` returns.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `run_id` (`integer`, required): No description.

Example input: `{"run_id":1}`

### `theirstackmcp_get_crm_send_settings`

What sending companies to the CRM writes · Read-only

What a send to the CRM writes: whether it creates companies, updates them or both, the CRM property each TheirStack field goes to and what happens when the CRM already has a value, and the owner and fixed values of new companies. `configured` is false while these are the defaults. Find the CRM property a field should go to with `list_crm_properties` and a `search` term; a `read_only` one can't be written.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `theirstackmcp_get_daily_credit_usage`

Get daily credit usage · Read-only

Retrieve daily API and UI credit consumption for your team, by charge date. Set group_by=search_pattern to group each day's credits by search patterns with the same stable filters. Charges without a search pattern appear as Other usage. Filter by types, exact endpoint path, origin, API key or search_pattern_key. Each group includes observed endpoints and origins. Choose exactly one group_by dimension: search_pattern, endpoint or origin. Omit it for daily totals. endpoints and origins are independent multiselect filters (OR within each, AND between them). Unfiltered grouped totals include all credits.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `api_key_id` (`string`, optional): No description.
- `end_datetime` (`string`, optional): End datetime in ISO format (e.g., 2023-01-01T23:59:59)
- `endpoint` (`string`, optional): Exact request URL path, e.g. /v1/jobs/search; host and query string are ignored.
- `endpoints` (`array`, optional): Match any exact request URL path; unassigned selects charges without a recorded endpoint. Intersects the singular endpoint filter.
- `group_by` (`string`, optional): No description. One of: `search_pattern`, `endpoint`, `origin`.
- `is_origin_app` (`boolean`, optional): No description.
- `origin` (`string`, optional): No description. One of: `api`, `app`, `web`, `mcp`, `admin_mcp`.
- `origins` (`array`, optional): Match any recorded origin; webhook requires a linked webhook event and unassigned selects missing attribution. Intersects the singular origin filter.
- `search_pattern_key` (`string`, optional): Only charges associated with this canonical search pattern.
- `start_datetime` (`string`, optional): Start datetime in ISO format (e.g., 2023-01-01T00:00:00)
- `status_codes` (`array`, optional): Match any HTTP response status code.
- `timezone` (`string`, optional): IANA timezone, such as Europe/Madrid. Default: `UTC`.
- `types` (`array`, optional): Filter by search type.

Example input: `{}`

### `theirstackmcp_get_datasets`

List datasets · Read-only

List the datasets available to your team (jobs, companies and technographics), updated daily in Parquet format, with the latest download URLs for bulk data access.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `theirstackmcp_get_email_preferences`

Get email preferences · Read-only

Get which optional emails the current user receives, grouped by category (usage, alerts, onboarding): `form_data` holds each preference as `true` or `false`, and `schema` describes each one. Emails with no preference here, such as invitations, failed payments and support ticket updates, are always sent.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `theirstackmcp_get_member_api_keys_usage`

List one member's API keys before removing them · Read-only

The active keys this member created for the current team, with the calls each made over the usage window. An empty list means removing them breaks no integration. Open to any member of the workspace, like the key list itself: it returns metadata the whole team can already see, and a member leaving on their own needs to read it too.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `user_id` (`integer`, required): No description.
- `window_days` (`integer`, optional): No description. Default: `7`.

Example input: `{"user_id":1}`

### `theirstackmcp_get_page`

Read a documentation page · Read-only

Read one page of TheirStack's public website, in full, as markdown.

Pass a URL returned by search_docs. A section anchor is ignored: the whole
page comes back. Reads theirstack.com docs, pricing, product pages, product
updates, blog posts, comparisons, use cases and signals. Other sites are
refused.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `url` (`string`, required): theirstack.com page URL, e.g. https://theirstack.com/en/docs/api-reference/features/count-results

Example input: `{"url":"<url>"}`

### `theirstackmcp_get_request_analytics`

Get daily request analytics · Read-only

Daily request activity with one optional breakdown. Counts and actual ledger credits refer to requests that ran in the selected window, bucketed by request date. Split charges count a request once; credits include later charges for those requests. Use credit consumption for billing totals by charge date. Filters match the individual request log.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `api_key_id` (`string`, optional): No description.
- `end_datetime` (`string`, optional): No description.
- `endpoint` (`string`, optional): No description.
- `endpoints` (`array`, optional): No description.
- `group_by` (`string`, optional): No description. One of: `search_pattern`, `endpoint`, `origin`, `status`.
- `is_origin_app` (`boolean`, optional): No description.
- `max_credits_consumed` (`integer`, optional): Only requests whose total (api + ui) credits consumed are at most this.
- `min_credits_consumed` (`integer`, optional): Only requests whose total (api + ui) credits consumed are at least this.
- `origin` (`string`, optional): No description. One of: `api`, `app`, `web`, `mcp`, `admin_mcp`.
- `origins` (`array`, optional): No description.
- `search_pattern_key` (`string`, optional): No description.
- `start_datetime` (`string`, optional): No description.
- `status_codes` (`array`, optional): No description.
- `timezone` (`string`, optional): IANA timezone, such as Europe/Madrid. Default: `UTC`.
- `types` (`array`, optional): No description.

Example input: `{}`

### `theirstackmcp_get_request_facet_metrics`

Get usage per request filter value · Read-only

How many requests and credits each filter value (endpoint, origin, status code, API key) accounts for in this team's requests over the selected window, plus the search patterns seen. Slower than `get_request_facets`, which returns the values alone.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `api_key_id` (`string`, optional): No description.
- `end_datetime` (`string`, optional): No description.
- `endpoint` (`string`, optional): No description.
- `endpoints` (`array`, optional): No description.
- `is_origin_app` (`boolean`, optional): No description.
- `max_credits_consumed` (`integer`, optional): Only requests whose total (api + ui) credits consumed are at most this.
- `min_credits_consumed` (`integer`, optional): Only requests whose total (api + ui) credits consumed are at least this.
- `origin` (`string`, optional): No description. One of: `api`, `app`, `web`, `mcp`, `admin_mcp`.
- `origins` (`array`, optional): No description.
- `search_pattern_key` (`string`, optional): No description.
- `start_datetime` (`string`, optional): No description.
- `status_codes` (`array`, optional): No description.
- `types` (`array`, optional): No description.

Example input: `{}`

### `theirstackmcp_get_request_facets`

List request filter values · Read-only

List the values seen in this team's requests over the selected window, to filter the request history by: endpoints, origins, status codes and API key IDs. Each list is narrowed by the filters on the other dimensions, not its own. Values only: for the search patterns, and how many requests and credits each value accounts for, use `get_request_facet_metrics`. API keys are identifiers only; no credentials are returned.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `api_key_id` (`string`, optional): No description.
- `end_datetime` (`string`, optional): No description.
- `endpoint` (`string`, optional): No description.
- `endpoints` (`array`, optional): No description.
- `is_origin_app` (`boolean`, optional): No description.
- `max_credits_consumed` (`integer`, optional): Only requests whose total (api + ui) credits consumed are at most this.
- `min_credits_consumed` (`integer`, optional): Only requests whose total (api + ui) credits consumed are at least this.
- `origin` (`string`, optional): No description. One of: `api`, `app`, `web`, `mcp`, `admin_mcp`.
- `origins` (`array`, optional): No description.
- `search_pattern_key` (`string`, optional): No description.
- `start_datetime` (`string`, optional): No description.
- `status_codes` (`array`, optional): No description.
- `types` (`array`, optional): No description.

Example input: `{}`

### `theirstackmcp_get_requests`

List requests · Read-only

List your team's individual API and app requests in a time range. Each request reports how many credits it consumed (api_credits, ui_credits), its response time (duration, in seconds), HTTP status code, endpoint type and the number of records returned. Use it to inspect per-request consumption and latency. Set group_by=search_pattern to return named summaries in groups, with an empty data list. Search patterns group requests with the same stable filters and includes credits, records, company domain sends and deduplication coverage. The date range selects when requests ran. Filter by types, exact endpoint path, origin, API key or search_pattern_key. Use credit_start_datetime/credit_end_datetime to find requests charged in that window even if they ran earlier; no request-date defaults apply in charge-window mode, and metadata.total_results reports matching requests. Unlinked charges have no request to return. Otherwise defaults to the last 5 days.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `api_key_id` (`string`, optional): Filter by API key id
- `credit_end_datetime` (`string`, optional): End of the charge-date window (inclusive).
- `credit_start_datetime` (`string`, optional): Start of the charge-date window (inclusive), independent of when requests ran.
- `credit_types` (`array`, optional): Only requests with positive charges of these types in the charge window: api or ui (Company credits). Returned credit totals use the same window and selected types.
- `end_datetime` (`string`, optional): End datetime in ISO format (e.g., 2023-01-01T23:59:59). Defaults to now.
- `endpoint` (`string`, optional): Exact request URL path, e.g. /v1/jobs/search; host and query string are ignored.
- `endpoints` (`array`, optional): Match any exact request URL path; unassigned selects charges without a recorded endpoint. Intersects the singular endpoint filter.
- `group_by` (`string`, optional): No description. One of: `search_pattern`.
- `is_origin_app` (`boolean`, optional): Filter by origin app or api
- `limit` (`integer`, optional): Return at most this many results. Default: `50`.
- `max_credits_consumed` (`integer`, optional): Only requests whose total (api + ui) credits consumed are at most this.
- `min_credits_consumed` (`integer`, optional): Only requests whose total (api + ui) credits consumed are at least this.
- `origin` (`string`, optional): Filter by request origin (api, app, web, mcp). One of: `api`, `app`, `web`, `mcp`, `admin_mcp`.
- `origins` (`array`, optional): Match any recorded origin; webhook requires a linked webhook event and unassigned selects missing attribution. Intersects the singular origin filter.
- `page` (`integer`, optional): The page number of the results. Default: `0`.
- `request_id_or` (`array`, optional): Return only these request ids. When set, the date range is ignored, so a single request can be addressed without knowing when it ran.
- `search_pattern_key` (`string`, optional): Only requests from this search pattern key.
- `start_datetime` (`string`, optional): Start datetime in ISO format (e.g., 2023-01-01T00:00:00). Defaults to 5 days ago.
- `status_codes` (`array`, optional): Match any HTTP response status code.
- `timezone` (`string`, optional): IANA timezone, such as Europe/Madrid. Default: `UTC`.
- `types` (`array`, optional): Filter by search type.

Example input: `{}`

### `theirstackmcp_get_requests_count`

Get request count · Read-only

Retrieve the daily count of API requests made by your team within a specified date range. Filter by types, exact endpoint path, origin, API key or search_pattern_key. credit_start_datetime/credit_end_datetime selects requests by charge date and suppresses request-date defaults; returned buckets still use the actual request date. credit_types selects positive API or Company credit charges. min_credits_consumed/max_credits_consumed bound the total (api + ui) credits a request consumed, matching the filter on the request list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `api_key_id` (`string`, optional): Filter by API key id
- `credit_end_datetime` (`string`, optional): End of the charge-date window (inclusive).
- `credit_start_datetime` (`string`, optional): Start of the charge-date window (inclusive), independent of when requests ran.
- `credit_types` (`array`, optional): Only requests with positive charges of these types in the charge window: api or ui (Company credits). Returned credit totals use the same window and selected types.
- `end_datetime` (`string`, optional): End datetime in ISO format (e.g., 2023-01-01T23:59:59)
- `endpoint` (`string`, optional): Exact request URL path, e.g. /v1/jobs/search; host and query string are ignored.
- `endpoints` (`array`, optional): Match any exact request URL path; unassigned selects charges without a recorded endpoint. Intersects the singular endpoint filter.
- `is_origin_app` (`boolean`, optional): Filter by origin app or api
- `max_credits_consumed` (`integer`, optional): Only requests whose total (api + ui) credits consumed are at most this.
- `min_credits_consumed` (`integer`, optional): Only requests whose total (api + ui) credits consumed are at least this.
- `origin` (`string`, optional): Filter by request origin (api, app, web, mcp). One of: `api`, `app`, `web`, `mcp`, `admin_mcp`.
- `origins` (`array`, optional): Match any recorded origin; webhook requires a linked webhook event and unassigned selects missing attribution. Intersects the singular origin filter.
- `search_pattern_key` (`string`, optional): No description.
- `start_datetime` (`string`, optional): Start datetime in ISO format (e.g., 2023-01-01T00:00:00)
- `status_codes` (`array`, optional): Match any HTTP response status code.
- `timezone` (`string`, optional): IANA timezone, such as Europe/Madrid. Default: `UTC`.
- `types` (`array`, optional): Filter by search type.

Example input: `{}`

### `theirstackmcp_get_saved_search`

Get saved search · Read-only

Get one of the team's saved searches by ID: its name, type, filters, email alert settings and whether a webhook is active on it.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `search_id` (`integer`, required): The ID of the saved search

Example input: `{"search_id":1}`

### `theirstackmcp_get_support_ticket`

Get support ticket · Read-only

Get one of your support tickets by ID: its title, description, category and current state. The messages exchanged about it are in the ticket's conversation.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ticket_id` (`integer`, required): No description.

Example input: `{"ticket_id":1}`

### `theirstackmcp_get_support_ticket_conversation`

Get support ticket conversation · Read-only

Every message exchanged about this ticket, plus its milestones.

Read live from the email thread, so it stays true whether the answer was
written in the app or by replying to the notification email. Messages carry
who wrote them (`customer` or `theirstack`) and a display name — never an
email address, on either side.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `ticket_id` (`integer`, required): No description.

Example input: `{"ticket_id":1}`

### `theirstackmcp_get_webhook`

Get webhook · Read-only

Retrieve the full details of a specific webhook by its ID including configuration, status, target URL, event type, linked saved search, and creation timestamp. Use this to inspect or debug a webhook setup.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `webhook_id` (`integer`, required): ID of the webhook

Example input: `{"webhook_id":1}`

### `theirstackmcp_list_api_keys`

List API keys · Read-only

Every active key of the current team, with the calls it made over the usage window and whether the member who created it still belongs to the workspace. Key (token) strings are never returned.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `window_days` (`integer`, optional): No description. Default: `7`.

Example input: `{}`

### `theirstackmcp_list_brand_book_versions`

List the workspace brand book versions · Read-only

The saved versions of the workspace brand book, newest first.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): No description. Default: `20`.

Example input: `{}`

### `theirstackmcp_list_company_lists`

List company lists · Read-only

Retrieve all company lists for the current team including list name, company count, and creation date. Use it to find a list's ID before reading its companies, adding companies to it or renaming it.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `theirstackmcp_list_credit_usage_sources`

List credit usage sources · Read-only

List the endpoints and origins that charged credits to the team in a date range (the last 30 days by default). Use it to pick values for the endpoint and origin filters of the daily credit consumption. `unassigned` stands for charges with no recorded endpoint or origin, and `webhook` appears only for charges linked to a webhook event.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end_datetime` (`string`, optional): No description.
- `start_datetime` (`string`, optional): No description.

Example input: `{}`

### `theirstackmcp_list_crm_properties`

CRM company properties · Read-only

The CRM's company properties a status rule can test: their internal name, label and type, how many matched companies have a value, and the values a choice property takes. A CRM can have hundreds of properties and some list thousands of values, so pass `search` with part of a name or label.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `search` (`string`, optional): Keeps the properties whose internal name or label contains this text, ignoring case

Example input: `{}`

### `theirstackmcp_list_crm_sends`

History of sends to the CRM · Read-only

The latest sends of companies to the CRM, newest first, with who sent each one and how many companies it created, updated, skipped or failed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `theirstackmcp_list_crm_syncs`

CRM sync history · Read-only

The workspace's latest CRM syncs, newest first: each one's kind, status, how many companies it read and, if it failed, why.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `theirstackmcp_list_industries`

List industries · Read-only

List the industries and their IDs, with how many jobs and companies we have in each, and search them by name. Use the IDs in the industry filters of a job or company search.

Free: it doesn't consume credits.

Our industries catalogue comes from [LinkedIn Industry Codes V2](https://learn.microsoft.com/en-us/linkedin/shared/references/reference-tables/industry-codes-v2)

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `industry` (`string`, optional): Name of an industry, case-insensitive. Will return industries that contain the given string either in their name, hierarchy or description. Default: ``.
- `limit` (`integer`, optional): Number of results per page. Default: `25`.
- `page` (`integer`, optional): Page number. Default: `0`.

Example input: `{}`

### `theirstackmcp_list_keyword_categories`

List keyword categories · Read-only

Returns a list of main keyword categories (technologies and buying intents) with the number of keywords and companies in each. Optionally filters to return a specific category if category_slug is provided.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category_slug` (`string`, optional): Optional category slug to filter and return only a specific category

Example input: `{}`

### `theirstackmcp_list_keyword_subcategories`

List keyword subcategories · Read-only

Returns a list of keyword subcategories with their keywords. Behavior: returns all subcategories if no parameters are provided; returns all subcategories for a specific parent category if only category_slug is provided; returns a specific subcategory if both category_slug and subcategory_slug are provided.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category_slug` (`string`, optional): Parent category slug to filter subcategories. If provided with subcategory_slug, returns only that specific subcategory. If provided alone, returns all subcategories for that parent category.
- `num_technologies_per_category` (`integer`, optional): Number of keywords per category to include in the response. Default: `5`.
- `subcategory_slug` (`string`, optional): Subcategory slug to filter by a specific subcategory. Must be used together with category_slug.

Example input: `{}`

### `theirstackmcp_list_saved_searches`

List saved searches · Read-only

Retrieve all active saved searches of the current team, including search filters, type, and creation date. Archived searches are left out, and so are the ones that hold a sales signal's filters, which you can still read by ID. Filter by user IDs or search type and sort by name, created, or updated date.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `order_by` (`string`, optional): Order by field. One of: `name`, `created_at`, `updated_at`. Default: `updated_at`.
- `order_direction` (`string`, optional): Order direction. One of: `asc`, `desc`. Default: `desc`.
- `types` (`array`, optional): Filter by type of search
- `user_ids` (`array`, optional): Get saved searches from users with these IDs. The IDs must be from people in the current users' team.

Example input: `{}`

### `theirstackmcp_list_support_tickets`

List support tickets · Read-only

List your support tickets with their category and state, filterable by category, state or text in the title or description. Check it before filing an issue that may already be reported.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `category_key` (`string`, optional): Filter tickets by category key
- `limit` (`integer`, optional): Maximum number of tickets to return. Default: `50`.
- `offset` (`integer`, optional): Number of tickets to skip before starting to return results. Default: `0`.
- `search` (`string`, optional): Search term to filter tickets by title or description
- `sort` (`string`, optional): Sort key for tickets list (e.g. created_at:desc). One of: `created_at_asc`, `created_at_desc`, `updated_at_asc`, `updated_at_desc`, `waiting_since_asc`, `waiting_since_desc`.
- `state_key` (`string`, optional): Filter tickets by state key

Example input: `{}`

### `theirstackmcp_list_webhook_event_types`

List webhook event types · Read-only

Returns supported webhook event types with their metadata. Pass `search_type=jobs` or `search_type=companies` to get only the events relevant to that search type.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `search_type` (`string`, optional): Filter event types by search type: 'jobs' or 'companies'. One of: `jobs`, `companies`.

Example input: `{}`

### `theirstackmcp_list_webhook_events`

List webhook events · Read-only

Retrieve a paginated list of all events triggered for a specific webhook including delivery status, payload, and timestamps. Filter by event status to find failed deliveries that may need to be retried.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `webhook_id` (`integer`, required): ID of the webhook
- `limit` (`integer`, optional): Number of results per page. Default: `25`.
- `offset` (`integer`, optional): Number of results to skip. Default: `0`.
- `status` (`string`, optional): Status of the webhook events to filter by. One of: `IN_PROGRESS`, `SUCCESS`, `FAILED`, `NOT_TRIGGERED`.

Example input: `{"webhook_id":1}`

### `theirstackmcp_list_webhooks`

List webhooks · Read-only

Retrieve all webhooks configured for your team including their status, target URL, event type, and linked saved search. Archived webhooks are excluded unless you pass include_archived=true. Use this to monitor your webhook integrations.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `include_archived` (`boolean`, optional): Include archived webhooks in the response. They no longer deliver events, but their event history is retained and their name is needed to label past events. Default: `false`.

Example input: `{}`

### `theirstackmcp_preview_crm_send`

Preview sending companies to the CRM · Read-only

How many of these companies a send to the CRM would create, update or skip, and why, without writing anything. Pass the `id` of each company as company search returns it. Call it before `send_companies_to_crm`.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `company_ids` (`array`, required): TheirStack company ids

Example input: `{"company_ids":[]}`

### `theirstackmcp_preview_crm_send_settings`

Review what sending companies to the CRM would write · Read-only

What these send settings would write for a few of the workspace's companies, property by property, without saving them or sending anything to the CRM. Call it before `save_crm_send_settings`. Workspace owners only.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `company_ids` (`array`, optional): Companies to review; a few the workspace revealed when empty
- `mappings` (`array`, optional): Where each TheirStack field goes; a field left out is not sent
- `mode` (`string`, optional): Create companies the CRM does not have and fill in the ones it has, only create, or only update. One of: `create_and_update`, `create_only`, `update_only`. Default: `create_and_update`.
- `new_company_values` (`array`, optional): Fixed values for the companies TheirStack creates
- `owner` (`string`, optional): Who owns the companies TheirStack creates: whoever sends them (matched by email to a CRM user) or nobody. One of: `sender`, `none`. Default: `sender`.

Example input: `{}`

### `theirstackmcp_preview_crm_status_rules`

Preview CRM status rules · Read-only

How many companies each status would get with these rules, and which companies would change status, without saving anything. Send every status in the order they are checked: the list replaces the current one.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `statuses` (`array`, required): The statuses in the order they are checked: the first one whose conditions hold gives a company its status, and a company that meets none is In CRM

Example input: `{"statuses":[]}`

### `theirstackmcp_search_companies`

Search companies · Read-only

Search and filter companies by firmographics (industry, country, employee count, revenue), funding, the technologies they use (technographics) and hiring signals (the roles and technologies they are hiring for). Use it to find the companies that match a profile, such as the companies in a country that use a technology or are hiring for a role. Returns the matching companies along with the jobs and technology objects that matched the filters you passed.

It consumes **3 API credits** for each company returned in the response.

Useful resources: [Preview data mode](https://theirstack.com/en/docs/api-reference/features/preview-data-mode), [Counting results](https://theirstack.com/en/docs/api-reference/features/count-results)

The response includes both company data and any matching jobs or technologies based on your filters.

Job, company, technographics and buying intent searches share one rate limit per user (10 per minute on the free plan).

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `blur_company_data` (`boolean`, optional): Enable preview mode to return blurred data without consuming credits in the TheirStack app. Deprecated: preview mode is being retired and will stop working over the API. It still works on paid workspaces created before August 11, 2026 and is not available on any other workspace; new access is only granted to sales intelligence products that preview data to their end users before unlocking it, by opening a support ticket at https://app.theirstack.com/support/new. When enabled, sensitive company fields (name, domain, URLs, descriptions) and job-specific fields (description, URLs) are blurred. Not available when filtering by company identifiers (company_name, company_domain, company_linkedin_url, company_id). Learn more in the [preview mode documentation](https://theirstack.com/en/docs/api-reference/features/preview-data-mode). Default: `false`.
- `company_country_code_not` (`array`, optional): Return companies whose HQ country code is not any of the ones passed here, case sensitive. Pass ISO2 country codes.
- `company_country_code_not_or_null` (`array`, optional): Return companies whose HQ country code is not any of the ones passed here, case sensitive. Companies whose country we don't know are returned as well. Pass ISO2 country codes.
- `company_country_code_or` (`array`, optional): Return companies whose HQ country code is any of the ones passed here, case sensitive. Pass ISO2 country codes.
- `company_crm_status_not` (`array`, optional): Return companies with none of these statuses in the CRM connected to your workspace. Takes the same values as `company_crm_status_or`. Webhooks and sales signals can't use this filter yet.
- `company_crm_status_or` (`array`, optional): Return companies with any of these statuses in the CRM connected to your workspace: the keys of your own statuses (`customer`, `open_deal` and `former_customer` to start with), `in_crm` for any other company the CRM holds, and `no_crm_match` for companies it doesn't. A status your workspace no longer has matches no company, and without a CRM connected every company counts as `no_crm_match`. Webhooks and sales signals can't use this filter yet.
- `company_description_pattern_accent_insensitive` (`boolean`, optional): Set to True to make company description searches accent insensitive. For example, "á" will match "a" as well. Default: `false`.
- `company_description_pattern_not` (`array`, optional): Case-insensitive patterns to match in the company description. Will exclude companies that match any of the patterns.
- `company_description_pattern_or` (`array`, optional): Case-insensitive patterns to match in the company description. Will return companies that match any of the patterns.
- `company_domain_not` (`array`, optional): Only return companies that don't match these domains exactly. It accepts full urls (https://www.google.com/) and emails (andrew@stripe.com).
- `company_domain_or` (`array`, optional): Only return companies that match these domains exactly. It accepts full urls (https://www.google.com/) and emails (andrew@stripe.com). This filter acts as an OR filter, so if you pass more than one company domain, it will return companies that match any of the domains.
- `company_id_not` (`array`, optional): Exclude companies that match these IDs. This filter acts as a NOT filter, so if you pass more than one company ID, it will exclude companies that match any of the IDs.
- `company_id_or` (`array`, optional): Only return companies that match these IDs exactly. This filter acts as an OR filter, so if you pass more than one company ID, it will return companies that match any of the IDs.
- `company_investors_or` (`array`, optional): Investors of the company
- `company_investors_partial_match_or` (`array`, optional): Investors of the company. Will return companies for which any of their investors contains any of the substrings passed here. For example, if you pass 'andree', all funds that match it (like 'Andreessen Horowitz', 'Andreessen Horowitz LLC', etc).
- `company_keyword_slug_and` (`array`, optional): Return results from companies that have mentioned all of these keywords in their jobs. Case sensitive. Pass slugs. Check out all the keywords we track at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0)
- `company_keyword_slug_not` (`array`, optional): Return results from companies that haven't mentioned any of these keywords in their jobs. Case sensitive. Pass slugs. Check out all the keywords we track at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0)
- `company_keyword_slug_or` (`array`, optional): Return results from companies that have mentioned any of these keywords in their jobs. Case sensitive. Pass slugs. Check out all the keywords we track at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0)
- `company_linkedin_url_or` (`array`, optional): Return companies whose LinkedIn page matches any of the values passed here. Both forms of LinkedIn company URL work — the vanity slug (`https://www.linkedin.com/company/google/`) and the numeric company ID (`https://www.linkedin.com/company/1038`) — as do a bare slug (`google`) and a bare numeric ID (`1038`). A numeric value is matched against the company's LinkedIn ID and its slug, so you do not need to know which of the two you are holding. We have a LinkedIn slug for ~26% of companies and a numeric LinkedIn ID for ~14%, so if you have the company's domain, `company_domain_or` matches more often.
- `company_list_id_not` (`array`, optional): Return companies that don't belong to any of the company lists passed here
- `company_list_id_or` (`array`, optional): Return companies that belong to any of the company lists passed here
- `company_location_pattern_or` (`array`, optional): Return companies whose city matches any of the patterns passed here. Case insensitive. For example, if you pass 'san francisco', it will return companies whose city is 'San Francisco', 'San Francisco Bay Area', etc.
- `company_name_case_insensitive_or` (`array`, optional): Only return companies that match these names exactly, case-insensitively.
- `company_name_not` (`array`, optional): Only return companies that don't match these names exactly, case-sensitively.
- `company_name_partial_match_not` (`array`, optional): Company names. Will return companies whose name doesn't contain any of the substrings passed here, case-insensitively. For example, if you pass 'google', it will exclude 'Google', 'Google LLC', 'Google Inc', etc.
- `company_name_partial_match_or` (`array`, optional): Company names. Will return companies whose name contains any of the substrings passed here, case-insensitively. For example, if you pass "google", it will return "Google", "Google LLC", "Google Inc", etc.
- `company_not_revealed_at_gte` (`string`, optional): Exclude companies (or jobs by their company) revealed in the caller's account at or after this ISO-8601 timestamp. Combine with `company_not_revealed_at_lte` to exclude a window. Companies the team never revealed are kept.
- `company_not_revealed_at_lte` (`string`, optional): Exclude companies (or jobs by their company) revealed in the caller's account at or before this ISO-8601 timestamp. Combine with `company_not_revealed_at_gte` to exclude a window. Companies the team never revealed are kept.
- `company_not_revealed_within_hours` (`integer`, optional): Exclude companies (or jobs by their company) revealed in the caller's account in the last N hours, counted back from when the search runs. `168` hides what the team revealed in the last 7 days; companies revealed earlier, or never, are kept. Viewing an already-revealed company again does not restart its window. Unlike `revealed_company_data=false`, which excludes the whole 90-day reveal period, this only excludes reveals inside the window.
- `company_revealed_at_gte` (`string`, optional): Filter companies (or jobs by their company) by when the company was revealed in the caller's account. Returns only companies revealed at or after this ISO-8601 timestamp. Scoped to the caller's team — has no effect for companies the team has never revealed.
- `company_revealed_at_lte` (`string`, optional): Filter companies (or jobs by their company) by when the company was revealed in the caller's account. Returns only companies revealed at or before this ISO-8601 timestamp. Scoped to the caller's team — has no effect for companies the team has never revealed.
- `company_revealed_within_hours` (`integer`, optional): Return only companies (or jobs by their company) revealed in the caller's account in the last N hours, counted back from when the search runs. `168` is the last 7 days. Saved searches and webhooks resolve the window on every run. It counts every reveal in the window: with N above 90 days (2160 hours) it also returns companies whose 90-day reveal has expired, which cost a credit to see again.
- `company_tags_or` (`array`, optional): Return companies that match any of these keywords
- `company_technology_slug_and` (`array`, optional): Return results from companies that have mentioned all of these technologies in their jobs (in job searches, not necessarily in the jobs returned). Case sensitive. Pass slugs. Check out all the technologies we track at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0) with `keyword_type=technology`
- `company_technology_slug_not` (`array`, optional): Return results from companies that haven't mentioned any of these technologies in their jobs. Case sensitive. Pass slugs. Check out all the technologies we track at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0) with `keyword_type=technology`
- `company_technology_slug_or` (`array`, optional): Return results from companies that have mentioned any of these technologies in their jobs (in job searches, not necessarily in the jobs returned). Case sensitive. Pass slugs. Check out all the technologies we track at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0) with `keyword_type=technology`
- `company_type` (`string`, optional): Filter by company type. One of: `recruiting_agency`, `direct_employer`, `all`.
- `cursor` (`string`, optional): Cursor for pagination
- `expand_technology_slugs` (`array`, optional): Specify technology slugs to include detailed technology usage information for each company. The response will include a 'technologies_found' field containing metrics like confidence score, ranking, and job count for each specified technology. Note: If a technology is not listed for a company, it means we haven't detected it in that company's jobs. This feature is useful for enriching company data with their technology stack details.
- `funding_stage_or` (`array`, optional): Funding stages of companies returned. Possible values: ['angel', 'convertible_note', 'debt_financing', 'equity_crowdfunding', 'other', 'private_equity', 'seed', 'series_a', 'series_b', 'series_c', 'series_d', 'series_e', 'series_f', 'series_g', 'series_h', 'venture_round_not_specified', 'series_i', 'series_j', 'undisclosed', 'series_unknown', 'pre_seed', 'post_ipo_secondary', 'post_ipo_equity', 'post_ipo_debt', 'non_equity_assistance', 'late_vc', 'initial_coin_offering', 'growth_equity_vc', 'grant', 'early_vc', 'corporate_round', 'secondary_market', 'product_crowdfunding']
- `include_total_results` (`boolean`, optional): When enabled, calculates and returns `total_results` and `total_companies` fields in the response. WARNING: This significantly slows down responses as it requires reading the entire dataset. Recommended usage: enable only for the initial request to get totals, then disable for subsequent pagination requests. Default: `false`.
- `industry_id_not` (`array`, optional): Industry ids to exclude. You can use any of [LinkedIn's Industry Codes V2](https://learn.microsoft.com/en-us/linkedin/shared/references/reference-tables/industry-codes-v2) or [GET /v0/catalog/industries](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_industries_v0)
- `industry_id_not_or_null` (`array`, optional): Industry ids to exclude. Companies whose industry we don't know are returned as well. You can use any of [LinkedIn's Industry Codes V2](https://learn.microsoft.com/en-us/linkedin/shared/references/reference-tables/industry-codes-v2) or [GET /v0/catalog/industries](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_industries_v0)
- `industry_id_or` (`array`, optional): Industry codes. You can use any of [LinkedIn's Industry Codes V2](https://learn.microsoft.com/en-us/linkedin/shared/references/reference-tables/industry-codes-v2) or [GET /v0/catalog/industries](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_industries_v0)
- `job_filters` (`object`, optional): Filter companies by the jobs they have posted. Takes the job filters of the job search endpoint and requires a date filter (`posted_at_max_age_days`, `posted_at_min_age_days`, `posted_at_gte` or `posted_at_lte`). Returns companies with at least one matching job, or at least `min_num_jobs_found` if set.
- `last_funding_round_date_gte` (`string`, optional): Only return companies whose last funding round date is after or on this date. Format: 'YYYY-MM-DD'
- `last_funding_round_date_lte` (`string`, optional): Only return companies whose last funding round date is before or on this date. Format: 'YYYY-MM-DD'
- `limit` (`integer`, optional): Number of results per page. Default: `25`.
- `max_employee_count` (`integer`, optional): Maximum number of employees in a company
- `max_employee_count_or_null` (`integer`, optional): Maximum number of employees in a company. If we don't have company size information, we will return it as well.
- `max_funding_usd` (`integer`, optional): Maximum company funding, in USD
- `max_revenue_usd` (`integer`, optional): Maximum company revenue, in USD
- `max_revenue_usd_or_null` (`integer`, optional): Maximum company revenue, in USD. Also returns companies with unknown revenue.
- `min_employee_count` (`integer`, optional): Minimum number of employees in a company
- `min_employee_count_or_null` (`integer`, optional): Minimum number of employees in a company. If we don't have company size information, we will return it as well.
- `min_funding_usd` (`integer`, optional): Minimum company funding, in USD
- `min_num_jobs_found` (`integer`, optional): Minimum number of jobs matching `job_filters` a company must have to be returned (thresholds the `num_jobs_found` count). Requires `job_filters` with a date filter, so the count is always computed over the date-bounded set of matching jobs.
- `min_revenue_usd` (`integer`, optional): Minimum company revenue, in USD
- `min_revenue_usd_or_null` (`integer`, optional): Minimum company revenue, in USD. Also returns companies with unknown revenue.
- `offset` (`integer`, optional): Number of results to skip. Required for [offset-based pagination](https://theirstack.com/en/docs/api-reference/pagination). Default: `0`.
- `only_yc_companies` (`boolean`, optional): Only return YC companies. Default: `false`.
- `page` (`integer`, optional): Page number. Required when using [page-based pagination](https://theirstack.com/en/docs/api-reference/pagination). Default: `0`.
- `property_exists_and` (`array`, optional): Return companies that have all of these fields not null. For example, if you pass ['domain', 'linkedin_url'], it will return companies that have both domain AND linkedin_url set.
- `property_exists_or` (`array`, optional): Return companies that have any of these fields not null. For example, if you pass ['domain', 'linkedin_url'], it will return companies that have a domain OR a linkedin_url set.
- `revealed_company_data` (`boolean`, optional): Filter companies (or jobs by their company) by whether the caller's team has them revealed. A company counts as revealed for 90 days after the team reveals it. `true` returns only revealed companies; `false` returns only companies the team has not revealed in the last 90 days, including the ones it never revealed.
- `tech_filters` (`object`, optional): Filter by technologies and buying intent topics detected for the company

Example input: `{}`

### `theirstackmcp_search_docs`

Search the documentation · Read-only

Search TheirStack's public documentation and get the matching pages as markdown.

Use it for any question about how TheirStack works: API endpoints and their
parameters, credits and what each call costs, limits, webhooks, datasets, the
MCP server and the app. Results are grouped by page, each with its URL and
the passages that matched.

- Search with the user's own words first. If nothing useful comes back, retry
  with the words the docs would use or the API parameter name. One topic per
  search.
- Passages are excerpts: read every relevant page in full with get_page
  before answering.
- The public docs are what customers read. When they disagree with internal
  notes or with what you remember, the docs win.
- Cite the page URL in your answer.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `query` (`string`, required): What to find, in natural language or as an API parameter name.
- `limit` (`integer`, optional): Maximum pages returned. Default: `5`.

Example input: `{"query":"<query>"}`

### `theirstackmcp_search_jobs`

Search jobs · Read-only

Search and filter job postings collected from company career sites and job boards. Filter by job title, keywords in the job description, company (name, domain or LinkedIn URL), location and country, technology and tech stack, salary, seniority, remote/hybrid, employment type, and posting date. Use it to find open roles, to see which companies are hiring for a role or a technology, or to follow the hiring of specific companies.

It consumes **1 API credit** for each job returned in the response.

You must specify at least one of the following filters, or otherwise your request will fail: `posted_at_max_age_days`, `posted_at_min_age_days`, `posted_at_gte`, `posted_at_lte`, `job_id_or`, `company_id_or`, `company_domain_or`, `company_linkedin_url_or`, `company_name_or`, `company_name_case_insensitive_or`, `company_name_partial_match_or`. This is for performance reasons. A company filter only satisfies this rule when it has fewer than 50 values: with more companies, also send a `posted_at_max_age_days`, `posted_at_min_age_days`, `posted_at_gte` or `posted_at_lte` filter. Filtering by `discovered_at_*` fields does not count.

To get the jobs of specific companies, filter by `company_domain_or` (most companies have a domain),`company_linkedin_url_or`, `company_name_or` or `company_name_case_insensitive_or`. Company identifier filters are combined with OR: a job matches when its company matches any value in any of them. If you identify companies in more than one way, send a separate request for each company.

Useful resources: [Avoiding getting the same job twice](https://theirstack.com/en/docs/api-reference/guides/avoid-getting-same-jobs-twice), [Fetching jobs periodically](https://theirstack.com/en/docs/guides/fetch-jobs-periodically), [Preview data mode](https://theirstack.com/en/docs/api-reference/features/preview-data-mode), [Counting results](https://theirstack.com/en/docs/api-reference/features/count-results)

Job, company, technographics and buying intent searches share one rate limit per user (10 per minute on the free plan).

Read only: yes. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `blur_company_data` (`boolean`, optional): Enable preview mode to return blurred data without consuming credits in the TheirStack app. Deprecated: preview mode is being retired and will stop working over the API. It still works on paid workspaces created before August 11, 2026 and is not available on any other workspace; new access is only granted to sales intelligence products that preview data to their end users before unlocking it, by opening a support ticket at https://app.theirstack.com/support/new. When enabled, sensitive company fields (name, domain, URLs, descriptions) and job-specific fields (description, URLs) are blurred. Not available when filtering by company identifiers (company_name, company_domain, company_linkedin_url, company_id). Learn more in the [preview mode documentation](https://theirstack.com/en/docs/api-reference/features/preview-data-mode). Default: `false`.
- `closed_at_gte` (`string`, optional): ISO 8601 date string (yyyy-mm-dd). Only return jobs closed on this date or after.
- `closed_at_lte` (`string`, optional): ISO 8601 date string (yyyy-mm-dd). Only return jobs closed on this date or before.
- `company_country_code_not` (`array`, optional): Return companies whose HQ country code is not any of the ones passed here, case sensitive. Pass ISO2 country codes.
- `company_country_code_not_or_null` (`array`, optional): Return companies whose HQ country code is not any of the ones passed here, case sensitive. Companies whose country we don't know are returned as well. Pass ISO2 country codes.
- `company_country_code_or` (`array`, optional): Return companies whose HQ country code is any of the ones passed here, case sensitive. Pass ISO2 country codes.
- `company_crm_status_not` (`array`, optional): Return companies with none of these statuses in the CRM connected to your workspace. Takes the same values as `company_crm_status_or`. Webhooks and sales signals can't use this filter yet.
- `company_crm_status_or` (`array`, optional): Return companies with any of these statuses in the CRM connected to your workspace: the keys of your own statuses (`customer`, `open_deal` and `former_customer` to start with), `in_crm` for any other company the CRM holds, and `no_crm_match` for companies it doesn't. A status your workspace no longer has matches no company, and without a CRM connected every company counts as `no_crm_match`. Webhooks and sales signals can't use this filter yet.
- `company_description_pattern_accent_insensitive` (`boolean`, optional): Set to True to make company description searches accent insensitive. For example, "á" will match "a" as well. Default: `false`.
- `company_description_pattern_not` (`array`, optional): Case-insensitive patterns to match in the company description. Will exclude companies that match any of the patterns.
- `company_description_pattern_or` (`array`, optional): Case-insensitive patterns to match in the company description. Will return companies that match any of the patterns.
- `company_domain_not` (`array`, optional): Only return companies that don't match these domains exactly. It accepts full urls (https://www.google.com/) and emails (andrew@stripe.com).
- `company_domain_or` (`array`, optional): Only return companies that match these domains exactly. It accepts full urls (https://www.google.com/) and emails (andrew@stripe.com). This filter acts as an OR filter, so if you pass more than one company domain, it will return companies that match any of the domains.
- `company_id_not` (`array`, optional): Exclude companies that match these IDs. This filter acts as a NOT filter, so if you pass more than one company ID, it will exclude companies that match any of the IDs.
- `company_id_or` (`array`, optional): Only return companies that match these IDs exactly. This filter acts as an OR filter, so if you pass more than one company ID, it will return companies that match any of the IDs.
- `company_investors_or` (`array`, optional): Investors of the company
- `company_investors_partial_match_or` (`array`, optional): Investors of the company. Will return companies for which any of their investors contains any of the substrings passed here. For example, if you pass 'andree', all funds that match it (like 'Andreessen Horowitz', 'Andreessen Horowitz LLC', etc).
- `company_keyword_slug_and` (`array`, optional): Return results from companies that have mentioned all of these keywords in their jobs. Case sensitive. Pass slugs. Check out all the keywords we track at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0)
- `company_keyword_slug_not` (`array`, optional): Return results from companies that haven't mentioned any of these keywords in their jobs. Case sensitive. Pass slugs. Check out all the keywords we track at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0)
- `company_keyword_slug_or` (`array`, optional): Return results from companies that have mentioned any of these keywords in their jobs. Case sensitive. Pass slugs. Check out all the keywords we track at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0)
- `company_linkedin_url_or` (`array`, optional): Return companies whose LinkedIn page matches any of the values passed here. Both forms of LinkedIn company URL work — the vanity slug (`https://www.linkedin.com/company/google/`) and the numeric company ID (`https://www.linkedin.com/company/1038`) — as do a bare slug (`google`) and a bare numeric ID (`1038`). A numeric value is matched against the company's LinkedIn ID and its slug, so you do not need to know which of the two you are holding. We have a LinkedIn slug for ~26% of companies and a numeric LinkedIn ID for ~14%, so if you have the company's domain, `company_domain_or` matches more often.
- `company_list_id_not` (`array`, optional): Return companies that don't belong to any of the company lists passed here
- `company_list_id_or` (`array`, optional): Return companies that belong to any of the company lists passed here
- `company_location_pattern_or` (`array`, optional): Return companies whose city matches any of the patterns passed here. Case insensitive. For example, if you pass 'san francisco', it will return companies whose city is 'San Francisco', 'San Francisco Bay Area', etc.
- `company_name_case_insensitive_or` (`array`, optional): Only return companies that match these names exactly, case-insensitively.
- `company_name_not` (`array`, optional): Only return companies that don't match these names exactly, case-sensitively.
- `company_name_partial_match_not` (`array`, optional): Company names. Will return companies whose name doesn't contain any of the substrings passed here, case-insensitively. For example, if you pass 'google', it will exclude 'Google', 'Google LLC', 'Google Inc', etc.
- `company_name_partial_match_or` (`array`, optional): Company names. Will return companies whose name contains any of the substrings passed here, case-insensitively. For example, if you pass "google", it will return "Google", "Google LLC", "Google Inc", etc.
- `company_not_revealed_at_gte` (`string`, optional): Exclude companies (or jobs by their company) revealed in the caller's account at or after this ISO-8601 timestamp. Combine with `company_not_revealed_at_lte` to exclude a window. Companies the team never revealed are kept.
- `company_not_revealed_at_lte` (`string`, optional): Exclude companies (or jobs by their company) revealed in the caller's account at or before this ISO-8601 timestamp. Combine with `company_not_revealed_at_gte` to exclude a window. Companies the team never revealed are kept.
- `company_not_revealed_within_hours` (`integer`, optional): Exclude companies (or jobs by their company) revealed in the caller's account in the last N hours, counted back from when the search runs. `168` hides what the team revealed in the last 7 days; companies revealed earlier, or never, are kept. Viewing an already-revealed company again does not restart its window. Unlike `revealed_company_data=false`, which excludes the whole 90-day reveal period, this only excludes reveals inside the window.
- `company_revealed_at_gte` (`string`, optional): Filter companies (or jobs by their company) by when the company was revealed in the caller's account. Returns only companies revealed at or after this ISO-8601 timestamp. Scoped to the caller's team — has no effect for companies the team has never revealed.
- `company_revealed_at_lte` (`string`, optional): Filter companies (or jobs by their company) by when the company was revealed in the caller's account. Returns only companies revealed at or before this ISO-8601 timestamp. Scoped to the caller's team — has no effect for companies the team has never revealed.
- `company_revealed_within_hours` (`integer`, optional): Return only companies (or jobs by their company) revealed in the caller's account in the last N hours, counted back from when the search runs. `168` is the last 7 days. Saved searches and webhooks resolve the window on every run. It counts every reveal in the window: with N above 90 days (2160 hours) it also returns companies whose 90-day reveal has expired, which cost a credit to see again.
- `company_tags_or` (`array`, optional): Return companies that match any of these keywords
- `company_technology_slug_and` (`array`, optional): Return results from companies that have mentioned all of these technologies in their jobs (in job searches, not necessarily in the jobs returned). Case sensitive. Pass slugs. Check out all the technologies we track at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0) with `keyword_type=technology`
- `company_technology_slug_not` (`array`, optional): Return results from companies that haven't mentioned any of these technologies in their jobs. Case sensitive. Pass slugs. Check out all the technologies we track at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0) with `keyword_type=technology`
- `company_technology_slug_or` (`array`, optional): Return results from companies that have mentioned any of these technologies in their jobs (in job searches, not necessarily in the jobs returned). Case sensitive. Pass slugs. Check out all the technologies we track at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0) with `keyword_type=technology`
- `company_type` (`string`, optional): Filter by company type. One of: `recruiting_agency`, `direct_employer`, `all`.
- `cursor` (`string`, optional): Cursor for pagination
- `discovered_at_gte` (`string`, optional): Only jobs discovered by TheirStack on this date or datetime or after will be returned. In UTC timezone. Does not satisfy the mandatory-filter rule; combine it with a `posted_at_*` filter.
- `discovered_at_lte` (`string`, optional): Only jobs discovered by TheirStack on this date or datetime or before will be returned. In UTC timezone. Does not satisfy the mandatory-filter rule; combine it with a `posted_at_*` filter.
- `discovered_at_max_age_days` (`integer`, optional): If 0, only return jobs added to our database in the current day. If 1, from today and yesterday, etc. Does not satisfy the mandatory-filter rule; combine it with a `posted_at_*` filter.
- `discovered_at_min_age_days` (`integer`, optional): If 1, only return jobs discovered by TheirStack until yesterday. If 2, until 2 days ago, etc. Does not satisfy the mandatory-filter rule; combine it with a `posted_at_*` filter.
- `easy_apply` (`boolean`, optional): If True, only return jobs where the candidate applies inside the job board with their profile there (LinkedIn Easy Apply, Indeed Apply). If False, only return jobs that send the candidate to the company's website or ATS, including jobs published on the company's own ATS. Jobs whose source doesn't say are excluded either way; use easy_apply_or_null to include them.
- `easy_apply_or_null` (`boolean`, optional): Same as easy_apply, but also returns jobs whose source doesn't say how to apply.
- `employment_statuses_or` (`array`, optional): Filter jobs by employment status. Returns jobs that match any of the specified employment types. If no values are provided or an empty list is sent, all jobs regardless of employment status will be returned.
- `funding_stage_or` (`array`, optional): Funding stages of companies returned. Possible values: ['angel', 'convertible_note', 'debt_financing', 'equity_crowdfunding', 'other', 'private_equity', 'seed', 'series_a', 'series_b', 'series_c', 'series_d', 'series_e', 'series_f', 'series_g', 'series_h', 'venture_round_not_specified', 'series_i', 'series_j', 'undisclosed', 'series_unknown', 'pre_seed', 'post_ipo_secondary', 'post_ipo_equity', 'post_ipo_debt', 'non_equity_assistance', 'late_vc', 'initial_coin_offering', 'growth_equity_vc', 'grant', 'early_vc', 'corporate_round', 'secondary_market', 'product_crowdfunding']
- `include_total_results` (`boolean`, optional): When enabled, calculates and returns `total_results` and `total_companies` fields in the response. WARNING: This significantly slows down responses as it requires reading the entire dataset. Recommended usage: enable only for the initial request to get totals, then disable for subsequent pagination requests. Default: `false`.
- `industry_id_not` (`array`, optional): Industry ids to exclude. You can use any of [LinkedIn's Industry Codes V2](https://learn.microsoft.com/en-us/linkedin/shared/references/reference-tables/industry-codes-v2) or [GET /v0/catalog/industries](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_industries_v0)
- `industry_id_not_or_null` (`array`, optional): Industry ids to exclude. Companies whose industry we don't know are returned as well. You can use any of [LinkedIn's Industry Codes V2](https://learn.microsoft.com/en-us/linkedin/shared/references/reference-tables/industry-codes-v2) or [GET /v0/catalog/industries](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_industries_v0)
- `industry_id_or` (`array`, optional): Industry codes. You can use any of [LinkedIn's Industry Codes V2](https://learn.microsoft.com/en-us/linkedin/shared/references/reference-tables/industry-codes-v2) or [GET /v0/catalog/industries](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_industries_v0)
- `is_closed` (`boolean`, optional): If True, only return closed jobs (jobs where TheirStack detected the posting was closed). If False, only return open jobs. If None, return all jobs regardless of closure status.
- `job_country_code_not` (`array`, optional): 2-letter ISO country code of the location of the job. Can pass more than 1. Will exclude jobs from these countries
- `job_country_code_or` (`array`, optional): 2-letter ISO country code of the location of the job. Can pass more than 1
- `job_description_contains_not` (`array`, optional): Exclude jobs whose descriptions contain ANY of these literal whole words or phrases. Uses the same word/phrase matching as job_description_contains_or, including adjacent words in order. Pass plain text, not regex. Uses the indexed description representation when enabled; exclusions alone can still scan many jobs. Indexed matching folds case and accents and treats punctuation as token boundaries; legacy search can handle case and punctuation differently. Pair with job_description_contains_or for positive matches. An exclusion removes the whole job, even if a positive term also matches. Pass each word or phrase as it is, without quotes: wrapping quotes are removed. A value with a comma returns a 422: remove the comma, or pass separate words as separate items. Accounts already sending commas have until December 8, 2026.
- `job_description_contains_or` (`array`, optional): Recommended filter for searching job descriptions. Pass literal whole words or phrases, not regex. Matches ANY entry (OR); words within a phrase must be adjacent and in order. Whole words only: 'quality' does not match 'inequality'. Uses the word/phrase text index when indexed description search is enabled: case and accents are folded, punctuation separates tokens, and 'C++', 'C#' and 'C' remain distinct. With legacy search enabled, case and punctuation handling can differ. Use job_description_contains_not for exclusions. Does not support wildcards, proximity or AND across entries. Pass each word or phrase as it is, without quotes: wrapping quotes are removed. A value with a comma returns a 422: remove the comma, or pass separate words as separate items. Accounts already sending commas have until December 8, 2026.
- `job_export_key_or` (`array`, optional): Internal export lookup keys for fetching a materialized job batch.
- `job_id_not` (`array`, optional): Exclude jobs with these IDs.
- `job_id_or` (`array`, optional): Get jobs with these IDs only.
- `job_keyword_slug_and` (`array`, optional): Will return jobs where all of these keyword slugs appear. Case sensitive. Check out all the keywords we track at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0)
- `job_keyword_slug_not` (`array`, optional): Will return jobs where none of these keyword slugs appear. Case sensitive. Check out all the keywords we track at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0)
- `job_keyword_slug_or` (`array`, optional): Will return jobs where any of these keyword slugs appear. Case sensitive. Check out all the keywords we track at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0)
- `job_location_not` (`array`, optional): Filter jobs by location. Returns jobs whose locations DO NOT match ANY of the specified location criteria. Each location criteria is specified using a JobLocationFilter object such as `{"id": 5128581}`; a bare id (`5128581`) is accepted too. Location names are not: find the ids with the [locations catalog endpoint](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_locations_v0).
- `job_location_or` (`array`, optional): Filter jobs by location. Returns jobs whose locations match ANY of the specified location criteria. Each location criteria is specified using a JobLocationFilter object such as `{"id": 5128581}`; a bare id (`5128581`) is accepted too. Location names are not: find the ids with the [locations catalog endpoint](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_locations_v0).
- `job_seniority_or` (`array`, optional): Will return jobs where the seniority is any of the ones passed here
- `job_technology_slug_and` (`array`, optional): Will return jobs where all of these technologies appear. Case sensitive. Pass slugs. Check out all the technologies we track at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0) with `keyword_type=technology`.
- `job_technology_slug_not` (`array`, optional): Will return jobs where none of these technologies appear. Case sensitive. Pass slugs. Check out all the technologies we track at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0) with `keyword_type=technology`.
- `job_technology_slug_or` (`array`, optional): Will return jobs where any of these technologies appear. Case sensitive. Pass slugs. Check out all the technologies we track at [GET /v0/catalog/keywords](https://theirstack.com/en/docs/api-reference/catalog/get_catalog_keywords_v0) with `keyword_type=technology`. If you pass more than one technology, we will return jobs that mention at least one of them.
- `job_title_not` (`array`, optional): Keyword-based patterns to exclude job titles. Case-insensitive. Excludes jobs whose title contains all the words in any of the patterns, in any order. For example, `marketing vp` excludes titles such as `VP of Marketing` or `Marketing VP, EMEA`. A value with a comma returns a 422: remove the comma, or pass separate titles as separate items. Accounts already sending commas have until December 8, 2026.
- `job_title_or` (`array`, optional): Keyword-based patterns to match job titles. Case-insensitive. Returns jobs whose title contains all the words in any of the patterns, in any order. For example, `marketing vp` matches titles such as `VP of Marketing` or `Marketing VP, EMEA`. Passing `["software engineer", "data scientist"]` returns jobs matching either pattern. A value with a comma returns a 422: remove the comma, or pass separate titles as separate items. Accounts already sending commas have until December 8, 2026.
- `job_title_pattern_and` (`array`, optional): Regex patterns to match job titles. Case-insensitive. Only jobs with title that match all of these patterns will be returned.
- `job_title_pattern_not` (`array`, optional): Regex patterns to match job titles. Case-insensitive. Jobs whose job title doesn't match any of the patterns will be returned.
- `job_title_pattern_or` (`array`, optional): Regex patterns to match job titles. Case-insensitive. Jobs whose job title matches any of the patterns will be returned.
- `last_funding_round_date_gte` (`string`, optional): Only return companies whose last funding round date is after or on this date. Format: 'YYYY-MM-DD'
- `last_funding_round_date_lte` (`string`, optional): Only return companies whose last funding round date is before or on this date. Format: 'YYYY-MM-DD'
- `limit` (`integer`, optional): Number of results per page. Default: `25`.
- `max_employee_count` (`integer`, optional): Maximum number of employees in a company
- `max_employee_count_or_null` (`integer`, optional): Maximum number of employees in a company. If we don't have company size information, we will return it as well.
- `max_funding_usd` (`integer`, optional): Maximum company funding, in USD
- `max_revenue_usd` (`integer`, optional): Maximum company revenue, in USD
- `max_revenue_usd_or_null` (`integer`, optional): Maximum company revenue, in USD. Also returns companies with unknown revenue.
- `max_salary_usd` (`number`, optional): Maximum annual salary in USD. For example, 150000 means $150,000.
- `min_employee_count` (`integer`, optional): Minimum number of employees in a company
- `min_employee_count_or_null` (`integer`, optional): Minimum number of employees in a company. If we don't have company size information, we will return it as well.
- `min_funding_usd` (`integer`, optional): Minimum company funding, in USD
- `min_revenue_usd` (`integer`, optional): Minimum company revenue, in USD
- `min_revenue_usd_or_null` (`integer`, optional): Minimum company revenue, in USD. Also returns companies with unknown revenue.
- `min_salary_usd` (`number`, optional): Minimum annual salary in USD. For example, 100000 means $100,000.
- `offset` (`integer`, optional): Number of results to skip. Required for [offset-based pagination](https://theirstack.com/en/docs/api-reference/pagination). Default: `0`.
- `only_yc_companies` (`boolean`, optional): Only return YC companies. Default: `false`.
- `page` (`integer`, optional): Page number. Required when using [page-based pagination](https://theirstack.com/en/docs/api-reference/pagination). Default: `0`.
- `posted_at_gte` (`string`, optional): ISO 8601 date string (yyyy-mm-dd). Only jobs published in this date or after will be returned. A datetime is accepted too and only its date in UTC is used.
- `posted_at_lte` (`string`, optional): ISO 8601 date string (yyyy-mm-dd). Only jobs published in this date or before will be returned. A datetime is accepted too and only its date in UTC is used.
- `posted_at_max_age_days` (`integer`, optional): Date posted max age in days. If 0, only return jobs posted today. If 1, from today and yesterday, etc.
- `posted_at_min_age_days` (`integer`, optional): Date posted min age in days. If 1, only return jobs posted until yesterday. If 30, until 30 days ago, etc. Combine it with `posted_at_max_age_days` for a range that moves with today: `posted_at_max_age_days: 90` and `posted_at_min_age_days: 30` return jobs posted between 90 and 30 days ago.
- `property_exists_and` (`array`, optional): Return jobs that have all of these fields not null. For example, if you pass ['company_object.domain', 'final_url'], it will only return jobs that have both a company domain and a final_url set.
- `property_exists_or` (`array`, optional): Return jobs that have any of these fields not null. For example, if you pass ['final_url'], it will return jobs that have a final_url set. This field also supports chaining of fields. For example, if you pass ['company_object.domain', 'company_object.linkedin_url'], it will return jobs that have a company domain or a company linkedin_url set.
- `revealed_company_data` (`boolean`, optional): Filter companies (or jobs by their company) by whether the caller's team has them revealed. A company counts as revealed for 90 days after the team reveals it. `true` returns only revealed companies; `false` returns only companies the team has not revealed in the last 90 days, including the ones it never revealed.
- `url_domain_not` (`array`, optional): Exclude jobs if their URL domain (from `url` or `source_url`) is in the provided case-insensitive list. For example, ['greenhouse.io', 'workable.com'] will exclude URLs containing 'greenhouse.io' or 'workable.com'. Refer to our list of sources at https://theirstack.com/en/docs/data/job/sources.
- `url_domain_or` (`array`, optional): Include jobs only if their URL domain (from `url` or `source_url`) is in the provided case-insensitive list. For example, ['greenhouse.io', 'workable.com'] will match URLs containing 'greenhouse.io' or 'workable.com'. Refer to our list of sources at https://theirstack.com/en/docs/data/job/sources.
- `workplace_types_or` (`array`, optional): Filter jobs by workplace type. Returns jobs that match any of the specified workplace types. `on_site` matches jobs that are neither hybrid nor remote. If no values are provided or an empty list is sent, jobs are not filtered by workplace type.

Example input: `{}`

### `theirstackmcp_add_companies_to_list`

Add companies to list · Write

Add companies to one of the team's company lists by their company IDs, the `id` of each company in a company search result. Returns the list with its new company count. If a company is not found, nothing is added and the error names the IDs that were not found.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `company_ids` (`array`, required): Company IDs to add, the `id` of each company in a company search result
- `list_id` (`integer`, required): No description.

Example input: `{"company_ids":[],"list_id":1}`

### `theirstackmcp_add_companies_to_multiple_lists`

Add companies to multiple lists · Write

Add the same companies to several of the team's company lists in one call, by their company IDs, the `id` of each company in a company search result. Nothing is added if any list ID isn't one of the team's lists.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `company_ids` (`array`, optional): Company IDs to add, the `id` of each company in a company search result
- `list_ids` (`array`, optional): IDs of the company lists to add the companies to

Example input: `{}`

### `theirstackmcp_create_company_list`

Create company list · Write

Create an empty company list for the team. Add companies to it afterwards by their company IDs.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Name of the company list

Example input: `{"name":"<name>"}`

### `theirstackmcp_create_sales_signal`

Create a sales signal · Write

Create a sales signal in your workspace: a search TheirStack keeps running, whose matching companies show up in the workspace's accounts feed with the evidence of why they match. Try its filters with `search_jobs` or `search_companies` first, and create the signal once they find the companies worth contacting. It charges API credits: up to 1,000 records on its first scan, then each new match while it is active. A name another live signal of the workspace has is refused (409), so a retried call never creates or charges twice.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `body` (`object`, required): The filters, as a flat object: the `search_jobs` filter fields when `search_type` is 'jobs', the `search_companies` ones when it is 'companies'. Don't wrap them in another key.
- `name` (`string`, required): Unique among the workspace's signals; also the name of its saved search
- `role` (`string`, required): What the signal means for the sale. One of: `target_role`, `decision_maker`, `customer`, `competitor`, `integration`, `prerequisite`, `pain`, `initiative`, `compliance`, `vertical`.
- `search_type` (`string`, required): `jobs` when `body` is a job search, `companies` when it is a company search. One of: `companies`, `jobs`.
- `description` (`string`, optional): Why it means they could buy
- `products` (`array`, optional): The products it pitches, by their name in the workspace's brand book
- `weight` (`integer`, optional): 1 low, 2 medium, 3 high. Default: `2`.

Example input: `{"body":{},"name":"<name>","role":"target_role","search_type":"companies"}`

### `theirstackmcp_create_saved_search`

Create saved search · Write

Save a job or company search so you can run it again, open it in the app or attach a webhook to it. The body takes the same filters as the job or company search. Saving costs no credits, and a name is generated from the filters when none is given.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `body` (`object`, required): The filters, as a flat object: the `search_jobs` filter fields when `type` is 'jobs', the `search_companies` ones when it is 'companies'. Don't wrap them in another key.
- `type` (`string`, required): Type of the saved search. One of: `companies`, `jobs`.
- `is_alert_active` (`boolean`, optional): Email new results to the creator of the saved search, weekly by default. Default: `false`.
- `name` (`string`, optional): Name of the saved search

Example input: `{"body":{},"type":"companies"}`

### `theirstackmcp_duplicate_company_list`

Duplicate company list · Write

Copy one of the team's company lists, with all its companies, into a new list owned by you and named like the original with ' (copy)' added.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `list_id` (`integer`, required): No description.

Example input: `{"list_id":1}`

### `theirstackmcp_report_data_bug`

Report a data bug · Write

Report wrong or missing data about a company or a job posting, such as an outdated employee count or tech stack, naming the affected company or URL. Opens a support ticket the team reviews.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `description` (`string`, required): What is wrong and what the correct value should be, in GitHub-flavoured Markdown (headings, lists, tables, code blocks), which is rendered as formatting.
- `title` (`string`, required): Short, human readable summary of the data issue
- `affected_url` (`string`, optional): A TheirStack or source URL where the wrong data can be seen
- `company_domain` (`string`, optional): Domain of the affected company
- `company_name` (`string`, optional): Name of the affected company, if the bug is about a company

Example input: `{"description":"<description>","title":"<title>"}`

### `theirstackmcp_request_technology`

Request a technology · Write

Ask TheirStack to add a technology that isn't in the keyword catalog yet, with its name and website, so it can be used in technology filters. Search the catalog first: this opens a support ticket the team follows up on.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Official or canonical name of the technology
- `url` (`string`, required): Official website of the technology (used to resolve it)
- `comment` (`string`, optional): Optional extra context about why the technology is needed, in GitHub-flavoured Markdown (headings, lists, tables, code blocks), which is rendered as formatting.
- `synonyms` (`array`, optional): Alternative names the technology is known by

Example input: `{"name":"<name>","url":"<url>"}`

### `theirstackmcp_share_feedback`

Share feedback · Write

Send feedback about TheirStack to the team.

Only for feedback. To ask for help, request a feature, book a call or ask
for a refund, point the user to the app's support page instead.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `feedback` (`string`, required): The feedback itself, in GitHub-flavoured Markdown (headings, lists, tables, code blocks), which is rendered as formatting.
- `title` (`string`, required): Short, human readable summary of the feedback

Example input: `{"feedback":"<feedback>","title":"<title>"}`

### `theirstackmcp_sync_crm`

Sync the CRM now · Write

Starts a full sync, which reads every company in the CRM again and gives each one its status under the current rules, or returns the sync already in progress. Workspace owners only.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs: none.

Example input: `{}`

### `theirstackmcp_archive_webhook`

Archive webhook · Destructive

Archive a webhook by its ID to permanently stop event delivery and remove it from the active webhook list. Archived webhooks and their event history are retained for reference but will no longer trigger notifications.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `webhook_id` (`integer`, required): ID of the webhook

Example input: `{"webhook_id":1}`

### `theirstackmcp_cancel_billing_invoice`

Cancel invoice · Destructive

Cancel an unpaid invoice: marks it uncollectible in Stripe, which voids it. Only open invoices can be cancelled.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `invoice_id` (`string`, required): The Stripe Invoice ID

Example input: `{"invoice_id":"<invoice_id>"}`

### `theirstackmcp_cancel_subscription`

Cancel subscription · Destructive

Cancel the current team's subscription at the end of the billing period, recording a mandatory cancellation survey in the same call.

Before calling this, collect the survey from the user — do not invent the answers:
- `reason`: why they are cancelling (one of the allowed values).
- `reason_detail`: why that reason, in their own words (required free text — e.g. which provider they are moving to, what price would have worked, which feature was missing).
- `experience`: how their overall experience was (`bad`/`okay`/`good`).
- `improvement_feedback`: what we could have done better (required free text).

The subscription keeps working until the period ends; the team is not billed again.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `experience` (`string`, required): Overall experience with the product while subscribed. One of: `bad`, `okay`, `good`.
- `improvement_feedback` (`string`, required): What we could have done better. Mandatory free text.
- `reason` (`string`, required): Primary reason for cancelling the subscription. One of: `no_longer_needed`, `different_provider`, `unmet_expectations`, `too_expensive`, `missing_features`, `technical_issues`, `other`.
- `reason_detail` (`string`, required): Why that reason, in the customer's own words: the provider they are switching to, the price that would have worked, the feature they missed, what changed so they no longer need it. Mandatory free text.
- `subscription_id` (`string`, required): The Stripe Subscription ID
- `auto_recharge_offer` (`string`, optional): Whether the customer accepted or declined the auto-recharge offer shown before the survey. Omit when the offer was not shown (no recent API usage). One of: `accepted`, `declined`.

Example input: `{"experience":"bad","improvement_feedback":"<improvement_feedback>","reason":"no_longer_needed","reason_detail":"<reason_detail>","subscription_id":"<subscription_id>"}`

### `theirstackmcp_create_webhook`

Create webhook · Destructive

Create a webhook on a saved search: each new record the search matches is sent as an HTTP POST to the URL you give, and every record sent consumes credits. Use it when the user wants new matches delivered to their own system. Check the URL first with a test event, and size the daily event limit from the saved search's estimated volume.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `search_id` (`integer`, required): ID of the search that the webhook is listening to.
- `url` (`string`, required): URL of the webhook
- `active_event_types` (`array`, optional): Event types this webhook subscribes to. If None, defaults to the search type's primary event (job_new for jobs, company_new for companies).
- `description` (`string`, optional): Description of the webhook
- `listening_start_time` (`string`, optional): Date when the webhook started listening for events. If listening_start_time is None, the webhook will listen to all events matching the search query regardless of when they occurred.
- `max_events_per_day` (`integer`, optional): Most new records the webhook takes on per UTC day, or null for no cap. A job webhook counts jobs: each can send its job.new and, when it closes, its job.closed, so a job costs at most two credits. Records over it are dropped, never sent, charged or queued for the next day. Minimum 1: to send nothing, disable the webhook.
- `secret` (`string`, optional): Secret used to sign webhook payloads with HMAC-SHA256. If set, deliveries include an X-TheirStack-Signature-256 header.
- `trigger_once_per_company` (`boolean`, optional): Only for webhook type ='job.new'. If true, Company A with 5 jobs → 1 event triggered. If false, Company A with 5 jobs → 5 events triggered. Default: `false`.

Example input: `{"search_id":1,"url":"<url>"}`

### `theirstackmcp_delete_company_list`

Delete company list · Destructive

Permanently delete a company list by ID. Only the list goes: the companies in it, and any other list that holds them, are not affected. Only the list's owner can delete it, and the 'Companies seen' list can't be deleted.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `list_id` (`integer`, required): No description.

Example input: `{"list_id":1}`

### `theirstackmcp_remove_companies_from_list`

Remove companies from list · Destructive

Remove companies from one of the team's company lists by their company IDs. Only their place in this list goes: the companies, and any other list that holds them, are not affected.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `list_id` (`integer`, required): No description.
- `company_ids` (`array`, optional): Company IDs to remove, the `id` of each company in a company search result

Example input: `{"list_id":1}`

### `theirstackmcp_rename_company_list`

Rename company list · Destructive

Give one of the team's company lists a new name. The 'Companies seen' list can't be renamed.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `list_id` (`integer`, required): No description.
- `new_name` (`string`, required): New name of the company list

Example input: `{"list_id":1,"new_name":"<new_name>"}`

### `theirstackmcp_retry_webhook_events`

Retry webhook events · Destructive

Send failed webhook events again, by their event IDs, to recover from a temporary failure such as a timeout or a server error at the receiving URL. Find the IDs by listing a webhook's events with status FAILED.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `webhook_event_ids` (`array`, required): IDs of the webhook events to retry.

Example input: `{"webhook_event_ids":[]}`

### `theirstackmcp_save_brand_book`

Save the workspace brand book · Destructive

Replace the workspace brand book with a new version; the previous one
stays in the history. Send the whole brand book (read it first and edit
it): fields left out are saved empty. Each ideal customer profile's
`filters` must be accepted by company search. Saving an inherited brand
book makes it the workspace's own.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `brand_book` (`object`, required): The whole brand book. It replaces the current one, which is kept in the history.
- `source` (`string`, optional): `agent` when an AI agent wrote it (e.g. after researching the company's website), `user` when a person edited it. One of: `user`, `agent`. Default: `user`.

Example input: `{"brand_book":{}}`

### `theirstackmcp_save_crm_send_settings`

Save what sending companies to the CRM writes · Destructive

Saves what sending companies to the CRM writes, and replaces the saved settings: whether a send creates companies, updates them or both, the CRM property each field goes to, and the owner and fixed values of new companies. Read the current ones with `get_crm_send_settings`, change only what was asked and send them whole. Check the result with `preview_crm_send_settings` first. Nothing is written to the CRM until someone sends companies. Workspace owners only.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `mappings` (`array`, optional): Where each TheirStack field goes; a field left out is not sent
- `mode` (`string`, optional): Create companies the CRM does not have and fill in the ones it has, only create, or only update. One of: `create_and_update`, `create_only`, `update_only`. Default: `create_and_update`.
- `new_company_values` (`array`, optional): Fixed values for the companies TheirStack creates
- `owner` (`string`, optional): Who owns the companies TheirStack creates: whoever sends them (matched by email to a CRM user) or nobody. One of: `sender`, `none`. Default: `sender`.

Example input: `{}`

### `theirstackmcp_save_crm_status_rules`

Save CRM status rules · Destructive

Saves the rules as a new version and starts a full sync that gives every company its status under them. Send every status in the order they are checked: the list replaces the current one. Keep the `key` of each existing status, so its companies and the links that filter by it follow it. Workspace owners only.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `statuses` (`array`, required): The statuses in the order they are checked: the first one whose conditions hold gives a company its status, and a company that meets none is In CRM

Example input: `{"statuses":[]}`

### `theirstackmcp_send_companies_to_crm`

Send companies to the CRM · Destructive

Sends up to 1,000 companies to the workspace's CRM. It creates the ones the CRM does not have and updates the ones it has, never a duplicate, with the fields `get_crm_send_settings` returns. Free: only companies the workspace revealed are sent, the rest are skipped. Pass the `id` of each company as company search returns it. The send is queued: read its result with `get_crm_send`.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `company_ids` (`array`, required): TheirStack company ids
- `label` (`string`, optional): Where the companies were sent from, as the history shows it

Example input: `{"company_ids":[]}`

### `theirstackmcp_test_webhook`

Test a webhook URL · Destructive

Send a test event to verify connectivity and payload handling. Either provide a webhook_id to test an existing webhook (with optional url/secret overrides), or provide url and event_type directly to test before creating a webhook.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `event_type` (`string`, optional): Type of event to simulate. Required when webhook_id is not provided. One of: `job_new`, `company_new`, `job_closed`.
- `secret` (`string`, optional): Secret used to sign webhook payloads with HMAC-SHA256. If set, deliveries include an X-TheirStack-Signature-256 header.
- `url` (`string`, optional): URL to send the test event to. Required when webhook_id is not provided.
- `webhook_id` (`integer`, optional): ID of an existing webhook to test. When provided, url and event_type are loaded from the stored webhook. Body fields (url, secret) can override stored values.

Example input: `{}`

### `theirstackmcp_update_email_preferences`

Update email preferences · Destructive

Turn the current user's optional emails on or off. Send only the preferences to change, grouped by category, as `true` (send) or `false` (don't send); the rest keep their value. Returns every preference after the change.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `alerts` (`object`, optional): No description.
- `onboarding` (`object`, optional): No description.
- `usage` (`object`, optional): No description.

Example input: `{}`

### `theirstackmcp_update_saved_search`

Update saved search · Destructive

Change a saved search's name, filters, type or email alert. Only the fields you send change. New filters also change what any webhook on this saved search delivers from then on. The saved search of a sales signal is refused; change its filters from the signal.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `search_id` (`integer`, required): The ID of the saved search
- `body` (`object`, optional): The filters, as a flat object: the `search_jobs` filter fields when `type` is 'jobs', the `search_companies` ones when it is 'companies'. Don't wrap them in another key.
- `frequency` (`string`, optional): How often the alert email is sent. One of: `daily`, `weekly`.
- `is_alert_active` (`boolean`, optional): Email new results to the creator of the saved search. Alerts only go to the creator.
- `name` (`string`, optional): Name of the saved search
- `type` (`string`, optional): Type of the saved search. One of: `companies`, `jobs`.

Example input: `{"search_id":1}`

### `theirstackmcp_update_webhook`

Update webhook · Destructive

Replace a webhook's settings: target URL, saved search, description, one event per company, and daily event limit. Send every setting you want to keep, because one left out goes back to its default (no daily limit, for example), so read the webhook first. The signing secret and the event types only change when sent. To pause or resume a webhook, change its status instead.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `search_id` (`integer`, required): ID of the search that the webhook is listening to.
- `url` (`string`, required): URL of the webhook
- `webhook_id` (`integer`, required): ID of the webhook
- `active_event_types` (`array`, optional): Event types this webhook subscribes to. If None, defaults to the search type's primary event (job_new for jobs, company_new for companies).
- `description` (`string`, optional): Description of the webhook
- `listening_start_time` (`string`, optional): Date when the webhook started listening for events. If listening_start_time is None, the webhook will listen to all events matching the search query regardless of when they occurred.
- `max_events_per_day` (`integer`, optional): Most new records the webhook takes on per UTC day, or null for no cap. A job webhook counts jobs: each can send its job.new and, when it closes, its job.closed, so a job costs at most two credits. Records over it are dropped, never sent, charged or queued for the next day. Minimum 1: to send nothing, disable the webhook.
- `secret` (`string`, optional): Secret used to sign webhook payloads with HMAC-SHA256. If set, deliveries include an X-TheirStack-Signature-256 header. Omit to keep current value; set to null to remove.
- `trigger_once_per_company` (`boolean`, optional): Only for webhook type ='job.new'. If true, Company A with 5 jobs → 1 event triggered. If false, Company A with 5 jobs → 5 events triggered. Default: `false`.

Example input: `{"search_id":1,"url":"<url>","webhook_id":1}`

### `theirstackmcp_update_webhook_status`

Pause or resume a webhook · Destructive

Pause or resume a webhook. A disabled webhook sends nothing. When you enable it again, by default it delivers every record matched while it was disabled. Pass skip_events_while_inactive=true when enabling to start the feed from that moment instead, so nothing matched while disabled is sent or charged.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `is_active` (`boolean`, required): No description.
- `webhook_id` (`integer`, required): ID of the webhook
- `skip_events_while_inactive` (`boolean`, optional): What happens to records matched while the webhook was disabled. Only read when enabling a disabled webhook (is_active=true). False (default): they are delivered and charged on the first scan after enabling. True: the feed starts from the moment the webhook is enabled, so records matched while it was disabled are never sent nor charged. Ignored when disabling. Default: `false`.

Example input: `{"is_active":true,"webhook_id":1}`

## Related

Other CRM & Sales connectors ([all 174](/agentkit/connectors/?category=crm-sales)):

- [Salesforce](/agentkit/connectors/salesforce/): Scalekit connector, OAuth, 74 tools
- [HubSpot](/agentkit/connectors/hubspot/): Scalekit connector, OAuth, 457 tools
- [Close](/agentkit/connectors/close/): Scalekit connector, OAuth, 103 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
