# Home

Go-to-market teams run on Sumble's data. The most detailed view of what companies use, who works there, and when they're ready to buy.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Get started</strong></td><td>Create your account, explore the web app, and make your first API call.</td><td><a href="/get-started/introduction">Introduction</a></td></tr><tr><td><strong>API Reference</strong></td><td>Find, enrich, and match organizations and people programmatically.</td><td><a href="/api/api">Overview</a></td></tr><tr><td><strong>Use the MCP server</strong></td><td>Connect AI assistants directly to Sumble data with the MCP integration.</td><td><a href="/api/mcp">MCP</a></td></tr></tbody></table>

## Common tasks

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Quick start</strong></td><td>Go from signup to your first search result in minutes.</td><td><a href="/get-started/get-started-with-sumble">Get started with Sumble</a></td></tr><tr><td><strong>Track signals</strong></td><td>Get notified when target accounts show buying intent through hiring activity.</td><td><a href="/web-app/account-intelligence/intent-signals">Intent signals</a></td></tr><tr><td><strong>Find organizations</strong></td><td>Query companies by technology stack, industry, location, and more.</td><td><a href="/api/core-data/organizations">Organizations</a></td></tr><tr><td><strong>Enrich contacts</strong></td><td>Retrieve email addresses and phone numbers for people at target accounts.</td><td><a href="/api/core-data/people">People</a></td></tr><tr><td><strong>Integrations</strong></td><td>Connect Sumble to your CRM, data warehouse, notifications, and identity provider.</td><td><a href="/system-setup-and-configuration/system-setup">Overview</a></td></tr><tr><td><strong>Understand credits</strong></td><td>Learn how API credits are consumed and how to track your usage.</td><td><a href="/get-started/credits">Credits</a></td></tr></tbody></table>

## Featured articles

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Data fields</strong></td><td>See which fields Sumble pulls from your CRM or data source to match accounts and users, and which ones are required.</td><td><a href="/system-setup-and-configuration/data-fields">Data fields</a></td></tr><tr><td><strong>Webhooks</strong></td><td>Get an HTTPS POST from Sumble for each new signal and priority signal, and verify it came from us. Beta, Enterprise plan.</td><td><a href="/system-setup-and-configuration/data-destinations/webhooks">Webhooks</a></td></tr><tr><td><strong>Signals API</strong></td><td>Search signals across your accounts, such as champion moves, new hires, and technology mentions, and pull your Priority Signals feed.</td><td><a href="/api/intelligence/signals">Signals</a></td></tr></tbody></table>


# Introduction

Sumble powers go-to-market work across the entire revenue org. Our intelligence layer drives the day-to-day for Sales, RevOps, Marketing, and Customer Success.

## What is Sumble?

Sumble is a live picture of the companies you sell to. For millions of organizations, it maps the technologies they run, the projects and teams they're building, the roles they're hiring for, and the people who work there. All of it is pulled from the job descriptions companies publish, the open web, and other public signals, and updated continuously.

It's built from what companies actually do: the roles they post, the tools their engineers name, the projects they staff. So the data reflects real activity, not self-reported profiles or stale lists. That's what makes it dependable enough to score an account, clean up a CRM record, or trigger an outbound play.

## Common use cases

Teams across the revenue org rely on Sumble for a wide range of go-to-market jobs:

| Team                 | What they use Sumble for                                                                                                     |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **RevOps**           | Account scoring and prioritization, whitespace analysis, CRM enrichment and cleanup, data licensing, and TAM / market sizing |
| **Sales**            | Account research for reps and AI workflows, trigger and signal-based selling, and competitive displacement                   |
| **Marketing**        | ABM targeting, event and campaign audiences, and inbound lead enrichment                                                     |
| **Customer Success** | Churn-risk and expansion monitoring across existing accounts                                                                 |

## Let's solve it together

Every use case above ladders up to a number you're measured on: more pipeline, higher win rates, cleaner data, earlier expansion signals. The fastest way to find out what Sumble can move for your team is a conversation. Tell us the problems you're working on, and we'll show you exactly where our data fits.

<a href="https://sumble.com/book-a-demo" class="button primary">Book a call</a>


# Get started with Sumble

Go from account creation to your first organization search and API call in under 10 minutes. This guide walks you through every step.

This guide walks you through creating a Sumble account, running your first search, setting up signals for target accounts, and making your first API call. You can complete the web app steps without any technical setup. The API works on every plan.

{% stepper %}
{% step %}

### Create your account

Go to [sumble.com](https://sumble.com) and click **Create Free account**.

Sign up with your work email address. Using a work email unlocks a 30-day Pro trial automatically, no credit card required. You'll receive a magic link by email; click it to complete sign-in.

{% hint style="info" %}
If your company is already in Sumble's database, signing up with your work email also gives the MCP server contextual awareness of your own tech stack for smarter recommendations.
{% endhint %}
{% endstep %}

{% step %}

### Explore the web app

Once you're logged in, you land on the organization search view. Use the filter panel to narrow down companies by what you care about:

* **Technologies:** find companies using a specific framework, language, or tool (e.g., Snowflake, React, Kubernetes)
* **Job function:** filter by the types of roles organizations are actively hiring for
* **Firmographics:** industry, location, and company size

Click any organization card to open its profile. You'll see a technology breakdown, recent hiring activity, and (on Pro) a list of people within the company.

{% hint style="info" %}
Free plan users can see the first page of results for any search. Upgrade to Pro to access up to 10 pages.
{% endhint %}
{% endstep %}

{% step %}

### Set up signals for target accounts

Signals notify you when companies you're tracking show hiring activity that indicates a relevant project or budget is in motion.

1. Open an organization's profile.
2. Click **Follow** to add it to your signal watchlist.
3. Go to **Account > Settings** to configure how you receive signal alerts: in the app, by weekly email digest, or via Slack.

How many signals each plan gets is in [Plans & billing](/get-started/plans-and-billing#compare-plans).
{% endstep %}

{% step %}

### Generate your first API key

API access is available on all plans. To generate a key:

1. Go to **Account > API Keys** in the top-right menu.
2. Enter a name for your key (e.g., `my-first-key` or the name of the integration you're building).
3. Click **Create Key**.
4. Copy the token immediately. It's only shown once.

{% hint style="warning" %}
Your API key is shown in full only at creation time. Copy it before closing the dialog. If you lose it, delete the key and generate a new one.
{% endhint %}

For full details on securing and using your key, see the [API](/api/api) section.
{% endstep %}

{% step %}

### Make your first API call

With your API key in hand, you can query Sumble's organization search endpoint. The following example finds companies using React:

```bash
curl https://api.sumble.com/v9/organizations \
  --request POST \
  --header "Authorization: Bearer $YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'EOF'
{
  "filter": {
    "query": "technology EQ 'react'"
  },
  "select": {
    "attributes": [
      "employee_count",
      "industry",
      "headquarters_country",
      "jobs_count"
    ]
  },
  "limit": 10,
  "order_by_column": "employee_count",
  "order_by_direction": "DESC"
}
EOF
```

Set `YOUR_API_KEY` in your environment (`export YOUR_API_KEY=...`) before running, or replace `$YOUR_API_KEY` in the command with the key you generated in the previous step.

A successful response looks like this:

```json
{
  "id": "0199f400-4123-7eca-9082-be2c94676bfc",
  "credits_used": 50,
  "credits_remaining": 9850,
  "total": 48291,
  "organizations": [
    {
      "attributes": {
        "id": 1726684,
        "name": "Acme Corp",
        "slug": "acme-corp",
        "url": "acme.com",
        "sumble_url": "https://sumble.com/l/org/TH2y9mGkRr1q",
        "employee_count": 320,
        "industry": "Information",
        "headquarters_country": "US",
        "jobs_count": 42
      },
      "entities": []
    }
  ],
  "source_data_url": "https://sumble.com/l/search/Xa1b2C3d4E5f"
}
```

From here, explore the full [API](/api/api) section to find organizations by any combination of filters, enrich them with detailed data, search for people, and more.
{% endstep %}
{% endstepper %}


# Your account & team

Start a Pro trial, add teammates, change your email or delete your account.

## Start a Pro trial

Sign up with your work email and Sumble starts a 30-day Pro trial automatically, with no credit card. A personal email address, such as Gmail, gets the Free plan. What each plan includes is in [Plans & billing](/get-started/plans-and-billing).

If you signed up with a work email and your account shows the Free plan, contact <support@sumble.com> and we'll start your trial.

## Add teammates

If your company has an Enterprise account, an admin invites people from **My Team > Users** and picks their seat: **Admin**, **Premium** or **Basic**. The steps are in [Users & seats](/system-setup-and-configuration/admin-portal/users-and-seats#invite-a-teammate). If you're not an admin, ask one of your company's admins.

On Free and Pro, each person has their own account and subscription. Teammates sign up with their own work email at [sumble.com](https://sumble.com), and each Pro subscription is billed to the person who holds it. To manage a team under one company account, [talk to sales](https://sumble.com/book-a-demo).

## Change your email

You can't change the email on an account yourself. Email <support@sumble.com> from your current address with the new one, and we'll move your account over.

## Delete your account

Email <support@sumble.com> from the address on your account and ask us to delete it. We remove your account and its data. To cancel a Pro subscription without deleting your account, see [Plans & billing](/get-started/plans-and-billing#billing).


# Plans & billing

Sumble serves the whole go-to-market org, and our three plans map to how deep you want to go.

## Compare plans

|                                          | Free                                        | Pro                                         | Enterprise                                                                          |
| ---------------------------------------- | ------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------- |
| Price                                    | Free                                        | $99 per user / month                        | Custom                                                                              |
| Monthly credits                          | 500                                         | 9,900                                       | Custom                                                                              |
| Search result pages                      | First page                                  | Up to 10 pages                              | Up to 10 pages                                                                      |
| Signals                                  | Up to 8 per week, chosen from your activity | Up to 20 per day, chosen from your activity | Unlimited, with signal types, technologies, job functions and routing you configure |
| Signal alerts in Slack                   | Yes                                         | Yes                                         | Yes                                                                                 |
| API and MCP                              | Yes                                         | Yes                                         | Yes                                                                                 |
| Ask Sumble and the Slack agent           | No                                          | Yes                                         | Yes                                                                                 |
| CRM, data warehouse and webhook delivery | No                                          | No                                          | Yes                                                                                 |

How credits are spent is in [Credits](/get-started/credits). To start a trial, add teammates or change your account, see [Your account & team](/get-started/account-and-team).

## Free

For anyone who wants to interact with the data at a high-level.

You get:

* Search the live knowledge graph across millions of companies: the technologies they run, their org functions, and the roles they're hiring for.
* A monthly allotment of credits for lookups.
* Slack delivery.

[Get started free](https://sumble.com/)

***

## Pro

For individual GTM users who use Sumble daily and want to go deeper.

Everything in Free, plus:

* Project filters to find companies running the migrations and initiatives you sell into.
* People matching to tie roles and projects to the right contacts.
* Trends across technologies, job functions, and headcount.
* Full-text search and deeper result pages.
* Draft outreach built from a company's own job posts.
* A larger monthly credit allotment and more daily signals.

$99 per user / month. Sign in with a corporate email for a 30-day trial.

[Start your trial](https://sumble.com/pricing)

***

## Enterprise

With Free and Pro, you do the work in Sumble.

With Enterprise, you tell us the problems you have and we'll help you solve them — wherever you sit in the go-to-market org.

See [Enterprise services](/enterprise-services/enterprise-services) for what we build with Enterprise customers.

[Talk to sales →](https://sumble.com/book-a-demo)

***

## Billing

### Cancel a subscription

Go to [Account > Billing & Credits](https://sumble.com/account/billing) and click **Manage**, then **Cancel plan**. Your account moves to the Free plan at the end of the billing period.

### Downloading invoices

1. Go to [Account > Billing & Credits](https://sumble.com/account/billing)
2. Click **Invoices**. On the Pro plan it is under **Manage**
3. Click **PDF** next to the invoice you want. An unpaid invoice shows **Pay** instead

This covers both your Pro subscription charges and any credit packages you've purchased.


# Credits

Credits are how Sumble meters data you take out of it: exports, contact reveals, API and MCP calls, and Ask Sumble answers. Browsing the web application is free.

## How credits work

Every action that extracts data costs credits. You pay for what you get back: the rows, the columns you pick, and the emails and phones Sumble finds.

### Credit costs

| Action                | Cost                                                                                                                  |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Data exports**      | Per row and per column, plus email and phone reveals we find. See [Data exports](/web-app/data-exports#credit-costs). |
| **Contact reveal**    | 10 credits per email and 80 per phone, the first time you reveal them. Nothing is charged when none is found.         |
| **API and MCP calls** | Priced per endpoint. See [API credits](/api/api#credits).                                                             |
| **Ask Sumble**        | Varies per answer. See [Ask Sumble](#ask-sumble) below.                                                               |

### Ask Sumble

Ask Sumble, in the web app and in Slack, charges per answer rather than at a fixed rate, because no two questions take the same amount of work. Each answer costs:

* the AI work it takes to read your question, plan, and write the reply, and
* the standard credit cost of any data the agent looks up on your behalf — the same rates as the rest of this table.

A short question against data the agent has already loaded costs very little. One that searches broadly, pulls many organizations, or reveals contacts costs more, because it is doing more.

The agent shows what an answer cost next to **Done** when it finishes, so you can see the price of a question straight away. Every successful turn is also included in your usage at [Account > Billing & Credits](https://sumble.com/account/billing). If an answer ends with an error, Sumble automatically refunds the credits charged during that attempt.

If your balance runs out mid-conversation, the agent stops before beginning another AI step and tells you it needs more credits. Depending on when the balance is exhausted, the response in progress may be incomplete. You can continue after your credits reset or you purchase more.

### Monthly allocations

Each plan includes a monthly credit allowance, listed in [Plans & billing](/get-started/plans-and-billing#compare-plans). Monthly credits reset each billing cycle.

### Company credit pools

An Enterprise company can hold a shared pool of credits for its members. Each member with a seat spends their own credits first. Once those are used up, Sumble draws from the company pool, so the member can keep working without buying credits of their own.

The pool runs for the company's contract term and ends with it.

Each member has a cap on how much they can draw from the pool in a term. Every seat type has a default cap, and the company's admins can set a different cap for any member on **My Team > Users** (see [Users & seats](/system-setup-and-configuration/admin-portal/users-and-seats#company-credit-pool)). A cap of zero means the member does not draw from the pool at all.

The balance Sumble shows you includes what you can still draw from the pool. [Account > Billing & Credits](https://sumble.com/account/billing) shows how much you can still draw from the pool. Click your credit balance and look for **Company pool**.

When the pool is empty or you reach your cap, ask one of your company's admins to raise your cap or refill the pool. Credits you purchase yourself stay yours and remain available whatever the state of the pool.

### Purchasing additional credits

If you need more credits beyond your monthly allocation:

1. Open [Account > Billing & Credits](https://sumble.com/account/billing?purchase_credits=true). The link opens the purchase panel. You can also open it from **Purchase credits** on that page, from **Purchase more** in an export, or from the message you see when you run out of credits.
2. Pick a credit package and click **Purchase**.
3. Complete the purchase through Stripe
4. Credits are added to your balance immediately

Purchased credits expire 3 months after purchase. Your free monthly allocation continues alongside any purchased credits.

For packages above 25,000 credits or team-wide purchases, [contact sales](https://sumble.com/book-a-demo).

## Frequently asked questions

**Are credits tied to individual accounts?**\
Yes. Credits cannot be shared between users. The exception is a [company credit pool](#company-credit-pools) on an Enterprise plan, which members draw from once their own credits are used up. For team-wide credit management, contact sales about enterprise packages.

**Can I get a refund on credits?**\
Credits you've spent are not refunded. Two cases settle automatically: an export refunds what it charged for rows it didn't return and contacts it didn't find, and Ask Sumble refunds an answer that ends with an error.

**Do unused monthly credits roll over?**\
No. Monthly allocation credits reset each cycle. Purchased credits last 3 months from the date of purchase.

**Where can I see my credit usage?**\
Go to [Account > Billing & Credits](https://sumble.com/account/billing) to view your credit usage and remaining balance.

**Where can I download my invoices?**\
See [Downloading invoices](/get-started/plans-and-billing#downloading-invoices) in Plans & billing.

**What happens if I run out of credits?**\
You can still browse the web application. Exports, contact reveals, API and MCP calls, and Ask Sumble stop until your credits reset or you buy more.

**Do enterprise integrations use credits?**\
Data shares and CRM syncs (Snowflake, Databricks, BigQuery, blob stores, Salesforce, HubSpot) are covered by your contract, not credits. [Webhooks](/system-setup-and-configuration/data-destinations/webhooks) cost 1 credit per delivered event.


# Our data

Good go-to-market decisions need data you can trust. Sumble's comes from what companies actually do, not self-reported profiles or stale lists, and every data point connects to the others so you can filter, segment, and aggregate your way to an answer without writing SQL or learning which table to query.

It isn't pulled from a decades-old legacy database, invented by an LLM, or passed through from another vendor. It's built from organization websites, job posts, and people profiles that are always linked and referenced, then modeled so you can query it flexibly.

## Primary sources

Sumble's organization data is rooted in two primary sources: job posts and people profiles. From these we derive organization metadata, tech stack, the teams a company is building, and how all of it trends over time. They're the root of the data tree, and you'll see them throughout the app in slideovers that show the underlying job post or profile.

{% tabs %}
{% tab title="Job Posts" %}

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-7b4d725e08a41ee35818118ddb6d9b62b26a5665%2Fimage%20(49).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Person Profile" %}

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-8844847daac08bfd3ab66d323d20007a0cc9c81b%2Fimage%20(64).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

## What Sumble derives

From job posts and profiles, Sumble builds the data below. Each page defines its fields.

| Page                                                           | What it covers                                                                                                                                   |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Organizations](/our-data/organizations)                       | Employees and people counts, industry, location, parents and subsidiaries, funding, revenue, cloud and AI token spend estimates, tags and status |
| [Technologies & projects](/our-data/technologies-and-projects) | Technologies used or mentioned, tech stacks, technology categories and projects                                                                  |
| [People](/our-data/people)                                     | Profiles, job functions and levels, and person scores                                                                                            |
| [Teams](/our-data/teams)                                       | Teams, how they're extracted and how they nest                                                                                                   |
| [Signals](/our-data/signals)                                   | The changes Sumble alerts on, and their priority                                                                                                 |
| [Sumble score](/our-data/sumble-score)                         | How accounts are ranked                                                                                                                          |
| [Filter reference](/our-data/filter-reference)                 | Every project type, technology category, job function and job level                                                                              |

## Data freshness

Sumble's data stays current through automated pipelines that run throughout the day.

| Data type            | Update frequency                                                                                                                                    |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Job posts            | Multiple times daily. New postings are ingested from aggregators and careers pages throughout the day.                                              |
| People profiles      | Daily. Professional profiles are refreshed and matched to organizations.                                                                            |
| Organization data    | Daily. Firmographic data, industry classifications, parent/subsidiary relationships, and attributes are recomputed every night.                     |
| Technologies & teams | Daily. Technologies and team structures are re-extracted from job posts using ML models.                                                            |
| Trends               | Daily. Historical trends for technologies, job functions, and headcount are recomputed with each pipeline run, drawing on years of historical data. |
| Intent signals       | Daily. New signals are generated after each data pipeline run.                                                                                      |

## Coverage

Sumble tracks a broad cross-section of the global job market: millions of organizations, millions of job postings and people profiles, and thousands of tracked technologies across categories like programming languages, cloud platforms, databases, and frameworks. Team structures are extracted for covered companies.

Coverage is deepest for technology companies and companies with active hiring, since job posts are a primary data source.

## Data quality

Raw job posts and profiles are unstructured text. Sumble turns them into structured, queryable data through several processing stages:

1. **Entity extraction:** Custom NER (Named Entity Recognition) models identify technologies, teams, projects, and other entities mentioned in job descriptions.
2. **Relation classification:** A second model classifies the relationship between entities, for example whether a technology is actively used or only mentioned.
3. **Entity linking:** Extracted entities are normalized and linked to canonical records, so "k8s", "Kubernetes", and "K8S" all resolve to the same technology.
4. **Deduplication:** Job posts and organizations are deduplicated across sources to prevent double-counting.
5. **Hierarchy construction:** Teams are organized into tree structures, job functions into a standardized hierarchy, and parent/subsidiary relationships are maintained for organizations.

This pipeline runs daily, reprocessing new data and updating existing records.


# Organizations

What Sumble knows about each organization: size, industry, location, hierarchy, funding, revenue, spend estimates, tags and status.

An organization is a company, government body, school or other employer. Sumble links every job post, person profile and team to the organization behind it, so each fact on this page connects to the evidence for it.

This page defines each organization field. To get these fields, use [organization search](/web-app/search-discovery/organization-search) and [exports](/web-app/data-exports) in the web app, the [Organizations API](/api/core-data/organizations), or a [data destination](/system-setup-and-configuration/data-destinations).

## Name, domain and LinkedIn page

Each organization has a name, a primary domain (`url` in the API), and any alternate names and domains it's known by. Sumble also stores the organization's LinkedIn company page. Matching a list of your accounts to Sumble uses all of these. See [Data fields](/system-setup-and-configuration/data-fields) for what to send.

## Employees and people

Sumble shows two different counts, and they answer different questions.

* **Employees** (`employee_count`) is the headcount the organization reports on its LinkedIn company page. It's the organization's own figure.
* **People** is the number of person profiles Sumble has linked to the organization. It's usually lower than Employees, because not every employee has a public profile Sumble can match. People counts are what Sumble uses for job function breakdowns, concentration and the [Sumble score](/our-data/sumble-score), because every person in them has a known role.

To size a team or a function, use People. To size the company as a whole, use Employees.

## Industry

Industry is the organization's sector, from the North American Industry Classification System (NAICS), such as *Information*, *Manufacturing* or *Finance and Insurance*.

## Location

Headquarters location is where the organization is based. Job and people locations are where its job posts and employees are. Filters treat the two differently: `hq_location` matches headquarters and `country` matches job or employee location. Locations come from [GeoNames](https://www.geonames.org/), licensed under CC BY 4.0. To find the code for a place, use [Location find](/api/lookups/locations).

## Parents and subsidiaries

Sumble links subsidiaries to their parent organization, so a company and everything it owns form one tree. Each organization has a `parent_id` and a list of `subsidiary_ids`.

Counts come in two scopes:

* **Rollup** counts include the organization and all its subsidiaries. Most counts in the web app and the API are rollups.
* **No rollup** counts include only the organization's own records.

When you divide one count by another, take both from the same scope. For example, the share of an organization's teams that use a technology is `team_count ÷ teams_count_rollup`, or `team_count_no_rollup ÷ teams_count_no_rollup` for the organization alone. The [Organizations API](/api/core-data/organizations#subsidiary-rollup-scope) lists which fields have which scope.

## Growth and concentration

* **Growth** is the change in a count over the last year, such as job posts for a technology or people in a job function.
* **Concentration** is the share of an organization that matches: the fraction of its job posts that match a query, or the fraction of its people in a job function.

## Funding

Funding fields describe the money an organization has raised. Sumble extracts them from SEC filings and web search with an LLM, so treat them as approximate. Amounts are in whole US dollars, and a round raised in another currency may not be converted.

| Field                          | Meaning                                                                                                            |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `funding_total_raised`         | Total raised across all rounds                                                                                     |
| `funding_valuation`            | Most recent post-money valuation                                                                                   |
| `funding_last_round_raised`    | Amount raised in the latest round                                                                                  |
| `funding_last_round_type`      | Type of the latest round, such as `seed`, `series_a` or `private_equity`                                           |
| `funding_last_round_date`      | Date of the latest round                                                                                           |
| `funding_last_round_investors` | Investor names in the latest round, lead investors first. Empty when press coverage of the round named no investor |

## Revenue

Revenue is the organization's reported revenue from its filings:

* US public companies: SEC filings
* US banks: FFIEC call reports
* US nonprofits: IRS Form 990
* Companies listed in the EU, EEA and UK: ESEF annual reports
* UK companies: accounts filed with Companies House
* French companies: accounts filed with INPI
* German companies: annual accounts published in the Bundesanzeiger
* Ukrainian companies: IFRS reports in XBRL

Only companies that file one of these can have it, and only those Sumble has linked to their filings. Expanded coverage is in the works. A blank revenue field means Sumble doesn't have a figure for that organization yet, not that it has no revenue.

Brazilian CVM revenue includes attribution to CVM and is covered by ODbL 1.0. You can [download the parsed CVM revenue data](/our-data/cvm-revenue) separately, free of charge. Revenue exports include the applicable attribution and download link. Australian Taxation Office corporate tax transparency figures carry attribution under [CC BY 3.0 AU](https://creativecommons.org/licenses/by/3.0/au/) and identify the income year.

Revenue is shown in the web app's organization list and can be filtered, sorted and exported. It isn't in the API or data shares yet.

* **Revenue** is the freshest annual figure. Sumble uses the trailing 12 months when the company has reported part of a year since its last fiscal year, and otherwise the latest fiscal year. If the latest fiscal year is more than a year older than the latest quarter, it uses that quarter × 4 and labels it an estimate. Hover over a figure to see which one it is and the date it runs to.
* **Revenue (latest FY)** is the latest full fiscal year.
* **Revenue (latest quarter)** is the most recent reported quarter.
* **Revenue growth (YoY)** compares the latest quarter with the same quarter a year earlier, or the latest fiscal year with the year before when no newer quarter exists. The tooltip shows the exact current and prior figures, their periods and filing links, and the formula `(current ÷ prior − 1) × 100%`. CVM growth tooltips also include source attribution and the parsed-data download.

The Revenue column shows US dollars, such as $97.1B, the amount it sorts and filters on. A figure reported in another currency is converted at the World Bank's average exchange rate for the calendar year most of the period falls in, or the nearest year within two years when that one isn't published. Where the World Bank publishes no rate that close, some figures use an estimated rate for that year instead, and the tooltip says so. Hover over it to see the figure as reported, its currency and the year of the rate. A figure in a currency without an exchange rate within two years of that year is shown in that currency, such as TWD 12.3B, sorts last and doesn't match a revenue filter. Revenue (latest FY) and Revenue (latest quarter) are in the currency the company reports in, always with its code, such as USD 201.2B or EUR 17.8B. Hover over any revenue figure to see the period it covers and open the filing it came from. German accounts have no lasting link, so their tooltip names the filing without linking it. Exports include the reported amount, its currency, the USD amount and the rate year.

### Old and acquired figures

A figure is current while its period ended in the last 18 months for a company that reports every quarter (SEC filers and US banks), or the last 24 months for one that reports once a year. Some sources publish long after the period ends, so they get longer: 30 months for a nonprofit's Form 990, and 36 for universities (IPEDS) and US local governments (Census of Governments), whose data comes out about two years late. After that:

* **Stale**, up to 36 months old (48 for IPEDS and the Census of Governments). The figure still shows, marked "stale". Hover to see the date it runs to and which rule made it stale. Revenue filters leave stale figures out unless you turn on **Include stale figures** in the Revenue filter. The setting is saved in the link, so a shared search keeps it.
* **No report in 36 months** (48 for IPEDS and the Census of Governments). No figure shows. Hover to see the end of the last period Sumble has and open that report.

Revenue (latest FY) and Revenue (latest quarter) follow the same age rule, each from the end of its own period, and always link the filing. They keep showing for an acquired company, since each is a dated figure from one filing.

* **Acquired.** When Sumble has an announced acquisition of the company and the company hasn't reported a period ending after it, the column shows "Acquired by" and links to the buyer. The buyer's own figure includes the company from then on, so Sumble never adds the two together. The date shown is when the deal was announced, which can be months before it closed. Hover to see the company's last figure on its own. If it is still hiring under its own name and isn't known to have been folded into the buyer, the tooltip says it still operates as its own company.

A company that keeps filing after it was acquired, for example because it has listed debt, keeps its own figure and is marked as part of the buyer since the deal. Sumble doesn't yet split an acquired company's revenue out of the buyer's reports.

Sorting by revenue treats current and stale figures alike and puts companies without a figure last. Exports carry each row's status, and for an acquired company the buyer and the announcement date.

## Estimated cloud spend

Estimated cloud spend is Sumble's estimate of what an organization spends on public cloud each year, in millions of US dollars. A model trained on companies with known cloud spend predicts it from the organization's cloud, infrastructure and engineering headcount, and Sumble refits it every night. It's an estimate, not a reported figure. For the cloud providers themselves, such as Amazon, Microsoft and Alphabet, it doesn't reflect their own infrastructure.

Estimated cloud spend is in the web app's organization list, in exports and in data shares.

## Estimated AI token spend

Estimated AI token spend is Sumble's estimate of what an organization spends each year on AI model usage, such as calls to OpenAI, Anthropic or Google models, in US dollars. It's the sum of two parts, shown separately in the web app:

* **Internal use:** AI used by the organization's own staff and internal tools.
* **Serving customers:** AI built into the products the organization sells.

A model fit every night estimates it from the organization's profile. Where Sumble has a vetted figure for an organization, such as a model provider's own numbers, that figure replaces or bounds the estimate. Estimated AI token spend is in the web app's organization list (Pro and Enterprise), in exports and in data shares.

## Tags

Tags are labels that describe what kind of organization this is. They appear as **Org Tags** on organization pages. To filter on a tag, use its slug, for example `tag EQ 'is_ai_native'`.

| Group                       | Tags                                                                                                                                                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Business model              | [B2B](#b2b), [B2C](#b2c)                                                                                                                                                                                            |
| Technology and go-to-market | [AI Native](#ai-native), [Digital Native](#digital-native), [IT Services](#it-services), [Professional Services](#professional-services)                                                                            |
| Organization type           | [Government](#government), [Hospital](#hospital), [K-12 School](#k-12-school), [Nonprofit](#nonprofit), [Recruitment Agency](#recruitment-agency), [University](#university), [Freelancing](#freelancing)           |
| Ownership                   | [Public Company](#public-company), [Venture Backed](#venture-backed), [Private Equity Owned](#private-equity-owned), [Private Equity Firm](#private-equity-firm), [State-Owned Enterprise](#state-owned-enterprise) |
| Lifecycle                   | [Closed](#closed), [Acquired & Absorbed](#acquired-and-absorbed), [Spinout](#spinout)                                                                                                                               |

### B2B

Slug: `b2b`. Sells products or services mainly to other businesses, with B2B making up a significant share of revenue: enterprise solutions, corporate clients, partnerships or large contracts.

### B2C

Slug: `b2c`. Sells products or services directly to individual consumers, or has a large consumer user base. Excludes organizations that mainly serve other businesses, even if those businesses sell to consumers.

### AI Native

Slug: `is_ai_native`. AI is the core capability of the organization's first product: the product wouldn't exist without modern AI such as LLMs or diffusion models. Excludes companies that added AI features to an existing product, and AI infrastructure, consulting or hardware vendors. Includes AI research labs that build foundation models.

### Digital Native

Slug: `digital_native`. The business model and core value were built on digital technology and online platforms from the start ("born digital"), rather than a traditional business that added digital later. An IT services firm can also be Digital Native.

### IT Services

Slug: `it_services`. IT consulting is a major business line for the organization.

### Professional Services

Slug: `professional_services`. Provides specialized expert services to clients, usually by project, rather than selling a product.

### Government

Slug: `org_type_government`. A body that exercises government authority: federal, state or local agencies, ministries, the military, legislatures, courts, regulators and international governmental organizations. Excludes state-owned enterprises that sell commercially (see [State-Owned Enterprise](#state-owned-enterprise)).

### Hospital

Slug: `org_type_hospital`. Provides inpatient medical care: hospitals, hospital systems and clinical networks that run hospitals, nonprofit or for-profit. Excludes outpatient clinics, pharmaceutical companies, health insurers and healthcare IT companies.

### K-12 School

Slug: `org_type_k12_school`. A primary or secondary school serving pre-K through grade 12: public school districts, charter schools, private and religious schools, and online K-12 academies. Excludes universities, tutoring companies and edtech companies.

### Nonprofit

Slug: `org_type_nonprofit`. A non-governmental, non-commercial organization with a public, charitable, social or community mission: NGOs, charities, foundations, trade associations and advocacy groups. Excludes universities, schools, hospitals and government agencies, even when they're legally nonprofits.

### Recruitment Agency

Slug: `org_type_recruitment_agency`. Posts jobs on behalf of other companies rather than for its own staff: staffing agencies, recruitment firms, temp agencies and executive search firms. Excludes companies with in-house recruiters and HR software vendors.

### University

Slug: `org_type_university`. A degree-granting institution of higher education: universities, colleges, community colleges, polytechnics and graduate schools, including their research institutes. Excludes K-12 schools, bootcamps and non-degree training providers.

### Freelancing

Slug: `freelancing`. A freelance marketplace, such as Upwork or Fiverr, that many freelancers list as their employer. Its People count includes those freelancers, so it overstates the organization's own staff.

### Public Company

Slug: `is_public_company`. Shares are listed and actively traded on a stock exchange. Excludes companies that were public but have gone private, and companies with only publicly traded debt.

### Venture Backed

Slug: `is_venture_backed`. Privately held and has raised institutional venture capital (seed through late stage), even if corporate investors also took part. Excludes companies that raised VC but have since gone public or been acquired, and companies funded only by grants, debt or non-venture corporate investment.

### Private Equity Owned

Slug: `is_private_equity_owned`. Majority-owned or controlled by a private equity firm, including active PE buyouts and current portfolio companies. Excludes corporate subsidiaries, exited PE positions, minority PE stakes without control, and venture-backed companies.

### Private Equity Firm

Slug: `is_private_equity_firm`. The organization's own core business is private equity or buyout investing (more than a third of what it does), rather than one line at a diversified financial firm. Applies whether or not the firm itself is publicly traded.

### State-Owned Enterprise

Slug: `is_soe`. Majority-owned or controlled by a national government and run commercially: national oil companies, state-owned banks, government-owned telecoms and airlines. Excludes US municipal utilities, state agencies and other sub-national bodies, which are [Government](#government).

### Closed

Slug: `closed`. Has permanently stopped operating: shut down, dissolved or bankrupt with no successor. Excludes companies that were acquired (see [Acquired & Absorbed](#acquired-and-absorbed)) and companies that are only temporarily inactive. See [Status](#status).

### Acquired and Absorbed

Slug: `acquired_and_absorbed`. Was bought by another company and no longer operates as its own brand. Sumble links it to the acquirer as a subsidiary, so its history rolls up to the parent.

### Spinout

Slug: `spinout`. Recently split off from a parent company, such as AUMOVIO from Continental. A spinout arrives with its whole headcount at once, which would look like a hiring surge, so the [Sumble score](/our-data/sumble-score#spin-outs) ignores its growth.

## Status

Each organization's `status` is `active` or `closed`. A closed organization also carries the [Closed](#closed) tag, and `status_reason` explains the decision.

Searches leave out closed organizations by default, so a query like "companies with 100+ employees" never returns dead companies. Matching your own list still returns them, so you find out when one of your accounts has shut down. The [Organizations API](/api/core-data/organizations#closed-organizations) explains how to include them in a search.

## CRM status

If your company connects Salesforce or HubSpot, each organization also has an account status for you: `customer`, `prospect` (in your CRM but not a customer) or `not_in_crm`. See [Filter and sort by CRM data](/system-setup-and-configuration/crm/crm-columns).


# CVM revenue data

Sumble uses revenue figures from financial statements filed with Brazil's Comissão de Valores Mobiliários, CVM. The source is the [CVM DFP dataset](https://dados.cvm.gov.br/dataset/cia_aberta-doc-dfp), made available under the [Open Database License, ODbL 1.0](https://opendatacommons.org/licenses/odbl/1-0/).

[Download the parsed CVM revenue data](https://sumble.com/api/open-data/cvm-revenue). The download index lists retained snapshots. Each ZIP contains a CSV of the parsed revenue records, an attribution notice and a manifest with a checksum. Downloads are free and do not require a Sumble account or API credits.

Records identify the Brazilian filing entity by CNPJ and include the reported period, amount, currency, statement classification and filing references. Amounts include currency-scale normalization and corrections. The download includes stored non-headline records as well as headline revenue.

The parsed CVM revenue database is available under ODbL 1.0. Sumble's contractual restrictions on reuse do not apply to rights granted under that license for this database. Preserve the attribution and license notices when sharing it, and follow ODbL's share-alike requirements when applicable.

The download contains the CVM revenue data, without Sumble organization IDs, entity-to-organization matches, websites or data from other sources. Other Sumble data retains its applicable terms.


# Technologies & projects

How Sumble decides an organization uses a technology, how technologies are grouped into categories, and what a project is.

Sumble tracks thousands of technologies, from programming languages and cloud platforms to sales and HR tools. It finds them in job posts and in people's profiles, then links every mention to one canonical technology, so "k8s", "Kubernetes" and "K8S" all count as Kubernetes.

To look up a technology's slug, use [Technology find](/api/lookups/technologies). The full list of categories and the technologies in each is in the [filter reference](/our-data/filter-reference#technology-categories).

## Where technology evidence comes from

An organization can be linked to a technology in two ways:

* **Job posts.** The organization's job posts name the technology.
* **People.** The organization's employees list the technology as a skill on their profiles.

Filters match on either source by default. The Organizations API's `match_source` setting can restrict a filter to job posts, to find companies *hiring for* a technology rather than ones that merely employ people who know it. See [Organizations API](/api/core-data/organizations#input).

## Used versus mentioned

Not every mention means the company runs the technology. "Experience with tools such as X, Y and Z" names three technologies in passing. Sumble's relation classification model reads each mention in context and decides whether the technology is **used** (the team works with it) or only **mentioned**.

* Most counts, such as a technology's job post count, include every mention.
* `job_post_used_count` counts only job posts where the technology is used.
* An organization's **tech stack** lists only **confirmed-used** technologies: ones its job posts show in active use. This is what the Tech Stack Overview page and the [Organization tech stack API](/api/core-data/organizations/organization-tech-stack) return.

## Technology categories

Every technology belongs to a category, such as Cloud Data Warehouse or Customer Relationship Manager (CRM), and categories are grouped by business function, such as Data & Analytics or Sales. Within a category, technologies are ordered by how often they appear in job posts.

Filtering on a category matches any technology in it. The [Sumble score](/our-data/sumble-score#why-technology-categories-not-individual-technologies) counts each category once, so a job post naming five data warehouses doesn't count five times.

## Projects

A project is a major technology initiative an organization is staffing, such as a cloud migration or a generative AI program. Sumble detects projects from the language and hiring patterns in job posts. The project types and what each covers are in the [filter reference](/our-data/filter-reference#project-types). Projects are available as search filters and as [signals](/our-data/signals#key-technology-projects).


# People

What Sumble knows about people: profiles, job functions and levels, where they work, and the scores that rank them.

Sumble keeps professional profiles for people at the organizations it tracks. Profiles are one of Sumble's two primary sources, with job posts. See [Our data](/our-data/our-data#primary-sources).

To find people in the web app, see [People search](/web-app/people-contacts/people-search). To get them through the API, see [People API](/api/core-data/people).

## Profiles

A profile holds a person's name, current title and employer, location, LinkedIn URL, past roles with dates, the "About" summary they wrote, and the skills and technologies they list. Sumble refreshes profiles daily and links each person to the organization they work for.

The number of people linked to an organization is its **People** count. It differs from the **Employees** count the organization reports. See [Employees and people](/our-data/organizations#employees-and-people).

## Job function and level

Sumble classifies each person's role into a job function, such as Data Engineer or Account Executive, and a job level, such as Manager or VP. The full lists are in the [filter reference](/our-data/filter-reference#job-functions).

Job functions form a tree. When a title is too general to place in a specific function, Sumble assigns the broader parent instead. So the people counts of a function's children don't add up to the count for the function itself.

## Technologies

A person's technologies are the skills and tools on their profile. An organization can match a technology filter through its job posts or through its people's profiles. See [Technologies & projects](/our-data/technologies-and-projects#where-technology-evidence-comes-from).

## Managers and direct reports

Sumble infers each person's likely managers and direct reports. The [People API](/api/core-data/people#composable-response) returns these as `related_people`.

## Contact details

Email addresses and phone numbers aren't part of a profile. Sumble looks them up when you reveal them, which costs credits. See [Credits](/get-started/credits).

## Scores

Sumble ranks people and teams against your ICP, the profile of the buyers you sell to. Your company sets it up under [ICP & sales context](/system-setup-and-configuration/admin-portal/icp-and-sales-context). Four scores use it:

* **Person score** (0 to 100) measures how well a person at an organization matches your ICP, with a breakdown of what contributed. The API returns it as `person_score`.
* **Contact score** (beta) ranks people on the People tab, the People page and in exports. Admins tune it under [Contact scoring](/system-setup-and-configuration/admin-portal/contact-scoring). Where it's turned on, it can differ from the API's `person_score`.
* **Team score** (0 to 100) measures the same for a team, with a Great, Good or Possible label. See [Teams](/our-data/teams).
* **Suggested contact relevance** (1 to 10) ranks the people Sumble suggests contacting for a single signal. It scores fit for that signal, not for your ICP overall, so it's on a different scale. See [Signals API](/api/intelligence/signals).

Person and team scores need one organization in scope at a time, because they compare people within that organization.

For ranking whole accounts, see [Sumble score](/our-data/sumble-score).


# Teams

What a team is in Sumble, how teams are extracted from job posts, and how they fit into an organization's hierarchy.

A team is a group inside an organization, such as an engineering team, a product group or a business unit. Sumble finds teams in job posts and arranges each organization's teams into a tree, for example Engineering → Platform → SRE.

To explore teams in the web app, see [Teams & org structure](/web-app/account-intelligence/teams). To get them through the API, see [Teams API](/api/core-data/teams).

## How teams are extracted

Sumble's entity extraction models read team and department names from job titles and descriptions. "Senior Engineer, Infrastructure Platform", for example, maps to the Infrastructure Platform team. Variants of a name are merged, so "Infra Platform" and "Infrastructure Platform" are one team.

## What each team carries

* **Job posts:** the job posts that mention the team. A post that names a child team also counts toward its parent teams, so one post can count toward several teams.
* **Technologies:** the technologies those job posts mention.
* **Job functions and locations:** the roles and places the team hires for.
* **First and last activity:** when the team's earliest and most recent job posts appeared.
* **People:** the people Sumble matches to the team, each with a confidence score. See [People](/our-data/people).

## Related teams

Related teams are teams that often appear together in job posts or use the same technologies. They point to adjacent groups that may matter for the same deal.

## Teams and subsidiaries

A team belongs to one organization. Teams don't roll up from subsidiaries to the parent: to get a subsidiary's teams through the API, ask for that subsidiary by its own ID. The web app's team tree shows subsidiaries alongside teams, because a subsidiary often works like a team of its parent. See [Parents and subsidiaries](/our-data/organizations#parents-and-subsidiaries).

## Team score

If your company has set up an ICP, each team gets a score from 0 to 100 for how well it matches. See [Scores](/our-data/people#scores).


# Signals

The signal types Sumble detects, what each one means, and how a signal gets its priority.

A signal is a change at an organization that suggests a selling opportunity: a new technology in its job posts, a new project, a hiring surge, a key hire, or a tracked contact moving jobs. Sumble builds signals from the same job posts and people profiles as the rest of [its data](/our-data/our-data).

This page defines the signal types. To see and act on signals in the web app, see [Intent signals](/web-app/account-intelligence/intent-signals). To get them through the API, see [Signals API](/api/intelligence/signals). For delivery to Slack, your CRM or a webhook, see [Notifications](/system-setup-and-configuration/notifications).

## Signal types

### Technology adoption

An organization starts mentioning a technology in its job posts. It comes in three forms:

* **First mention by company.** The technology appears in the organization's job posts for the first time. The company is likely evaluating or adopting it.
* **First mention by team.** The technology appears in one team's job posts for the first time, even if other teams already use it. This catches a tool spreading inside a company.
* **Any mention.** Any new job post at the organization mentions the technology. Use it to keep watch on key accounts.

### Key technology projects

An organization posts jobs tied to a major technology initiative, such as a cloud migration or a generative AI project. A project usually means budget and an open evaluation. The full list of project types and what each covers is in the [filter reference](/our-data/filter-reference#project-types).

### Acceleration in job posts

Job posts for a technology or job function rise or fall by a statistically significant amount over a 12-month window. A surge in Kubernetes job posts suggests a company scaling its infrastructure. A drop in posts naming a competitor can matter as much as a spike in your own technology.

### New hires

A person with a given technology skill, or in a target job function, starts a new role at the organization. Sumble separates leadership hires (Manager and above, see [job levels](/our-data/filter-reference#job-levels)) from individual contributor hires. New leaders often bring the tools they used before.

### Growth in headcount

The number of people in a job function at the organization grows or shrinks. A signal needs both a meaningful percentage change and a meaningful absolute change, so small teams don't trigger on one hire.

### Competitor churn

Mentions of a competitor's technology fall while related migration projects appear. The company may be replacing that competitor.

### Own product churn

Mentions of your own product fall at an account. The customer may be reducing their use of it.

### Champion alerts

Your company gives Sumble a list of people from your CRM to track: champions, economic buyers, past users or anyone else you choose. Sumble alerts you when one of them changes companies. Someone who already knows your product, now at a new organization, is a warm lead.

Champion tracking is set up for Enterprise customers from the contacts in Salesforce or HubSpot. See [Salesforce](/system-setup-and-configuration/crm/salesforce-package) and [HubSpot](/system-setup-and-configuration/crm/hubspot#champion-tracking).

### Keyword tracking

Job posts mention a term that standard filters don't cover: a certification (SOC 2, HIPAA), a pain point (technical debt, scalability) or a methodology. Keywords are set up per customer.

## Priority

Every signal has a priority: high, medium or low. The priority comes from the signal configuration that produced it, so the same signal type can be high for one team and low for another. Web app filters, Slack delivery and webhooks all use it.

## Priority Signals

Priority Signals are short summaries Sumble writes of the most important signals for one person, drawn from the signals on their accounts. They appear in the web app, in Slack digests, through the [API](/api/intelligence/signals#search-priority-signals) and in [Salesforce](/system-setup-and-configuration/crm/salesforce-package#priority-signals).

## How often signals update

Signals are generated after Sumble's data refreshes, so they follow the schedule in [Data freshness](/our-data/our-data#data-freshness).


# Sumble score

The Sumble score ranks every organization in your account list so you can focus on the accounts most likely to be genuine buyers — not just the ones that look busy.

Each scored account also gets a fit label: **Great**, **Good** or **Possible**. The label comes from the account's rank among all the accounts scored for your company, so the top-ranked accounts are Great. In the API they are `sumble_score` and `sumble_fit` on the [Organizations](/api/core-data/organizations) endpoint.

{% hint style="info" %}
**Sumble Score v2** — We've updated the scoring model. Scores now reflect structured signals — size, growth, and market concentration — adjusted for company profile. Accounts that frequently mention lots of technologies but rarely buy software (such as IT services firms) now rank lower, so your highest-priority accounts are more likely to convert.
{% endhint %}

## How the score is built

Every account is scored across three dimensions. Each dimension gets a share of the 100-point budget, and within each, individual signals are weighted by importance, not by how many technologies or job functions your ICP happens to include. The shares below are the defaults; admins can change them in the [account scoring wizard](/system-setup-and-configuration/admin-portal/account-scoring).

| Dimension     | Budget share | What it measures                                                                                                                                                                                                                                                                                           |
| ------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Size          | 50%          | How much relevant headcount does this account have? By default 35% comes from people in your target job functions, 35% from people on teams using your technology categories, 20% from your individual technologies and 10% from your projects.                                                            |
| Growth        | 30%          | Is the account growing in your target job functions? By default 85% comes from how fast that headcount is expanding and 15% from recent funding: the latest round in the past two years, sized against headcount and discounted as it ages. Growth often precedes new tool adoption and budget allocation. |
| Concentration | 20%          | What share of the company is your target persona or tech team? A small company where your persona is 30% of headcount often signals a better fit than a large company where they're 3%.                                                                                                                    |

### Spin-outs

A company spun out of a parent shows up with its whole headcount at once, which would read as explosive hiring. Growth is not scored for these companies while they carry the [Spinout](/our-data/organizations#spinout) tag; their Size and Concentration signals are unaffected, and the score breakdown says when Growth has been left out for this reason.

## Why technology categories, not individual technologies

Many of the signals that feed into your score come from job post activity — including which technologies a company is actively hiring around. When Sumble evaluates those technology signals, it scores at the category level rather than by individual tool.

Job posts frequently name several technologies in passing — "experience with tools such as X, Y, and Z." Scoring each technology individually would give an account a separate bonus for every one of those mentions, inflating the score for what is really a single signal. The bonus applies once per category instead, regardless of how many technologies from that category appear in an account's job posts. This keeps scores grounded in genuine adoption signals rather than the breadth of a job description's technology list.

## Profile adjustment

After the base score is calculated, it is multiplied by a profile factor derived from the account's [organization tags](/our-data/organizations#tags), which describe what kind of company it is, such as its business model, organization type or ownership.

Org tags that indicate a strong buyer profile increase the score; tags that suggest a poor fit reduce it. An IT services firm, for example, may score high on raw size and technology mentions — but if its org tags signal it is more likely a reseller or partner than a buyer, its final score is adjusted down accordingly.

Accounts with no relevant org tags receive a multiplier of 1 — their score is unchanged.

{% hint style="info" %}
Sumble picks the org tag adjustments for your ICP. Admins can change which tags boost or penalize accounts, and by how much, in the [account scoring wizard](/system-setup-and-configuration/admin-portal/account-scoring). Once you change them, Sumble stops adjusting them for you.
{% endhint %}

## What changed from v1

|                    | v1                                                                                                                                   | v2                                                                                                                                                                                                     |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Signal weights     | Divided a fixed budget by however many technologies and job functions the domain tracked. More entities = smaller weight per entity. | Fixed budget split by dimension (size / growth / concentration), then split evenly within each dimension, with secondary entities weighted below primary ones. Entity count no longer dilutes weights. |
| Profile adjustment | Not applied                                                                                                                          | Final score multiplied by an org-tag factor. Company type is accounted for — not just what's in the job posts.                                                                                         |
| IT services firms  | Often ranked high — lots of technology mentions drove up the raw score.                                                              | Ranked more accurately — profile adjustment corrects for companies that mention many technologies but rarely buy.                                                                                      |
| Score range        | 0–100 (same formula, unbounded in edge cases)                                                                                        | 0–100, tighter distribution                                                                                                                                                                            |

## The math

Each raw signal value is normalized to a 0–1 scale, then weighted and summed. Counts use a log transform; growth rates and shares use raw values.

**Step 1 — Normalize**

```
// p99 = 99th percentile of x across all organizations
// x   = ln(1 + raw) for counts; raw for growth / shares

normalized = min( (1 − e^(−x / p99)) / (1 − e^−1) , 1 )
```

An organization at the 99th percentile scores approximately 1.0 on that signal.

**Step 2 — Weight and sum**

```
// Default budget: size 50 | growth 30 | concentration 20
// By default, signals in a dimension share its budget evenly within a tier:
//   w = 1 per key-tier signal, 0.6 per other-tier signal
// Admins can override any of these in the account scoring wizard

base_score = Σ ( normalized × effective_weight )
```

**Step 3 — Apply profile adjustment**

```
// adj_t = per-tag adjustment fraction (e.g. +0.15 or −0.20)
// Boosts apply to base first; penalties apply to the boosted subtotal

multiplier  = ∏ ( 1 + adj_t )   // over matching boost tags
boosted     = base_score × multiplier
final_score = boosted × ∏ ( 1 + adj_t )   // over matching penalty tags
```

In one line: **v1** was `score = Σ (normalized × heuristic_weight)`. **v2** is `score = Σ (normalized × budgeted_weight) × tag_multipliers`.

## Common questions

**Will my scores change?**\
In the Sumble web app, scores already use the v2 model. The relative ranking of accounts is more accurate, but individual values will differ from v1.

For CRM enrichments, the transition is controlled. Each enrichment config has a `version` field (`v1` or `v2`, defaulting to `v1`), so existing CRM integrations keep receiving v1 scores until you explicitly switch. You can run v1 and v2 side by side to compare before cutting over. If you have automations or thresholds that depend on specific score values, review them before switching your enrichment config to v2.

**Can I customize the weights?**\
Yes. Admins can change the dimension, family and per-item weights and the org tag adjustments in the [account scoring wizard](/system-setup-and-configuration/admin-portal/account-scoring). Changes apply from that night's scoring run.

**How often are scores updated?**\
Scores are recalculated daily as new job posts, people data, and CRM enrichments are processed.

**What if a score seems wrong?**\
Open the account's score drawer to see a full breakdown by dimension — you can see exactly which signals are contributing and by how much. If something looks off, contact your account team.

## Appendix: Score breakdown details

The following explains how points are attributed per tag in the score breakdown UI. This is included for transparency — it does not affect how the final score is calculated.

### How points are shown per tag

When multiple tags apply, their multipliers stack — the combined effect is larger than any single tag on its own. To show a meaningful number per tag in the score breakdown, the combined uplift is split across tags in proportion to each tag's own percentage.

For example:

* Two +15% tags multiply to 1.15 × 1.15 = +32.25% combined. Since both tags are equal, the uplift is split evenly — +16.13% each.
* A +5% and a +10% tag: 1.05 × 1.1 = +15.5% combined, split 5:10 — so +5.17% and +10.33% respectively.

The percentage shown next to a tag in the web app is that tag's own multiplier. The points shown are its share of the combined uplift.

### Boosts and penalties are applied separately

Boosts and penalties are kept in separate piles rather than pooled together. This ensures that the sign of each row in the breakdown always matches what the tag actually is — a boost always shows a positive contribution, a penalty always shows a negative one.

In practice: boosts apply to the base score first, producing a boosted subtotal. Penalties then apply to that subtotal — not to the original base. This order means penalties are calculated on a larger number, which keeps boosts from being artificially inflated by doing it the other way around.


# Filter reference

Sumble's search, signals, and API all filter along the same set of dimensions — technologies organized into categories, strategic project types, and more. The values below cover the full scope of what Sumble tracks across each dimension.

## Project types

Project types identify organizations actively running major technology initiatives, detected from job post language and hiring patterns. They are available as filters in search and as signal triggers.

| Project type                          | Slug                                    | What it signals                                                                                                                                |
| ------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Cloud Migration                       | `cloud_migration`                       | Organizations hiring for cloud migration roles — moving workloads, applications, or infrastructure from on-premise systems to cloud providers. |
| Cloud Cost Optimization               | `cloud_cost_optimization`               | Job posts mentioning FinOps, cloud spend management, and cost governance tooling.                                                              |
| Data Infrastructure Migration         | `data_infrastructure_migration`         | Hiring around data platform modernization — moving data warehouses, rebuilding pipelines, or replacing legacy analytics stacks.                |
| Design System Migration               | `design_system_migration`               | Companies rebuilding or replacing their component library or design system.                                                                    |
| Digital Transformation                | `digital_transformation`                | Broad technology modernization programs spanning multiple domains.                                                                             |
| Frontend Migration                    | `frontend_migration`                    | Moving from legacy frontend frameworks to modern alternatives such as React, Vue, Next.js, or TypeScript.                                      |
| Generative AI                         | `generative_ai`                         | Hiring for GenAI implementation: LLM integration, RAG pipelines, AI agents, and foundation model work.                                         |
| Microservices Migration               | `microservices_migration`               | Decomposing monolithic applications into microservices or service-oriented architectures.                                                      |
| Security Infrastructure Modernization | `security_infrastructure_modernization` | Upgrading or replacing security tooling — SIEM, IAM, EDR, and zero-trust networking.                                                           |

## Technology categories

Technologies are organized into categories, grouped by business function. Within each category, technologies are ordered by how frequently they appear across job posts.

### Engineering & R\&D

Infrastructure, languages, CI/CD, and developer tooling.

| Category                                    | Technologies                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cloud Vendor                                | AWS, Azure, GCP, Oracle Cloud, IBM Cloud, Heroku, Digital Ocean, Alibaba Cloud, OVH, Huawei Cloud, Linode, Rackspace, Tencent Cloud, Scaleway                                                                                                                                                                                                                                                                                                                                                                                                                 |
| CI/CD                                       | Azure DevOps, GitHub, Jenkins, GitLab, Bitbucket, GitHub Actions, GitLab CI/CD, CircleCI, Atlassian Bamboo, TeamCity, Travis CI, Concourse, Hudson, GoCD, CloudBuild, Cruise Control, CodeShip                                                                                                                                                                                                                                                                                                                                                                |
| Infrastructure as Code Tools                | Terraform, Ansible, Chef, Puppet, AWS CloudFormation, AWS Cloud Formation, Pulumi, Salt, SaltStack, Azure Resource Manager, Crossplane, Azure Automation, OpenTofu, GCP Deployment Manager, HEAT, CFEngine, Cloud Deployment Manager, XLD, Ansible AWX                                                                                                                                                                                                                                                                                                        |
| Logging, Observability & Monitoring         | Splunk, Grafana, Prometheus, ELK, Datadog, Dynatrace, SolarWinds, New Relic, OpenTelemetry, AWS CloudWatch, AppDynamics, Kibana, Azure Monitor, Zabbix, Nagios, Sentry, Azure Application Insights, K6, LogicMonitor, ThousandEyes, Fluentd, Graylog, Sumo Logic, Jaeger, CheckMK, Fluentbit, GCP Cloud Monitoring, Geneos, Honeycomb, IBM Netcool, Telegraf, Zipkin, Sensu, Perfmon, Sumo, ITRS Geneos, Filebeat, Coralogix, IBM Instana, Pingdom, Splunk APM, Logz.io, Foglight, TrueSight, ElasticStack, Papertrail, Loggly, nmon, Lightstep, Chronosphere |
| Virtualization Technologies                 | VMware, Hyper-V, VMware ESXi, VMware vSphere, Red Hat KVM, Red Hat OpenStack, Nutanix, Proxmox, Microsoft Hyper-V, Oracle VirtualBox, Xen, LXC, Nutanix AHV, Citrix Hypervisor, RHEV, Xen Server, OpenVZ                                                                                                                                                                                                                                                                                                                                                      |
| Cloud and Container Orchestration Platforms | OpenShift, AWS Lambda, AWS EC2, AWS EKS, Azure AKS, Azure Functions, AWS ECS, AWS Fargate, Azure App Services, Rancher, GCP GKE, AWS Elastic Beanstalk, GCP Cloud Functions, Azure VMs, GCP App Engine, Compute Engine, GCP Cloud Run, Azure Service Fabric, Azure Virtual Machines, VMware Tanzu, K3s, Azure Container Instances, PKS, Kops, Google Anthos, kubeadm                                                                                                                                                                                          |
| Serverless Compute                          | AWS Lambda, Azure Functions, GCP Cloud Functions, Cloudflare Workers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Version Control Systems                     | SVN, Microsoft TFS, Apache Subversion, Perforce, Mercurial, CVS, Clear Case, PVCS                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Javascript Frameworks                       | Angular, React, TypeScript, Vue.js, Flutter, React Native, Next.js, jQuery, Nuxt.js, Svelte, Vite, Backbone.js, Ember.js, ExtJS, Alpine.js, Knockout.js, Gatsby.js, Google Polymer, Lit, Remix.js, Stencil.js, HTMX, Meteor, JET, Preact, Prototype, Astro.js, LitElement, Vue 2, Sencha, SolidJS, YUI, DurandalJS, Qwik                                                                                                                                                                                                                                      |
| Code Editors and IDEs                       | Microsoft Visual Studio, Visual Studio Code, Eclipse, IntelliJ, VIM, NetBeans, Atom, WebStorm, Notepad++, Emacs, Sublime Text, Sublime, RubyMine                                                                                                                                                                                                                                                                                                                                                                                                              |
| Programming Languages and Frameworks        | Java, Python, PHP, Microsoft .NET, Bash, C, Microsoft C#, C++, Microsoft PowerShell, Node.js, Golang, MATLAB, VB.NET, COBOL, Delphi, Rust, Ruby, ASP, Fortran, Ada, IBM Assembler, PowerBuilder, ms vc++, Microsoft Visual C++, Easytrieve, PL/1, Basic, Pascal, Paradox, Deno, Microsoft Visual C#, ActiveX, C++/CLI, Visual C, Zig, J#, JScript.NET                                                                                                                                                                                                         |
| Mobile Development Technologies             | Android, iOS, Kotlin, Flutter, Swift, React Native, Objective-C, Android Studio, Dart, Xcode, Ionic, Xamarin, Apache Cordova, .NET MAUI, Capacitor, Blackberry, Ionic Framework, NativeScript, Windows Mobile                                                                                                                                                                                                                                                                                                                                                 |
| Message Queue Technologies                  | Kafka, RabbitMQ, AWS SQS, IBM MQ, AWS Kinesis, TIBCO, ActiveMQ, Pulsar, Solace, MSMQ, NSQ, Oracle AQ, LBM                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

### Data & Analytics

Data warehousing, BI, ETL, orchestration, and storage.

| Category                          | Technologies                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Cloud Data Warehouse              | Databricks, Snowflake, Microsoft Fabric, Azure Synapse, GCP BigQuery, AWS Redshift, AWS Athena, ClickHouse                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Business Intelligence             | Microsoft Power BI, Tableau, Looker, Qlik, Google Data Studio, IBM Cognos, MicroStrategy, Microsoft SSRS, AWS QuickSight, Spotfire, Domo, ThoughtSpot, Redash, Sigma Computing, OMNI, Sisense, Periscope, Mode Analytics                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ETL                               | Informatica, DBT, Azure Data Factory, Microsoft SSIS, AWS Glue, Ab Initio, Talend, Fivetran, Oracle ODI, Pentaho, IBM DataStage, Matillion, IICS, Airbyte, PowerCenter, Oracle Data Integrator, SnowPipe, Stitch, HVR, Trifacta, Attunity, Stambia, AWS Data Pipeline, Coalesce, IBM CloudPaks, Meltano, Rivery, OWB                                                                                                                                                                                                                                                                                                                                                                       |
| Data Pipeline Orchestration       | Azure Data Factory, Airflow, Microsoft Fabric, Control-M, AWS Step Functions, Autosys, Apache Oozie, Dagster, Prefect, Luigi, TWS, GCP Cloud Composer, UC4, Tidal, Databricks Workflows, Azkaban, Metaflow, Astronomer, Digdag, Flyte, IBM CloudPaks                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Big Data Processing and Analytics | Spark, Hadoop, PySpark, Hive, Flink, Spark SQL, Presto, Spark Streaming, ClickHouse, MapReduce, Apache Impala, Trino, Apache Beam, Apache Druid, Kafka Streams, Denodo, Apache Storm, Apache Flume, Dremio, Starburst, KSQL, Apache Pinot, StarRocks, Doris, Apache Kylin, Apache Samza                                                                                                                                                                                                                                                                                                                                                                                                    |
| Event Streaming                   | Kafka, RabbitMQ, IBM MQ, AWS Kinesis, Azure Event Hub, ActiveMQ, Confluent, AWS MSK, Pulsar, GCP Pub/Sub, AWS MQ, RedPanda, Redis Streams, Red Hat AMQ                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Stream Processing                 | Flink, AWS Kinesis, GCP Dataflow, Spark Streaming, Apache Beam, Kafka Streams, Apache Storm, Azure Stream Analytics, Striim, Apache Samza, IBM Streams, TIBCO StreamBase                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Data Lake                         | Azure Data Lake, Delta Lake, Parquet, Apache Iceberg, Apache Hudi                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| OLAP                              | Databricks, Snowflake, Azure Synapse, GCP BigQuery, Teradata, AWS Redshift, Cloudera, AWS Athena, ClickHouse, Oracle Exadata, Vertica, SingleStore, Greenplum, Dremio, IBM Netezza, Starburst, Oracle Autonomous Data Warehouse, Qubole                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Data Catalog                      | Collibra, Azure Purview, Alation, Databricks Unity Catalog, Atlan, AWS Glue Data Catalog, GCP Dataplex, Informatica EDC, Data.World, Talend Data Catalog, Alex Solutions, Qlik Data Catalog                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Database Technologies             | Microsoft SQL Server, PostgreSQL, MySQL, MongoDB, Redis, Azure SQL, IBM DB2, Cassandra, AWS RDS, AWS DynamoDB, Azure Cosmos DB, MariaDB, AWS Aurora, SAP Sybase, Apache HBase, Couchbase, SQL Database, SingleStore, Hazelcast, GCP CloudSQL, Aerospike, IBM Informix, CouchDB, Ignite, GCP BigTable, ScyllaDB, GCP FireStore, AWS DocumentDB, GCP Spanner, TiDB, AlloyDB, Azure Table Storage, ArangoDB, Firebase Realtime Database, Gemfire, SQL Oracle, RocksDB, Yugabyte, ehcache, Percona, Azure PostgreSQL, Oracle Datapump, InnoDB, RavenDB, SQL Managed Instance, FoundationDB, Oracle Coherence, Cloud Datastore, Riak, GridGain, SAP IQ, OrientDB, Azure Tables, MyISAM, LevelDB |
| Document Store                    | MongoDB, AWS DynamoDB, Azure Cosmos DB, Couchbase, CouchDB, MarkLogic, GCP FireStore, AWS DocumentDB, ArangoDB, RavenDB, OrientDB                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### AI & ML

Machine learning, LLMs, MLOps, and AI development tooling.

| Category                                         | Technologies                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Vibe Coding                                      | Lovable, Replit, V0, Figma Make, Bolt.new, Base44                                                                                                                                                                                                                                                                                                                |
| Coding Agents                                    | cursor, GitHub Copilot, Claude Code, Windsurf, OpenAI Codex, Amazon Q, DEVIN, Jules, Cline, KIRO, Google Antigravity, Gemini CLI, Tabnine, Aider, openCode, Roo Code, Factory.ai                                                                                                                                                                                 |
| Lexical Search                                   | Elasticsearch, AWS OpenSearch, Apache Solr, Apache Lucene, Algolia                                                                                                                                                                                                                                                                                               |
| Vector Database                                  | Pinecone, ChromaDB, Weaviate, pgvector, FAISS, Milvus, Qdrant                                                                                                                                                                                                                                                                                                    |
| Commercial Data Science                          | MATLAB, SAS, Alteryx, AWS Sagemaker, Azure ML, GCP Vertex AI, IBM SPSS, Dataiku, H2O.ai, IBM Watson, DataRobot, Hex, Seeq, Domino Data Lab, IBM CloudPaks, C3.ai, Databricks Notebooks, Altair RapidMiner, Braincube, SymphonyAI, Iguazio                                                                                                                        |
| Deep Learning Frameworks                         | PyTorch, TensorFlow, Keras, JAX, MXNet, FastAI                                                                                                                                                                                                                                                                                                                   |
| Classical ML Frameworks                          | scikit-learn, XGBoost, LightGBM, statsmodels, SparkML, CatBoost                                                                                                                                                                                                                                                                                                  |
| Distributed Training                             | Ray, DeepSpeed, Horovod, Megatron-LM                                                                                                                                                                                                                                                                                                                             |
| Inference & Serving                              | NVIDIA Triton, TensorRT, ONNX, vLLM, SGLang, TorchServe, TensorFlow Serving, KServe, Seldon, BentoML, GROQ, Together AI, Baseten, Fireworks AI                                                                                                                                                                                                                   |
| MLOps & Lifecycle                                | MLFlow, Kubeflow, DVC, Weights & Biases, TFX, Argo Workflow                                                                                                                                                                                                                                                                                                      |
| GenAI & Orchestration                            | LangChain, LlamaIndex, Semantic Kernel, Haystack                                                                                                                                                                                                                                                                                                                 |
| OSS LLMs                                         | Mistral, Meta Llama, DeepSeek, Qwen, Kimi, GPT OSS, Google Gemma, Microsoft Phi, Z.ai GLM / ChatGLM, NVIDIA Nemotron, IBM Granite, OLMo, DBRX, Liquid Foundation Models                                                                                                                                                                                          |
| Machine Learning Frameworks                      | PyTorch, scikit-learn, LangChain, TensorFlow, Keras, HuggingFace, LlamaIndex, JAX, XGBoost, Ray, MXNet, Caffe, LightGBM, DeepSpeed, statsmodels, SparkML, Theano, CatBoost, CNTK, Horovod, Chainer, Megatron-LM, FastAI                                                                                                                                          |
| ML Training                                      | PyTorch, TensorFlow, Keras, HuggingFace, JAX, Weights & Biases                                                                                                                                                                                                                                                                                                   |
| MLOps                                            | AWS Sagemaker, MLFlow, Azure ML, GCP Vertex AI, Kubeflow, Ray                                                                                                                                                                                                                                                                                                    |
| OSS Data Science                                 | R, scikit-learn, Pandas, NumPy, Jupyter, D3.js, Matplotlib, SciPy, Streamlit, Plotly, KNIME, Seaborn, Shiny, Chart.js, ggplot2, ggplot, Altair, Recharts, Bokeh, Apache ECharts                                                                                                                                                                                  |
| Generative Image Generation                      | Midjourney, Runway, Stable Diffusion, Adobe Firefly, DALL-E                                                                                                                                                                                                                                                                                                      |
| AI Frameworks for Language Models                | LangChain, LangGraph, LlamaIndex, Autogen, Semantic Kernel, Haystack                                                                                                                                                                                                                                                                                             |
| Natural Language Processing and Vector Databases | Elasticsearch, AWS OpenSearch, Apache Solr, Pinecone, ChromaDB, spaCy, Weaviate, pgvector, FAISS, NLTK, Milvus, Qdrant, Algolia, Coveo, OpenNLP, CoreNLP, Stanford CoreNLP, Stanford NLP                                                                                                                                                                         |
| Conversational AI Platforms                      | AWS Lex, GCP Dialogflow, IBM Watson, Rasa, Kore.AI, Microsoft Bot Framework, Cognigy, Nuance Mix, Microsoft LUIS                                                                                                                                                                                                                                                 |
| Machine Learning Algorithms                      | XGBoost, Transformer, Random Forest, LightGBM, Gradient Boosting, Neural Network, Deep Neural Networks, Convolutional Neural Networks, recurrent neural networks                                                                                                                                                                                                 |
| Machine Learning Platforms and Tools             | Databricks, Alteryx, AWS Sagemaker, MLFlow, Azure ML, HuggingFace, AWS Bedrock, GCP Vertex AI, Dataiku, Kubeflow, NVIDIA Triton, KNIME, TensorRT, ONNX, vLLM, IBM WatsonX, H2O.ai, DVC, DataRobot, Weights & Biases, Anaconda, TFX, SGLang, TorchServe, TensorFlow Serving, KServe, Seldon, Domino Data Lab, Argo Workflow, BentoML, Altair RapidMiner, comet.ml |

### Product & Design

Design tools, project management, prototyping, and design systems.

| Category                         | Technologies                                                                                                                                                                                                                                                                                                                                                                       |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Design                           | Figma, Adobe Premiere, Adobe Creative Cloud, Adobe After Effects, Adobe Illustrator, Canva, Adobe Photoshop, Adobe InDesign, Adobe XD, Sketch, CorelDraw, InVision, Axure, Framer, Balsamiq, Zeplin, Figjam, Principle, Protopie, Procreate, Origami, Rive, OmniGraffle, Marvel, UXPin, Wireframe.cc, Abstract, Inkscape, Google Web Designer, Flinto, Proto.io, Affinity Designer |
| Project Management Tools         | Jira, Microsoft Project, Smartsheet, Monday.com, Asana, Adobe Workfront, Trello, Notion, Airtable, ClickUp, Wrike, Basecamp, Linear, VersionOne, Teamwork, Microsoft Planner, GitHub Issues, Pipefy, Workamajig, Mavenlink, Pivotal Tracker, Taiga, RallyDev                                                                                                                       |
| Feature Flagging and A/B Testing | Optimizely, VWO, LaunchDarkly, AB Tasty, Statsig, Split.io, Eppo                                                                                                                                                                                                                                                                                                                   |
| Diagramming                      | Microsoft Visio, Lucidchart, Miro, SAP Signavio, ARIS, Mural, Bizagi, Draw\.io, Figjam, OmniGraffle, Gliffy, SmartDraw, Creately                                                                                                                                                                                                                                                   |
| Design System                    | Material UI, Google Material Design, Ant Design, Carbon, Fluent UI, Lightning UI, AUI, Fluent Design                                                                                                                                                                                                                                                                               |

### IT Security

IAM, SIEM, EDR, network security, vulnerability management, and compliance.

| Category                                         | Technologies                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Identity and Access Management (IAM)             | Microsoft Active Directory, Microsoft Entra ID, Okta, SailPoint, CyberArk, LDAP, Keycloak, Microsoft ADFS, ForgeRock, Saviynt, Auth0, AWS IAM, BeyondTrust, Ping Identity, PingFederate, Delinea, One Identity, SiteMinder, Centrify, GCP IAM, MIM, OIM, OneLogin, Microsoft Identity Manager, IdentityIQ, PingAccess, IdentityNow, OAM, Thycotic, Oracle Identity Manager, OpenAM, Shibboleth, Oracle Access Manager, NetIQ, CA SiteMinder, ISIM, Oracle Unified Directory, Oracle Internet Directory, CA Directory, Oracle Virtual Directory, IBM Security Identity Manager             |
| Security Information and Event Management (SIEM) | Splunk, Azure Sentinel, Splunk Enterprise Security, IBM QRadar, Google Chronicle, Rapid7, Sumo Logic, LogRhythm, Exabeam, Elastic Security, Splunk ITSI, Securonix, LogRhythm SIEM, Gurucul, Elastic Security SIEM, AlienVault OSSIM, Graylog Security                                                                                                                                                                                                                                                                                                                                    |
| Endpoint Detection and Response (EDR)            | SentinelOne, Crowdstrike, Tanium, Microsoft Defender for Endpoint, McAfee, CrowdStrike Falcon, Trend Micro, Symantec, VMware Carbon Black, Symantec Endpoint Protection, Cisco Secure Endpoint                                                                                                                                                                                                                                                                                                                                                                                            |
| Endpoint Management                              | Microsoft SCCM, Microsoft Intune, JAMF, HCL BigFix, Microsoft WSUS, VMware Workspace ONE, Tanium, Ivanti, Apple Business Manager, Kandji, JumpCloud, MobileIron, ManageEngine Endpoint Central, Altiris, LANDesk, KACE, SOTI, Mosyle, IBM MaaS360, Addigy, Xenmobile, Munki, SCCM/Intune, Apple Configurator, Shavlik, Hexnode, Blade Logic, Meraki Systems Manager, Ivanti Endpoint Manager, Apple MDM, Scalefusion, Filewave, FleetDM, SimpleMDM, Jamf School, Miradore, Google Endpoint Management, Fleetsmith                                                                         |
| Cloud Security                                   | Tenable, Microsoft Defender for Cloud, AWS CloudTrail, Azure Sentinel, CrowdStrike Falcon, Wiz, AWS Security Hub, AWS Config, Palo Alto Networks Prisma Cloud, AWS Inspector, GCP Security Command Center, Aqua Security, Check Point CloudGuard, Lacework, Orca Security, Rapid7 Insight CloudSec, Trend Micro Cloud One, Qualys Cloud Platform                                                                                                                                                                                                                                          |
| Vulnerability Management                         | Tenable Nessus, OpenVAS, Nexpose, Qualys VMDR, Rapid7 InsightVM, Rapid7 Nexpose, Greenbone, Microsoft Defender Vulnerability Management                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Network Security and Infrastructure              | Cisco, Fortinet, F5, Palo Alto Networks, Juniper, Check Point, Palo Alto Networks Firewall, Cisco ASA, Aruba, Zscaler, Fortigate, Arista, Fortinet Firewalls, Citrix ADC, Bluecoat, Brocade, Netskope, Ruckus, HPE Aruba, Cisco Umbrella, Radware, A10, Stormshield, Extreme, Palo Alto Prisma Access, Zscaler ZPA, BIG-IP, Juniper SRX, Arbor, Cisco SDA, Mellanox, CATO, SRX, Alcatel-Lucent, Cisco ACS, Juniper Firewalls, Sophos Firewall, Hirschmann, Moxa, H3C, Cisco Security, Aerohive, Allied Telesis, Stratix, Cato Networks, Netscreen, SafeNet, iBoss                         |
| Security and Vulnerability Management            | SonarQube, Tenable Nessus, Tenable, Burp Suite, Sonar, Qualys, Fortify, Nmap, Checkmarx, Veracode, Snyk, Rapid7, Black Duck, HCL AppScan, Coverity, Trivy, OWASP ZAP, Wiz, HP WebInspect, SonarCloud, Palo Alto Networks Prisma Cloud, OpenVAS, Twistlock, Nexpose, Acunetix, Sysdig, PMD, Aqua Security, JFrog Xray, Semgrep, Sonatype, Retina, Anchore, Checkstyle, Klocwork, Nexus IQ, AppDetective, FOSSA, FindBugs, Lacework, Clair, MAST, Orca Security, 42Crunch, AppSpider, Cyberwatch, CodeDx, DefectDojo, SAINT, NodeZero, Vicarius, OX Security, RidgeBot, Outpost24, AccuKnox |
| Static Application Security Testing (SAST)       | GitLab, SonarQube, Artifactory, Fortify, Checkmarx, Synopsys, Veracode, Snyk, Black Duck, Coverity, Trivy, JFrog, GitHub Advanced Security, Aqua Security, Dependabot, JFrog Xray, Semgrep, Sonatype, Klocwork, Mend, WhiteSource, Kiuwan, CodeSonar, Cycode, Contrast Security, Aikido, Wiz Code, OX Security, Endor Labs, CodeAnt, Zeropath                                                                                                                                                                                                                                             |
| Dynamic Application Security Testing (DAST)      | Tenable, Burp Suite, HCL AppScan, OWASP ZAP, HP WebInspect, Acunetix, Invicti, AppSpider, Qualys WAS, Whitehat, StackHawk, VAddy, Cenzic Hailstorm                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Governance, Risk, and Compliance (GRC)           | ACL, Archer, OneTrust, ServiceNow GRC, IDEA, RSA Archer, AuditBoard, MetricStream, TeamMate, IBM OpenPages, ProcessUnity, LogicGate                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Digital Certificate Management                   | Venafi, Thales, Entrust, DigiCert, Keyfactor                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

### Information Technology

Collaboration, productivity, ITSM, integration, and enterprise storage.

| Category                                   | Technologies                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Communication and Collaboration Tools      | Microsoft Teams, Zoom, Slack, Google Meet, Google Meet, Microsoft Skype, Microsoft Skype for Business, GoToMeeting, OBS, Adobe Connect, ON24, vMix, GoToWebinar, Cisco CUCM, FaceTime, BlueJeans, Cisco Telepresence, Zoom Meetings, Zoom Webinar, Streamyard, LINE WORKS, Cisco Meeting Server, Wirecast, Webex Teams, Microsoft Lync, MSRA, Cisco Presence, AVAYA Communications Manager |
| Office Productivity Software               | Microsoft Excel, Microsoft Word, Microsoft PowerPoint, Google Sheets, Google Slides, Keynote, Open Office, Prezi, Pages, Numbers, Quip, Libre Office                                                                                                                                                                                                                                       |
| IT Service Management Tools                | ServiceNow, Zendesk, Jira Service Desk, Remedy, BMC Remedy, Ivanti, Cherwell, BMC Helix, HPSM, HP Service Center, Peregrine Service Center                                                                                                                                                                                                                                                 |
| Integration and API Management             | MuleSoft, Boomi, TIBCO, Google Apigee, BizTalk, webMethods, IBM API Connect, Workato, AWS API Gateway, Kong, Snaplogic, WSO2, Celigo, IBM Integration Bus, HULFT, Axway, Jitterbit, IBM App Connect, SuiteTalk, IBM Sterling Integrator, Dataspider, Software AG, 3Scale, Tray.io, Asteria, Gravitee, Mashery, Tyk                                                                         |
| iPaaS                                      | Informatica, Microsoft Power Automate, MuleSoft, Boomi, Oracle Integration Cloud, Talend, TIBCO, Zapier, n8n, webMethods, Workato, Snaplogic, Make.com, Celigo, Jitterbit, IBM App Connect, Tray.io, Cleo, IFTTT                                                                                                                                                                           |
| Computerized Maintenance Management System | Maximo, eMaint, MaintainX, Maintenance Connection, Fiix, MEX, Brightly, UpKeep, Limble, Hippo                                                                                                                                                                                                                                                                                              |
| Enterprise Storage Solutions               | NetApp, IBM, Dell, Nutanix, EMC, Pure Storage, HPE, Dell EMC, vSAN, Lenovo, VxRail, Isilon, Supermicro, Nimble, Synology, Simplivity, PowerStore, PowerMax, Unisys, VNX, Datacore, VMAX, PowerScale, Scality, Cisco Hyperflex, HP 3PAR, HPE ProLiant, Alletra, HPE Nimble, Compellent, PowerVault, EqualLogic, XtremIO                                                                     |
| Data Backup and Recovery Solutions         | Veeam, Commvault, ConnectWise, NetBackup, Rubrik, Cohesity, Zerto, Acronis, Automate, Autotask, Veritas, IBM TSM, Veritas NetBackup, NetApp Storage, Datto, Avamar, VMware vRealize, Kaseya, Networker, ONTAP, Backup Exec, Arcserve, DataDomain, N-Able, Site Recovery Manager, LabTech, N-Central, StorageCraft, E-Series, Storage Grid, SolidFire                                       |

### Sales

CRM, sales engagement, and GTM data and enrichment platforms.

| Category                            | Technologies                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sales and Lead Generation Tools     | Outreach, Gong, Salesloft, Clay, Clari, Instantly, Apollo.io, Lemlist, Groove, Orum, Seamless.ai, Nooks                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| GTM Enrichment and Signals          | ZoomInfo, LinkedIn Sales Navigator, 6Sense, Clay, Demandbase, Lusha, Apollo.io, Pitchbook, Cognism, Clearbit, Crunchbase, LeadIQ, Seamless.ai, Minerva, RingLead, Hunter.io, Snov.io, RocketReach, Common Room, Dropcontact, UserGems, SalesIntel, Dealfront, Warmly, CB Insights, BuiltWith, Swordfish, HG Insights, Dealroom, FullEnrich, SignalHire, ContactOut, BetterContact, Trigify, storeleads, LinkedIn Sales Insights, Prospeo, Wappalyzer, Ocean iO, Datagma, People Data Labs, Findymail, Retention.com, Zeliq, LeadMagic, SMARTe, Champify, ReverseContact, Enrow, Theirstack, IcyPeas, Openmart, Harmonic AI, Versium |
| Customer Relationship Manager (CRM) | Salesforce, Microsoft Dynamics, HubSpot, HubSpot CRM, SAP CRM, Oracle Siebel, Pipedrive, Zoho CRM, SugarCRM, Freshsales, Insightly, Attio, Monday CRM, Copper CRM                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

### Marketing

Marketing automation, CMS, advertising, analytics, and ecommerce.

| Category                                    | Technologies                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Marketing Automation Platforms              | Salesforce Marketing Cloud, Adobe Marketo, Adobe Experience Cloud, Mailchimp, Adobe Campaign, Salesforce Pardot, Klaviyo, Oracle Eloqua, Braze, Adobe Journey Optimizer, Constant Contact, RD Station, ActiveCampaign, Customer.io, Iterable, GoHighLevel, Clevertap, Brevo, MoEngage, Bloomreach, Oracle Responsys, IBM Unica, HubSpot Marketing Hub, Campaign Monitor, Aprimo, Zoho Campaigns, Emma, Selligent, Acoustic, Sendinblue, Infusionsoft, Keap, RedPoint, Oracle Marketing Cloud, Leanplum                                                                                                                                                    |
| Content Management Systems (CMS)            | WordPress, Adobe Experience Manager, Sitecore, Drupal, Optimizely, Webflow, Contentful, Wix, Joomla, Squarespace, Umbraco, HubSpot CMS, Strapi, Sanity, Kentico, Sitefinity, Storyblok, Contentstack, Episerver, GoDaddy, Duda, Weebly, osCommerce, Ektron                                                                                                                                                                                                                                                                                                                                                                                                |
| Headless CMS                                | Contentful, Strapi, Sanity, Storyblok, Ghost, Prismic, Contentful CMS, Directus, Strapi CMS, DatoCMS, Hygraph                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Ad Tech Platforms                           | Google DV360, Google Campaign Manager, Trade Desk, Google Ad Manager, Amazon DSP, DCM, CM360, Google DoubleClick, Sizmek, Xandr, Adform, Freewheel, Google Display & Video 360, Innovid, Flashtalking, MediaMath, AppNexus, DBM, Magnite, Pubmatic, OpenX                                                                                                                                                                                                                                                                                                                                                                                                 |
| Digital Advertising Platforms               | Google Ads, Facebook Ads, Meta Ads, TikTok Ads, LinkedIn Ads, Bing Ads, Meta Ads Manager, Microsoft Ads, Facebook Ads Manager, Facebook Business Manager, Twitter Ads, Google Search Ads 360, Amazon Ads, LinkedIn Campaign Manager, Meta Business Manager, Instagram Ads, Amazon Advertising, YouTube Ads, TikTok Ads Manager, Kenshoo, Marin, Google Performance Max, Google Ads Manager, Pinterest Ads, Outbrain, Facebook Advertising, Snapchat Ads, LinkedIn Advertising, FB Ads, Reddit Ads, Search Ignite, Click Equations, Apple Search, LinkedIn Ads Manager, Amazon Search, Twitter Ads Manager, DoubleClick Search, Bing Ads Editor, Quora Ads |
| Account-Based Marketing Platforms           | 6Sense, Demandbase, Terminus, Rollworks                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Web Analytics and Optimization Tools        | Google Analytics, Adobe Analytics, Optimizely, Microsoft Clarity, Amplitude, Mixpanel, Hotjar, Adobe Target, Pendo, WebTrends, Contentsquare, VWO, Google Optimize, Matomo, FullStory, Heap, PostHog, AB Tasty, Karte, Piano Analytics, Dynamic Yield, Piwik Pro, Chartbeat, Crazy Egg, Parse.ly, Monetate, Kameleoon, Coremetrics, AT Internet, Usabilla, Universal Analytics                                                                                                                                                                                                                                                                            |
| Social Media Management and Analytics Tools | Sprout Social, Meta Business Suite, Hootsuite, Sprinklr, Buffer, Brandwatch, Meltwater, Later, Cision, Talkwalker, Muck Rack, Metricool, Netbase, Social Studio, Dash Hudson, Khoros, Tagger, Twitter Analytics, Crimson Hexagon, Tweetdeck, BuzzSumo, Critical Mention, Stilingue, Sysomos, Socialbakers, Synthesio, Digimind, Spredfast                                                                                                                                                                                                                                                                                                                 |
| Customer Data Platform                      | Segment, Adobe Experience Platform, Tealium, Treasure Data, mParticle, Rudderstack, Amperity, ActionIQ, Lytics                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| SEO and Digital Marketing Tools             | Google Search Console, SEMrush, Ahrefs, Screaming Frog, Moz, SimilarWeb, Sistrix, Google Keyword Planner, BrightEdge, Conductor, Majestic, Ubersuggest, Yext, SurferSEO, Botify, DeepCrawl, SpyFu, Searchmetrics, OnCrawl, Majestic SEO, seoClarity, Ryte, Serpstat                                                                                                                                                                                                                                                                                                                                                                                       |
| eCommerce Platform                          | Shopify, Adobe Magento, WooCommerce, BigCommerce, Shopify Plus, Adobe Commerce, SAP Commerce Cloud, Prestashop, Shopware, VTEX, SAP Commerce, Commercetools, Opencart, HCL Commerce, Spryker, Fluent Commerce, HubSpot Commerce Hub                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Tag Management                              | Google Tag Manager, GTM, Adobe Launch, Tealium IQ, Ensighten, Adobe DTM                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Affiliate and Mobile Attribution Platforms  | Appsflyer, Adjust, IMPACT, Branch, AWIN, Rakuten, Kochava, Singular, ShareASale, CJ, Partnerize, Commission Junction, Affise                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

### Finance

ERP, accounting, procurement, payments, and financial planning.

| Category                                                               | Technologies                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Accounting and ERP Software                                            | NetSuite, Microsoft Dynamics 365 Business Central, Microsoft Dynamics 365 Finance, QuickBooks, Sage, Odoo, Sage Intacct, Xero, QuickBooks Online, Tally, SAP Business One, Microsoft Dynamics GP, Sage 50, Epicor, Sage 300, Acumatica, Sage 100, Zoho Books, Syspro, MYOB, QuickBooks Desktop, QBO, Tally ERP, Tally Prime, Quicken, Microsoft Dynamics SL, FreshBooks |
| ERP and Business Management Software                                   | SAP, Microsoft Dynamics 365 Business Central, Oracle, Microsoft Dynamics 365 Finance, JDE, Microsoft Dynamics GP, Workday Financials, Lawson, AFAS, Infor, QAD, Protheus, TOTVS, Baan, Infor LN, Exact, MAPICS, ProAlpha, Datasul, LN, MFG Pro, Microsoft Dynamics SL, Infor XA, Unit 4                                                                                 |
| Procurement and Expense Management                                     | SAP Concur, SAP Ariba, Coupa, SAP Fieldglass, Bill.com, Ivalua, Jaggaer, Expensify, Ramp, Basware, Esker, SAP SRM, Dext, Zycus, Zip, Navan, GEP, Tipalti, Brex, Hubdoc, Tungsten, Divvy, Taulia, GEP SMART                                                                                                                                                              |
| Payment Processing Technologies                                        | Stripe, PayPal, Adyen, Cybersource, Braintree, Authorize.net                                                                                                                                                                                                                                                                                                            |
| Point of Sale (POS)                                                    | Micros, Toast, Aloha, Simphony, Square, Clover, Revel, Shopify POS, Silverware, Brink POS, Lightspeed POS, Shift4, SpotOn, Touchbistro, Upserve, NCR Silver, Harbortouch, Lavu                                                                                                                                                                                          |
| Tax Compliance Software                                                | Vertex, Avalara, OneSource, CCH, Corptax, BNA, GoSystems, Sovos, RIA Checkpoint                                                                                                                                                                                                                                                                                         |
| Corporate Performance Management (CPM) and Financial Planning Software | OneStream, Oracle Hyperion, Anaplan, Workday Adaptive Planning, IBM Cognos, SAP SAC, Oracle Essbase, SAP BPC, HFM, IBM TM1, Oracle HFM, Oracle EPM, Tagetik, IBM Planning Analytics, LucaNet, Oracle FCCS, SAP BFC, Oracle PBCS, Board, Planful, Jedox, Oracle EPM Cloud, Pigment, Vena, CCH Tagetik, Prophix, SAP Group Reporting, Longview, SAP FC, Host Analytics    |
| Financial Technology Platforms                                         | nCino, Aladdin, Avaloq, Loan IQ, FIS, Finacle, Fiserv, Oracle Flexcube, eFront, Temenos, Charles River, ACBS, AFS, BlackRock Aladdin, Finastra, SimCorp, Bloomberg AIM, Fidessa, Mambu, BaNCS, Eagle PACE, Syndtrak, FlexTrade                                                                                                                                          |

### HR

ATS, HCM, payroll, learning management, and people analytics.

| Category                                 | Technologies                                                                                                                                                                                                                                                                                   |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Applicant Tracking Systems (ATS)         | LinkedIn Recruiter, Greenhouse, iCIMS, Indeed, Oracle Taleo, Workday Recruiting, Lever, SmartRecruiters, Ashby, Avature, Workable, Jobvite, Naukri, Bullhorn, Teamtailor, DICE, Monster, Recruitee, CareerBuilder, Breezy HR                                                                   |
| Learning Management Systems              | Canvas, Moodle, Blackboard, Cornerstone, Google Classroom, Brightspace, Docebo, D2L, SAP Litmos, Schoology, Saba, Degreed, Seesaw, SumTotal, Sakai, EdCast, AbsorbLMS                                                                                                                          |
| Core HCM Suites                          | Workday, SAP SuccessFactors, Oracle HCM, UKG, UKG Pro, ADP Workforce Now, Ceridian Dayforce, Paylocity, Paycom, BambooHR, Sage HR, Personio, Rippling, Paycor, HiBob, Gusto, Ramco, Talentsoft, Darwinbox, TriNet, Meta4, Cegedim, Justworks, Namely, Infor HCM, ADP Vantage HCM, Factorial HR |
| HRIS (SMB & Mid-Market)                  | Paylocity, Paycom, BambooHR, Personio, Rippling, Paycor, HiBob, iSolved, Namely, CharlieHR, Factorial HR                                                                                                                                                                                       |
| Payroll Platforms                        | ADP, ADP Workforce Now, Rippling, Paychex, Gusto, SAP Payroll, ADP GlobalView, QuickBooks Payroll, OnPay, Wave Payroll                                                                                                                                                                         |
| Workforce Management (Time & Scheduling) | UKG Workforce Management, Workforce Software, Horoquartz, Quinyx, Reflexis                                                                                                                                                                                                                     |
| PEO & Employer of Record                 | Deel, TriNet, Justworks                                                                                                                                                                                                                                                                        |
| People Analytics                         | Lattice, Visier, Culture Amp, Chart Hop                                                                                                                                                                                                                                                        |

### Support

Contact center, CCaaS, customer success, and user research.

| Category                            | Technologies                                                                                                                                                                                                                                                                                                                     |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Contact Center Technologies         | Salesforce Service Cloud, Genesys, Avaya, Genesys Cloud, Verint, RingCentral, AWS Connect, NICE CXone, Five9, Twilio, NICE, IEX, Mitel, Aspect, Talkdesk, Dialpad, Calabrio, NICE WFM, 8x8, NICE inContact, Vonage, Gamma, Cisco UCCE, Blue Pumpkin, Teleopti, Nexidia, CallMiner, Aspect eWFM, Cirrus, Interactive Intelligence |
| Contact Center as a Service (CCaaS) | Genesys, Genesys Cloud, AWS Connect, NICE CXone, Five9, Talkdesk, Genesys Engage, Twilio Flex, Genesys IVR, Vonage Contact Center                                                                                                                                                                                                |
| Survey and User Research Tools      | Qualtrics, SurveyMonkey, Google Forms, Medallia, Microsoft Forms, Maze, UserTesting, Dovetail, Typeform, UserZoom, Decipher, Alchemer, UserTesting.com, Optimal Workshop, dScout                                                                                                                                                 |
| Customer Success Platforms          | Gainsight, Catalyst, ChurnZero, Planhat, Totango                                                                                                                                                                                                                                                                                 |

### Legal

CLM, legal research, compliance, and e-discovery.

| Category                                | Technologies                                                                                                                                                                                                                                |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Contract Lifecycle Management           | DocuSign, Conga, Ironclad, Icertis, DocuSign CLM, Agiloft, Apttus                                                                                                                                                                           |
| Legal and Compliance Technology         | LexisNexis, Westlaw, Actimize, PACER, Fircosoft, Fenergo, RDC, World Check, CLEAR, Accurint, NetReveal, Dow Jones, Bloomberg Law, TLO, Practical Law, CourtLink, Lex Machina, Intelligize, VitalLaw                                         |
| Digital Forensics and E-Discovery Tools | Relativity, Axiom, EnCase, FTK, Nuix, Cellebrite, Trial Director, Concordance, X-Ways, IPRO, Everlaw, DISCO, CaseMap, Reveal, Brainspace, Autopsy, Clearwell, Velociraptor, XRY, Ringtail, LiveNote, Redline, Sleuthkit, BlackLight, WinHex |

## Job functions

Job functions classify the role type of a job post or person. Filtering by a parent function automatically includes all sub-functions beneath it.

### Board of Directors

Board members and non-executive directors.

| Job function               | Slug                 |
| -------------------------- | -------------------- |
| Board of Directors *(all)* | `board-of-directors` |

### Clothing & Fashion

Fashion design and apparel roles.

| Job function               | Slug                         |
| -------------------------- | ---------------------------- |
| Clothing & Fashion *(all)* | `clothing-&-fashion`         |
| Fashion & Textile Designer | `fashion-&-textile-designer` |

### Construction, Real Estate, Facilities & Maintenance

Construction management, facilities, and real estate.

| Job function                                                | Slug                                                  |
| ----------------------------------------------------------- | ----------------------------------------------------- |
| Construction, Real Estate, Facilities & Maintenance *(all)* | `construction,-real-estate,-facilities-&-maintenance` |
| Construction                                                | `construction`                                        |
| Architect                                                   | `architect`                                           |
| Architectural Designer                                      | `architectural-designer`                              |
| Civil Designer                                              | `civil-designer`                                      |
| Electrician                                                 | `electrician`                                         |
| Interior Designer                                           | `interior-designer`                                   |
| Furniture Designer                                          | `furniture-designer`                                  |
| Landscaping                                                 | `landscaping`                                         |
| Structural Designer                                         | `structural-designer`                                 |
| Urban Designer                                              | `urban-designer`                                      |
| Facilities                                                  | `facilities`                                          |
| Real Estate                                                 | `real-estate`                                         |

### Consultant

General consulting and advisory roles.

| Job function          | Slug                    |
| --------------------- | ----------------------- |
| Consultant *(all)*    | `consultant`            |
| Management Consultant | `management-consultant` |

### Education

Teaching, training, curriculum, and academic administration.

| Job function           | Slug                     |
| ---------------------- | ------------------------ |
| Education *(all)*      | `education`              |
| Adjunct Faculty        | `adjunct-faculty`        |
| Instructional Designer | `instructional-designer` |
| K-12 Teacher           | `k-12-teacher`           |
| Librarian              | `librarian`              |
| Professor              | `professor`              |
| School Administrator   | `school-administrator`   |
| School Counselor       | `school-counselor`       |
| Teaching Assistant     | `teaching-assistant`     |
| Tutor                  | `tutor`                  |

### Engineering & R\&D

Software, hardware, data, research, and scientific roles.

| Job function                          | Slug                                    |
| ------------------------------------- | --------------------------------------- |
| Engineering & R\&D *(all)*            | `engineering-&-r&d`                     |
| Data, Analytics & Machine Learning    | `data,-analytics-&-machine-learning`    |
| AI Engineer                           | `ai-engineer`                           |
| Actuary                               | `actuary`                               |
| Actuarial Associate                   | `actuarial-associate`                   |
| Bioinformatician                      | `bioinformatician`                      |
| Data Abstractor                       | `data-abstractor`                       |
| Data Analyst                          | `data-analyst`                          |
| Data Annotator                        | `data-annotator`                        |
| Data Entry                            | `data-entry`                            |
| Data Governance                       | `data-governance`                       |
| Data Scientist                        | `data-scientist`                        |
| Economist                             | `economist`                             |
| Machine Learning                      | `machine-learning`                      |
| MLOps Engineer                        | `mlops-engineer`                        |
| Statistician                          | `statistician`                          |
| Engineer                              | `engineer`                              |
| Acoustical Engineer                   | `acoustical-engineer`                   |
| Aerospace Engineer                    | `aerospace-engineer`                    |
| Agricultural Engineer                 | `agricultural-engineer`                 |
| Applied Scientist                     | `applied-scientist`                     |
| Automation Engineer                   | `automation-engineer`                   |
| Automotive Engineer                   | `automotive-engineer`                   |
| Biomedical Engineer                   | `biomedical-engineer`                   |
| Chemical Engineer                     | `chemical-engineer`                     |
| Civil Engineer                        | `civil-engineer`                        |
| Railway Engineer                      | `railway-engineer`                      |
| Structural Engineer                   | `structural-engineer`                   |
| Telecommunications Engineer           | `telecommunications-engineer`           |
| Traffic Engineer                      | `traffic-engineer`                      |
| Water Resources Engineer              | `water-resources-engineer`              |
| Combat Engineer                       | `combat-engineer`                       |
| Data Center Engineer                  | `data-center-engineer`                  |
| Developer Relations                   | `developer-relations`                   |
| Technical Writer                      | `technical-writer`                      |
| Drilling Engineer                     | `drilling-engineer`                     |
| Electrical Engineer                   | `electrical-engineer`                   |
| Control Engineer                      | `control-engineer`                      |
| Hardware Engineer                     | `hardware-engineer`                     |
| Chip Designer                         | `chip-designer`                         |
| Power Engineer                        | `power-engineer`                        |
| Embedded Engineer                     | `embedded-engineer`                     |
| Firmware Engineer                     | `firmware-engineer`                     |
| Environmental Engineer                | `environmental-engineer`                |
| Geotechnical Engineer                 | `geotechnical-engineer`                 |
| Hydrology Engineer                    | `hydrology-engineer`                    |
| Industrial Engineer                   | `industrial-engineer`                   |
| Marine Engineer                       | `marine-engineer`                       |
| Materials Engineer                    | `materials-engineer`                    |
| Mechanical Engineer                   | `mechanical-engineer`                   |
| Robotics Engineer                     | `robotics-engineer`                     |
| Metallurgical Engineer                | `metallurgical-engineer`                |
| Mining Engineer                       | `mining-engineer`                       |
| Nanotechnology Engineer               | `nanotechnology-engineer`               |
| Network Engineer                      | `network-engineer`                      |
| Nuclear Engineer                      | `nuclear-engineer`                      |
| Ocean Engineer                        | `ocean-engineer`                        |
| Optical Engineer                      | `optical-engineer`                      |
| Petroleum Engineer                    | `petroleum-engineer`                    |
| Prompt Engineer                       | `prompt-engineer`                       |
| Quality Engineer                      | `quality-engineer`                      |
| Reservoir Engineer                    | `reservoir-engineer`                    |
| Safety Engineer                       | `safety-engineer`                       |
| Security Engineer                     | `security-engineer`                     |
| Application Security Engineer         | `application-security-engineer`         |
| Cloud Security Engineer               | `cloud-security-engineer`               |
| DevSecOps Engineer                    | `devsecops-engineer`                    |
| Information Security Engineer         | `information-security-engineer`         |
| Network Security Engineer             | `network-security-engineer`             |
| Penetration Tester                    | `penetration-tester`                    |
| SIEM Engineer                         | `siem-engineer`                         |
| Security Architect                    | `security-architect`                    |
| Software Engineer                     | `software-engineer`                     |
| Analytics Engineer                    | `analytics-engineer`                    |
| Cloud Engineer                        | `cloud-engineer`                        |
| Data Architect                        | `data-architect`                        |
| Data Engineer                         | `data-engineer`                         |
| DataOps Engineer                      | `dataops-engineer`                      |
| Database Engineer                     | `database-engineer`                     |
| DevOps Engineer                       | `devops-engineer`                       |
| Engineering Productivity              | `engineering-productivity`              |
| Frontend Engineer                     | `frontend-engineer`                     |
| Infrastructure Engineer               | `infrastructure-engineer`               |
| Integration Engineer                  | `integration-engineer`                  |
| Mobile Developer                      | `mobile-developer`                      |
| Netsuite Developer                    | `netsuite-developer`                    |
| Network Operations Engineer           | `network-operations-engineer`           |
| Observability Engineer                | `observability-engineer`                |
| Performance Engineer                  | `performance-engineer`                  |
| Platform Engineer                     | `platform-engineer`                     |
| SAP Developer                         | `sap-developer`                         |
| Salesforce Developer                  | `salesforce-developer`                  |
| ServiceNow Developer                  | `servicenow-developer`                  |
| Sharepoint Developer                  | `sharepoint-developer`                  |
| Site Reliability Engineer             | `site-reliability-engineer`             |
| Software Architect                    | `software-architect`                    |
| Cloud Architect                       | `cloud-architect`                       |
| Software Development Engineer in Test | `software-development-engineer-in-test` |
| Workday Developer                     | `workday-developer`                     |
| Systems Engineer                      | `systems-engineer`                      |
| Technical Designer                    | `technical-designer`                    |
| 3D Designer                           | `3d-designer`                           |
| CAD Designer                          | `cad-designer`                          |
| Mechanical Designer                   | `mechanical-designer`                   |
| Test Engineer                         | `test-engineer`                         |
| Researcher                            | `researcher`                            |
| Research Assistant                    | `research-assistant`                    |
| Research Scientist                    | `research-scientist`                    |
| Scientist                             | `scientist`                             |
| Astronomer                            | `astronomer`                            |
| Biologist                             | `biologist`                             |
| Botanist                              | `botanist`                              |
| Ecologist                             | `ecologist`                             |
| Geneticist                            | `geneticist`                            |
| Microbiologist                        | `microbiologist`                        |
| Zoologist                             | `zoologist`                             |
| Chemist                               | `chemist`                               |
| Biochemist                            | `biochemist`                            |
| Epidemiologist                        | `epidemiologist`                        |
| Geologist                             | `geologist`                             |
| Meteorologist                         | `meteorologist`                         |
| Neuroscientist                        | `neuroscientist`                        |
| Oceanographer                         | `oceanographer`                         |
| Physicist                             | `physicist`                             |
| Toxicologist                          | `toxicologist`                          |

### Entertainment

Media production, creative, and performing arts.

| Job function          | Slug                    |
| --------------------- | ----------------------- |
| Entertainment *(all)* | `entertainment`         |
| Actor                 | `actor`                 |
| Audio Visual Designer | `audio-visual-designer` |
| Camera Operator       | `camera-operator`       |
| Character Designer    | `character-designer`    |
| Costume Designer      | `costume-designer`      |
| Exhibition Designer   | `exhibition-designer`   |
| Musician              | `musician`              |
| Narrative Designer    | `narrative-designer`    |
| Producer              | `producer`              |
| Set Designer          | `set-designer`          |
| Visual Artist         | `visual-artist`         |

### Executive

General executive leadership roles (CEO, CTO, COO, and similar).

| Job function      | Slug        |
| ----------------- | ----------- |
| Executive *(all)* | `executive` |

### Financial Markets

Capital markets, trading, and investment roles.

| Job function              | Slug                 |
| ------------------------- | -------------------- |
| Financial Markets *(all)* | `financial-markets`  |
| Investment Banking        | `investment-banking` |
| Investment Manager        | `investment-manager` |

### Frontline & Manual Labor

Operations, logistics, skilled trades, and physical work.

| Job function                     | Slug                       |
| -------------------------------- | -------------------------- |
| Frontline & Manual Labor *(all)* | `frontline-&-manual-labor` |
| Cleaner                          | `cleaner`                  |
| Driver                           | `driver`                   |
| Florist                          | `florist`                  |
| Hairdresser                      | `hairdresser`              |
| Pilot                            | `pilot`                    |
| Production Worker                | `production-worker`        |
| Retail                           | `retail`                   |
| Skilled Trades                   | `skilled-trades`           |
| Warehouse                        | `warehouse`                |

### General & Administrative

Admin, finance, legal, HR, and cross-functional support.

| Job function                       | Slug                                 |
| ---------------------------------- | ------------------------------------ |
| General & Administrative *(all)*   | `general-&-administrative`           |
| Administrator                      | `administrator`                      |
| Chief of Staff                     | `chief-of-staff`                     |
| Executive Assistant                | `executive-assistant`                |
| Office Manager                     | `office-manager`                     |
| Receptionist                       | `receptionist`                       |
| Finance                            | `finance`                            |
| Accountant                         | `accountant`                         |
| Accounts Payable & Receivable      | `accounts-payable-&-receivable`      |
| Auditor                            | `auditor`                            |
| Payroll                            | `payroll`                            |
| Claims & Underwriting              | `claims-&-underwriting`              |
| FP\&A                              | `fp&a`                               |
| FinOps                             | `finops`                             |
| Financial Analyst                  | `financial-analyst`                  |
| Financial Controller               | `financial-controller`               |
| Financial Operations               | `financial-operations`               |
| Loan Officer                       | `loan-officer`                       |
| Human Resources                    | `human-resources`                    |
| Compensation & Benefits            | `compensation-&-benefits`            |
| Human Resources Information System | `human-resources-information-system` |
| Learning & Development             | `learning-&-development`             |
| Recruiter                          | `recruiter`                          |
| Legal & Compliance                 | `legal-&-compliance`                 |
| Compliance                         | `compliance`                         |
| Lawyer                             | `lawyer`                             |
| Legal Assistant                    | `legal-assistant`                    |
| Paralegal                          | `paralegal`                          |
| Public Policy                      | `public-policy`                      |

### Government

Public sector, policy, military, and regulatory roles.

| Job function       | Slug              |
| ------------------ | ----------------- |
| Government *(all)* | `government`      |
| Civil Servant      | `civil-servant`   |
| Diplomat           | `diplomat`        |
| Law Enforcement    | `law-enforcement` |
| Military           | `military`        |

### Healthcare Services

Clinical, medical, and patient care roles.

| Job function                  | Slug                            |
| ----------------------------- | ------------------------------- |
| Healthcare Services *(all)*   | `healthcare-services`           |
| Behavior Analyst & Technician | `behavior-analyst-&-technician` |
| Caregiver                     | `caregiver`                     |
| Dental Assistant              | `dental-assistant`              |
| Dental Hygienist              | `dental-hygienist`              |
| Dentist                       | `dentist`                       |
| Immunologist                  | `immunologist`                  |
| Laboratory Services           | `laboratory-services`           |
| Medical Assistant             | `medical-assistant`             |
| Medical Coder                 | `medical-coder`                 |
| Mental Health Counselor       | `mental-health-counselor`       |
| Nurse                         | `nurse`                         |
| Nurse Practitioner            | `nurse-practitioner`            |
| Nutritionist                  | `nutritionist`                  |
| Occupational Therapist        | `occupational-therapist`        |
| Optometrist                   | `optometrist`                   |
| Paramedic                     | `paramedic`                     |
| Pharmacist                    | `pharmacist`                    |
| Pharmacy Technician           | `pharmacy-technician`           |
| Phlebotomist                  | `phlebotomist`                  |
| Physical Therapist            | `physical-therapist`            |
| Physician                     | `physician`                     |
| Physician Assistant           | `physician-assistant`           |
| Podiatrist                    | `podiatrist`                    |
| Psychologist                  | `psychologist`                  |
| Radiologic Technologist       | `radiologic-technologist`       |
| Radiologist                   | `radiologist`                   |
| Respiratory Therapist         | `respiratory-therapist`         |
| Social Worker                 | `social-worker`                 |
| Clergy                        | `clergy`                        |
| Speech Therapist              | `speech-therapist`              |
| Surgeon                       | `surgeon`                       |
| Veterinary Services           | `veterinary-services`           |

### Information Technology

IT operations, systems administration, and enterprise apps.

| Job function                   | Slug                       |
| ------------------------------ | -------------------------- |
| Information Technology *(all)* | `information-technology`   |
| Business Systems               | `business-systems`         |
| Database Administrator         | `database-administrator`   |
| Datacenter Administrator       | `datacenter-administrator` |
| IT Security                    | `it-security`              |
| Security Analyst               | `security-analyst`         |
| IT Support                     | `it-support`               |
| Network Administrator          | `network-administrator`    |
| Netsuite Administrator         | `netsuite-administrator`   |
| SAP Administrator              | `sap-administrator`        |
| Salesforce Administrator       | `salesforce-administrator` |
| ServiceNow Administrator       | `servicenow-administrator` |
| Sharepoint Administrator       | `sharepoint-administrator` |
| Workday Administrator          | `workday-administrator`    |

### Journalist

Writing, editing, and media reporting.

| Job function         | Slug                   |
| -------------------- | ---------------------- |
| Journalist *(all)*   | `journalist`           |
| Broadcast Journalist | `broadcast-journalist` |
| Editor               | `editor`               |
| Reporter             | `reporter`             |
| Writer               | `writer`               |

### Product & Design

Product management, UX, and design.

| Job function               | Slug                         |
| -------------------------- | ---------------------------- |
| Product & Design *(all)*   | `product-&-design`           |
| Designer                   | `designer`                   |
| Brand Designer             | `brand-designer`             |
| Game Designer              | `game-designer`              |
| Game Artist                | `game-artist`                |
| Industrial Designer        | `industrial-designer`        |
| Package Designer           | `package-designer`           |
| Motion Designer            | `motion-designer`            |
| Animation Designer         | `animation-designer`         |
| CGI Designer               | `cgi-designer`               |
| VFX Designer               | `vfx-designer`               |
| Video Designer             | `video-designer`             |
| User Experience Designer   | `user-experience-designer`   |
| User Experience Researcher | `user-experience-researcher` |
| Visual Designer            | `visual-designer`            |
| User Interface Designer    | `user-interface-designer`    |
| Product Manager            | `product-manager`            |

### Sales, Marketing, Customer Support & Business Development

Revenue-generating and customer-facing roles.

| Job function                                                      | Slug                                                        |
| ----------------------------------------------------------------- | ----------------------------------------------------------- |
| Sales, Marketing, Customer Support & Business Development *(all)* | `sales,-marketing,-customer-support-&-business-development` |
| Business Development                                              | `business-development`                                      |
| Customer Support, Solutions and Success                           | `customer-support,-solutions-and-success`                   |
| Customer Engineer                                                 | `customer-engineer`                                         |
| Forward Deployed Engineer                                         | `forward-deployed-engineer`                                 |
| Customer Success                                                  | `customer-success`                                          |
| Customer Support                                                  | `customer-support`                                          |
| Call Center                                                       | `call-center`                                               |
| Engagement Manager                                                | `engagement-manager`                                        |
| Solutions Architect                                               | `solutions-architect`                                       |
| Marketing                                                         | `marketing`                                                 |
| Brand Marketing                                                   | `brand-marketing`                                           |
| Communications                                                    | `communications`                                            |
| Interpreter                                                       | `interpreter`                                               |
| Content Creator                                                   | `content-creator`                                           |
| Content Marketing                                                 | `content-marketing`                                         |
| Creative Director                                                 | `creative-director`                                         |
| Customer Marketing                                                | `customer-marketing`                                        |
| Demand Generation                                                 | `demand-generation`                                         |
| Lifecycle Marketing                                               | `lifecycle-marketing`                                       |
| Digital Marketing                                                 | `digital-marketing`                                         |
| Social Media Manager                                              | `social-media-manager`                                      |
| Events                                                            | `events`                                                    |
| Field Marketing                                                   | `field-marketing`                                           |
| Growth Marketing                                                  | `growth-marketing`                                          |
| Performance Marketing                                             | `performance-marketing`                                     |
| SEO                                                               | `seo`                                                       |
| Influencer Marketing                                              | `influencer-marketing`                                      |
| Market Research                                                   | `market-research`                                           |
| Partner Marketing                                                 | `partner-marketing`                                         |
| Product Marketing                                                 | `product-marketing`                                         |
| Product Enablement                                                | `product-enablement`                                        |
| Revenue Operations                                                | `revenue-operations`                                        |
| GTM Engineer                                                      | `gtm-engineer`                                              |
| Marketing Operations                                              | `marketing-operations`                                      |
| Marketing Analyst                                                 | `marketing-analyst`                                         |
| Sales Operations                                                  | `sales-operations`                                          |
| Sales Analyst                                                     | `sales-analyst`                                             |
| Sales Enablement                                                  | `sales-enablement`                                          |
| Sales                                                             | `sales`                                                     |
| Account Executive                                                 | `account-executive`                                         |
| Enterprise Account Executive                                      | `enterprise-account-executive`                              |
| Mid-Market Account Executive                                      | `mid-market-account-executive`                              |
| SMB Account Executive                                             | `smb-account-executive`                                     |
| Account Manager                                                   | `account-manager`                                           |
| Key Account Manager                                               | `key-account-manager`                                       |
| Channel Sales                                                     | `channel-sales`                                             |
| Partner Enablement                                                | `partner-enablement`                                        |
| Inside Sales Representative                                       | `inside-sales-representative`                               |
| Outside Sales Representative                                      | `outside-sales-representative`                              |
| Sales Development Representative                                  | `sales-development-representative`                          |
| Sales Engineer                                                    | `sales-engineer`                                            |

### Sports

Athletic, coaching, and sports management roles.

| Job function      | Slug                |
| ----------------- | ------------------- |
| Sports *(all)*    | `sports`            |
| Athlete           | `athlete`           |
| Athletic Director | `athletic-director` |
| Coach             | `coach`             |
| Personal Trainer  | `personal-trainer`  |

### Strategy & Operations

Business strategy, operations, finance, and project management.

| Job function                  | Slug                            |
| ----------------------------- | ------------------------------- |
| Strategy & Operations *(all)* | `strategy-&-operations`         |
| Analyst                       | `analyst`                       |
| Pricing Analyst               | `pricing-analyst`               |
| Operations                    | `operations`                    |
| Air Traffic Controller        | `air-traffic-controller`        |
| Documentation                 | `documentation`                 |
| Environmental Health & Safety | `environmental-health-&-safety` |
| Fraud Investigator            | `fraud-investigator`            |
| Procurement & Supply Chain    | `procurement-&-supply-chain`    |
| Buyer                         | `buyer`                         |
| Inventory Manager             | `inventory-manager`             |
| Procurement                   | `procurement`                   |
| Supply Chain                  | `supply-chain`                  |
| Program Manager               | `program-manager`               |
| Quality Assurance             | `quality-assurance`             |
| Quality Analyst               | `quality-analyst`               |
| Strategy                      | `strategy`                      |
| Corporate Development         | `corporate-development`         |

### Travel & Hospitality

Tourism, hospitality, and travel industry roles.

| Job function                 | Slug                   |
| ---------------------------- | ---------------------- |
| Travel & Hospitality *(all)* | `travel-&-hospitality` |
| Hospitality                  | `hospitality`          |
| Chef                         | `chef`                 |
| Flight Attendant             | `flight-attendant`     |
| Front Desk                   | `front-desk`           |
| Restaurant Manager           | `restaurant-manager`   |
| Server                       | `server`               |
| Travel Agent                 | `travel-agent`         |

## Job levels

Job levels classify seniority. Filtering by `job_level_min` returns that level and above; `job_level_max` caps the range. Use the name exactly as shown — levels are not slug-formatted.

| Level                  | What it covers                                                              |
| ---------------------- | --------------------------------------------------------------------------- |
| Board Member           | Chairperson, board member, non-executive director.                          |
| CXO                    | Chief executive-level officers: CEO, CTO, CFO, COO, CMO, CISO, and similar. |
| SVP                    | Senior Vice President, Executive Vice President, Corporate Vice President.  |
| VP                     | Vice President.                                                             |
| Executive Director     | Executive Director (distinct from VP and Senior Director).                  |
| Senior Director        | Senior Director, Sr. Director.                                              |
| Director               | Director.                                                                   |
| General Manager        | General Manager.                                                            |
| Head                   | Head of a function or department.                                           |
| Associate Director     | Associate Director.                                                         |
| Senior Manager         | Senior Manager, Sr. Manager.                                                |
| Manager                | Manager, Supervisor.                                                        |
| Principal              | Principal or Staff-level individual contributor.                            |
| Lead                   | Lead, Team Lead.                                                            |
| Senior                 | Senior or Sr. individual contributor.                                       |
| Individual Contributor | All other non-managerial roles.                                             |


# Overview

The Sumble API is a RESTful service for programmatic access to Sumble's organization, people, and job-post data. Use it to enrich CRM data, build lead-generation tools, and run market research queries.

## Overview

The API is organized into a few groups of endpoints:

#### [Core data](/api/core-data)

Sumble's primary entities. Each is a single composable endpoint: resolve a list you already have, or search by an advanced filter, then use `select` to choose exactly which attributes and metrics come back.

* [Organizations](/api/core-data/organizations) — resolve a list of companies or search by technology, job function, industry, and firmographic filters; compose which attributes and per-entity metrics return; retrieve recent organization signals or an organization's confirmed-used tech stack
* [People](/api/core-data/people) — resolve a list of people or search by organization and role; compose which attributes return, including contact information (email, phone) and related people (managers, direct reports)
* [Job posts](/api/core-data/jobs) — resolve a list of jobs or search by organization and filters; compose which attributes return, including full descriptions, extracted technologies, teams, and functions, and related people (hiring managers, team members)
* [Teams](/api/core-data/teams) — resolve a list of teams or search by organization and filters; compose which attributes return, including ICP fit score, related people, and the team's job posts

#### [ID & slug lookups](/api/lookups)

Turn human-readable names into the canonical slugs and identifiers the core data endpoints expect in their filters.

* [Technology find](/api/lookups/technologies) — search the catalog for technology names and slugs, resolve known names/slugs/aliases to canonical technologies, and resolve technology categories to their constituent technologies
* [Project find](/api/lookups/projects) — resolve a list of project names or slugs to canonical identifiers
* [Job function & level lookup](/api/lookups/job-title-lookup) — resolve a list of job titles to canonical job function and level identifiers

#### [Intelligence endpoints](/api/intelligence)

AI-generated intelligence on the organizations you care about.

* [Signals](/api/intelligence/signals) — search recent account signals by organization, person, technology, job function, account list or signal ID; search Priority Signals by organization, person, or job post IDs, or source signal ID.
* [Intelligence briefs](/api/intelligence/intelligence-briefs) — generate an AI account brief for an organization

#### [Lists](/api/lists)

Create, manage, and access your saved lists.

* [Organization lists](/api/lists/organization-lists) — create, manage, and access saved organization lists
* [Contact lists](/api/lists/contact-lists) — create, manage, and access saved people lists

#### [Support](/api/support)

Report data quality issues and submit general support requests programmatically.

* [Support](/api/support) — report a data quality issue (`POST /support/data-quality`) or submit a general support request (`POST /support`); both are free and reply to your account email

#### [MCP](/api/mcp)

* [MCP](/api/mcp) — connect Sumble to Claude, Cursor, ChatGPT, and other MCP clients

## Getting started

### 1. Generate your API key

Go to [sumble.com/account/api-keys](https://sumble.com/account/api-keys) and create a new key. Store it securely — it won't be shown again.

### 2. Base URL

All endpoints are served from:

```
https://api.sumble.com/v9/
```

{% hint style="info" %}
This is the only base URL for the Sumble API. If you have seen a `sumble.com/paid-api/...` path in an older example or a support thread, replace it with `https://api.sumble.com/` — that path is not a supported public endpoint.
{% endhint %}

### 3. Authenticate

Every request requires your API key as a Bearer token in the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

### 4. Make your first request

This request resolves an organization by domain and composes exactly the fields it returns — baseline attributes plus a per-technology metric:

```bash
curl https://api.sumble.com/v9/organizations \
  --request POST \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "organizations": [
      { "url": "stripe.com" }
    ],
    "select": {
      "attributes": ["name", "industry", "employee_count"],
      "entities": [
        { "type": "technology", "term": "python", "metrics": ["job_post_count"] }
      ]
    }
  }'
```

### 5. Compose your response

Most endpoints follow the same pattern: provide either a **list** of entities to resolve or a **filter** to search, then use the `select` block to request exactly the `attributes` — and, where supported, per-entity `entities` metrics — you want back. You only pay for what you request (see [Credits](#credits)). Each endpoint page documents its full set of inputs and selectable fields.

### Next steps

* Browse the [endpoint reference](#overview) for inputs, response fields, and examples
* Prefer to work through an AI client? Set up [MCP](/api/mcp)
* Review [credit costs](#credits) before running large jobs

## File downloads

Most endpoints that return rows accept a `file_name` parameter: in the request body for a `POST`, as a query parameter for a `GET`. Set it and the results go into a file instead of the response:

* The rows array in the response comes back empty, and a `file` object takes its place, with the file's name, kind, columns, row count, size and an authenticated Sumble download URL. The response's other fields, such as credit usage and match counts, stay as they are.
* The credit cost is the same as for inline results.
* Opening the download URL requires the file owner's Sumble web session.

Each endpoint's page describes what one row of its file holds. Through MCP, Ask Sumble and Slack attach the file to the reply. Other MCP clients should give the user the download URL rather than rebuild the file with code.

End the name in `.csv`, `.xlsx` or `.json`. All three hold the same results. They differ in how those results are shaped and typed:

* `.csv` is plain UTF-8 text, so every cell is text. A value starting with `=`, `+`, `-` or `@` gets a leading apostrophe, which stops a spreadsheet running it as a formula.
* `.xlsx` is an Excel workbook with a single sheet, named for what it holds. Numbers stay numeric and booleans stay boolean, so sorting and arithmetic work without retyping a column, and text that looks like a formula keeps its exact characters. Excel caps a cell at 32,767 characters and longer values are truncated.
* `.json` is an array of objects, indented and UTF-8, holding the same results the response would have returned inline. Nothing is quoted, truncated or flattened to suit a spreadsheet, so this is the format to take when the results are going into a program.

**The column names are on row 1 of an `.xlsx`**, frozen and filterable, so a library's default header row reads them: `pandas.read_excel(path)` needs no offset. The Sumble surface the file came from, who asked for it and when are in the workbook's document properties (File > Info in Excel) and its printed footer. Files made before this changed had a title row above the column names; read those with `pandas.read_excel(path, header=1)`.

**An `.xlsx` folds each Sumble link into the name it belongs to.** Where a `.csv` has a `sumble_url` column beside `name`, the workbook makes the name itself a link and drops the URL column. The same goes for a prefixed pair, such as `organization_name` with `organization_sumble_url`. Excel shows the link, but a library that reads cell values does not: `pandas.read_excel` gives you the name without the URL. Take the `.csv` or the `.json`, or the inline rows, when you need the URL as data. The `columns` list in the response metadata always describes what that file actually holds.

**A `.csv` and an `.xlsx` are flat; a `.json` is not.** A sheet has one row per result and no nested columns, so the two spreadsheet formats open an object out into prefixed columns — a job's `organization` becomes `organization_id`, `organization_name`, `organization_domain` — and write a repeated value, such as a person's experience or a job's technologies, as compact JSON text in a single cell. A `.json` keeps the structure the inline response has, so `organization` is an object and `technologies` is an array. If you are parsing those cells back out, take the `.json` instead.

Two consequences for the response metadata. `columns` on a `.json` lists the top-level keys of each object, not the sheet's column names, and `row_count` counts the top-level results — for the tech stack, that is the business functions, where the sheet has one row per evidence technology.

## Credits

API calls consume credits from your account. Costs vary by endpoint:

| Endpoint                                                                                             | Cost                                                                                                                                                                                                                                                        |
| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Organizations](/api/core-data/organizations)                                                        | Per organization: 1 base credit + 1 per paid attribute + the metrics requested per entity. Unmatched inputs are free.                                                                                                                                       |
| [Organization signals](/api/core-data/organizations/organization-signals)                            | 1 credit per signal returned. Organizations with no returned signals are free.                                                                                                                                                                              |
| [Organization tech stack](/api/core-data/organizations/organization-tech-stack)                      | 1 credit per technology returned. Organizations with no confirmed-used technologies are free.                                                                                                                                                               |
| [Signals search](/api/intelligence/signals)                                                          | 1 credit per signal returned. Searches with no returned signals are free.                                                                                                                                                                                   |
| [Priority Signals search](/api/intelligence/signals#search-priority-signals)                         | 1 credit per priority signal returned. Searches with no returned priority signals are free.                                                                                                                                                                 |
| [Intelligence briefs](/api/intelligence/intelligence-briefs)                                         | 50 credits per completed brief                                                                                                                                                                                                                              |
| [People](/api/core-data/people)                                                                      | Per person: 1 base credit + 1 per paid attribute + 1 per related person returned. Unmatched inputs are free. Contact reveals cost extra (10 credits per email, 80 per phone, first reveal only) — see the [People page](/api/core-data/people#credit-cost). |
| [Job posts](/api/core-data/jobs)                                                                     | Per job: 1 base credit + 1 per paid attribute + 1 per related person returned. Unmatched inputs are free.                                                                                                                                                   |
| [Teams](/api/core-data/teams)                                                                        | Per team: 1 base credit + 1 per paid attribute + 1 per related person + 1 per job post returned. Unmatched inputs are free.                                                                                                                                 |
| [Job function & level lookup](/api/lookups/job-title-lookup)                                         | 1 credit per 100 matched titles                                                                                                                                                                                                                             |
| [Organization lists](/api/lists/organization-lists)                                                  | 1 credit per list or organization returned                                                                                                                                                                                                                  |
| [Create / add to list](/api/lists/organization-lists)                                                | No credit cost                                                                                                                                                                                                                                              |
| [Contact lists](/api/lists/contact-lists)                                                            | 1 credit per list or person returned                                                                                                                                                                                                                        |
| [Create / add to contact list](/api/lists/contact-lists)                                             | No credit cost                                                                                                                                                                                                                                              |
| [Conversation history](/api/conversations)                                                           | No credit cost                                                                                                                                                                                                                                              |
| [Technologies find](/api/lookups/technologies)                                                       | 1 credit if results found                                                                                                                                                                                                                                   |
| [Technologies lookup](/api/lookups/technologies#look-up-technologies)                                | 1 credit per 100 matched technologies                                                                                                                                                                                                                       |
| [Technology categories lookup](/api/lookups/technologies#look-up-technology-categories)              | 1 credit per 100 matched categories                                                                                                                                                                                                                         |
| [Projects lookup](/api/lookups/projects#look-up-projects)                                            | 1 credit per 100 matched projects                                                                                                                                                                                                                           |
| [Location find](/api/lookups/locations)                                                              | 1 credit if results found                                                                                                                                                                                                                                   |
| [Priority Signal relevance and feedback](/api/intelligence/signals#update-priority-signal-relevance) | No credit cost                                                                                                                                                                                                                                              |
| [Signal configs and config health](/api/intelligence/signals#list-signal-configs)                    | No credit cost                                                                                                                                                                                                                                              |
| [Documentation search](/api/documentation)                                                           | No credit cost                                                                                                                                                                                                                                              |
| [Support](/api/support)                                                                              | No credit cost                                                                                                                                                                                                                                              |
| [Webhooks](/system-setup-and-configuration/data-destinations/webhooks)                               | 1 credit per delivered event                                                                                                                                                                                                                                |

A `technology_category` entity with `granularity: "exploded"` counts each technology in the category individually — a category with 3 technologies multiplies that entity's metric cost by 3.

See [Credits](/get-started/credits) for monthly allowances and buying more credits.

## Rate limits

API usage is subject to rate limiting to ensure service stability. Each user can do 10 requests per second (aggregated through all the endpoints), allowing occasional bursts.

Once the rate limit is reached, the API responds with response code 429.

## Timeouts

A request can run for up to 55 seconds. After that the API stops it and responds with status code 504 and this body:

```json
{
  "detail": "The request took longer than 55 seconds and was stopped. No credits were charged. Retry it, or send fewer items per request.",
  "type": "request_timeout"
}
```

A request that times out is not charged. Set your client timeout to 65 seconds or more. A client that disconnects earlier is still charged if the request completes.

If a request times out, retry it. If it keeps timing out, send fewer items per request, for example fewer organizations or fewer entities per call.

## Error responses

| Status Code | Meaning                                   |
| ----------- | ----------------------------------------- |
| 200         | Success                                   |
| 202         | Accepted, in progress — retry soon        |
| 400         | Bad request — check your request body     |
| 401         | Unauthorized — invalid or missing API key |
| 402         | Insufficient credits                      |
| 429         | Rate limited — wait and retry             |
| 500         | Server error — contact support            |
| 504         | Timed out, no credits charged. Retry      |


# OpenAPI & client generation

Sumble doesn't publish a first-party SDK. Instead, the API is fully described by an OpenAPI 3 spec, so you can generate a typed client in your language of choice.

## Spec URL

The spec is published and versioned:

```
https://api.sumble.com/openapi.json?version=v9
```

You can also browse it interactively in [Swagger UI](https://api.sumble.com/docs).

## Generate a client

[OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) is the most widely used generator and supports most languages. For example, to generate a Python client:

```bash
openapi-generator-cli generate \
  -i "https://api.sumble.com/openapi.json?version=v9" \
  -g python \
  -o ./sumble-client
```

Swap `-g python` for `typescript`, `go`, `java`, `csharp`, or any other [supported generator](https://openapi-generator.tech/docs/generators).

Whatever client you generate, authenticate by passing your API key as a Bearer token. See the [Overview](/api/api) for details.


# Documentation search

Search Sumble's product documentation without downloading or indexing it yourself. Each result includes a path, title, and short matching excerpt. Published pages also include a URL. Other pages return `null` for `url`.

Use a few words or a short question. Search is case-insensitive and accounts for common English word forms, so a query does not need to use the exact wording on the page. BM25 scores the words independently: word order and adjacency do not make an exact phrase match.

The endpoint searches pages from [docs.sumble.com](https://docs.sumble.com) and additional product guidance. Use the returned URL to cite a published page. Use `path` with `GetDocumentationPage` to read the full page through MCP.

### Credit cost

Free.


# Core data endpoints

The core data endpoints return Sumble's primary entities — organizations, people, job posts, and teams. Each is a single composable endpoint that works in two modes: resolve a list you already have (match / list mode) or search by an advanced filter (search mode). Use the `select` block to compose exactly which attributes and metrics come back.

* [Organizations](/api/core-data/organizations) — resolve or search companies; compose firmographics, technology, and per-entity metrics; retrieve recent organization signals or an organization's confirmed-used tech stack.
* [People](/api/core-data/people) — resolve or search people; compose attributes, contact info (email, phone), and related people.
* [Job posts](/api/core-data/jobs) — resolve or search job postings; compose descriptions, extracted entities, and related people.
* [Teams](/api/core-data/teams) — resolve or search teams; compose attributes, ICP fit score, related people, and job posts.


# Organizations

## Find, match, and enrich organizations

The single endpoint for working with organizations. Provide either a **list of organizations** to resolve (match mode) or an **advanced query filter** (search mode), and compose exactly which attributes and per-entity metrics you get back. This replaces the previous `find`, `enrich`, and `match` endpoints.

### Input

Provide exactly one of:

* **`organizations`**: a list of up to 1,000 organizations to resolve, each identified by any combination of Sumble `id`, `slug`, `name`, `url` (domain), and `location`. At least a name or URL is required when you don't pass an id or slug. Covers the previous `match` and `enrich` flows.
* **`filter`**: an advanced query selecting the organizations to return (firmographics, technologies, job functions, and more). Covers the previous `find` flow.

When filtering, **`match_source`** controls what evidence lets an organization match a job-side filter such as technology, job function, or location (`country`):

* **`any`** (default): an org matches if the evidence appears in **either** its job posts **or** its employees' LinkedIn profiles. For example, `technology EQ 'laravel'` matches a company that posts Laravel jobs *or* simply employs people who list Laravel as a skill. Likewise, `country EQ 'US:New York:New York City'` matches a company hiring in New York City *or* one with employees based there.
* **`job_post`**: restricts matches to **job-post evidence only**. An org that matches only through its employees is excluded, such as one whose employees list a technology that none of its job posts mention, or one with staff in a city where it has no job posts. Use this when you want companies that are actively *hiring for* a technology or *hiring in* a location, rather than merely *staffed with* people who fit. This scopes matching only; per-entity `people_count` metrics still report all people at the matched org.

### Composable response

The `select` block dictates exactly which attributes return; nothing is mandatory:

* **`attributes`**: baseline company attributes. What each one means is in [Our data: Organizations](/our-data/organizations).

  * Identity: `id`, `name`, `slug`, `url`, `sumble_url` and `linkedin_url`. These are free.
  * Firmographics: `employee_count`, `industry` and `headquarters_country`.
  * Hierarchy: `parent_id` and `subsidiary_ids`.
  * Counts: `jobs_count_rollup` / `jobs_count_no_rollup`, `teams_count_rollup` / `teams_count_no_rollup` and `people_count_rollup` / `people_count_no_rollup` (see [Subsidiary rollup scope](#subsidiary-rollup-scope)), plus the legacy `jobs_count` and `teams_count`.
  * Score: `sumble_score` and its `sumble_fit` label (`Great`, `Good` or `Possible`). See [Sumble score](/our-data/sumble-score).
  * Classification: `tags`, returned as [tag slugs](/our-data/organizations#tags), and `status` / `status_reason` (see [Closed organizations](#closed-organizations)).
  * Funding: `funding_total_raised`, `funding_valuation`, `funding_last_round_raised`, `funding_last_round_type`, `funding_last_round_date` and `funding_last_round_investors`. See [Funding](/our-data/organizations#funding).
  * CRM: `account_status` (`customer`, `prospect` or `not_in_crm`). Free, and returned only when your account has a linked CRM seat.

  Like every attribute, these are returned only when listed.
* **`entities`**: per-entity metrics for a technology, job function, project, advanced query, or technology category, request counts like `job_post_count`, `people_count`, `team_count`, growth, and concentration. Technology, job function, and project selections also expose the record-scope `job_post_count_no_rollup`, `team_count_no_rollup`, and `people_count_no_rollup` (technology and job function only for people). Each rollup metric also includes a deep link to view the underlying data in Sumble.

### Custom technology categories

Custom categories are in private preview, limited to Sumble staff and staff-impersonated sessions. These endpoints can read and filter categories, but cannot create or edit them.

Use the exact slug returned by [category lookup](/api/lookups/technologies#look-up-technology-categories), such as `custom:cloud` or an ID-based reference like `custom:id:123`. Custom categories use a separate filter field:

```json
{
  "filter": {"query": "custom_technology_category EQ 'custom:cloud'"},
  "select": {
    "attributes": ["id", "name"],
    "entities": [{
      "type": "technology_category",
      "term": "custom:cloud",
      "granularity": "aggregate",
      "metrics": ["job_post_count", "people_count", "team_count"]
    }]
  }
}
```

Do not pass a custom slug to the canonical `technology_category` filter field. `custom_technology_category` supports `EQ` and `IN`. You can combine it with canonical category filters using `AND` or `OR`.

For entity selections, keep `type: "technology_category"` and set `term` to the custom slug. Both `aggregate` and `exploded` work, including `since`. Aggregate counts cover the union of member technologies rather than adding their counts together. Exploded selections return per-technology metrics and charge for the current, deduplicated member technologies. An empty category has no exploded components or component charges.

Each call reads the current category definition. A deleted or inaccessible category returns an error before charging. For confirmed-used primary technologies, use [Organization tech stack](/api/core-data/organizations/organization-tech-stack#custom-categories).

### Subsidiary rollup scope

Entity metrics and the `*_rollup` attributes include the organization **and all of its subsidiaries**. The `*_no_rollup` variants count only the organization's own records. When you divide one count by another, take both from the same scope. See [Parents and subsidiaries](/our-data/organizations#parents-and-subsidiaries). The legacy `jobs_count` and `teams_count` attributes come from a different source; use the `*_rollup` or `*_no_rollup` attributes when computing ratios against entity metrics.

The `*_no_rollup` entity metrics are all-time only. When a selection sets `since`, they are excluded from `metrics: "all"`, and requesting one explicitly together with `since` returns HTTP `422`.

### Sorting

In filter mode, `order_by_column` sorts the results and `order_by_direction` sets the direction. Sortable columns: `industry`, `employee_count`, `first_activity_time`, `last_activity_time`, `jobs_count`, `teams_count`, `people_count`, `jobs_count_growth_6mo` and `account_score`.

Three sorts take a parameter:

* `people_concentration` and `people_count_growth_1y` sort by one job function's share of the organization's people, or that function's people growth over the last year. Name the job function in `order_by_job_function`.
* `job_post_concentration` sorts by the share of the organization's job posts that match an advanced query. Pass the query in `order_by_advanced_query`.

### File output

Set `file_name` to get the results as a file instead of inline `organizations`. The formats and the response shape are in [File downloads](/api/api#file-downloads).

A `.json` file contains one object per organization in the same structure as the inline `organizations` results. Entities and their component technologies stay nested. Its `row_count` counts organizations, and `columns` lists the objects' top-level keys.

A `.csv` or `.xlsx` file has a fixed set of columns. Requests change the number of rows, not the columns:

* An organization with no entity results gets one row. This retains attribute-only results and unmatched inputs.
* Each entity result gets one row with its counts, growth values, concentration values, and links in their own columns.
* An exploded technology category gets one row per component technology. The parent category stays in the `entity_*` columns, and the technology appears in the `component_*` columns.
* Organization attributes repeat when an organization has several entity rows. List-valued attributes such as `tags` and `subsidiary_ids` contain compact JSON text in their cells.

### Credit cost

Charged per matched organization (match mode) or per returned organization (search mode). Unmatched inputs are free.

Per organization the cost is:

* **1 base credit**, plus:
* **1 credit per paid attribute** requested (`id`, `name`, `slug`, `url`, `sumble_url`, `linkedin_url` and `account_status` are free), plus
* **per entity selection**, the number of metrics requested. `metrics: "all"` expands to every metric valid for that entity type. A `technology_category` entity with `granularity: "exploded"` multiplies by the number of technologies in the category.

For example, matching one organization and requesting 3 paid attributes plus one technology with 2 metrics costs `1 + 3 + 2 = 6` credits. The API checks affordability up front and returns HTTP `402` before doing any work you can't pay for.

## POST /v9/organizations

> Unified organizations endpoint

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"EnrichOrganizationsRequest":{"properties":{"organizations":{"anyOf":[{"items":{"$ref":"#/components/schemas/MatchOrganizationInput"},"type":"array","maxItems":1000,"minItems":1},{"type":"null"}],"title":"Organizations","description":"List of organizations to resolve and enrich. Mutually exclusive with `filter`."},"filter":{"anyOf":[{"$ref":"#/components/schemas/Query"},{"type":"null"}],"description":"Advanced query selecting the organizations to return. Mutually exclusive with `organizations`."},"include_closed":{"type":"boolean","title":"Include Closed","description":"Filter mode only: include organizations marked permanently closed (`status` = 'closed') in the results — they are excluded by default. Request the `status` / `status_reason` attributes to identify which results are closed. Not valid with `organizations` (direct lookups always resolve closed organizations).","default":false},"select":{"$ref":"#/components/schemas/Select","description":"Dictates exactly which columns are returned."},"limit":{"type":"integer","maximum":200,"minimum":1,"title":"Limit","description":"Maximum number of results to return.","default":10},"offset":{"type":"integer","maximum":10000,"minimum":0,"title":"Offset","description":"Number of results to skip.","default":0},"order_by_column":{"anyOf":[{"type":"string","enum":["industry","employee_count","employee_count_int","first_activity_time","last_activity_time","jobs_count","teams_count","people_count","jobs_count_growth_6mo","cloud_spend_estimate_millions_usd","account_score"]},{"type":"string","enum":["people_concentration","people_count_growth_1y"]},{"type":"string","const":"job_post_concentration"},{"type":"null"}],"title":"Order By Column","description":"Column to order by (filter mode only). Parameterized sorts (this endpoint only): `people_concentration` and `people_count_growth_1y` sort by the named job function's people metrics — the all-time fraction of the org's tracked people in it, and its current YoY people growth % (latest month vs. one year earlier; orgs without growth data sort last) respectively — and require `order_by_job_function`. `job_post_concentration` sorts by the all-time fraction of the org's job posts matching `order_by_advanced_query`, which it requires. `source_data_url` is omitted for all three, since the listing page cannot reproduce their ordering."},"order_by_direction":{"anyOf":[{"type":"string","enum":["ASC","DESC"]},{"type":"null"}],"title":"Order By Direction","description":"Direction to order by (filter mode only)."},"order_by_job_function":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Order By Job Function","description":"Job function whose people metrics drive the sort. Required with (and only valid with) `order_by_column=\"people_concentration\"` or `order_by_column=\"people_count_growth_1y\"`."},"order_by_advanced_query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Order By Advanced Query","description":"Advanced query whose matching job posts form the sort numerator. Required with (and only valid with) `order_by_column=\"job_post_concentration\"`. Allowed fields: technology, technology_category, job_function, project, job_level, country. Both the matching and total job counts are all-time."},"match_source":{"type":"string","enum":["any","job_post"],"title":"Match Source","description":"Filter mode only. Which evidence an organization may match the `filter` on. `any` (default) matches on either job posts or the skills its employees list on LinkedIn/Coresignal. `job_post` restricts matches to job-post evidence only, so an org that matches solely because an employee lists the technology (with no job posts mentioning it) is excluded. Applies to all job-side filters (technology, job function, hiring location, etc.).","default":"any"}},"additionalProperties":false,"type":"object","required":["select"],"title":"EnrichOrganizationsRequest"},"MatchOrganizationInput":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Organization name"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Organization website URL or domain"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location","description":"Organization location (country name or code)"},"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Id","description":"Organization Id on Sumble. When set, the row identifies a Sumble org directly and bypasses matching; name/url/location are not required."},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug","description":"Organization slug on Sumble. When set, the row identifies a Sumble org directly and bypasses matching; name/url/location are not required."}},"additionalProperties":false,"type":"object","title":"MatchOrganizationInput"},"Query":{"properties":{"query":{"type":"string","title":"Query"}},"type":"object","required":["query"],"title":"Query"},"Select":{"properties":{"attributes":{"items":{"type":"string","enum":["id","slug","name","url","employee_count","industry","jobs_count","teams_count","jobs_count_rollup","jobs_count_no_rollup","teams_count_rollup","teams_count_no_rollup","people_count_rollup","people_count_no_rollup","headquarters_country","sumble_score","sumble_url","parent_id","subsidiary_ids","tags","status","status_reason","account_status","funding_total_raised","funding_valuation","funding_last_round_raised","funding_last_round_type","funding_last_round_date"]},"type":"array","title":"Attributes","description":"Baseline company attributes to include. Off by default.","default":[]},"entities":{"items":{"$ref":"#/components/schemas/EntitySelection"},"type":"array","title":"Entities","description":"Per-entity metric selections.","default":[]}},"additionalProperties":false,"type":"object","title":"Select"},"EntitySelection":{"properties":{"type":{"type":"string","enum":["job_function","technology","project","advanced_query","technology_category"],"title":"Type","description":"The entity type to enrich against."},"term":{"type":"string","minLength":1,"title":"Term","description":"The entity term: a technology name, job function, project, category, or advanced query string."},"metrics":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string","const":"all"},{"type":"null"}],"title":"Metrics","description":"Metric names valid for `type`, or \"all\". Required for every type."},"granularity":{"anyOf":[{"type":"string","enum":["aggregate","exploded"]},{"type":"null"}],"title":"Granularity","description":"`technology_category` only (required there, disallowed elsewhere). `aggregate` rolls the category up into one set of counts; `exploded` decomposes into per-component-technology counts."},"since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since","description":"Scopes job_post_count, job_post_used_count, team_count, and people_count to activity since this date (YYYY-MM-DD). Does not affect people_count_growth_1y. No-rollup metrics are all-time only: with `since` set they are excluded from `metrics: \"all\"` and rejected if requested explicitly."}},"additionalProperties":false,"type":"object","required":["type","term"],"title":"EntitySelection"},"EnrichOrganizationsResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"organizations":{"items":{"$ref":"#/components/schemas/ResultRow"},"type":"array","title":"Organizations"},"matched_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Matched Count"},"total":{"type":"integer","title":"Total"},"source_data_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Source Data Url"}},"type":"object","required":["id","credits_used","credits_remaining","organizations","total"],"title":"EnrichOrganizationsResponse"},"ResultRow":{"properties":{"input":{"anyOf":[{"$ref":"#/components/schemas/MatchOrganizationInput"},{"type":"null"}]},"attributes":{"anyOf":[{"$ref":"#/components/schemas/Attributes"},{"type":"null"}]},"entities":{"items":{"$ref":"#/components/schemas/EntityResult"},"type":"array","title":"Entities","default":[]}},"type":"object","title":"ResultRow"},"Attributes":{"properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Id"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"employee_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Employee Count"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"},"jobs_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Jobs Count"},"teams_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Teams Count"},"jobs_count_rollup":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Jobs Count Rollup","description":"Total job posts at the organization including all subsidiaries (hierarchy rollup). Consistent with the entity-metric `job_post_count` and the denominator of `job_post_concentration`."},"jobs_count_no_rollup":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Jobs Count No Rollup","description":"Job posts attributed to this organization's own records only, excluding subsidiaries. Consistent with the `job_post_count_no_rollup` entity metric."},"teams_count_rollup":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Teams Count Rollup","description":"Total teams at the organization including all subsidiaries (hierarchy rollup). Consistent with the entity-metric `team_count`; use this rather than the legacy `teams_count` (own-records only, different source) as the denominator for team-share math against entity metrics."},"teams_count_no_rollup":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Teams Count No Rollup","description":"Teams attributed to this organization's own records only, excluding subsidiaries. Consistent with the `team_count_no_rollup` entity metric."},"people_count_rollup":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"People Count Rollup","description":"People tracked by Sumble at the organization including all subsidiaries (hierarchy rollup). Consistent with the entity-metric `people_count` and the denominator of `people_concentration`. Not the same as `employee_count` (LinkedIn-reported headcount)."},"people_count_no_rollup":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"People Count No Rollup","description":"People attributed to this organization's own records only, excluding subsidiaries. Consistent with the `people_count_no_rollup` entity metric."},"headquarters_country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headquarters Country"},"sumble_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sumble Score"},"sumble_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sumble Url"},"parent_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Parent Id"},"subsidiary_ids":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Subsidiary Ids"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Lifecycle status of the organization: 'active', or 'closed' (permanently ceased operations — shut down, dissolved, or bankrupt with no successor). Returned when requested via `select.attributes`; costs 1 credit like any other paid baseline attribute. Advanced-query filter results exclude closed organizations unless the request sets `include_closed`. More statuses (e.g. 'acquired_absorbed') may be added over time."},"status_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status Reason","description":"For a non-'active' status, the free-text reason for that determination. Null for active organizations. Returned when requested via `select.attributes`; costs 1 credit like any other paid baseline attribute."},"account_status":{"anyOf":[{"type":"string","enum":["customer","prospect","not_in_crm"]},{"type":"null"}],"title":"Account Status","description":"CRM relationship between the org and the user's account: 'customer' (a customer account in the user's CRM), 'prospect' (tracked in CRM but not a customer), or 'not_in_crm' (no CRM record). Free (no credit cost). Only populated when the user's account has a linked CRM seat; omitted for other users even if requested."},"funding_total_raised":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Funding Total Raised","description":"Total funding raised across all rounds, in whole USD. LLM-extracted from SEC filings and web search; approximate, and may be unconverted for non-USD rounds."},"funding_valuation":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Funding Valuation","description":"Most recent post-money valuation, in whole USD. LLM-extracted; approximate."},"funding_last_round_raised":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Funding Last Round Raised","description":"Amount raised in the latest funding round, in whole USD. LLM-extracted; approximate."},"funding_last_round_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Funding Last Round Type","description":"Latest funding round type, e.g. seed, series_a, private_equity."},"funding_last_round_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Funding Last Round Date","description":"Date of the latest funding round (ISO YYYY-MM-DD)."},"cloud_spend_estimate_millions_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cloud Spend Estimate Millions Usd"}},"type":"object","title":"Attributes"},"EntityResult":{"properties":{"type":{"type":"string","enum":["job_function","technology","project","advanced_query","technology_category"],"title":"Type"},"term":{"type":"string","title":"Term"},"job_post_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Job Post Count"},"job_post_count_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Post Count Url"},"job_post_used_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Job Post Used Count","description":"technology only. Number of the org's job posts that list this technology as actively used (rather than merely mentioned). Scoped to the same `since` window as job_post_count when set. None for non-technology entities."},"team_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Team Count"},"team_count_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Team Count Url"},"people_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"People Count"},"people_count_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"People Count Url"},"job_post_concentration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Job Post Concentration","description":"advanced_query only. Fraction (0-1) of the org's job posts matching the query. Scoped to the same `since` window as job_post_count when set. None for unresolved orgs or orgs with no job posts."},"people_concentration":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"People Concentration","description":"job_function only. Fraction (0-1) of the org's tracked people in this job function: people_count / total people in the org. Scoped to the same `since` window as people_count when set. None for unresolved orgs or orgs with no tracked people."},"people_count_growth_1y":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"People Count Growth 1Y"},"people_count_growth_1y_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"People Count Growth 1Y Url"},"job_post_count_growth_1y":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Job Post Count Growth 1Y"},"job_post_count_growth_1y_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Post Count Growth 1Y Url"},"job_post_count_no_rollup":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Job Post Count No Rollup","description":"technology, job_function, and project selections only. Same as `job_post_count` but excluding records attributed to subsidiaries (the organization's own records only). All-time only — not affected by `since`."},"team_count_no_rollup":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Team Count No Rollup","description":"technology, job_function, and project selections only. Same as `team_count` but excluding records attributed to subsidiaries. All-time only — not affected by `since`."},"people_count_no_rollup":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"People Count No Rollup","description":"technology and job_function selections only. Same as `people_count` but excluding records attributed to subsidiaries. All-time only — not affected by `since`."},"granularity":{"anyOf":[{"type":"string","enum":["aggregate","exploded"]},{"type":"null"}],"title":"Granularity"},"components":{"anyOf":[{"items":{"$ref":"#/components/schemas/EntityResult"},"type":"array"},{"type":"null"}],"title":"Components"}},"type":"object","required":["type","term"],"title":"EntityResult"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/organizations":{"post":{"tags":["organizations"],"summary":"Unified organizations endpoint","operationId":"enrich_organizations_unified__api_version__organizations_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichOrganizationsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichOrganizationsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Closed organizations

Some organizations are [closed](/our-data/organizations#status): shut down, dissolved or bankrupt with no successor. The two modes treat them differently:

* **Match mode** still resolves closed organizations, so you find out when an account in your CRM has shut down. Request `status` (`active` or `closed`) and `status_reason` to identify them. Each is a paid attribute.
* **Search mode** leaves closed organizations out by default. Set `include_closed: true` to include them, and request `status` / `status_reason` to tell them apart.

## Tags

Filter on the `tag` field using a tag slug, for example `tag EQ 'is_ai_native'`. The `tags` attribute returns the slugs on each organization. Every tag, its slug and what it means is in [Our data: Tags](/our-data/organizations#tags).

## CVM revenue licensing

Where CVM revenue data is supplied, its parsed source database is available separately under [ODbL 1.0](https://opendatacommons.org/licenses/odbl/1-0/). See [CVM revenue data](/our-data/cvm-revenue) for source attribution, free downloads and reuse terms.


# Organization signals

## Retrieve recent signals for a single organization

Retrieve the recent signals for a single organization: champion movements, recent hires and promotions, technology and product mentions, projects and initiatives, technology and job function trends. Use this endpoint when you already have the Sumble organization `id`.

### Input

Pass the Sumble organization `id` in the URL path:

```bash
curl https://api.sumble.com/v9/organizations/1726684/signals \
  --header "Authorization: Bearer $API_KEY"
```

The endpoint does not accept a request body. If the organization does not exist, the API returns HTTP `404`.

### Response

The response contains a `signals` array. Each signal includes a display-ready `title`, `display_type`, and `date`, plus optional context such as `subtitle`, `type`, `organization_name`, `organization_id`, `location`, `job_function`, `priority`, `explanation`, and `sales_angle`.

For person-movement signals, `subtitle` may include a normalized start-date label such as `Started Jun 2026` or `Starting Jul 2026`.

### File output

Set the `file_name` query parameter to get the organization's signals as a file. See [File downloads](/api/api#file-downloads). The file contains one row per signal and one column per response field. `matched_technologies` and `suggested_contacts` contain compact JSON text within their cells in a `.csv` or `.xlsx`, and stay nested in a `.json`.

### Credit cost

1 credit per signal returned. Organizations with no returned signals do not consume credits.

## GET /v9/organizations/{organization\_id}/signals

> Get organization signals

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"SignalsResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"signals":{"items":{"$ref":"#/components/schemas/Signal"},"type":"array","title":"Signals"}},"type":"object","required":["id","credits_used","credits_remaining","signals"],"title":"SignalsResponse"},"Signal":{"properties":{"signal_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Signal Id"},"title":{"type":"string","title":"Title"},"subtitle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subtitle"},"explanation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Explanation"},"sales_angle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sales Angle"},"date":{"type":"string","format":"date-time","title":"Date"},"sumble_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sumble Url"},"display_type":{"type":"string","title":"Display Type"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"matched_technologies":{"anyOf":[{"items":{"$ref":"#/components/schemas/SignalTechnology"},"type":"array"},{"type":"null"}],"title":"Matched Technologies"},"organization_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization Name"},"organization_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Organization Id"},"job_post_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Job Post Id"},"person_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Person Id"},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"job_function":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Function"},"priority":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Priority"},"signal_config_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Signal Config Id","description":"The `id` of the signal config that generated this signal. Returned only when that config is visible to your account; pass it to List Signal Configs to read the full definition."},"signal_config_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signal Config Name","description":"Display name of the signal config that generated this signal. This remains available as explanation context even when the full config is not visible to your account."},"suggested_contacts":{"anyOf":[{"$ref":"#/components/schemas/SuggestedContacts"},{"type":"null"}]},"account_status":{"anyOf":[{"type":"string","enum":["customer","prospect","not_in_crm"]},{"type":"null"}],"title":"Account Status","description":"CRM relationship between the signal's organization and the calling account: 'customer' (a customer account in the calling account's CRM), 'prospect' (tracked in CRM but not a customer), or 'not_in_crm' (no CRM record). Only populated when the calling account has a linked CRM seat (Salesforce or HubSpot); otherwise absent or null even when requested, depending on the caller (the REST API omits null fields, MCP returns them as null)."}},"type":"object","required":["title","date","display_type"],"title":"Signal"},"SignalTechnology":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"}},"type":"object","required":["name","slug"],"title":"SignalTechnology"},"SuggestedContacts":{"properties":{"people":{"items":{"$ref":"#/components/schemas/SuggestedContact"},"type":"array","title":"People"},"sumble_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sumble Url"}},"type":"object","required":["people"],"title":"SuggestedContacts"},"SuggestedContact":{"properties":{"person_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Person Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"}},"type":"object","title":"SuggestedContact"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/organizations/{organization_id}/signals":{"get":{"tags":["organizations"],"summary":"Get organization signals","operationId":"get_organization_signals__api_version__organizations__organization_id__signals_get","parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"integer","title":"Organization Id"}},{"name":"technology_slugs","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Technology slugs to filter signals by. Repeat this query parameter to filter by multiple technologies. Use POST /technologies/lookup to resolve technology names, slugs, or aliases to canonical slugs; use POST /technologies/find to search for matching technologies.","title":"Technology Slugs"},"description":"Technology slugs to filter signals by. Repeat this query parameter to filter by multiple technologies. Use POST /technologies/lookup to resolve technology names, slugs, or aliases to canonical slugs; use POST /technologies/find to search for matching technologies."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


# Organization tech stack

## Retrieve the confirmed-used tech stack for a single organization

Retrieve an organization's **confirmed-used** technology stack, grouped by business function and technology category — the same grouping and ranking used by the Tech Stack Overview page on sumble.com. Use this endpoint when you already have the Sumble organization `id` and want to know what an organization actually runs in production, not merely what its job posts or employee profiles mention in passing.

This is different from filtering the [Organizations](/api/core-data/organizations) endpoint by `technology`, or reading its `job_post_count` metric — both of those match on *any* mention. This endpoint restricts to technologies Sumble has confirmed are actually in use.

### Input

Pass the Sumble organization `id` in the URL path:

```bash
curl https://api.sumble.com/v9/organizations/1726684/techs \
  --header "Authorization: Bearer $API_KEY"
```

The endpoint does not accept a request body. If the organization does not exist, the API returns HTTP `404`.

To get the tech stack as a file, pass `file_name` (see [File downloads](/api/api#file-downloads)):

```bash
curl "https://api.sumble.com/v9/organizations/1726684/techs?file_name=vanta-tech-stack.csv" \
  --header "Authorization: Bearer $API_KEY"
```

### Custom categories

Custom categories are in private preview, limited to Sumble staff and staff-impersonated sessions. To add your custom categories to the canonical stack, pass their exact slugs as repeated `custom_technology_categories` query parameters:

```bash
curl --get "https://api.sumble.com/v9/organizations/1726684/techs" \
  --header "Authorization: Bearer $API_KEY" \
  --data-urlencode "custom_technology_categories=custom:cloud" \
  --data-urlencode "custom_technology_categories=custom:data-platforms"
```

The response adds a `Custom categories` business-function group. Its categories have `is_custom: true`; canonical categories have `is_custom: false`. Each requested custom category uses its current member technologies and the same confirmed-use and primary-vendor selection rules as canonical categories. Custom categories do not have the five-category limit used by canonical business functions. Categories without confirmed-used evidence are omitted.

Repeated slugs are deduplicated. An unavailable category returns an error before charging. The usual per-returned-technology cost applies, including when a technology appears in both a canonical and a custom category. This endpoint cannot create or edit categories.

### Response

The response contains a `business_functions` array in the same display order as the Tech Stack Overview page. Each business function contains up to five categories, ranked by confirmed-use evidence. Business functions without detected technologies are returned with an empty `categories` array.

Each category includes a `category_slug`, `category_name` (short), `category_name_full`, and `is_custom`, plus:

* **`technologies`** — the confirmed-used, top-tier ("primary") technologies Sumble found for that category at this organization. Each technology includes its `name`, `slug`, a `job_post_used_count` (the number of job posts confirming active use, not mere mentions), and its `domain` when known.
* **`evidence`** — the full ranked list of every confirmed-used technology detected in that category (a superset of `technologies`), each as `{name, job_post_used_count}`. Use this for the complete picture rather than just the headline picks.

Categories without confirmed-used technologies are omitted.

### File output

File output includes `is_custom` on each category row.

A `.json` file holds the `business_functions` array in the same structure as the inline response, with each function's categories, technologies, and evidence nested. Its `row_count` counts business functions, and `columns` lists their top-level keys.

A `.csv` or `.xlsx` file has one row per technology in a category's full `evidence` list. Its width is fixed. Organizations with more technologies produce more rows, not more columns.

Each row repeats its organization, business function, and category context. `business_function_rank`, `category_rank`, and `evidence_rank` preserve the response order. `is_primary` marks technologies that also appear in the category's `technologies` list. Those rows include `technology_slug`, `technology_domain`, and `primary_rank`; the fields are blank for evidence-only technologies.

### Credit cost

1 credit per technology returned in `technologies` (summed across all returned business functions and categories). Organizations with no confirmed-used technologies do not consume credits.

## GET /v9/organizations/{organization\_id}/techs

> Get organization tech stack

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"OrganizationTechStackResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"organization_id":{"type":"integer","title":"Organization Id"},"organization_slug":{"type":"string","title":"Organization Slug"},"business_functions":{"items":{"$ref":"#/components/schemas/OrganizationTechStackBusinessFunction"},"type":"array","title":"Business Functions"}},"type":"object","required":["id","credits_used","credits_remaining","organization_id","organization_slug","business_functions"],"title":"OrganizationTechStackResponse"},"OrganizationTechStackBusinessFunction":{"properties":{"business_function":{"type":"string","title":"Business Function"},"categories":{"items":{"$ref":"#/components/schemas/OrganizationTechStackCategory"},"type":"array","title":"Categories"}},"type":"object","required":["business_function","categories"],"title":"OrganizationTechStackBusinessFunction"},"OrganizationTechStackCategory":{"properties":{"category_slug":{"type":"string","title":"Category Slug"},"category_name":{"type":"string","title":"Category Name"},"category_name_full":{"type":"string","title":"Category Name Full"},"technologies":{"items":{"$ref":"#/components/schemas/OrganizationTechStackTechnology"},"type":"array","title":"Technologies"},"evidence":{"items":{"$ref":"#/components/schemas/OrganizationTechStackEvidenceItem"},"type":"array","title":"Evidence"}},"type":"object","required":["category_slug","category_name","category_name_full","technologies","evidence"],"title":"OrganizationTechStackCategory"},"OrganizationTechStackTechnology":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"job_post_used_count":{"type":"integer","title":"Job Post Used Count"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"}},"type":"object","required":["name","slug","job_post_used_count"],"title":"OrganizationTechStackTechnology","description":"A confirmed-used (\"primary\") technology within a category."},"OrganizationTechStackEvidenceItem":{"properties":{"name":{"type":"string","title":"Name"},"job_post_used_count":{"type":"integer","title":"Job Post Used Count"}},"type":"object","required":["name","job_post_used_count"],"title":"OrganizationTechStackEvidenceItem","description":"One confirmed-used technology detected in a category, with the number\nof job posts that confirm it (not merely mention it) is actually in use.\n\nThis is the full, unfiltered list for the category — a superset of\n`OrganizationTechStackCategory.technologies`, which is trimmed to the\ntop-tier (primary) picks."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/organizations/{organization_id}/techs":{"get":{"tags":["organizations"],"summary":"Get organization tech stack","operationId":"get_organization_techs__api_version__organizations__organization_id__techs_get","parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"integer","title":"Organization Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationTechStackResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


# People

## Find, match, and enrich people

The single endpoint for working with people. Provide either a **list of people** to resolve (list mode) or a **filter** to find people using structured criteria or plain-language search, and compose exactly which attributes you get back. This replaces the previous `find`, `find-related-people`, and `enrich` endpoints.

### Input

Provide exactly one of:

* **`people`** — a list of up to 1,000 people to resolve, each identified by a Sumble `person_id`, a `linkedin_url`, or a work `email` (used in that order of precedence). Limited to 25 entries when requesting contact attributes, related people, or email identifiers. Covers the previous `enrich` and `find-related-people` flows.
  * Entries identified by `email` may also carry an optional **`name`**. It isn't an identifier — an entry with only a name is rejected — but it noticeably improves email resolution, especially for addresses like `firstname@company.com` where the name can't be read off the address, and for people whose email is at a former employer. Include it whenever you have it.
* **`filter`** selects people using an advanced query or search. Use `organization_ids`, up to 1,000, and/or a saved `organization_list_id` to scope either approach to those organizations. Covers the previous `find` flow.

#### Advanced query

`filter.query` matches people using a structured query expression over job functions, technologies, job levels, locations, and more. Provide an organization scope.

In filter mode, `limit` (default 10, max 200) and `offset` page through results, and `order_by_column` sorts by `start_date`, `job_level`, or `person_score`. Sorting by `person_score` requires exactly one organization in scope and an ICP configured for your account.

#### Search

Use `filter.search` to describe responsibilities or experience in plain language. Results are ranked by relevance. Search is available on Sumble Pro and Enterprise plans, and needs API version v8 or later.

For search, `requested_total` sets the maximum number of people across all pages, from 1 to 1,000. It defaults to `limit`, so a request with `limit: 10` returns at most ten people in total. To request 100 people in pages of 20, set `requested_total: 100` and `limit: 20` from the first request. Keep the search, scope, and `requested_total` unchanged when paging, and increase `offset` by `limit`.

Results include the best available matches, which may only partly match your description. `total` is the size of this ranked list, capped by `requested_total`, rather than a count of everyone who might match. A short or empty page can mean some profiles are unavailable. Continue until `offset + limit >= total`.

```json
{
  "filter": {
    "search": "Salesforce administrators or revenue operations managers who own Salesforce CRM",
    "organization_ids": [10441, 27730],
    "locations": ["US:Texas"]
  },
  "select": { "attributes": ["name", "job_title"] },
  "limit": 25,
  "offset": 0
}
```

Omit the organization filters to search across Sumble's people records. With an organization scope, add `"include_past_employers": true` to `filter` to include former employees. This option requires `search`.

Add `locations` to `filter` to search only people whose profile location is in one of the places you name. Pass up to 200 location codes from [Find locations](/api/lookups/locations), such as `US`, `US:Texas`, or `US:Texas:Austin`. A person matches when their location is in any of them, and a state or country code matches every city in it. A code that resolves to no place, or that is not shaped like `US`, `US:Texas` or `US:Texas:Austin`, returns a 400 error naming it. Region codes such as `EMEA` are not accepted: send the region as `parent`, then each subregion it returns as `parent`, and pass the country codes. This option requires `search`.

`search` cannot be combined with `query`. Search results come back in relevance order. Set `order_by_column` to sort them by `start_date`, `job_level`, or `person_score` instead. A sort covers the search's results up to `requested_total`, so set `requested_total` before the first page.

`person_score` works with `search` too. Each person gets the same score filter mode gives them, and the results stay in relevance order unless you sort by `person_score`.

#### Writing a good search

Describe the people the way their own profile would, in one or two short sentences: the role, what they own or do, and the concrete tools, products, or domains they work with.

What works well:

* Short role lists with a few specifics. A plural role noun, a seniority, and a product name work better than a paragraph of instructions.
* Naming the seniority, such as "director or VP of finance", and listing the titles a role goes by when they vary, such as "engineering managers, directors of engineering, heads of platform".
* Exact product and technology names.
* Including the forms people use for a role or field, such as "engineer" and "engineering".
* Filters for what must hold. `organization_ids` enforces the employer and `locations` enforces the place, using codes from [Find locations](/api/lookups/locations).
* Another language when results are thin and the people you want may write their profiles in it, such as "engenheiro de dados com experiência em Spark". Run it as a second search and merge the results by `person_id`.

Searches that work well: "FinOps lead who manages cloud cost optimization"; "database administrators or backend engineers who work with PostgreSQL in production"; "CISO, head of operational resilience, or leaders responsible for business continuity and disaster recovery".

What does not work:

* Long instruction-style text. Keep the search to the people you want; instructions about what to return or how to format it are not followed.

### Composable response

The `select` block dictates exactly which attributes return — nothing is mandatory:

* **`attributes`** — a list of person attributes, or `"all"`. Available: `name`, `linkedin_url`, `job_title`, `job_function`, `job_level`, `location`, `country`, `current_employer`, `technologies`, `person_score`, the profile attributes `experience` and `summary`, and the contact attributes `email` and `phone`. `person_id` and `sumble_url` are always included for free.
  * The contact attributes `email` and `phone` must be requested explicitly — they are never part of `"all"` — and are only available in list mode, for up to 25 people per request.
  * The profile attributes must also be requested explicitly. They work in both modes; a list-mode request selecting them is capped at 200 people, matching the search-mode page size. `experience` is the person's LinkedIn-style role history, newest first: `title`, `start_date` and `end_date` (`YYYY-MM`, null end for a current role), `duration`, `location`, the person's own `description` of the role, and an `employer` shaped like `current_employer` (`organization_id`, `slug`, and `sumble_url` when Sumble knows the organization, plus the employer's `name` and `linkedin_url` from the profile). `summary` is the profile's "About" section as the person wrote it.
  * `person_score` is your ICP match score (0–100) with its contribution breakdown. See [Scores](/our-data/people#scores). It requires filter mode with exactly one organization in scope and an ICP configured; `"all"` includes it opportunistically when those requirements are met. Requesting it explicitly in list mode returns an error, and it isn't available for related people. Sorting by `person_score` is descending only, and it adds `person_score` to every returned row, charged like any paid attribute.
* **`related_people`** — inferred managers and/or direct reports for each matched person. Choose the `direction` (`managers`, `direct_reports`) and which attributes to return for them. Add `confidence` to a related person's attributes to get why they were returned: a 0–1 score with its breakdown. Available in list mode only, for up to 25 people per request.

### File output

Set `file_name`, such as `people.csv`, to get the results as a file instead of inline `people`. The formats and the response shape are in [File downloads](/api/api#file-downloads).

A `.json` file contains one object per person in the same structure as the inline `people` results, so the current employer and person score stay objects and technologies, experience, managers, and direct reports stay arrays.

A `.csv` or `.xlsx` file contains one row per person. In list mode, unmatched inputs remain as rows with their `input_*` columns populated. Person, current-employer, and person-score scalar values have their own columns. Repeated or nested values — technologies, experience, matched score features, managers, and direct reports — are compact JSON in one cell.

Pass `file_name` only when starting an [asynchronous request](#asynchronous-requests). Poll with `request_id` alone; the successful poll carries the `file`.

If the file cannot be written, the request still succeeds and returns the rows inline with no `file`. A download problem never costs you a result you have already paid for, so handle both shapes.

### Credit cost

Charged per matched person (list mode) or per returned person (search mode). Unmatched inputs are free.

Per person the cost is:

* **1 base credit**, plus:
* **1 credit per paid attribute** requested (`name` is free), plus
* **1 credit per related person** returned.

Contact and email-identifier charges apply on top:

* **Email reveal**: 10 credits the first time your account reveals an email for a given person; repeat requests while the reveal is active are free, and nothing is charged when no email is found.
* **Phone reveal**: 80 credits the first time your account reveals a phone for a given person, with the same repeat and not-found rules.
* **Email identifiers**: resolving an input `email` to a person costs 20 credits per unique email that resolves; emails that don't resolve are free.

For example, returning 10 people with 2 paid attributes each costs `10 × (1 + 2) = 30` credits. The API checks affordability up front and returns HTTP `402` before doing any work you can't pay for.

## Asynchronous requests

`POST /people` is **asynchronous** in both modes: it starts a background job and returns immediately with a `request_id`. You then poll the same endpoint with that `request_id` to retrieve the status and, once ready, the result.

{% stepper %}
{% step %}

### Start the request

`POST /people` with a `people` or `filter` body exactly as described above. The response has `status: "pending"` and a `request_id`. No credits are charged yet, but the request is fully validated and your balance is pre-checked up front, so you still receive the usual `400`/`402` immediately — for example if `person_score` is misconfigured or you can't afford the worst-case cost.
{% endstep %}

{% step %}

### Poll for the result

`POST /people` with `{ "request_id": "..." }`. While the job runs you get `status: "pending"` or `"running"`. When it finishes you get a terminal status and, on success, the full result (`people`, `total`, and the other fields).
{% endstep %}
{% endstepper %}

Asynchronous list requests also let Sumble fall back to a deeper reverse-enrichment lookup for input `email`s it can't resolve immediately — those results are filled in before the job completes, rather than coming back unmatched.

### Limits on open searches

Each user can have 20 [searches](#search) pending or running at a time. Starting another one returns HTTP `429` with `"type": "search_concurrency"` and a `Retry-After` header giving the seconds to wait. Nothing is started and no credits are charged. Wait that long, then send the same request again. The limit applies only to starting a search, so polls and requests without `search` are never refused this way.

### Poll request body

| Field        | Type   | Description                                                                                                                                 |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `request_id` | string | The `request_id` returned when the job was started. Provide this **alone** to poll — don't send `people`, `filter`, or `file_name` with it. |

### Job status values

| `status`    | Meaning                                                                         |
| ----------- | ------------------------------------------------------------------------------- |
| `pending`   | Queued, not started yet.                                                        |
| `running`   | The request is being processed.                                                 |
| `succeeded` | Done; the result fields are included in the response.                           |
| `failed`    | The request did not finish. The `error` field says why and whether to resubmit. |

### When you're charged

Credits are charged **once, on the first poll that returns `succeeded`**. `failed` jobs cost nothing. Polling is always free: the `credits_used` field reflects what this particular call charged, so the successful poll reports the total and every subsequent poll of the same job reports `0`.

### Async response fields

Alongside the usual result fields, the response includes:

| Field        | Type   | Description                                                                                                                                      |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `request_id` | string | Id of the async job. Poll `POST /people` with this id to retrieve the result.                                                                    |
| `status`     | string | Job status — one of `pending`, `running`, `succeeded`, or `failed`.                                                                              |
| `file`       | object | Metadata and download URL for the file requested with `file_name`; present when the job succeeds. See [File downloads](/api/api#file-downloads). |
| `error`      | object | Why the job failed. Present only when `status` is `failed`. See [Failed requests](#failed-requests).                                             |

### Failed requests

A failed poll response carries an `error` object:

| Field      | Type              | Description                               |
| ---------- | ----------------- | ----------------------------------------- |
| `code`     | string            | `unavailable`, `expired`, or `internal`.  |
| `message`  | string            | What happened and what to do next.        |
| `retry_at` | string (ISO 8601) | When to resubmit. Omitted for `internal`. |

If `retry_at` is set, resubmit the original request at or after that time. If it isn't, the request failed because of an internal error; contact <support@sumble.com> if it keeps failing.

| `code`        | Meaning                                                                                                                                                                     |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `unavailable` | The service was temporarily unavailable and could not complete the request: it was too busy, or a restart interrupted it. `retry_at` is about 30 seconds after the failure. |
| `expired`     | A `filter.search` request waited more than 30 minutes to start, so it never ran. `retry_at` is the time it failed, so resubmit now.                                         |
| `internal`    | Something went wrong on our side. No `retry_at`.                                                                                                                            |

To resubmit, send the original `people` or `filter` request again. That starts a new job with a new `request_id`. Polling the failed `request_id` keeps returning the same failure, and `retry_at` doesn't move. A failed job costs nothing.

```json
{
  "request_id": "019d...",
  "status": "failed",
  "credits_used": 0,
  "credits_remaining": 6571,
  "error": {
    "code": "unavailable",
    "message": "The service was temporarily unavailable and could not complete this request. Resubmit the original request after retry_at.",
    "retry_at": "2026-11-03T15:04:35Z"
  }
}
```

### Example: start then poll

{% tabs %}
{% tab title="Start" %}

```bash
curl -X POST https://api.sumble.com/v9/people \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "people": [ { "email": "lou@sumble.com" } ], "select": { "attributes": ["name", "job_title"] } }'
# -> { "request_id": "019d...", "status": "pending", "credits_used": 0, "credits_remaining": 6571 }
```

{% endtab %}

{% tab title="Poll" %}

```bash
curl -X POST https://api.sumble.com/v9/people \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "request_id": "019d..." }'
# -> { "request_id": "019d...", "status": "succeeded", "credits_used": 4, "people": [ ... ], "total": 1 }
```

{% endtab %}
{% endtabs %}

## Unified people endpoint

> Find, match, and enrich people. Provide a \`people\` list (list mode) or a \`filter\` (search mode) and compose the response with \`select\`.\
> \
> On \*\*v7 and earlier\*\* this endpoint is synchronous: one call returns the people.\
> \
> On \*\*v8 and later\*\* it is \*\*asynchronous\*\* in both modes. Send a \`people\` or \`filter\` body to start a background job — the response returns a \`request\_id\` and \`status: "pending"\`, and no credits are charged yet (the request is validated and your balance pre-checked, so you still get a \`400\`/\`402\` up front). Then send \`{ "request\_id": "..." }\` to the same endpoint to poll: you get \`status\` \`pending\`/\`running\` until it finishes, then \`succeeded\` (with the full \`people\`/\`total\` result) or \`failed\`. Credits are charged once, on the first \`succeeded\` poll; repeat polls report \`credits\_used: 0\`. The async response adds \`request\_id\` and \`status\` fields.

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"EnrichPeopleRequest":{"properties":{"people":{"anyOf":[{"items":{"$ref":"#/components/schemas/PersonInput"},"type":"array","maxItems":1000,"minItems":1},{"type":"null"}],"title":"People","description":"List of people to resolve and enrich. One result row per entry, in input order. Mutually exclusive with `filter`."},"filter":{"anyOf":[{"$ref":"#/components/schemas/PeopleFilter"},{"type":"null"}],"description":"Query selecting the people to return. Mutually exclusive with `people`."},"select":{"$ref":"#/components/schemas/PeopleSelect","description":"Dictates exactly which attributes are returned."},"limit":{"type":"integer","maximum":200,"minimum":1,"title":"Limit","description":"Maximum number of people to return (filter mode only; ignored when `people` is provided).","default":10},"offset":{"type":"integer","maximum":10000,"minimum":0,"title":"Offset","description":"Number of results to skip (filter mode only; ignored when `people` is provided).","default":0},"order_by_column":{"anyOf":[{"type":"string","enum":["person_score","start_date","job_level"]},{"type":"null"}],"title":"Order By Column","description":"Column to order by (filter mode only): `start_date` (current role start), `job_level` (seniority rank), or `person_score`. `person_score` sorts people by how well they match your ideal customer profile (ICP) and includes — and charges for — the `person_score` attribute on every row; it requires the filter to resolve to exactly one organization and an ICP configured for your account, and only supports descending order. Default: Sumble's standard people ordering."},"order_by_direction":{"anyOf":[{"type":"string","enum":["ASC","DESC"]},{"type":"null"}],"title":"Order By Direction","description":"Sort direction; DESC when omitted."},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id","description":"(v8 only) Id of a previously started async request (returned by the kickoff call). Provide this alone to poll for the status and result."}},"additionalProperties":false,"type":"object","title":"EnrichPeopleRequest"},"PersonInput":{"properties":{"person_id":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Person Id","description":"Person id on Sumble. When set, it identifies the person directly and `linkedin_url`/`email` are ignored."},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url","description":"LinkedIn profile URL of the person, e.g. 'https://www.linkedin.com/in/<slug>'. Entries whose URL is not a profile URL come back unmatched. Takes precedence over `email`."},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Work email of the person, resolved via reverse enrichment. Costs 20 extra credits when it resolves to a returned person; emails that don't resolve come back unmatched, free. Only used when neither `person_id` nor `linkedin_url` is provided."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Full name of the person, used only to disambiguate the reverse-enrichment lookup when resolving by `email`. Not an identifier on its own — an entry with just a name is rejected — and ignored for `person_id`/`linkedin_url` entries. Supplying it materially improves resolution for addresses whose local part isn't a parseable name (e.g. `firstname@company.com`), and lets the matcher recognise people whose email is at a former employer."}},"additionalProperties":false,"type":"object","title":"PersonInput"},"PeopleFilter":{"properties":{"organization_ids":{"anyOf":[{"items":{"type":"integer"},"type":"array","maxItems":1000,"minItems":1},{"type":"null"}],"title":"Organization Ids","description":"Sumble organization ids to search within. People queries are organization-scoped: provide this and/or `organization_list_id`."},"organization_list_id":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Organization List Id","description":"Id of one of your saved organization lists (see /organization-lists) whose organizations to search within. Combined with `organization_ids` when both are provided."},"query":{"anyOf":[{"$ref":"#/components/schemas/Query"},{"type":"null"}],"description":"Advanced query narrowing the people returned (job functions, technologies, job levels, locations, ...)."}},"additionalProperties":false,"type":"object","title":"PeopleFilter"},"Query":{"properties":{"query":{"type":"string","title":"Query"}},"type":"object","required":["query"],"title":"Query"},"PeopleSelect":{"properties":{"attributes":{"anyOf":[{"items":{"type":"string","enum":["name","email","phone","linkedin_url","job_title","job_function","job_level","location","country","current_employer","technologies","person_score","confidence"]},"type":"array"},{"type":"string","const":"all"}],"title":"Attributes","description":"Person-level attributes to include, or 'all' for every attribute-priced attribute. Off by default. 'all' excludes contact attributes (email, phone), which must be requested explicitly, and includes `person_score` only when it is available (filter mode with exactly one organization in scope and an ICP configured for your account) — otherwise it is skipped, not an error. When `person_score` is included and no `order_by_column` is set, results are ordered by it. Note that 'all' grows — and its cost grows — as new attributes are added to the endpoint.","default":[]},"related_people":{"anyOf":[{"$ref":"#/components/schemas/RelatedPeopleSelection"},{"type":"null"}],"description":"Also return people related to each matched person, up or down the org hierarchy. Relationships are inferred from org structure and seniority (technology, job function, team, location and job-level similarity), not actual reporting lines. Only available in match mode (`people`), for at most 25 people per request. Each related person returned costs 1 credit."}},"additionalProperties":false,"type":"object","title":"PeopleSelect"},"RelatedPeopleSelection":{"properties":{"direction":{"items":{"type":"string","enum":["managers","direct_reports"]},"type":"array","minItems":1,"title":"Direction","description":"Which hierarchy direction(s) to return."},"attributes":{"anyOf":[{"items":{"type":"string","enum":["name","email","phone","linkedin_url","job_title","job_function","job_level","location","country","current_employer","technologies","person_score","confidence"]},"type":"array"},{"type":"string","const":"all"}],"title":"Attributes","description":"Person-level attributes to include for each related person, or 'all' for every attribute available here. Contact attributes (email, phone) and `person_score` are not available here; `confidence` (the inferred relationship's score breakdown) is only available here.","default":[]}},"additionalProperties":false,"type":"object","required":["direction"],"title":"RelatedPeopleSelection"},"EnrichPeopleResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id","description":"(v8 only) Id of the async request. Poll POST /people with this id to retrieve the status and result."},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"(v8 only) Request status: pending, running, succeeded, or failed. Null on the synchronous (<= v7) endpoint."},"people":{"anyOf":[{"items":{"$ref":"#/components/schemas/PersonRow"},"type":"array"},{"type":"null"}],"title":"People"},"matched_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Matched Count","description":"List mode only: how many input entries resolved to a Sumble person."},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"},"source_data_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Source Data Url"}},"type":"object","required":["id","credits_used","credits_remaining"],"title":"EnrichPeopleResponse"},"PersonRow":{"properties":{"input":{"anyOf":[{"$ref":"#/components/schemas/PersonInput"},{"type":"null"}],"description":"The input entry this row corresponds to (list mode only)."},"person_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Person Id","description":"Absent when the input entry didn't resolve to a person."},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url","description":"Link to the person's Sumble profile page."},"attributes":{"anyOf":[{"$ref":"#/components/schemas/PersonAttributes"},{"type":"null"}],"description":"The requested person-level attributes; absent when none resolve."},"related_people":{"anyOf":[{"$ref":"#/components/schemas/RelatedPeopleResult"},{"type":"null"}],"description":"Requested related people (match mode with `select.related_people`)."}},"type":"object","title":"PersonRow"},"PersonAttributes":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Revealed work email (match mode only). The first successful reveal per person costs 10 credits; repeat reveals while active are free."},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone","description":"Revealed phone number (match mode only). The first successful reveal per person costs 80 credits; repeat reveals while active are free."},"linkedin_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Linkedin Url"},"job_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Title"},"job_function":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Function"},"job_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Level"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"current_employer":{"anyOf":[{"$ref":"#/components/schemas/CurrentEmployer"},{"type":"null"}]},"technologies":{"anyOf":[{"items":{"$ref":"#/components/schemas/PersonTechnology"},"type":"array"},{"type":"null"}],"title":"Technologies","description":"Technologies from the skills on the person's LinkedIn profile, normalized to Sumble's technology catalog. The slug can be used in `filter.query` (technology EQ '<slug>'). Empty when none of the profile's skills map to a known technology."},"person_score":{"anyOf":[{"$ref":"#/components/schemas/PersonScore"},{"type":"null"}],"description":"How well the person matches your ideal customer profile (ICP), 0-100, with a per-feature breakdown. Priced like other paid attributes. Filter mode only; selecting it explicitly requires the filter to resolve to exactly one organization and an ICP configured for your account (`attributes: \"all\"` skips it instead when unavailable). Included automatically when sorting with `order_by_column=\"person_score\"`."}},"type":"object","title":"PersonAttributes"},"CurrentEmployer":{"properties":{"organization_id":{"type":"integer","title":"Organization Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date","description":"Start of the person's current role (YYYY-MM)."},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url","description":"Link to the organization's Sumble profile page."}},"type":"object","required":["organization_id"],"title":"CurrentEmployer"},"PersonTechnology":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"}},"type":"object","required":["name","slug"],"title":"PersonTechnology"},"PersonScore":{"properties":{"value":{"type":"number","title":"Value","description":"How well the person matches your ideal customer profile (ICP), 0-100. Sum of the three contributions below."},"skill_contribution":{"type":"number","title":"Skill Contribution","description":"Points from technologies the person uses that match your ICP."},"job_function_contribution":{"type":"number","title":"Job Function Contribution","description":"Points from the person's job function matching your ICP."},"seniority_contribution":{"type":"number","title":"Seniority Contribution","description":"Points from the person's job level (seniority)."},"matched_features":{"items":{"$ref":"#/components/schemas/PersonScoreFeature"},"type":"array","title":"Matched Features","description":"The matched technologies and job functions behind the skill and job-function contributions, highest contribution first."}},"type":"object","required":["value","skill_contribution","job_function_contribution","seniority_contribution","matched_features"],"title":"PersonScore"},"PersonScoreFeature":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"match_type":{"type":"string","enum":["technology","job_function"],"title":"Match Type"},"contribution":{"type":"number","title":"Contribution","description":"Points of the 0-100 score attributable to this feature."}},"type":"object","required":["name","slug","match_type","contribution"],"title":"PersonScoreFeature"},"RelatedPeopleResult":{"properties":{"managers":{"anyOf":[{"items":{"$ref":"#/components/schemas/RelatedPersonRow"},"type":"array"},{"type":"null"}],"title":"Managers","description":"Inferred managers; present only when requested."},"direct_reports":{"anyOf":[{"items":{"$ref":"#/components/schemas/RelatedPersonRow"},"type":"array"},{"type":"null"}],"title":"Direct Reports","description":"Inferred direct reports; present only when requested."}},"type":"object","title":"RelatedPeopleResult"},"RelatedPersonRow":{"properties":{"person_id":{"type":"integer","title":"Person Id"},"sumble_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Sumble Url","description":"Link to the person's Sumble profile page."},"confidence":{"anyOf":[{"$ref":"#/components/schemas/RelatedPersonConfidence"},{"type":"null"}],"description":"Why this person was returned: confidence score (0-1) with per-category and per-feature breakdowns. Present when the `confidence` attribute is requested. Not the ICP-based `person_score`."},"attributes":{"anyOf":[{"$ref":"#/components/schemas/PersonAttributes"},{"type":"null"}],"description":"The requested person-level attributes; absent when none resolve."}},"type":"object","required":["person_id","sumble_url"],"title":"RelatedPersonRow"},"RelatedPersonConfidence":{"properties":{"score":{"type":"number","title":"Score","description":"How strongly this person relates to the source person (people endpoint) or job posting (jobs endpoint), 0-1. Sum of the five contributions below. Measures similarity on shared features (technologies, job functions, teams, locations, job titles) — unrelated to the ICP-based `person_score` attribute."},"technology_contribution":{"type":"number","title":"Technology Contribution","description":"Share from technologies shared with the source."},"job_function_contribution":{"type":"number","title":"Job Function Contribution","description":"Share from matching job functions."},"team_contribution":{"type":"number","title":"Team Contribution","description":"Share from shared teams."},"location_contribution":{"type":"number","title":"Location Contribution","description":"Share from matching locations."},"title_similarity_contribution":{"type":"number","title":"Title Similarity Contribution","description":"Share from semantic similarity between job titles."},"matched_features":{"items":{"$ref":"#/components/schemas/RelatedPersonConfidenceFeature"},"type":"array","title":"Matched Features","description":"The specific matched features behind the contributions, highest contribution first."}},"type":"object","required":["score","technology_contribution","job_function_contribution","team_contribution","location_contribution","title_similarity_contribution","matched_features"],"title":"RelatedPersonConfidence"},"RelatedPersonConfidenceFeature":{"properties":{"match_type":{"type":"string","enum":["technology","job_function","team","location","title_similarity"],"title":"Match Type"},"name":{"type":"string","title":"Name","description":"The matched feature's name; for title_similarity, the related person's own job title."},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug","description":"Null for location and title_similarity matches."},"contribution":{"type":"number","title":"Contribution","description":"Share of the confidence score attributable to this feature."}},"type":"object","required":["match_type","name","contribution"],"title":"RelatedPersonConfidenceFeature"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/people":{"post":{"tags":["people"],"summary":"Unified people endpoint","description":"Find, match, and enrich people. Provide a `people` list (list mode) or a `filter` (search mode) and compose the response with `select`.\n\nOn **v7 and earlier** this endpoint is synchronous: one call returns the people.\n\nOn **v8 and later** it is **asynchronous** in both modes. Send a `people` or `filter` body to start a background job — the response returns a `request_id` and `status: \"pending\"`, and no credits are charged yet (the request is validated and your balance pre-checked, so you still get a `400`/`402` up front). Then send `{ \"request_id\": \"...\" }` to the same endpoint to poll: you get `status` `pending`/`running` until it finishes, then `succeeded` (with the full `people`/`total` result) or `failed`. Credits are charged once, on the first `succeeded` poll; repeat polls report `credits_used: 0`. The async response adds `request_id` and `status` fields.","operationId":"enrich_people_unified__api_version__people_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichPeopleRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichPeopleResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


# Job posts

## Find, match, and enrich job posts

The single endpoint for working with job postings. Provide either a **list of job IDs** to resolve (list mode) or an **advanced query filter** (search mode), and compose exactly which attributes you get back. This replaces the previous `find`, job details, and `find-related-people` endpoints.

### Input

Provide exactly one of:

* **`jobs`** — a list of up to 1,000 jobs to resolve, each identified by its Sumble `job_id`. Covers the previous job details flow. Limited to 200 entries when requesting descriptions and 25 entries when requesting related people.
* **`filter`** — the jobs to return: `organization_ids` (up to 1,000), a saved `organization_list_id`, and/or an advanced `query` (technologies, technology categories, job functions, countries, hiring period, and more). A query on its own searches the whole corpus. Covers the previous `find` flow.

In filter mode, `limit` (default 10, max 200) and `offset` page through results.

### Composable response

The `select` block dictates exactly which attributes return — nothing is mandatory:

* **`attributes`** — a list of job attributes, or `"all"`. Available: `title`, `description` (the full posting text), `location`, `posted_date`, `organization`, and the extracted entities `technologies` (with a `used` flag distinguishing technologies the team uses from ones merely mentioned), `teams`, `job_functions`, `job_levels`, and `projects`. `job_id` and `sumble_url` are always included for free.
* **`related_people`** — the people most relevant to each job, typically hiring managers and team members at the organization. Choose which person attributes to return and a per-job `limit` (default 5, max 25). Available in both modes, for up to 25 jobs per request.

### File output

Set `file_name`, such as `jobs.csv`, to get the results as a file instead of inline `jobs`. The formats and the response shape are in [File downloads](/api/api#file-downloads).

A `.json` file contains one object per job in the same structure as the inline `jobs` results, so the organization stays an object and technologies, teams, job functions, job levels, projects, and related people stay arrays.

A `.csv` or `.xlsx` file contains one row per job. In list mode, unmatched inputs stay as rows with their `input_job_id` column populated. Job and organization scalar values get their own columns. Repeated values (technologies, teams, job functions, job levels, projects, and related people) are compact JSON in one cell.

### Credit cost

Charged per matched job (list mode) or per returned job (search mode). Unmatched inputs are free.

Per job the cost is:

* **1 base credit**, plus:
* **1 credit per paid attribute** requested (`title` is free), plus
* **1 credit per related person** returned.

For example, returning 5 jobs with 3 paid attributes and 2 related people each costs `5 × (1 + 3 + 2) = 30` credits. The API checks affordability up front and returns HTTP `402` before doing any work you can't pay for.

## POST /v9/jobs

> Unified jobs endpoint

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"EnrichJobsRequest":{"properties":{"jobs":{"anyOf":[{"items":{"$ref":"#/components/schemas/JobInput"},"type":"array","maxItems":1000,"minItems":1},{"type":"null"}],"title":"Jobs","description":"List of jobs to enrich by id. One result row per entry, in input order. Mutually exclusive with `filter`."},"filter":{"anyOf":[{"$ref":"#/components/schemas/JobsFilter"},{"type":"null"}],"description":"Query selecting the jobs to return. Mutually exclusive with `jobs`."},"select":{"$ref":"#/components/schemas/JobsSelect","description":"Dictates exactly which attributes are returned."},"limit":{"type":"integer","maximum":200,"minimum":1,"title":"Limit","description":"Maximum number of jobs to return (filter mode only; ignored when `jobs` is provided).","default":10},"offset":{"type":"integer","maximum":10000,"minimum":0,"title":"Offset","description":"Number of results to skip (filter mode only; ignored when `jobs` is provided).","default":0}},"additionalProperties":false,"type":"object","required":["select"],"title":"EnrichJobsRequest"},"JobInput":{"properties":{"job_id":{"type":"integer","minimum":1,"title":"Job Id","description":"Job id on Sumble."}},"additionalProperties":false,"type":"object","required":["job_id"],"title":"JobInput"},"JobsFilter":{"properties":{"organization_ids":{"anyOf":[{"items":{"type":"integer"},"type":"array","maxItems":1000,"minItems":1},{"type":"null"}],"title":"Organization Ids","description":"Sumble organization ids to scope the search to. Unknown ids simply match no jobs."},"organization_list_id":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Organization List Id","description":"Id of one of your saved organization lists (see /organization-lists) whose organizations to search within. Combined with `organization_ids` when both are provided."},"query":{"anyOf":[{"$ref":"#/components/schemas/Query"},{"type":"null"}],"description":"Advanced query narrowing the jobs returned (technologies, technology categories, job functions, countries, hiring period, ...)."}},"additionalProperties":false,"type":"object","title":"JobsFilter"},"Query":{"properties":{"query":{"type":"string","title":"Query"}},"type":"object","required":["query"],"title":"Query"},"JobsSelect":{"properties":{"attributes":{"anyOf":[{"items":{"type":"string","enum":["title","description","location","posted_date","organization","technologies","teams","job_functions","job_levels","projects"]},"type":"array"},{"type":"string","const":"all"}],"title":"Attributes","description":"Job attributes to include, or 'all' for every available attribute (including the full `description`). Off by default. Note that 'all' grows — and its cost grows — as new attributes are added to the endpoint.","default":[]},"related_people":{"anyOf":[{"$ref":"#/components/schemas/JobRelatedPeopleSelection"},{"type":"null"}],"description":"Also return the people likely involved in each job's hiring — scored hiring managers and team members at the posting organization, inferred from team, job function, location and technology similarity, not actual reporting lines. Available in both modes, for at most 200 jobs per request. Each related person returned costs 1 credit."}},"additionalProperties":false,"type":"object","title":"JobsSelect"},"JobRelatedPeopleSelection":{"properties":{"attributes":{"anyOf":[{"items":{"type":"string","enum":["name","email","phone","linkedin_url","job_title","job_function","job_level","location","country","current_employer","technologies","person_score","confidence"]},"type":"array"},{"type":"string","const":"all"}],"title":"Attributes","description":"Person-level attributes to include for each related person, or 'all' for every attribute available here. Contact attributes (email, phone) and `person_score` are not available here; `confidence` (the inferred relationship's score breakdown) is only available here.","default":[]},"limit":{"type":"integer","maximum":25,"minimum":1,"title":"Limit","description":"Maximum related people returned per job.","default":5},"job_levels":{"items":{"type":"string"},"type":"array","title":"Job Levels","description":"Only return related people whose job level is one of these (by name, e.g. 'Director', 'VP'); matching is OR across the list. When provided, this replaces the default seniority filter. When empty (the default), only likely hiring managers are returned — people at Manager level or above, and more senior than the role.","default":[]},"job_functions":{"items":{"type":"string"},"type":"array","title":"Job Functions","description":"Only return related people whose primary job function is one of these (by name, e.g. 'Engineering') or a descendant of one; matching is OR across the list and all descendants. Combined with `job_levels` as AND. Empty (the default) applies no job function filter.","default":[]},"sort_order":{"type":"string","enum":["score","level"],"title":"Sort Order","description":"How related people are ranked: 'score' (similarity score, the default; ties broken by seniority) or 'level' (seniority; ties broken by score).","default":"score"},"sort_direction":{"type":"string","enum":["desc","asc"],"title":"Sort Direction","description":"Direction for `sort_order`. The default 'desc' puts the highest score / most senior people first.","default":"desc"}},"additionalProperties":false,"type":"object","title":"JobRelatedPeopleSelection"},"EnrichJobsResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"jobs":{"items":{"$ref":"#/components/schemas/JobRow"},"type":"array","title":"Jobs"},"matched_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Matched Count","description":"List mode only: how many input entries matched a Sumble job."},"total":{"type":"integer","title":"Total"},"source_data_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Source Data Url"}},"type":"object","required":["id","credits_used","credits_remaining","jobs","total"],"title":"EnrichJobsResponse"},"JobRow":{"properties":{"input":{"anyOf":[{"$ref":"#/components/schemas/JobInput"},{"type":"null"}],"description":"The input entry this row corresponds to (list mode only)."},"job_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Job Id","description":"Absent when the input entry didn't match a Sumble job."},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url","description":"Link to the job posting's Sumble page."},"attributes":{"anyOf":[{"$ref":"#/components/schemas/JobAttributes"},{"type":"null"}],"description":"The requested job attributes; absent when none are requested."},"related_people":{"anyOf":[{"items":{"$ref":"#/components/schemas/RelatedPersonRow"},"type":"array"},{"type":"null"}],"title":"Related People","description":"Scored hiring managers / team members for the job. Present (possibly empty) when `select.related_people` is requested and the job matched; absent otherwise."}},"type":"object","title":"JobRow"},"JobAttributes":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"posted_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Posted Date"},"organization":{"anyOf":[{"$ref":"#/components/schemas/JobOrganization"},{"type":"null"}]},"technologies":{"anyOf":[{"items":{"$ref":"#/components/schemas/JobTechnology"},"type":"array"},{"type":"null"}],"title":"Technologies","description":"All technologies extracted from the posting; empty list when requested but none were extracted."},"teams":{"anyOf":[{"items":{"$ref":"#/components/schemas/JobTeam"},"type":"array"},{"type":"null"}],"title":"Teams","description":"Teams extracted from the posting; empty list when requested but none were extracted."},"job_functions":{"anyOf":[{"items":{"$ref":"#/components/schemas/app__schemas__paid_api__jobs_unified__JobFunction"},"type":"array"},{"type":"null"}],"title":"Job Functions","description":"Job functions classified from the posting; empty list when requested but none were classified."},"job_levels":{"anyOf":[{"items":{"$ref":"#/components/schemas/app__schemas__paid_api__jobs_unified__JobLevel"},"type":"array"},{"type":"null"}],"title":"Job Levels","description":"Seniority levels classified from the posting; empty list when requested but none were classified."},"projects":{"anyOf":[{"items":{"$ref":"#/components/schemas/JobProject"},"type":"array"},{"type":"null"}],"title":"Projects","description":"Projects extracted from the posting; empty list when requested but none were extracted."}},"type":"object","title":"JobAttributes"},"JobOrganization":{"properties":{"organization_id":{"type":"integer","title":"Organization Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url","description":"Link to the organization's Sumble profile page."}},"type":"object","required":["organization_id"],"title":"JobOrganization"},"JobTechnology":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"used":{"type":"boolean","title":"Used","description":"True when the posting indicates the technology is used by the team, not merely mentioned."},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url","description":"The posting organization's jobs page filtered to this technology."}},"type":"object","required":["name","slug","used"],"title":"JobTechnology"},"JobTeam":{"properties":{"team_id":{"type":"integer","title":"Team Id"},"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url","description":"Link to the team's Sumble page."}},"type":"object","required":["team_id","name","slug"],"title":"JobTeam"},"app__schemas__paid_api__jobs_unified__JobFunction":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url","description":"The posting organization's jobs page filtered to this job function."}},"type":"object","required":["name","slug"],"title":"JobFunction"},"app__schemas__paid_api__jobs_unified__JobLevel":{"properties":{"name":{"type":"string","title":"Name"}},"type":"object","required":["name"],"title":"JobLevel"},"JobProject":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"goal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Goal"},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url","description":"The posting organization's jobs page filtered to this project."}},"type":"object","required":["name","slug"],"title":"JobProject"},"RelatedPersonRow":{"properties":{"person_id":{"type":"integer","title":"Person Id"},"sumble_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Sumble Url","description":"Link to the person's Sumble profile page."},"confidence":{"anyOf":[{"$ref":"#/components/schemas/RelatedPersonConfidence"},{"type":"null"}],"description":"Why this person was returned: confidence score (0-1) with per-category and per-feature breakdowns. Present when the `confidence` attribute is requested. Not the ICP-based `person_score`."},"attributes":{"anyOf":[{"$ref":"#/components/schemas/PersonAttributes"},{"type":"null"}],"description":"The requested person-level attributes; absent when none resolve."}},"type":"object","required":["person_id","sumble_url"],"title":"RelatedPersonRow"},"RelatedPersonConfidence":{"properties":{"score":{"type":"number","title":"Score","description":"How strongly this person relates to the source person (people endpoint) or job posting (jobs endpoint), 0-1. Sum of the five contributions below. Measures similarity on shared features (technologies, job functions, teams, locations, job titles) — unrelated to the ICP-based `person_score` attribute."},"technology_contribution":{"type":"number","title":"Technology Contribution","description":"Share from technologies shared with the source."},"job_function_contribution":{"type":"number","title":"Job Function Contribution","description":"Share from matching job functions."},"team_contribution":{"type":"number","title":"Team Contribution","description":"Share from shared teams."},"location_contribution":{"type":"number","title":"Location Contribution","description":"Share from matching locations."},"title_similarity_contribution":{"type":"number","title":"Title Similarity Contribution","description":"Share from semantic similarity between job titles."},"matched_features":{"items":{"$ref":"#/components/schemas/RelatedPersonConfidenceFeature"},"type":"array","title":"Matched Features","description":"The specific matched features behind the contributions, highest contribution first."}},"type":"object","required":["score","technology_contribution","job_function_contribution","team_contribution","location_contribution","title_similarity_contribution","matched_features"],"title":"RelatedPersonConfidence"},"RelatedPersonConfidenceFeature":{"properties":{"match_type":{"type":"string","enum":["technology","job_function","team","location","title_similarity"],"title":"Match Type"},"name":{"type":"string","title":"Name","description":"The matched feature's name; for title_similarity, the related person's own job title."},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug","description":"Null for location and title_similarity matches."},"contribution":{"type":"number","title":"Contribution","description":"Share of the confidence score attributable to this feature."}},"type":"object","required":["match_type","name","contribution"],"title":"RelatedPersonConfidenceFeature"},"PersonAttributes":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Revealed work email (match mode only). The first successful reveal per person costs 10 credits; repeat reveals while active are free."},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone","description":"Revealed phone number (match mode only). The first successful reveal per person costs 80 credits; repeat reveals while active are free."},"linkedin_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Linkedin Url"},"job_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Title"},"job_function":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Function"},"job_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Level"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"current_employer":{"anyOf":[{"$ref":"#/components/schemas/CurrentEmployer"},{"type":"null"}]},"technologies":{"anyOf":[{"items":{"$ref":"#/components/schemas/PersonTechnology"},"type":"array"},{"type":"null"}],"title":"Technologies","description":"Technologies from the skills on the person's LinkedIn profile, normalized to Sumble's technology catalog. The slug can be used in `filter.query` (technology EQ '<slug>'). Empty when none of the profile's skills map to a known technology."},"person_score":{"anyOf":[{"$ref":"#/components/schemas/PersonScore"},{"type":"null"}],"description":"How well the person matches your ideal customer profile (ICP), 0-100, with a per-feature breakdown. Priced like other paid attributes. Filter mode only; selecting it explicitly requires the filter to resolve to exactly one organization and an ICP configured for your account (`attributes: \"all\"` skips it instead when unavailable). Included automatically when sorting with `order_by_column=\"person_score\"`."}},"type":"object","title":"PersonAttributes"},"CurrentEmployer":{"properties":{"organization_id":{"type":"integer","title":"Organization Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date","description":"Start of the person's current role (YYYY-MM)."},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url","description":"Link to the organization's Sumble profile page."}},"type":"object","required":["organization_id"],"title":"CurrentEmployer"},"PersonTechnology":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"}},"type":"object","required":["name","slug"],"title":"PersonTechnology"},"PersonScore":{"properties":{"value":{"type":"number","title":"Value","description":"How well the person matches your ideal customer profile (ICP), 0-100. Sum of the three contributions below."},"skill_contribution":{"type":"number","title":"Skill Contribution","description":"Points from technologies the person uses that match your ICP."},"job_function_contribution":{"type":"number","title":"Job Function Contribution","description":"Points from the person's job function matching your ICP."},"seniority_contribution":{"type":"number","title":"Seniority Contribution","description":"Points from the person's job level (seniority)."},"matched_features":{"items":{"$ref":"#/components/schemas/PersonScoreFeature"},"type":"array","title":"Matched Features","description":"The matched technologies and job functions behind the skill and job-function contributions, highest contribution first."}},"type":"object","required":["value","skill_contribution","job_function_contribution","seniority_contribution","matched_features"],"title":"PersonScore"},"PersonScoreFeature":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"match_type":{"type":"string","enum":["technology","job_function"],"title":"Match Type"},"contribution":{"type":"number","title":"Contribution","description":"Points of the 0-100 score attributable to this feature."}},"type":"object","required":["name","slug","match_type","contribution"],"title":"PersonScoreFeature"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/jobs":{"post":{"tags":["jobs"],"summary":"Unified jobs endpoint","operationId":"enrich_jobs_unified__api_version__jobs_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichJobsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichJobsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


# Teams

## Find and enrich teams

The single endpoint for working with teams — the groups Sumble extracts from an organization's job postings (for example "Platform Engineering" or "Data Science") and organizes into a per-organization hierarchy. Provide either a **list of team IDs** to resolve (list mode) or an **organization-scoped filter** (search mode), and compose exactly which attributes you get back per team.

### Input

Provide exactly one of:

* **`teams`** — a list of up to 1,000 teams to resolve, each identified by its Sumble `team_id` (for example the `team_id`s returned on the extracted teams of the job posts endpoint). Returns one row per entry, in input order.
* **`filter`** — the teams to return: one or more `organization_ids` (up to 1,000), optionally narrowed by an advanced `query` (technologies, technology categories, job functions, hiring period) and a `since` date. Teams are returned for the listed organizations only — there is no parent/subsidiary roll-up, so pass subsidiary organization IDs explicitly to include their teams.

In filter mode, `limit` (default 10, max 200) and `offset` page through results, and `order_by_column` sorts by `jobs_count`, `first_activity`, `last_activity`, or `score` (default `jobs_count`, descending). Sorting by `score` requires exactly one organization in scope and an ICP configured for your account. `since` windows the activity-based metrics (`jobs_count`, `first_activity`, `last_activity`) to postings on or after that date; the aggregated lists below remain all-time. List mode returns teams in input order.

### Composable response

The `select` block dictates exactly which attributes return — nothing is mandatory:

* **`attributes`** — a list of team attributes, or `"all"`. Available: `organization`, `breadcrumbs` (the team's parent chain), `jobs_count`, `technology_list`, `job_function_list`, `location_list`, `first_activity`, `last_activity`, and `score`. `team_id`, `name`, and `sumble_url` are always included for free.
  * `score` is your ICP match score (0–100) for the team — a Great / Good / Possible fit bucket with its per-feature contribution breakdown. Like the people endpoint's `person_score`, it requires filter mode with exactly one organization in scope and an ICP configured; `"all"` includes it opportunistically when those requirements are met.
* **`related_people`** — the people associated with each team, each with a person–team `confidence` breakdown. Choose which person attributes to return (the same attributes as the people endpoint, excluding the contact details `email`/`phone`) and a per-team cap `max_per_team` (default 10, max 100). Available in both modes, for up to 25 teams per request.
* **`job_posts`** — the job postings mentioning each team. Choose which `components` to return — `job_details`, `technologies`, `job_functions`, `job_level`, or `"all"` — a per-team cap `max_per_team` (default 10, max 100), and an optional `since` window. Full description text is not available here; fetch it from the job posts endpoint using the returned `job_id`s.

Results are always a flat list; `breadcrumbs` gives each team's parent chain (for example Engineering → Platform → SRE). A team's job metrics count postings that mention it directly or via a child team, so one posting can count toward several teams.

### Credit cost

Charged per matched team (list mode) or per returned team (search mode). Unmatched inputs are free.

Per team the cost is:

* **1 base credit**, plus:
* **1 credit per paid attribute** requested (`score` counts as one paid attribute), plus
* **1 credit per related person** returned, plus
* **1 credit per job post** returned.

For example, returning 10 teams with 3 paid attributes and 5 related people each costs `10 × (1 + 3 + 5) = 90` credits. The API checks affordability up front and returns HTTP `402` before doing any work you can't pay for.

## POST /v9/teams

> Unified teams endpoint

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"FindTeamsRequest":{"properties":{"teams":{"anyOf":[{"items":{"type":"integer"},"type":"array","maxItems":1000,"minItems":1},{"type":"null"}],"title":"Teams","description":"List of Sumble team ids to retrieve and enrich. One result row per entry, in input order. Mutually exclusive with `filter`."},"filter":{"anyOf":[{"$ref":"#/components/schemas/TeamsFilter"},{"type":"null"}],"description":"Query selecting the teams to return. Mutually exclusive with `teams`."},"select":{"$ref":"#/components/schemas/TeamsSelect","description":"Dictates exactly which attributes are returned."},"limit":{"type":"integer","maximum":200,"minimum":1,"title":"Limit","description":"Maximum number of teams to return (filter mode only; ignored when `teams` is provided).","default":10},"offset":{"type":"integer","maximum":10000,"minimum":0,"title":"Offset","description":"Number of results to skip (filter mode only; ignored when `teams` is provided).","default":0},"order_by_column":{"anyOf":[{"type":"string","enum":["jobs_count","first_activity","last_activity","score"]},{"type":"null"}],"title":"Order By Column","description":"Column to order by (filter mode only): `jobs_count`, `first_activity` or `last_activity`. Default: jobs_count."},"order_by_direction":{"anyOf":[{"type":"string","enum":["ASC","DESC"]},{"type":"null"}],"title":"Order By Direction","description":"Sort direction; DESC when omitted."}},"additionalProperties":false,"type":"object","required":["select"],"title":"FindTeamsRequest"},"TeamsFilter":{"properties":{"organization_ids":{"items":{"type":"integer"},"type":"array","maxItems":1000,"minItems":1,"title":"Organization Ids","description":"Sumble organization ids to search within. Teams are returned for these organizations only — no parent/subsidiary roll-up. Unknown ids simply match no teams."},"query":{"anyOf":[{"$ref":"#/components/schemas/Query"},{"type":"null"}],"description":"Advanced query narrowing the teams returned (technologies, technology categories, job functions, hiring period)."},"since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since","description":"Only count activity (jobs_count, first/last activity) on or after this date (YYYY-MM-DD). Does not affect the aggregated technology / job-function / location lists, which are all-time."}},"additionalProperties":false,"type":"object","required":["organization_ids"],"title":"TeamsFilter"},"Query":{"properties":{"query":{"type":"string","title":"Query"}},"type":"object","required":["query"],"title":"Query"},"TeamsSelect":{"properties":{"attributes":{"anyOf":[{"items":{"type":"string","enum":["organization","breadcrumbs","jobs_count","technology_list","job_function_list","location_list","first_activity","last_activity","score"]},"type":"array"},{"type":"string","const":"all"}],"title":"Attributes","description":"Team attributes to include, or 'all' for every available attribute. Off by default. 'all' includes `score` only when it is available (an ICP configured for your account) — otherwise it is skipped, not an error. Note that 'all' grows — and its cost grows — as new attributes are added to the endpoint.","default":[]},"related_people":{"anyOf":[{"$ref":"#/components/schemas/TeamRelatedPeopleSelection"},{"type":"null"}],"description":"Also return the people associated with each team, with a person-team match score. Available in both modes. Each related person returned costs 1 credit."},"job_posts":{"anyOf":[{"$ref":"#/components/schemas/JobPostsSelection"},{"type":"null"}],"description":"Also return the job postings mentioning each team, with composable job components. Each job posting returned costs 1 credit."}},"additionalProperties":false,"type":"object","title":"TeamsSelect"},"TeamRelatedPeopleSelection":{"properties":{"attributes":{"anyOf":[{"items":{"type":"string","enum":["name","email","phone","linkedin_url","job_title","job_function","job_level","location","country","current_employer","technologies","person_score","confidence"]},"type":"array"},{"type":"string","const":"all"}],"title":"Attributes","description":"Person-level attributes to include for each related person, or 'all' for every attribute available here. Contact attributes (email, phone) and `person_score` are not available here; `confidence` (the person-team match score breakdown) is only available here.","default":[]},"max_per_team":{"type":"integer","maximum":100,"minimum":1,"title":"Max Per Team","description":"Maximum related people returned per team.","default":10}},"additionalProperties":false,"type":"object","title":"TeamRelatedPeopleSelection"},"JobPostsSelection":{"properties":{"components":{"anyOf":[{"items":{"type":"string","enum":["job_details","technologies","job_functions","job_level"]},"type":"array"},{"type":"string","const":"all"}],"title":"Components","description":"Job components to return per posting, or 'all' for every available component. Mirrors the unified jobs endpoint: `job_details` (title, location, posted date), `technologies`, `job_functions`, `job_level`. Never includes the full description (fetch that from the jobs endpoint with the returned job ids).","default":[]},"max_per_team":{"type":"integer","maximum":100,"minimum":1,"title":"Max Per Team","description":"Maximum job postings returned per team.","default":10},"since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Since","description":"Only return job postings pulled on or after this date (YYYY-MM-DD)."}},"additionalProperties":false,"type":"object","title":"JobPostsSelection"},"FindTeamsResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"teams":{"items":{"$ref":"#/components/schemas/TeamResultRow"},"type":"array","title":"Teams"},"matched_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Matched Count","description":"List mode only: how many input ids matched a Sumble team."},"total":{"type":"integer","title":"Total"},"source_data_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Source Data Url"}},"type":"object","required":["id","credits_used","credits_remaining","teams","total"],"title":"FindTeamsResponse"},"TeamResultRow":{"properties":{"input":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Input","description":"The input team id this row corresponds to (list mode only)."},"team_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Team Id","description":"Absent when the input id didn't match a Sumble team."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url","description":"Link to the team's Sumble page."},"attributes":{"anyOf":[{"$ref":"#/components/schemas/TeamAttributes"},{"type":"null"}],"description":"The requested team attributes; absent when none are requested."},"related_people":{"anyOf":[{"items":{"$ref":"#/components/schemas/TeamRelatedPersonRow"},"type":"array"},{"type":"null"}],"title":"Related People","description":"People associated with the team. Present (possibly empty) when `select.related_people` is requested and the team matched; absent otherwise."},"job_posts":{"anyOf":[{"items":{"$ref":"#/components/schemas/TeamJobPostRow"},"type":"array"},{"type":"null"}],"title":"Job Posts","description":"Job postings mentioning the team. Present (possibly empty) when `select.job_posts` is requested and the team matched; absent otherwise."}},"type":"object","title":"TeamResultRow"},"TeamAttributes":{"properties":{"organization":{"anyOf":[{"$ref":"#/components/schemas/TeamOrganization"},{"type":"null"}]},"breadcrumbs":{"anyOf":[{"items":{"$ref":"#/components/schemas/TeamBreadcrumb"},"type":"array"},{"type":"null"}],"title":"Breadcrumbs","description":"Parent-team chain from the root to this team."},"jobs_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Jobs Count"},"technology_list":{"anyOf":[{"items":{"$ref":"#/components/schemas/TeamTechnology"},"type":"array"},{"type":"null"}],"title":"Technology List","description":"Technologies the team uses, aggregated from its job postings (all-time)."},"job_function_list":{"anyOf":[{"items":{"$ref":"#/components/schemas/TeamJobFunction"},"type":"array"},{"type":"null"}],"title":"Job Function List","description":"Job functions the team hires for, aggregated from its job postings (all-time)."},"location_list":{"anyOf":[{"items":{"$ref":"#/components/schemas/TeamLocation"},"type":"array"},{"type":"null"}],"title":"Location List","description":"Locations where the team operates, derived from its job postings (all-time)."},"first_activity":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Activity","description":"Earliest job posting mentioning the team."},"last_activity":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Activity","description":"Latest job posting mentioning the team."},"score":{"anyOf":[{"$ref":"#/components/schemas/TeamScore"},{"type":"null"}],"description":"Sumble team score against your ICP, 0-100. Returned only when an ICP is configured for your account (`attributes: \"all\"` skips it otherwise instead of erroring)."}},"type":"object","title":"TeamAttributes"},"TeamOrganization":{"properties":{"organization_id":{"type":"integer","title":"Organization Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url","description":"Link to the organization's Sumble profile page."}},"type":"object","required":["organization_id"],"title":"TeamOrganization"},"TeamBreadcrumb":{"properties":{"team_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Team Id"},"name":{"type":"string","title":"Name"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug"},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url","description":"Link to the ancestor team's Sumble page."}},"type":"object","required":["name"],"title":"TeamBreadcrumb"},"TeamTechnology":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"used":{"type":"boolean","title":"Used","description":"True when the team's postings indicate the technology is used, not merely mentioned.","default":false},"jobs_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Jobs Count","description":"Job postings mentioning this technology for the team."}},"type":"object","required":["name","slug"],"title":"TeamTechnology"},"TeamJobFunction":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"jobs_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Jobs Count","description":"Job postings hiring for this job function for the team."}},"type":"object","required":["name","slug"],"title":"TeamJobFunction"},"TeamLocation":{"properties":{"name":{"type":"string","title":"Name"},"jobs_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Jobs Count","description":"Job postings for the team in this location."}},"type":"object","required":["name"],"title":"TeamLocation"},"TeamScore":{"properties":{"value":{"type":"number","title":"Value","description":"How well the team matches your ideal customer profile (ICP), 0-100."},"fit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fit","description":"Qualitative fit bucket (e.g. 'Great', 'Good', 'Possible')."},"components":{"items":{"$ref":"#/components/schemas/TeamScoreComponent"},"type":"array","title":"Components","description":"The matched features behind the score, highest contribution first.","default":[]}},"type":"object","required":["value"],"title":"TeamScore"},"TeamScoreComponent":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug"},"match_type":{"type":"string","title":"Match Type"},"contribution":{"type":"number","title":"Contribution","description":"Points of the 0-100 score attributable to this feature."}},"type":"object","required":["match_type","contribution"],"title":"TeamScoreComponent"},"TeamRelatedPersonRow":{"properties":{"person_id":{"type":"integer","title":"Person Id"},"sumble_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Sumble Url","description":"Link to the person's Sumble profile page."},"confidence":{"anyOf":[{"$ref":"#/components/schemas/TeamMembershipConfidence"},{"type":"null"}],"description":"Why this person was returned: person-team match score with a per-feature breakdown. Present when the `confidence` attribute is requested."},"attributes":{"anyOf":[{"$ref":"#/components/schemas/PersonAttributes"},{"type":"null"}],"description":"The requested person-level attributes; absent when none resolve."}},"type":"object","required":["person_id","sumble_url"],"title":"TeamRelatedPersonRow"},"TeamMembershipConfidence":{"properties":{"score":{"type":"number","title":"Score","description":"How strongly this person relates to the team, based on shared team, job-function, technology, location and title-embedding signals. Unrelated to the ICP-based team `score` attribute."},"matched_features":{"items":{"$ref":"#/components/schemas/TeamMembershipFeature"},"type":"array","title":"Matched Features","description":"The specific matched features behind the score.","default":[]}},"type":"object","required":["score"],"title":"TeamMembershipConfidence"},"TeamMembershipFeature":{"properties":{"match_type":{"type":"string","enum":["team","job_function","technology","location","embedding"],"title":"Match Type"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug"},"is_parent":{"type":"boolean","title":"Is Parent","default":false},"score":{"type":"number","title":"Score","description":"Share of the match score attributable to this feature."}},"type":"object","required":["match_type","score"],"title":"TeamMembershipFeature"},"PersonAttributes":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email","description":"Revealed work email (match mode only). The first successful reveal per person costs 10 credits; repeat reveals while active are free."},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone","description":"Revealed phone number (match mode only). The first successful reveal per person costs 80 credits; repeat reveals while active are free."},"linkedin_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Linkedin Url"},"job_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Title"},"job_function":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Function"},"job_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Level"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"current_employer":{"anyOf":[{"$ref":"#/components/schemas/CurrentEmployer"},{"type":"null"}]},"technologies":{"anyOf":[{"items":{"$ref":"#/components/schemas/PersonTechnology"},"type":"array"},{"type":"null"}],"title":"Technologies","description":"Technologies from the skills on the person's LinkedIn profile, normalized to Sumble's technology catalog. The slug can be used in `filter.query` (technology EQ '<slug>'). Empty when none of the profile's skills map to a known technology."},"person_score":{"anyOf":[{"$ref":"#/components/schemas/PersonScore"},{"type":"null"}],"description":"How well the person matches your ideal customer profile (ICP), 0-100, with a per-feature breakdown. Priced like other paid attributes. Filter mode only; selecting it explicitly requires the filter to resolve to exactly one organization and an ICP configured for your account (`attributes: \"all\"` skips it instead when unavailable). Included automatically when sorting with `order_by_column=\"person_score\"`."}},"type":"object","title":"PersonAttributes"},"CurrentEmployer":{"properties":{"organization_id":{"type":"integer","title":"Organization Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date","description":"Start of the person's current role (YYYY-MM)."},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url","description":"Link to the organization's Sumble profile page."}},"type":"object","required":["organization_id"],"title":"CurrentEmployer"},"PersonTechnology":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"}},"type":"object","required":["name","slug"],"title":"PersonTechnology"},"PersonScore":{"properties":{"value":{"type":"number","title":"Value","description":"How well the person matches your ideal customer profile (ICP), 0-100. Sum of the three contributions below."},"skill_contribution":{"type":"number","title":"Skill Contribution","description":"Points from technologies the person uses that match your ICP."},"job_function_contribution":{"type":"number","title":"Job Function Contribution","description":"Points from the person's job function matching your ICP."},"seniority_contribution":{"type":"number","title":"Seniority Contribution","description":"Points from the person's job level (seniority)."},"matched_features":{"items":{"$ref":"#/components/schemas/PersonScoreFeature"},"type":"array","title":"Matched Features","description":"The matched technologies and job functions behind the skill and job-function contributions, highest contribution first."}},"type":"object","required":["value","skill_contribution","job_function_contribution","seniority_contribution","matched_features"],"title":"PersonScore"},"PersonScoreFeature":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"match_type":{"type":"string","enum":["technology","job_function"],"title":"Match Type"},"contribution":{"type":"number","title":"Contribution","description":"Points of the 0-100 score attributable to this feature."}},"type":"object","required":["name","slug","match_type","contribution"],"title":"PersonScoreFeature"},"TeamJobPostRow":{"properties":{"job_id":{"type":"integer","title":"Job Id"},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url","description":"Link to the job posting's Sumble page."},"attributes":{"anyOf":[{"$ref":"#/components/schemas/JobAttributes"},{"type":"null"}],"description":"The requested job components; absent when none are requested."}},"type":"object","required":["job_id"],"title":"TeamJobPostRow"},"JobAttributes":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"posted_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Posted Date"},"organization":{"anyOf":[{"$ref":"#/components/schemas/JobOrganization"},{"type":"null"}]},"technologies":{"anyOf":[{"items":{"$ref":"#/components/schemas/JobTechnology"},"type":"array"},{"type":"null"}],"title":"Technologies","description":"All technologies extracted from the posting; empty list when requested but none were extracted."},"teams":{"anyOf":[{"items":{"$ref":"#/components/schemas/JobTeam"},"type":"array"},{"type":"null"}],"title":"Teams","description":"Teams extracted from the posting; empty list when requested but none were extracted."},"job_functions":{"anyOf":[{"items":{"$ref":"#/components/schemas/app__schemas__paid_api__jobs_unified__JobFunction"},"type":"array"},{"type":"null"}],"title":"Job Functions","description":"Job functions classified from the posting; empty list when requested but none were classified."},"job_levels":{"anyOf":[{"items":{"$ref":"#/components/schemas/app__schemas__paid_api__jobs_unified__JobLevel"},"type":"array"},{"type":"null"}],"title":"Job Levels","description":"Seniority levels classified from the posting; empty list when requested but none were classified."},"projects":{"anyOf":[{"items":{"$ref":"#/components/schemas/JobProject"},"type":"array"},{"type":"null"}],"title":"Projects","description":"Projects extracted from the posting; empty list when requested but none were extracted."}},"type":"object","title":"JobAttributes"},"JobOrganization":{"properties":{"organization_id":{"type":"integer","title":"Organization Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url","description":"Link to the organization's Sumble profile page."}},"type":"object","required":["organization_id"],"title":"JobOrganization"},"JobTechnology":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"used":{"type":"boolean","title":"Used","description":"True when the posting indicates the technology is used by the team, not merely mentioned."},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url","description":"The posting organization's jobs page filtered to this technology."}},"type":"object","required":["name","slug","used"],"title":"JobTechnology"},"JobTeam":{"properties":{"team_id":{"type":"integer","title":"Team Id"},"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url","description":"Link to the team's Sumble page."}},"type":"object","required":["team_id","name","slug"],"title":"JobTeam"},"app__schemas__paid_api__jobs_unified__JobFunction":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url","description":"The posting organization's jobs page filtered to this job function."}},"type":"object","required":["name","slug"],"title":"JobFunction"},"app__schemas__paid_api__jobs_unified__JobLevel":{"properties":{"name":{"type":"string","title":"Name"}},"type":"object","required":["name"],"title":"JobLevel"},"JobProject":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"goal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Goal"},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url","description":"The posting organization's jobs page filtered to this project."}},"type":"object","required":["name","slug"],"title":"JobProject"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/teams":{"post":{"tags":["teams"],"summary":"Unified teams endpoint","operationId":"find_teams__api_version__teams_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindTeamsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindTeamsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


# ID & slug lookups

Resolve human-readable names to the canonical slugs and identifiers that the core data endpoints expect in their filters. Use these to turn a spreadsheet of names — technologies, projects, or job titles — into stable identifiers before querying.

* [Technology find](/api/lookups/technologies) — search the technology catalog and resolve names, slugs, or aliases to canonical technologies and categories
* [Project find](/api/lookups/projects) — resolve project names or slugs to canonical projects
* [Job function & level lookup](/api/lookups/job-title-lookup) — resolve raw job titles to canonical job function and level identifiers
* [Location find](/api/lookups/locations). Find codes for the `hq_location` and `country` filters by searching names or listing a location's children.


# Technology find

## Find technologies

Search Sumble's technology catalog by name. Returns up to 50 technologies whose names match the query, ranked by exact-name match first and then by how many organizations mention the technology across jobs and people.

Each result includes the technology `slug` (the canonical identifier you can pass to other API endpoints, such as organization filters), the display `name`, and a `count` of organizations that mention it. The response also returns `total_count` — the total number of matching technologies in the catalog, which may exceed the 50 rows returned.

Use this endpoint to look up valid technology slugs before calling endpoints that accept a technology filter.

### File output

Set `file_name` to get the matches as a file. See [File downloads](/api/api#file-downloads). The file contains one row per returned technology with its slug, name, and organization count.

### Credit cost

1 credit per request that returns at least one technology. Requests with no matches do not consume credits.

## POST /v9/technologies/find

> Find technologies by name

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"GetTechnologiesRequest":{"properties":{"query":{"type":"string","title":"Query"}},"type":"object","required":["query"],"title":"GetTechnologiesRequest"},"GetTechnologiesResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"technologies":{"items":{"$ref":"#/components/schemas/app__schemas__paid_api__technologies__GetTechnologiesResponse__TechDetails"},"type":"array","title":"Technologies"},"total_count":{"type":"integer","title":"Total Count"}},"type":"object","required":["id","credits_used","credits_remaining","technologies","total_count"],"title":"GetTechnologiesResponse"},"app__schemas__paid_api__technologies__GetTechnologiesResponse__TechDetails":{"properties":{"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["slug","name","count"],"title":"TechDetails"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/technologies/find":{"post":{"tags":["technologies"],"summary":"Find technologies by name","operationId":"get_technologies__api_version__technologies_find_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTechnologiesRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTechnologiesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

***

## Look up technologies

Resolve a list of technology names, slugs, or aliases to their canonical Sumble technologies. Pass a `technologies` array (1–1000 entries) and receive one entry in `results` for every input, in the same order you supplied them.

Each result pairs your original `input` with the matched `technology`, or `null` when nothing matches — so the response always lines up one-to-one with your request. Use its canonical `slug` as the identifier for other API endpoints, such as organization filters. A matched technology also lists the `categories` it belongs to.

The response also returns `matched_count`, the number of inputs that resolved to a technology.

Use this endpoint when you already have a set of technology names, slugs, or aliases — for example, from a spreadsheet or a prior call — and need stable, canonical identifiers to pass into follow-up requests. To search the catalog by a single partial name instead, use [Find technologies](#find-technologies).

### File output

Set `file_name` to get the matches as a file. See [File downloads](/api/api#file-downloads).

A `.json` file contains one object per input in the same structure as the inline `results`, so the matched technology stays an object with its categories nested.

A `.csv` or `.xlsx` file contains one row per input, including unmatched inputs, with separate columns for the matched technology's ID, slug, and name. `categories` contains compact JSON text in its cell.

### Credit cost

1 credit per 100 matched technologies. Unmatched inputs do not consume credits.

## POST /v9/technologies/lookup

> Look up technologies by name, slug, or alias

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"LookupTechnologiesRequest":{"properties":{"technologies":{"items":{"type":"string"},"type":"array","maxItems":1000,"minItems":1,"title":"Technologies","description":"List of technology names, slugs, or aliases to look up"}},"type":"object","required":["technologies"],"title":"LookupTechnologiesRequest"},"LookupTechnologiesResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"matched_count":{"type":"integer","title":"Matched Count"},"results":{"items":{"$ref":"#/components/schemas/app__schemas__paid_api__technologies__LookupTechnologiesResponse__LookupResult"},"type":"array","title":"Results"}},"type":"object","required":["id","credits_used","credits_remaining","matched_count","results"],"title":"LookupTechnologiesResponse"},"app__schemas__paid_api__technologies__LookupTechnologiesResponse__LookupResult":{"properties":{"input":{"type":"string","title":"Input"},"technology":{"anyOf":[{"$ref":"#/components/schemas/app__schemas__paid_api__technologies__LookupTechnologiesResponse__TechDetails"},{"type":"null"}]}},"type":"object","required":["input","technology"],"title":"LookupResult"},"app__schemas__paid_api__technologies__LookupTechnologiesResponse__TechDetails":{"properties":{"id":{"type":"integer","title":"Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"categories":{"items":{"$ref":"#/components/schemas/TechCategory"},"type":"array","title":"Categories"}},"type":"object","required":["id","slug","name","categories"],"title":"TechDetails"},"TechCategory":{"properties":{"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"name_short":{"type":"string","title":"Name Short"}},"type":"object","required":["slug","name","name_short"],"title":"TechCategory"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/technologies/lookup":{"post":{"tags":["technologies"],"summary":"Look up technologies by name, slug, or alias","operationId":"lookup_technologies__api_version__technologies_lookup_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupTechnologiesRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupTechnologiesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

***

## Look up technology categories

Resolve a list of technology category slugs or names to their canonical Sumble categories. Pass a `technology_categories` array (1–1000 entries) and receive one entry in `results` for every input, in the same order you supplied them.

Each result pairs your original `input` with the matched `category`, or `null` when nothing matches. A matched category includes the `technologies` it contains, ordered by how frequently they appear in job postings.

The response also returns `matched_count`, the number of inputs that resolved to a category.

Custom categories are in private preview, limited to Sumble staff and staff-impersonated sessions. During preview, this lookup also resolves your visible custom categories by exact `custom:<slug>` or name. Custom matches include `is_custom: true`; canonical matches have `is_custom: false`. Prefer the slug when names overlap, because canonical matches take precedence. Unknown or inaccessible categories return `category: null`.

Older custom categories may return an ID-based reference such as `custom:id:123`. Use the returned reference unchanged in filters, entity selections, and tech-stack requests. Do not derive a reference from the category name.

Custom matches contain the current member technologies. An empty category still matches, with an empty `technologies` array. Lookup does not create or edit categories. Use the returned slug in a `custom_technology_category` query filter or a `technology_category` entity selection. See [Custom technology categories](/api/core-data/organizations#custom-technology-categories).

Use this endpoint when you have a set of category slugs or names and need to enumerate the technologies they contain — for example, to expand a category filter into individual technology slugs before passing them to another endpoint.

### File output

Set `file_name` to get the matches as a file. See [File downloads](/api/api#file-downloads).

A `.json` file contains one object per input in the same structure as the inline `results`, so the matched category stays an object with its technologies nested.

A `.csv` or `.xlsx` file contains one row per input, including unmatched inputs, with separate columns for the matched category's slug, name, and short name. `technologies` contains compact JSON text in its cell.

The `is_custom` column distinguishes custom and canonical matches. It is blank for unmatched inputs.

### Credit cost

1 credit per 100 matched categories. Unmatched inputs do not consume credits.

## POST /v9/technologies/categories/lookup

> Look up technology categories by slug or name

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"LookupTechnologyCategoriesRequest":{"properties":{"technology_categories":{"items":{"type":"string"},"type":"array","maxItems":1000,"minItems":1,"title":"Technology Categories","description":"List of technology category slugs or names to look up"}},"type":"object","required":["technology_categories"],"title":"LookupTechnologyCategoriesRequest"},"LookupTechnologyCategoriesResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"matched_count":{"type":"integer","title":"Matched Count"},"results":{"items":{"$ref":"#/components/schemas/app__schemas__paid_api__technologies__LookupTechnologyCategoriesResponse__LookupResult"},"type":"array","title":"Results"}},"type":"object","required":["id","credits_used","credits_remaining","matched_count","results"],"title":"LookupTechnologyCategoriesResponse"},"app__schemas__paid_api__technologies__LookupTechnologyCategoriesResponse__LookupResult":{"properties":{"input":{"type":"string","title":"Input"},"category":{"anyOf":[{"$ref":"#/components/schemas/CategoryDetails"},{"type":"null"}]}},"type":"object","required":["input","category"],"title":"LookupResult"},"CategoryDetails":{"properties":{"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"name_short":{"type":"string","title":"Name Short"},"technologies":{"items":{"$ref":"#/components/schemas/Technology"},"type":"array","title":"Technologies","description":"Technologies in the category. Technologies mentioned most often in job postings appear first."}},"type":"object","required":["slug","name","name_short","technologies"],"title":"CategoryDetails"},"Technology":{"properties":{"id":{"type":"integer","title":"Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"}},"type":"object","required":["id","slug","name"],"title":"Technology"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/technologies/categories/lookup":{"post":{"tags":["technologies"],"summary":"Look up technology categories by slug or name","operationId":"lookup_technology_categories__api_version__technologies_categories_lookup_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupTechnologyCategoriesRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupTechnologyCategoriesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


# Project find

## Look up projects

Resolve a list of project names or slugs to their canonical Sumble projects. Pass a `projects` array (1–1000 entries) and receive one entry in `results` for every input, in the same order you supplied them.

Each result pairs your original `input` with the matched `project`, or `null` when nothing matches — so the response always lines up one-to-one with your request. Use a matched project's canonical `slug` as the identifier for other API endpoints.

The response also returns `matched_count`, the number of inputs that resolved to a project.

Use this endpoint when you already have a set of project names or slugs — for example, from a spreadsheet or a prior call — and need stable, canonical identifiers to pass into follow-up requests.

### File output

Set `file_name` to get the matches as a file. See [File downloads](/api/api#file-downloads).

A `.json` file contains one object per input in the same structure as the inline `results`, so the matched project stays an object.

A `.csv` or `.xlsx` file contains one row per input, including unmatched inputs, with separate columns for the matched project's ID, slug, and name.

### Credit cost

1 credit per 100 matched projects. Unmatched inputs do not consume credits.

## POST /v9/projects/lookup

> Look up projects by name

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"LookupProjectsRequest":{"properties":{"projects":{"items":{"type":"string"},"type":"array","maxItems":1000,"minItems":1,"title":"Projects","description":"List of project names or slugs to look up"}},"type":"object","required":["projects"],"title":"LookupProjectsRequest"},"LookupProjectsResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"matched_count":{"type":"integer","title":"Matched Count"},"results":{"items":{"$ref":"#/components/schemas/app__schemas__paid_api__projects__LookupProjectsResponse__LookupResult"},"type":"array","title":"Results"}},"type":"object","required":["id","credits_used","credits_remaining","matched_count","results"],"title":"LookupProjectsResponse"},"app__schemas__paid_api__projects__LookupProjectsResponse__LookupResult":{"properties":{"input":{"type":"string","title":"Input"},"project":{"anyOf":[{"$ref":"#/components/schemas/ProjectDetails"},{"type":"null"}]}},"type":"object","required":["input","project"],"title":"LookupResult"},"ProjectDetails":{"properties":{"id":{"type":"integer","title":"Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"}},"type":"object","required":["id","slug","name"],"title":"ProjectDetails"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/projects/lookup":{"post":{"tags":["projects"],"summary":"Look up projects by name","operationId":"lookup_projects__api_version__projects_lookup_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupProjectsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupProjectsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


# Job function & level lookup

Resolve a list of job titles to their canonical Sumble job function and level. Pass a `titles` array (1–1000 entries) and receive one entry in `results` for every input, in the same order you supplied them.

Each result pairs the original `input` title with two classifications: `job_function` and `job_level`. Either may be `null` when no confident match is available for that classification. The `job_level` includes a `level_rank` that orders levels from individual contributor to executive.

The response also returns `matched_count`, the number of titles that resolved to at least one classification.

Use this endpoint when you have a list of raw job titles and need structured, queryable identifiers — for example, to normalize titles from a CSV before passing job function or level filters to the people or jobs endpoints.

## File output

Set `file_name` to get the classifications as a file. See [File downloads](/api/api#file-downloads).

A `.json` file contains one object per input title in the same structure as the inline `results`, with the matched job function and level nested.

A `.csv` or `.xlsx` file contains one row per input title with these columns:

* `input`
* `job_function_id`
* `job_function_slug`
* `job_function_name`
* `job_level_id`
* `job_level_name`
* `job_level_rank`

Unmatched classifications have empty cells.

### Credit cost

1 credit per 100 matched titles. Unmatched titles do not consume credits.

## POST /v9/jobs/title-lookup

> Look up the function and level for job titles

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"LookupTitlesRequest":{"properties":{"titles":{"items":{"type":"string"},"type":"array","maxItems":1000,"minItems":1,"title":"Titles","description":"List of job titles to look up"}},"type":"object","required":["titles"],"title":"LookupTitlesRequest"},"LookupTitlesResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"matched_count":{"type":"integer","title":"Matched Count"},"results":{"items":{"$ref":"#/components/schemas/app__schemas__paid_api__jobs__LookupTitlesResponse__LookupResult"},"type":"array","title":"Results"}},"type":"object","required":["id","credits_used","credits_remaining","matched_count","results"],"title":"LookupTitlesResponse"},"app__schemas__paid_api__jobs__LookupTitlesResponse__LookupResult":{"properties":{"input":{"type":"string","title":"Input"},"job_function":{"anyOf":[{"$ref":"#/components/schemas/app__schemas__paid_api__jobs__LookupTitlesResponse__JobFunction"},{"type":"null"}]},"job_level":{"anyOf":[{"$ref":"#/components/schemas/app__schemas__paid_api__jobs__LookupTitlesResponse__JobLevel"},{"type":"null"}]}},"type":"object","required":["input","job_function","job_level"],"title":"LookupResult"},"app__schemas__paid_api__jobs__LookupTitlesResponse__JobFunction":{"properties":{"id":{"type":"integer","title":"Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"}},"type":"object","required":["id","slug","name"],"title":"JobFunction"},"app__schemas__paid_api__jobs__LookupTitlesResponse__JobLevel":{"properties":{"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"level_rank":{"type":"integer","title":"Level Rank"}},"type":"object","required":["id","name","level_rank"],"title":"JobLevel"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/jobs/title-lookup":{"post":{"tags":["jobs"],"summary":"Look up the function and level for job titles","operationId":"lookup_job_titles__api_version__jobs_title_lookup_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupTitlesRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupTitlesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


# Location find

## Find locations

Find location codes with `POST /v9/locations/find`. Use them in `hq_location` for organization headquarters or `country` for jobs and people. Country, state, and city codes work in both filters. Region codes work only in `hq_location`.

### Request modes

| Request body         | Result                                                                                                                    |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `{"query":"austin"}` | Search country, state, and city names and aliases.                                                                        |
| `{"parent":"US"}`    | List a location's children. `US` returns states, and `US:Texas` returns cities. A region returns subregions or countries. |
| `{}`                 | List top-level regions and countries.                                                                                     |

Pass `query`, `parent`, or neither. Passing both fields, or a blank value for either field, returns a 422 error. Using an unknown code or a city code as `parent` returns a 400 error. Cities have no children.

Name searches return up to 100 results, ordered by exact name match first, then by job count. City listings return up to 500 results, ordered by job count. Name searches do not return regions.

### Location codes

Use each returned `code` exactly as given. Codes are case-sensitive and use colons to separate the country, state, and city. A code has one, two or three parts; a code with more parts, an empty country, or an empty last part is rejected.

| Location type | Example code      |
| ------------- | ----------------- |
| Country       | `US` or `UK`      |
| State         | `US:Texas`        |
| City          | `US:Texas:Austin` |
| Region        | `EMEA`            |

State codes use full names, such as `US:California`. A code such as `US:CA` is invalid. Name searches also match abbreviations and aliases, so `{"query":"CA"}` finds California and `{"query":"san fran"}` finds San Francisco. The returned code uses the full name. The United Kingdom's code is `UK`.

Region codes are `EMEA`, `APAC`, `NAMER`, `LATAM`, `Americas`, `Europe`, `MiddleEast`, and `Africa`. To filter jobs or people by a region, first find its country codes. For example:

1. Send `{"parent":"EMEA"}` to get `Europe`, `MiddleEast`, and `Africa`.
2. Pass each returned code as `parent`, such as `{"parent":"Europe"}`, to get the countries in that subregion.
3. Combine those country codes in a `country IN (...)` clause.

For headquarters, use the region code directly, such as `hq_location IN ('EMEA')`.

### Response fields

Each entry in `locations` contains:

| Field          | Meaning                                                                                                             |
| -------------- | ------------------------------------------------------------------------------------------------------------------- |
| `code`         | Location code to use in a filter.                                                                                   |
| `name`         | Display name.                                                                                                       |
| `type`         | `region`, `country`, `state`, or `city`.                                                                            |
| `path`         | Ancestor names, outermost first. For Austin, this is `["United States", "Texas"]`. Empty for regions and countries. |
| `expandable`   | Whether this location has children you can list by passing its `code` as `parent`.                                  |
| `orgs_count`   | Number of organizations headquartered there.                                                                        |
| `jobs_count`   | Number of job posts located there.                                                                                  |
| `people_count` | Number of people located there.                                                                                     |

### Credit cost

1 credit for a request that returns at least one location. Requests with no matches cost no credits.


# Intelligence endpoints

AI-generated intelligence on the organizations you care about.

* [Signals](/api/intelligence/signals) — search recent account signals by organization, person, technology, job function, or saved organization list
* [Events](/api/intelligence/events) — search conferences and industry events, and get the people speaking at one
* [Intelligence briefs](/api/intelligence/intelligence-briefs) — generate an AI account brief summarizing the angle, relevant contacts, technology signals, teams, and recent changes


# Signals

Search Sumble Signals across the accounts available to your API key. Signals include champion movements, recent hires and promotions, technology and product mentions, projects and initiatives, and technology or job function trends.

Use this endpoint when you want a filtered feed across many accounts. If you already have one Sumble organization `id`, use [Organization signals](/api/core-data/organizations/organization-signals) instead.

Use Priority Signals search when you want the AI-generated digest items from your Priority Signals feed, filtered by the signal, organization, person, or job post IDs attached to their source signals.

Use the signal configs listing when you want the standing rules behind the feed — what each signal watches for, and how much of your feed it drives.

## Search signals

Search by any combination of signal IDs, organization IDs, person IDs, technology slugs, job function names, priorities, saved organization list IDs, and signal config IDs. The request body may be omitted; when present, all filter fields are optional. Filters are combined with AND; values inside each filter array are combined with OR.

```bash
curl https://api.sumble.com/v9/signals \
  --request POST \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": {
      "signal_ids": [123],
      "organization_ids": [31],
      "person_ids": [12729201],
      "job_functions": ["Account Executive"],
      "priorities": ["high"],
      "account_list_ids": [4],
      "signal_config_ids": [512]
    }
  }'
```

To search people-movement signals by job function, omit `technology_slugs` unless the same signals also have matching technology metadata.

To search for signals about specific people, pass their Sumble person IDs in `person_ids`. This matches the `person_id` field returned on person-related signals.

To see what one of your standing rules has turned up, pass its ID in `signal_config_ids`. This matches the `signal_config_id` returned on each signal; use [List signal configs](#list-signal-configs) to find the IDs your account can read. Because a search only ever covers signals already in your feed, this filter narrows that feed — it never exposes signals or configs you could not otherwise see.

### Recency window

This endpoint returns only signals from the **last 60 days**, regardless of the other filters you apply. This keeps searches fast and focused on current activity.

The only exception is a direct lookup by `signal_ids`: those signals are always returned regardless of age.

### Pagination

Results default to 100 signals per page, with a maximum `limit` of 100. Use `offset` to skip results; it defaults to 0 and accepts values up to 10,000. Results use deterministic newest-first ordering. Each returned signal costs 1 credit, so larger pages and additional pages consume credits for every signal returned.

### Response

The response contains a `signals` array. Each signal includes `signal_id`, a display-ready `title`, `display_type`, and `date`, plus optional context such as `subtitle`, `type`, `organization_name`, `organization_id`, `person_id`, `matched_technologies`, `location`, `job_function`, `priority`, `explanation`, and `sales_angle`.

Each signal carries the `signal_config_name` of the rule that generated it. When that config is visible to your account, the signal also carries its `signal_config_id`; pass the ID to [List signal configs](#list-signal-configs) to read the full rule. A coworker's individual config remains private, but its name still explains why the signal appears in a shared domain feed.

For person-movement signals, `subtitle` may include a normalized start-date label such as `Started Jun 2026` or `Starting Jul 2026`.

A signal about a person carries two links for them: `person_sumble_url`, their Sumble profile page, and `linkedin_url`. Use the Sumble profile as the primary link — it is the page that carries what Sumble knows about them.

Job-post signals (technology and product mentions, projects, and first mentions) also include `suggested_contacts`: the top contacts to consider reaching out to at the account, ranked by relevance. It contains a `people` array — each with `person_id`, `name`, `title`, `sumble_url`, `linkedin_url`, and a relevance `score` from 1 to 10 (higher is a stronger match) — and a `sumble_url` on `suggested_contacts` itself, linking to all matching people for the job post.

Each signal also includes `account_status`: the CRM relationship between the signal's organization and your account (`customer`, `prospect`, or `not_in_crm`). Only populated when your account has a linked CRM seat (Salesforce or HubSpot). Without one, the REST API omits the field and the `SearchSignals` MCP tool returns it as `null`.

### File output

Set `file_name` to get the matching signals as a file. See [File downloads](/api/api#file-downloads). The file contains the requested page, with one row per signal and one column per response field. `matched_technologies` and `suggested_contacts` contain compact JSON text within their cells in a `.csv` or `.xlsx`, and stay nested in a `.json`.

### Credit cost

1 credit per signal returned. Searches with no returned signals do not consume credits.

## Search signals

> Signals are sales-relevant events such as champion job changes, recent hires and promotions, technology and product mentions, projects and initiatives, and technology and job-function trends. Job-post signals (technology and product mentions, projects, and first mentions) also include \`suggested\_contacts\`: the top few people to consider reaching out to at the account, plus a link to view all of them. Each signal also carries \`account\_status\`: the CRM relationship between the signal's organization and the calling account ('customer', 'prospect', or 'not\_in\_crm'). Only populated when the calling account has a linked CRM seat (Salesforce or HubSpot). Results are paginated with \`limit\` (default and maximum 100) and \`offset\` (default 0, maximum 10,000).

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"SearchSignalsRequest":{"properties":{"filter":{"$ref":"#/components/schemas/SearchSignalsFilter","description":"Filter criteria for signals search."},"limit":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of signals to return.","default":100},"offset":{"type":"integer","maximum":10000,"minimum":0,"title":"Offset","description":"Number of signals to skip.","default":0}},"additionalProperties":false,"type":"object","title":"SearchSignalsRequest"},"SearchSignalsFilter":{"properties":{"organization_ids":{"anyOf":[{"items":{"type":"integer","exclusiveMinimum":0},"type":"array"},{"type":"null"}],"title":"Organization Ids","description":"Organization IDs to filter signals by."},"person_ids":{"anyOf":[{"items":{"type":"integer","exclusiveMinimum":0},"type":"array"},{"type":"null"}],"title":"Person Ids","description":"Sumble person IDs to filter signals by."},"signal_ids":{"anyOf":[{"items":{"type":"integer","exclusiveMinimum":0},"type":"array"},{"type":"null"}],"title":"Signal Ids","description":"Signal IDs to filter signals by."},"technology_slugs":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Technology Slugs","description":"Canonical technology slugs to filter signals by, such as `kubernetes` or `salesforce`."},"job_functions":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Job Functions","description":"Job function names to filter signals by, such as `Engineering` or `Sales`."},"priorities":{"anyOf":[{"items":{"type":"string","enum":["high","medium","low"]},"type":"array"},{"type":"null"}],"title":"Priorities","description":"Priorities to filter signals by. Matches the `priority` field returned on each signal."},"account_list_ids":{"anyOf":[{"items":{"type":"integer","exclusiveMinimum":0},"type":"array"},{"type":"null"}],"title":"Account List Ids","description":"Account list IDs to filter signals to accounts in those lists."},"signal_config_ids":{"anyOf":[{"items":{"type":"integer","exclusiveMinimum":0},"type":"array"},{"type":"null"}],"title":"Signal Config Ids","description":"Signal config IDs to filter signals by. Matches the `signal_config_id` returned on each signal."}},"additionalProperties":false,"type":"object","title":"SearchSignalsFilter"},"SignalsResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"signals":{"items":{"$ref":"#/components/schemas/Signal"},"type":"array","title":"Signals"}},"type":"object","required":["id","credits_used","credits_remaining","signals"],"title":"SignalsResponse"},"Signal":{"properties":{"signal_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Signal Id"},"title":{"type":"string","title":"Title"},"subtitle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subtitle"},"explanation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Explanation"},"sales_angle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sales Angle"},"date":{"type":"string","format":"date-time","title":"Date"},"sumble_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sumble Url"},"display_type":{"type":"string","title":"Display Type"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"matched_technologies":{"anyOf":[{"items":{"$ref":"#/components/schemas/SignalTechnology"},"type":"array"},{"type":"null"}],"title":"Matched Technologies"},"organization_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization Name"},"organization_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Organization Id"},"job_post_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Job Post Id"},"person_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Person Id"},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"job_function":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Function"},"priority":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Priority"},"signal_config_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Signal Config Id","description":"The `id` of the signal config that generated this signal. Returned only when that config is visible to your account; pass it to List Signal Configs to read the full definition."},"signal_config_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signal Config Name","description":"Display name of the signal config that generated this signal. This remains available as explanation context even when the full config is not visible to your account."},"suggested_contacts":{"anyOf":[{"$ref":"#/components/schemas/SuggestedContacts"},{"type":"null"}]},"account_status":{"anyOf":[{"type":"string","enum":["customer","prospect","not_in_crm"]},{"type":"null"}],"title":"Account Status","description":"CRM relationship between the signal's organization and the calling account: 'customer' (a customer account in the calling account's CRM), 'prospect' (tracked in CRM but not a customer), or 'not_in_crm' (no CRM record). Only populated when the calling account has a linked CRM seat (Salesforce or HubSpot); otherwise absent or null even when requested, depending on the caller (the REST API omits null fields, MCP returns them as null)."}},"type":"object","required":["title","date","display_type"],"title":"Signal"},"SignalTechnology":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"}},"type":"object","required":["name","slug"],"title":"SignalTechnology"},"SuggestedContacts":{"properties":{"people":{"items":{"$ref":"#/components/schemas/SuggestedContact"},"type":"array","title":"People"},"sumble_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sumble Url"}},"type":"object","required":["people"],"title":"SuggestedContacts"},"SuggestedContact":{"properties":{"person_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Person Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"}},"type":"object","title":"SuggestedContact"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/signals":{"post":{"tags":["signals"],"summary":"Search signals","description":"Signals are sales-relevant events such as champion job changes, recent hires and promotions, technology and product mentions, projects and initiatives, and technology and job-function trends. Job-post signals (technology and product mentions, projects, and first mentions) also include `suggested_contacts`: the top few people to consider reaching out to at the account, plus a link to view all of them. Each signal also carries `account_status`: the CRM relationship between the signal's organization and the calling account ('customer', 'prospect', or 'not_in_crm'). Only populated when the calling account has a linked CRM seat (Salesforce or HubSpot). Results are paginated with `limit` (default and maximum 100) and `offset` (default 0, maximum 10,000).","operationId":"search_signals__api_version__signals_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchSignalsRequest"}}}},"responses":{"200":{"description":"Signals matching the requested filters. Charged one credit per signal returned. Job-post signals also carry `suggested_contacts` with the top contacts to consider and a link to view all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Search Priority Signals

Search your Priority Signals digest items by any combination of signal IDs, organization IDs, person IDs, job post IDs, your relevance feedback, and whether you wrote feedback. The request body may be omitted; when present, all filter fields are optional. Filters are combined with AND; values inside each filter array are combined with OR.

Priority Signals are AI-generated summaries of the highest-priority signals in your account feed. Each result includes the digest item `id`, headline and content, a URL to view the digest in Sumble, source `signal_ids`, searchable `organization_ids`, `person_ids`, and `job_post_ids` derived from the source signals, your relevance feedback (`is_relevant`), and your written `feedback`.

```bash
curl https://api.sumble.com/v9/signals/priority \
  --request POST \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": {
      "signal_ids": [123],
      "organization_ids": [31],
      "person_ids": [12729201],
      "job_post_ids": [789],
      "is_relevant": true
    }
  }'
```

The `is_relevant` filter accepts `true` (only signals you marked relevant) or `false` (only signals you marked not relevant). Omit it to return priority signals regardless of feedback — omitting it does **not** match only unreviewed (no-feedback) signals.

The `has_feedback` filter accepts `true` (only signals you wrote feedback on) or `false` (only signals without written feedback). Omit it to return priority signals either way.

### Pagination

Results default to 20 priority signals per page, with a maximum `limit` of 100. Use `offset` to skip results; it defaults to 0 and accepts values up to 10,000. Results are ordered by completion time, with a deterministic tie-breaker. Each returned priority signal costs 1 credit, so larger pages and additional pages consume credits for every priority signal returned.

### Response

The response contains a `priority_signals` array. Each priority signal includes `id`, `url`, `signal_ids`, `headline`, `content`, `date`, `organization_ids`, `person_ids`, and `job_post_ids`. `is_relevant` is `true` or `false` when you have given feedback. Without feedback, the REST API omits the field and the `SearchPrioritySignals` MCP tool returns it as `null`. `feedback` holds your written feedback and follows the same rule when there is none. The `date` is returned as `YYYY-MM-DD`.

### File output

Set `file_name` to get the requested page as a file. See [File downloads](/api/api#file-downloads). The file contains one row per priority signal. `signal_ids`, `organization_ids`, `person_ids`, and `job_post_ids` contain compact JSON text within their cells in a `.csv` or `.xlsx`, and stay nested in a `.json`.

### Credit cost

1 credit per priority signal returned. Searches with no returned priority signals do not consume credits.

## Search priority signals

> Priority signals are AI-generated digest items summarizing the most important signals in a user's account feed. They optionally can be searched by signal, organization, person, or job post IDs attached to their source signals. Returns the most recent priority signals based on the specified filters, or omit filters to simply return the latest. Results are paginated with \`limit\` (default 20, maximum 100) and \`offset\` (default 0, maximum 10,000).

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"SearchPrioritySignalsRequest":{"properties":{"filter":{"$ref":"#/components/schemas/SearchPrioritySignalsFilter","description":"Filter criteria for priority signals search."},"limit":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Maximum number of priority signals to return.","default":20},"offset":{"type":"integer","maximum":10000,"minimum":0,"title":"Offset","description":"Number of priority signals to skip.","default":0}},"additionalProperties":false,"type":"object","title":"SearchPrioritySignalsRequest"},"SearchPrioritySignalsFilter":{"properties":{"organization_ids":{"anyOf":[{"items":{"type":"integer","exclusiveMinimum":0},"type":"array"},{"type":"null"}],"title":"Organization Ids","description":"Organization IDs to filter priority signals by."},"person_ids":{"anyOf":[{"items":{"type":"integer","exclusiveMinimum":0},"type":"array"},{"type":"null"}],"title":"Person Ids","description":"Sumble person IDs to filter priority signals by."},"signal_ids":{"anyOf":[{"items":{"type":"integer","exclusiveMinimum":0},"type":"array"},{"type":"null"}],"title":"Signal Ids","description":"Signal IDs to filter priority signals by."},"job_post_ids":{"anyOf":[{"items":{"type":"integer","exclusiveMinimum":0},"type":"array"},{"type":"null"}],"title":"Job Post Ids","description":"Job post IDs to filter priority signals by."},"is_relevant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Relevant","description":"Filter by your relevance feedback: true for priority signals you marked relevant, false for ones you marked not relevant. Omit to return priority signals regardless of feedback -- this does not match only unreviewed (null-feedback) signals."}},"additionalProperties":false,"type":"object","title":"SearchPrioritySignalsFilter"},"PrioritySignalsResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"priority_signals":{"items":{"$ref":"#/components/schemas/PrioritySignal"},"type":"array","title":"Priority Signals"}},"type":"object","required":["id","credits_used","credits_remaining","priority_signals"],"title":"PrioritySignalsResponse"},"PrioritySignal":{"properties":{"id":{"type":"integer","title":"Id"},"url":{"type":"string","title":"Url"},"headline":{"type":"string","title":"Headline"},"content":{"type":"string","title":"Content"},"date":{"type":"string","format":"date","title":"Date"},"signal_ids":{"items":{"type":"integer"},"type":"array","title":"Signal Ids"},"organization_ids":{"items":{"type":"integer"},"type":"array","title":"Organization Ids"},"person_ids":{"items":{"type":"integer"},"type":"array","title":"Person Ids"},"job_post_ids":{"items":{"type":"integer"},"type":"array","title":"Job Post Ids"},"is_relevant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Relevant","description":"Your relevance feedback on this priority signal: true (relevant), false (not relevant), or no feedback. When no feedback exists, the REST API omits this field and MCP returns it as null. Update it with the Update Priority Signal Relevance endpoint."}},"type":"object","required":["id","url","headline","content","date"],"title":"PrioritySignal"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/signals/priority":{"post":{"tags":["signals"],"summary":"Search priority signals","description":"Priority signals are AI-generated digest items summarizing the most important signals in a user's account feed. They optionally can be searched by signal, organization, person, or job post IDs attached to their source signals. Returns the most recent priority signals based on the specified filters, or omit filters to simply return the latest. Results are paginated with `limit` (default 20, maximum 100) and `offset` (default 0, maximum 10,000).","operationId":"search_priority_signals__api_version__signals_priority_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPrioritySignalsRequest"}}}},"responses":{"200":{"description":"Priority signals matching the requested filters. Charged one credit per priority signal returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrioritySignalsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Update Priority Signal Relevance

Mark a priority signal (identified by its `id` from Search Priority Signals) as relevant or not relevant, or clear previously-set feedback. This mirrors the relevant / not relevant feedback available in the web app, and the feedback is weighed when generating your future digests.

```bash
curl https://api.sumble.com/v9/signals/priority/88/relevance \
  --request POST \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "is_relevant": true }'
```

Pass `"is_relevant": true` (relevant), `false` (not relevant), or `null` to clear previously-set feedback.

### Response

Returns the updated `id` and `is_relevant`.

### Credit cost

Free — this endpoint does not consume credits.

## Update priority signal relevance

> Mark a priority signal (identified by its \`id\` from Search Priority Signals) as relevant or not relevant, or clear previously-set feedback by passing \`is\_relevant: null\`. Mirrors the relevant / not relevant feedback available in the web app. Free -- does not consume credits.

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"UpdatePrioritySignalRelevanceRequest":{"properties":{"is_relevant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Relevant","description":"Whether this priority signal is relevant (true) or not relevant (false). Pass null to clear previously-set feedback."}},"additionalProperties":false,"type":"object","required":["is_relevant"],"title":"UpdatePrioritySignalRelevanceRequest"},"PrioritySignalRelevanceResponse":{"properties":{"id":{"type":"integer","title":"Id"},"is_relevant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Relevant"}},"type":"object","required":["id"],"title":"PrioritySignalRelevanceResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/signals/priority/{item_id}/relevance":{"post":{"tags":["signals"],"summary":"Update priority signal relevance","description":"Mark a priority signal (identified by its `id` from Search Priority Signals) as relevant or not relevant, or clear previously-set feedback by passing `is_relevant: null`. Mirrors the relevant / not relevant feedback available in the web app. Free -- does not consume credits.","operationId":"update_priority_signal_relevance__api_version__signals_priority__item_id__relevance_post","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"integer","title":"Item Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePrioritySignalRelevanceRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrioritySignalRelevanceResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Update Priority Signal Feedback

Tell Sumble why a priority signal (identified by its `id` from Search Priority Signals) was or wasn't relevant, in your own words. Sumble reads this feedback when it writes your future priority signals, and Ask Sumble sees it too. A sentence about why works better than a bare verdict: "Already a customer, so expansion signals matter more than new hiring" tells the model what to change.

```bash
curl https://api.sumble.com/v9/signals/priority/88/feedback \
  --request POST \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "feedback": "Already a customer, so expansion signals matter more than new hiring." }'
```

`feedback` takes up to 2,000 characters and replaces any earlier feedback on the item. Pass `null` or an empty string to clear it. Written feedback is separate from `is_relevant`; set that with Update Priority Signal Relevance.

### Response

Returns the updated `id` and `feedback`.

### Credit cost

Free. This endpoint does not consume credits.

## List signal configs

A signal config is a standing rule that decides which signals reach you — "this technology mentioned in a job post", "a champion changed jobs", "this hiring trend is increasing" — narrowed by a filter over organizations, technologies, job functions and other attributes. Every signal in your feed was generated by one of them.

This endpoint lists the configs your account can read, so you can tell what your feed is actually watching and, when authorized, resolve a signal's `signal_config_id` into the rule behind it. It is read-only: configs are created and edited in the web app, not through the API.

For an active-config listing, filter by types and priorities, or omit the request body to return everything visible. An explicit `signal_config_ids` filter is a separate historical lookup: it cannot be combined with types or priorities, and it can return deleted configs that your account is authorized to read. Values inside each filter array are combined with OR.

```bash
curl https://api.sumble.com/v9/signals/configs \
  --request POST \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": {
      "signal_config_ids": [512]
    }
  }'
```

### Access

Configs are scoped exactly as they are on the web app's signal settings page:

* If your account belongs to a Sumble Enterprise customer with Signals enabled, you read that customer's shared configs.
* On a Pro plan, you read your own configs, preceded by any configs shared across your email domain.
* Otherwise you read only your own configs.

Normal listings exclude deleted configs. An explicit lookup by `signal_config_ids` also uses the web app's config-detail permissions and can return an authorized deleted config so historical signals remain explainable. A coworker's individual config is not readable even when one of its generated signals appears in your shared domain feed. An ID your account cannot read is reported in the response `message` rather than returned, and the response never reveals whether such a config exists.

### Response

The response contains a `signal_configs` array. Each config includes:

| Field                        | Description                                                                                                                                                                                                                                                            |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                         | The config's ID. Matches `signal_config_id` on the signals it generates.                                                                                                                                                                                               |
| `name`, `slug`               | Display name and stable slug.                                                                                                                                                                                                                                          |
| `type`                       | The kind of event watched for, e.g. `technology_any_mentions`. Matches `type` on the signals it generates.                                                                                                                                                             |
| `priority`                   | `high`, `medium`, or `low` — stamped on every signal it generates.                                                                                                                                                                                                     |
| `scope`                      | `user` (yours alone), `customer` (shared across your Sumble Enterprise account), or `domain` (shared across your email domain). Only `user` configs are yours to change.                                                                                               |
| `sumble_url`                 | Link to the config's settings page in the web app. For deleted configs, the REST API omits the field and the `ListSignalConfigs` MCP tool returns it as `null`.                                                                                                        |
| `deleted`                    | Whether the config has been deleted. `true` appears only in explicit ID lookups.                                                                                                                                                                                       |
| `days`                       | Lookback window, in days, over which the config evaluates activity.                                                                                                                                                                                                    |
| `filter_by`                  | `advanced_query` or `customer_people` — how the config selects matches.                                                                                                                                                                                                |
| `advanced_query`             | The filter tree deciding which organizations, technologies, job functions and other attributes match.                                                                                                                                                                  |
| `people_filter`, `job_level` | Extra restrictions on people-movement configs.                                                                                                                                                                                                                         |
| `sales_play`                 | Free-text sales play shown alongside the config's signals.                                                                                                                                                                                                             |
| `increasing`                 | For trend configs, whether it watches an increasing (`true`) or decreasing (`false`) trend.                                                                                                                                                                            |
| `sort_order`                 | The config's position in the web app's signal settings list.                                                                                                                                                                                                           |
| `signal_count_7d`            | How many signals the config produced in the last 7 days — a good proxy for how much of your feed it drives. For a `user`-scoped config this counts signals delivered to you; for a shared (`customer` or `domain`) config it counts every signal the config generated. |

A `message` explains when the account has no readable active configs or a requested `signal_config_ids` value is not visible. Otherwise the REST API omits the field and the `ListSignalConfigs` MCP tool returns it as `null`.

### File output

Set `file_name` to get the matching configs as a file. See [File downloads](/api/api#file-downloads). The file contains one row per config and one column per response field. `advanced_query` contains compact JSON text within its cell in a `.csv` or `.xlsx`, and stays nested in a `.json`.

### Credit cost

Free — this endpoint does not consume credits.

## List signal configs

> List the signal configs that decide which signals you receive -- their names, types, priorities, lookback windows, and filters, plus how many signals each has produced in the last 7 days and a link to its settings page. Read-only, and scoped exactly as the web app's signal settings page is: your own configs, your Sumble Enterprise account's shared configs, or your email domain's shared configs, whichever apply to you. Normal listings exclude deleted configs; an explicit ID lookup can return an authorized deleted config without a settings link. Free -- does not consume credits.

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"ListSignalConfigsRequest":{"properties":{"filter":{"$ref":"#/components/schemas/ListSignalConfigsFilter","description":"Filter criteria for the signal configs listing."}},"additionalProperties":false,"type":"object","title":"ListSignalConfigsRequest"},"ListSignalConfigsFilter":{"properties":{"signal_config_ids":{"anyOf":[{"items":{"type":"integer","exclusiveMinimum":0},"type":"array"},{"type":"null"}],"title":"Signal Config Ids","description":"Signal config IDs to look up, including authorized deleted configs. Cannot be combined with `types` or `priorities`. IDs not visible to your account are reported in the response `message` rather than returned."},"types":{"anyOf":[{"items":{"$ref":"#/components/schemas/SignalTypeEnum"},"type":"array"},{"type":"null"}],"title":"Types","description":"Signal config types to return."},"priorities":{"anyOf":[{"items":{"type":"string","enum":["high","medium","low"]},"type":"array"},{"type":"null"}],"title":"Priorities","description":"Signal config priorities to return."}},"additionalProperties":false,"type":"object","title":"ListSignalConfigsFilter"},"SignalTypeEnum":{"type":"string","enum":["project","org_technology_first_mentions","team_technology_first_mentions","job_function_recent_hires","job_function_any_mentions","job_keyword_any_mentions","technology_any_mentions","technology_trends","technology_recent_hires","job_function_trends","champion_alert","funding_event"],"title":"SignalTypeEnum"},"SignalConfigsResponse":{"properties":{"signal_configs":{"items":{"$ref":"#/components/schemas/SignalConfig"},"type":"array","title":"Signal Configs"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Explains when the account has no signal configs or a requested `signal_config_ids` value is not visible. Otherwise the REST API omits this field and MCP returns it as null."}},"type":"object","required":["signal_configs"],"title":"SignalConfigsResponse"},"SignalConfig":{"properties":{"id":{"type":"integer","title":"Id","description":"The signal config's ID. Matches `signal_config_id` on the signals it generates."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"The config's display name, as shown in the web app."},"slug":{"type":"string","title":"Slug","description":"Stable slug identifying the config."},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The kind of event this config watches for. Matches the `type` field on the signals it generates."},"priority":{"anyOf":[{"type":"string","enum":["high","medium","low"]},{"type":"null"}],"title":"Priority","description":"Priority stamped on every signal this config generates. Matches the `priority` field on those signals."},"scope":{"type":"string","enum":["user","customer","domain"],"title":"Scope","description":"Who the config belongs to: 'user' (yours alone), 'customer' (shared across your Sumble Enterprise account), or 'domain' (shared across everyone at your email domain). Only 'user' configs are yours to change."},"sumble_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sumble Url","description":"Web app URL for this config's settings page. For deleted configs, whose settings page no longer exists, the REST API omits this field and MCP returns it as null."},"deleted":{"type":"boolean","title":"Deleted","description":"Whether the config has been deleted. Deleted configs are returned only for explicit `signal_config_ids` lookups.","default":false},"sort_order":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sort Order","description":"The config's position in the web app's signal settings list."},"days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Days","description":"Lookback window, in days, over which the config evaluates matching activity."},"job_level":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Level","description":"Job level the config restricts people-movement matches to."},"sales_play":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sales Play","description":"Free-text sales play attached to the config, shown with its signals."},"increasing":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Increasing","description":"For trend configs, whether it watches for an increasing (true) or decreasing (false) trend."},"filter_by":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"How the config selects matches: 'advanced_query' (see `advanced_query`) or 'customer_people' (tracked people from your CRM)."},"people_filter":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"People Filter","description":"Additional people filter applied to people-movement configs."},"advanced_query":{"anyOf":[{"$ref":"#/components/schemas/AdvancedQuery"},{"type":"null"}],"description":"The config's advanced query: the filter tree deciding which organizations, technologies, job functions, and other attributes match."},"signal_count_7d":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Signal Count 7D","description":"How many signals this config produced in the last 7 days -- a good proxy for how much of the feed it drives. Counted the same way the web app counts it: for a 'user'-scoped config, signals delivered to you; for a shared ('customer' or 'domain') config, every signal the config generated."}},"type":"object","required":["id","slug","scope"],"title":"SignalConfig","description":"One signal config, as the owning user sees it in the web app."},"AdvancedQuery":{"properties":{"operator":{"type":"string","enum":["AND","OR","EQ","NOT EQ","IN","NOT IN","IN ALL","NOOP"],"title":"Operator"},"children":{"anyOf":[{"items":{"$ref":"#/components/schemas/AdvancedQuery"},"type":"array"},{"type":"null"}],"title":"Children"},"field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field"},"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"string","format":"date"},{"type":"null"}],"title":"Value"},"values":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"items":{"type":"integer"},"type":"array"},{"items":{"type":"string","format":"date"},"type":"array"},{"items":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"string","format":"date"}]},"type":"array"},{"type":"null"}],"title":"Values"}},"type":"object","required":["operator"],"title":"AdvancedQuery"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/signals/configs":{"post":{"tags":["signals"],"summary":"List signal configs","description":"List the signal configs that decide which signals you receive -- their names, types, priorities, lookback windows, and filters, plus how many signals each has produced in the last 7 days and a link to its settings page. Read-only, and scoped exactly as the web app's signal settings page is: your own configs, your Sumble Enterprise account's shared configs, or your email domain's shared configs, whichever apply to you. Normal listings exclude deleted configs; an explicit ID lookup can return an authorized deleted config without a settings link. Free -- does not consume credits.","operationId":"list_signal_configs__api_version__signals_configs_post","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ListSignalConfigsRequest"},{"type":"null"}],"title":"Model"}}}},"responses":{"200":{"description":"Signal configs matching the requested filters. Free -- does not consume credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalConfigsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get signal config health

Use signal config health to compare the delivery and engagement of the standing rules behind your feed. The endpoint is read-only and free. The request body is optional; set `weeks` from 1 to 26 to choose the history window. It defaults to 12 weeks.

```bash
curl https://api.sumble.com/v9/signals/configs/health \
  --request POST \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "weeks": 12 }'
```

### Audience

The `audience` field explains whose activity is included. `self` means the response covers only signals delivered to you, never coworkers' engagement. `customer` means the metrics are aggregated across users at your customer account. A customer admin receives the customer audience only when the visible configs are the customer's shared configs. Everyone else receives their own activity.

### Response

The response contains one health record for each active config visible to the audience:

| Field                                                                         | Description                                                                                                                                               |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `weeks`                                                                       | Number of weeks included in the delivery history.                                                                                                         |
| `audience`                                                                    | `self` for your own deliveries, or `customer` for an aggregate across your customer's users.                                                              |
| `signal_configs`                                                              | Health metrics for each active config visible to the audience.                                                                                            |
| `id`, `name`, `slug`, `type`, `priority`, `scope`, `sort_order`, `sumble_url` | Config identity and settings-page link. Only `user` scope configs are yours to change.                                                                    |
| `delivered`                                                                   | Signals delivered during the selected period.                                                                                                             |
| `clicked`                                                                     | Delivered signals clicked, favorited, or given relevance feedback.                                                                                        |
| `positive`                                                                    | Delivered signals clicked, favorited, or marked relevant without a not-relevant mark.                                                                     |
| `not_relevant`                                                                | Signals marked not relevant.                                                                                                                              |
| `not_my_account`                                                              | Signals marked with the `Not my account` reason.                                                                                                          |
| `recipients`                                                                  | Number of distinct users who received signals from this config. For `self`, this is you or zero.                                                          |
| `click_rate`, `positive_rate`, `not_relevant_rate`                            | The corresponding count divided by `delivered`, rounded to three decimal places. These values are `null` when `delivered` is zero.                        |
| `share_of_feed`                                                               | This config's deliveries divided by the deliveries from all returned configs, rounded to three decimal places. It is `null` when there are no deliveries. |
| `weekly_delivered`                                                            | Delivery counts by week, oldest first. The final value is the most recent seven days.                                                                     |
| `zero_signal_weeks`                                                           | Number of weeks with no deliveries.                                                                                                                       |
| `not_relevant_reasons`                                                        | Reasons selected for not-relevant feedback, each with its count and up to five most common context values in `top_values`.                                |
| `message`                                                                     | Explains when no signal configs are visible. Otherwise the REST API omits this field and the `GetSignalConfigHealth` MCP tool returns it as `null`.       |

Compare configs with each other rather than using fixed rate thresholds, since normal rates differ by signal type. A high share of the feed with few clicks, or a common not-relevant reason, can point to a config that is too broad. For example, `Not my geography` with a repeated location in `top_values` may suggest adding a location filter. `Not a relevant tech` may point to a technology list that needs tightening. Many weeks with no signals can mean a config is too narrow or its `days` lookback is too short. Steady delivery with almost no clicks can indicate low value.

When recommending a change, explain which metrics or reason values support it and include the `sumble_url`. Only configs with `scope: user` are yours to change; customer and domain configs are managed by an admin.


# Events

Search conferences and industry events, and the people Sumble matched as their speakers. These endpoints return what the Events page in Sumble shows.

## Search events

Filter by the event itself (`period`, `locations`, `keywords`) and by its people (`person_ids`, `organization_ids`, `account_list_ids`, `job_functions`, `job_levels`, `account_status`, `crm`). An event matches when any of its people match the people filters. Send at least `{}` as the body. Every filter is optional: leaving one out, `null` and `[]` all mean no filter. Filters are combined with AND; values inside each filter array are combined with OR.

```bash
curl https://api.sumble.com/v9/events \
  --request POST \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": {
      "period": "upcoming",
      "locations": ["US:California"],
      "account_list_ids": [4],
      "job_levels": ["VP", "Director"]
    },
    "order_by_column": "date"
  }'
```

`period` is `upcoming` (the default), `previous` or `all`. `locations` takes location codes such as `US`, `US:Texas` or `US:Texas:Austin`, or `VIRTUAL`; use [Location find](/api/lookups/locations) to turn place names into codes. `keywords` matches words in the event's name, location, topics or sponsors, or in a person's name, title or company, and supports quotes, `or` and `-` as in web search.

`account_status` takes `customer`, `prospect` or `not_in_crm`, describing the CRM account of each person's employer, or `yours` for an employer with a CRM account you own. `crm` takes `champion`, `new_lead` or `yours`, describing the person's own CRM record. Both need a linked CRM, and `crm` also needs CRM people matched to Sumble; without them a person's `crm` flags are `null`. Either filter returns a 400 when your account can't apply it.

`person_ids` keeps the events those people appeared at. With `"period": "all"` it finds every one, past and upcoming.

Your ICP ranks events and people; it doesn't filter them. Without an ICP, `has_icp` in the response is `false`, `relevance` order falls back to start date, soonest first for `upcoming` events and latest first for `previous` and `all`, and each person's `relevance` is `null`.

### Ordering and pagination

`order_by_column` is `relevance` (the default: events with the most people who fit your ICP first) or `date` (soonest start first). `order_by_direction` (`ASC` or `DESC`) reverses either one.

Results default to 20 events per page, with a maximum `limit` of 100. Use `offset` to skip results. `total` counts matching events across all pages.

### Response

Each event has an `id`, `name`, `starts_on`, `ends_on`, `location`, `official_url`, a `sumble_url` to its page in Sumble, and two counts. `people_count` is everyone Sumble matched to the event, before any filter. `matching_people_count` is the people your filter matches, and `people` holds up to three of them, best fit to your ICP first. Use [Get an event](#get-an-event) for the rest.

Each person has a `person_id`, `name`, the `job_title`, `company` and `role` the event lists for them, the `speaker_page_url` that lists them, a `sumble_url` to their Sumble profile, their current `organization`, their ICP `relevance` from 0 to 1, and `crm` flags (`is_champion`, `is_owned_by_you`, `is_new_lead`) when you have a linked CRM.

### Credit cost

1 credit per event returned. Searches with no results do not consume credits.

## Get an event

Get one event by `id` with every person Sumble matched to it, best fit to your ICP first. The people filters from [Search events](#search-events) narrow them the same way, except `person_ids`, which only search takes.

```bash
curl https://api.sumble.com/v9/events/1234 \
  --request POST \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": {
      "job_functions": ["Engineering"],
      "job_levels": ["VP", "Director"]
    }
  }'
```

People default to 100 per page, with a maximum `limit` of 100. `total_people` counts matching people across all pages. An unknown `id` returns 404.

### Credit cost

1 credit per person returned. A page with no people does not consume credits.


# Intelligence briefs

Retrieve an AI-generated intelligence brief for an organization. The brief summarizes the account angle, relevant contacts, technology signals, teams, and recent changes, and includes a link to view the same brief in Sumble.

Intelligence briefs are generated asynchronously. If the brief is still being prepared, the API returns HTTP `202` with a `Retry-After` header. Retry the same URL after that interval to get the completed brief.

Completed briefs stay cached until their source data changes. When any input is newer than the oldest section, Sumble regenerates the full brief before returning it.

### Credit cost

Completed intelligence briefs cost 50 credits. HTTP `202` pending responses do not consume credits.

## GET /v9/organizations/{organization\_id}/intelligence-brief

> Retrieve the intelligence brief for an organization

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"IntelligenceBriefResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"organization_id":{"type":"integer","title":"Organization Id"},"organization_slug":{"type":"string","title":"Organization Slug"},"title":{"type":"string","title":"Title"},"body":{"type":"string","title":"Body"},"sumble_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Sumble Url"}},"type":"object","required":["id","credits_used","credits_remaining","organization_id","organization_slug","title","body","sumble_url"],"title":"IntelligenceBriefResponse"},"IntelligenceBriefPendingResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Always 'pending' for 202 responses","default":"pending"},"organization_id":{"type":"integer","title":"Organization Id"},"organization_slug":{"type":"string","title":"Organization Slug"},"message":{"type":"string","title":"Message"}},"type":"object","required":["organization_id","organization_slug","message"],"title":"IntelligenceBriefPendingResponse","description":"Returned with HTTP 202 when the brief is being generated.\n\nThe caller should retry the same URL after the `Retry-After` header. No\ncredits are consumed for 202 responses."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/organizations/{organization_id}/intelligence-brief":{"get":{"tags":["organizations"],"summary":"Retrieve the intelligence brief for an organization","operationId":"get_intelligence_brief__api_version__organizations__organization_id__intelligence_brief_get","parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"integer","title":"Organization Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/IntelligenceBriefResponse"},{"$ref":"#/components/schemas/IntelligenceBriefPendingResponse"}],"title":"Response Get Intelligence Brief  Api Version  Organizations  Organization Id  Intelligence Brief Get"}}}},"202":{"description":"The brief is being generated. Retry the same URL after the `Retry-After` header. No credits are consumed.","headers":{"Retry-After":{"description":"Suggested seconds to wait before retrying the same URL","schema":{"type":"integer"}}},"content":{"application/json":{}}},"422":{"description":"The organization/domain does not have enough data to generate an intelligence brief. No credits are consumed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


# Lists

Create, manage, and access your saved lists.

* [Organization lists](/api/lists/organization-lists) — create, manage, and access saved organization lists
* [Contact lists](/api/lists/contact-lists) — create, manage, and access saved people lists


# Organization lists

Create, manage, and access organization lists in your Sumble account via the API.

Organization lists let you group target accounts for tracking, enrichment, or export. You can create lists, add organizations to them, and retrieve their contents programmatically.

See [Account lists](/web-app/lists-monitoring/account-lists) for how lists are created and managed in the web application.

## Credit cost

| Operation                              | Cost                               |
| -------------------------------------- | ---------------------------------- |
| List organization lists                | 1 credit per list returned         |
| Get organization list details          | 1 credit per organization returned |
| Create organization list               | No credit cost                     |
| Rename organization list               | No credit cost                     |
| Add organizations to a list            | No credit cost                     |
| Set a list's Signals inclusion setting | No credit cost                     |
| Set a list deleted or restored         | No credit cost                     |

## List organization lists

Returns your saved organization lists with each list's ID, web app URL, organization count, type, read-only/deletable flags, deleted status, and Signals inclusion setting.

Pass `file_name` to get the lists as a file, with one row per saved list. See [File downloads](/api/api#file-downloads).

## GET /v9/organization-lists

> List organization lists

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"OrganizationListsResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"organization_lists":{"items":{"$ref":"#/components/schemas/OrganizationListSummary"},"type":"array","title":"Organization Lists"}},"type":"object","required":["id","credits_used","credits_remaining","organization_lists"],"title":"OrganizationListsResponse"},"OrganizationListSummary":{"properties":{"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"},"organizations_count":{"type":"integer","title":"Organizations Count"},"type":{"$ref":"#/components/schemas/OrganizationListType"},"read_only":{"type":"boolean","title":"Read Only"},"deletable":{"type":"boolean","title":"Deletable"},"deleted":{"type":"boolean","title":"Deleted","default":false},"include_in_signals":{"type":"boolean","title":"Include In Signals","default":true}},"type":"object","required":["id","name","url","organizations_count","type","read_only","deletable"],"title":"OrganizationListSummary"},"OrganizationListType":{"type":"string","enum":["group","user"],"title":"OrganizationListType"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/organization-lists":{"get":{"tags":["organization-lists"],"summary":"List organization lists","operationId":"list_organization_lists__api_version__organization_lists_get","parameters":[{"name":"include_deleted","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Deleted"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationListsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

***

## Get organization list details

Returns one organization list and the organizations currently in it. Each organization includes its Sumble profile URL as `sumble_url`; `url` is the organization's own website. For callers with CRM status access, organizations also include `account_status` (`customer`, `prospect`, or `not_in_crm`) and `crm_url` when an unambiguous CRM account record can be linked. A missing CRM record returns `account_status: "not_in_crm"`; `null` means CRM status is unavailable to the caller.

Pass `file_name` to get the organization rows as a file. See [File downloads](/api/api#file-downloads).

Use the `list_id` returned from the list endpoint.

## GET /v9/organization-lists/{list\_id}

> Get organization list details

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"OrganizationListResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"list_info":{"$ref":"#/components/schemas/OrganizationListSummary"},"organizations":{"items":{"$ref":"#/components/schemas/OrganizationListOrganization"},"type":"array","title":"Organizations","description":"Organization rows. Empty when `file` is present because the file contains these rows."},"file":{"anyOf":[{"$ref":"#/components/schemas/ApiFileResponse"},{"type":"null"}],"description":"Metadata for the downloadable file created when `file_name` was supplied. Ask Sumble and Slack attach it automatically. In other MCP clients, present `download_url` to the user. Do not recreate the file."}},"type":"object","required":["id","credits_used","credits_remaining","list_info","organizations"],"title":"OrganizationListResponse"},"OrganizationListSummary":{"properties":{"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"},"organizations_count":{"type":"integer","title":"Organizations Count"},"type":{"$ref":"#/components/schemas/OrganizationListType"},"read_only":{"type":"boolean","title":"Read Only"},"deletable":{"type":"boolean","title":"Deletable"},"deleted":{"type":"boolean","title":"Deleted","default":false},"include_in_signals":{"type":"boolean","title":"Include In Signals","default":true}},"type":"object","required":["id","name","url","organizations_count","type","read_only","deletable"],"title":"OrganizationListSummary"},"OrganizationListType":{"type":"string","enum":["group","user"],"title":"OrganizationListType"},"OrganizationListOrganization":{"properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug"},"sumble_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Sumble Url"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"employee_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Employee Count"},"account_status":{"anyOf":[{"type":"string","enum":["customer","prospect","not_in_crm"]},{"type":"null"}],"title":"Account Status"},"crm_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Crm Url"}},"type":"object","title":"OrganizationListOrganization"},"ApiFileResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Opaque file identifier."},"filename":{"type":"string","title":"Filename","description":"Filename shown to the user."},"media_type":{"type":"string","title":"Media Type","description":"IANA media type."},"kind":{"type":"string","enum":["organization_list","contact_list"],"title":"Kind","description":"The kind of data contained in the file."},"row_count":{"type":"integer","title":"Row Count","description":"Number of data rows in the file."},"columns":{"items":{"type":"string"},"type":"array","title":"Columns","description":"Column names in file order."},"size_bytes":{"type":"integer","title":"Size Bytes","description":"File size in bytes."},"download_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Download Url","description":"Authenticated Sumble URL where the user can download the file."}},"type":"object","required":["id","filename","media_type","kind","row_count","columns","size_bytes","download_url"],"title":"ApiFileResponse","description":"Metadata for a file created by the API for the user."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/organization-lists/{list_id}":{"get":{"tags":["organization-lists"],"summary":"Get organization list details","operationId":"get_organization_list__api_version__organization_lists__list_id__get","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"integer","title":"List Id"}},{"name":"include_deleted","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Deleted"}},{"name":"file_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

***

## Create organization list

Create a new, empty organization list. Use the returned `id` to add organizations to it.

## POST /v9/organization-lists

> Create an organization list

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"CreateOrganizationListRequest":{"properties":{"name":{"type":"string","title":"Name"}},"type":"object","required":["name"],"title":"CreateOrganizationListRequest"},"CreateOrganizationListResponse":{"properties":{"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"}},"type":"object","required":["id","name","url"],"title":"CreateOrganizationListResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/organization-lists":{"post":{"tags":["organization-lists"],"summary":"Create an organization list","operationId":"create_organization_list__api_version__organization_lists_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrganizationListRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrganizationListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

***

## Rename organization list

Change an existing list's name. The list keeps its `id`, URL, and organizations — only the name changes, so there is no need to recreate a list to rename it.

List names are not unique, so a rename never conflicts with another of your lists. Group lists (read-only territories synced from your CRM) cannot be renamed, and return `403`.

## Rename an organization list

> Rename one of your organization lists.\
> \
> Only the list's name changes: its id, url, and organizations are untouched.\
> Names are not unique, so renaming never conflicts with another list.\
> \
> Group lists (read-only territories synced from your CRM) cannot be renamed.

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"RenameOrganizationListRequest":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name"}},"type":"object","required":["name"],"title":"RenameOrganizationListRequest"},"RenameOrganizationListResponse":{"properties":{"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"}},"type":"object","required":["id","name","url"],"title":"RenameOrganizationListResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/organization-lists/{list_id}/name":{"post":{"tags":["organization-lists"],"summary":"Rename an organization list","description":"Rename one of your organization lists.\n\nOnly the list's name changes: its id, url, and organizations are untouched.\nNames are not unique, so renaming never conflicts with another list.\n\nGroup lists (read-only territories synced from your CRM) cannot be renamed.","operationId":"rename_organization_list__api_version__organization_lists__list_id__name_post","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"integer","title":"List Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenameOrganizationListRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenameOrganizationListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

***

## Add organizations to a list

Add organizations to an existing list by their Sumble IDs or slugs. Organizations that are already in the list are silently skipped. Invalid IDs or slugs are returned in the failure arrays.

If you have company names or domains but not Sumble IDs or slugs, use the [organizations endpoint](/api/core-data/organizations#find-match-and-enrich-organizations) first to resolve them.

## POST /v9/organization-lists/{list\_id}/organizations

> Add organizations to a list

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"AddOrganizationsRequest":{"properties":{"organization_ids":{"items":{"type":"integer"},"type":"array","title":"Organization Ids","default":[]},"organization_slugs":{"items":{"type":"string"},"type":"array","title":"Organization Slugs","default":[]}},"type":"object","title":"AddOrganizationsRequest"},"AddOrganizationsResponse":{"properties":{"added":{"items":{"type":"integer"},"type":"array","title":"Added"},"failed_ids":{"items":{"type":"integer"},"type":"array","title":"Failed Ids"},"failed_slugs":{"items":{"type":"string"},"type":"array","title":"Failed Slugs"}},"type":"object","required":["added","failed_ids","failed_slugs"],"title":"AddOrganizationsResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/organization-lists/{list_id}/organizations":{"post":{"tags":["organization-lists"],"summary":"Add organizations to a list","operationId":"add_organizations_to_list__api_version__organization_lists__list_id__organizations_post","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"integer","title":"List Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddOrganizationsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddOrganizationsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

***

## Set a list's Signals inclusion setting

Include or exclude an organization list's accounts from future Signals delivery. Lists are included by default. This mirrors the per-list Signals toggle in the web app.

## Set a list's signals inclusion setting

> Include or exclude an organization list's accounts from your signals feed.\
> \
> Pass \`\`include\_in\_signals=false\`\` to exclude this list's accounts from your\
> signals, or \`\`true\`\` to include them again. Lists are included by default.\
> This mirrors the per-list signals toggle in the dashboard.

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"SetOrganizationListSignalsRequest":{"properties":{"include_in_signals":{"type":"boolean","title":"Include In Signals"}},"type":"object","required":["include_in_signals"],"title":"SetOrganizationListSignalsRequest"},"OrganizationListSignalsResponse":{"properties":{"id":{"type":"integer","title":"Id"},"include_in_signals":{"type":"boolean","title":"Include In Signals"}},"type":"object","required":["id","include_in_signals"],"title":"OrganizationListSignalsResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/organization-lists/{list_id}/signals":{"post":{"tags":["organization-lists"],"summary":"Set a list's signals inclusion setting","description":"Include or exclude an organization list's accounts from your signals feed.\n\nPass ``include_in_signals=false`` to exclude this list's accounts from your\nsignals, or ``true`` to include them again. Lists are included by default.\nThis mirrors the per-list signals toggle in the dashboard.","operationId":"set_organization_list_signals__api_version__organization_lists__list_id__signals_post","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"integer","title":"List Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetOrganizationListSignalsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationListSignalsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

***

## Set a list deleted or restored

Soft-delete an organization list or restore a previously deleted one. Pass `{ "deleted": true }` to delete the list, or `{ "deleted": false }` to restore it. Deleting a list preserves its organizations; deleting individual organizations from a list is a separate operation.

Deleted lists are hidden by default. To retrieve them with their preserved organization counts and details, pass `include_deleted=true` on the list and detail endpoints above.

## Set an organization list's deleted status

> Soft-delete or restore an organization list.\
> \
> Soft-deletion is reversible: pass \`\`deleted=false\`\` to restore a list.\
> Deleting or restoring a list does not delete or restore individual\
> organizations in the list. Pass \`\`include\_deleted=true\`\` to the list/detail\
> endpoints to see deleted lists.

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"SetOrganizationListDeletedRequest":{"properties":{"deleted":{"type":"boolean","title":"Deleted"}},"type":"object","required":["deleted"],"title":"SetOrganizationListDeletedRequest"},"SetOrganizationListDeletedResponse":{"properties":{"id":{"type":"integer","title":"Id"},"deleted":{"type":"boolean","title":"Deleted"}},"type":"object","required":["id","deleted"],"title":"SetOrganizationListDeletedResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/organization-lists/{list_id}/deleted":{"post":{"tags":["organization-lists"],"summary":"Set an organization list's deleted status","description":"Soft-delete or restore an organization list.\n\nSoft-deletion is reversible: pass ``deleted=false`` to restore a list.\nDeleting or restoring a list does not delete or restore individual\norganizations in the list. Pass ``include_deleted=true`` to the list/detail\nendpoints to see deleted lists.","operationId":"set_organization_list_deleted__api_version__organization_lists__list_id__deleted_post","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"integer","title":"List Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetOrganizationListDeletedRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetOrganizationListDeletedResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


# Contact lists

Create, manage, and access contact lists (people lists) in your Sumble account via the API.

Contact lists let you save and organize people for outreach, tracking, or export. You can create lists, add people to them by their Sumble person IDs, and retrieve the full list with enriched contact details.

See [Contact lists](/web-app/lists-monitoring/contact-lists) for how lists are created and managed in the web application.

## Credit cost

| Operation                | Cost                         |
| ------------------------ | ---------------------------- |
| List contact lists       | 1 credit per list returned   |
| Get contact list details | 1 credit per person returned |
| Create contact list      | No credit cost               |
| Add people to a list     | No credit cost               |

## List contact lists

Returns your saved contact lists with each list's ID, name, and people count.

Pass `file_name` to get the lists as a file, with one row per saved list. See [File downloads](/api/api#file-downloads).

## GET /v9/contact-lists

> List contact lists

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"ContactListsResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"contact_lists":{"items":{"$ref":"#/components/schemas/ContactListSummary"},"type":"array","title":"Contact Lists"}},"type":"object","required":["id","credits_used","credits_remaining","contact_lists"],"title":"ContactListsResponse"},"ContactListSummary":{"properties":{"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"people_count":{"type":"integer","title":"People Count"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"}},"type":"object","required":["id","name","people_count","url"],"title":"ContactListSummary"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/contact-lists":{"get":{"tags":["contact-lists"],"summary":"List contact lists","operationId":"list_contact_lists__api_version__contact_lists_get","parameters":[],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

***

## Get contact list details

Returns one contact list and the people currently in it, with enriched profile data including name, job title, job function, LinkedIn URL, organization, and contact information (emails and phone when available).

Use the `list_id` returned from the list endpoint.

Pass `file_name` to get the person rows as a file. See [File downloads](/api/api#file-downloads).

## GET /v9/contact-lists/{list\_id}

> Get contact list details

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"ContactListResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"list_info":{"$ref":"#/components/schemas/ContactListSummary"},"people":{"items":{"$ref":"#/components/schemas/ContactListPerson"},"type":"array","title":"People","description":"Person rows. Empty when `file` is present because the file contains these rows."},"file":{"anyOf":[{"$ref":"#/components/schemas/ApiFileResponse"},{"type":"null"}],"description":"Metadata for the downloadable file created when `file_name` was supplied. Ask Sumble and Slack attach it automatically. In other MCP clients, present `download_url` to the user. Do not recreate the file."}},"type":"object","required":["id","credits_used","credits_remaining","list_info","people"],"title":"ContactListResponse"},"ContactListSummary":{"properties":{"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"people_count":{"type":"integer","title":"People Count"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"}},"type":"object","required":["id","name","people_count","url"],"title":"ContactListSummary"},"ContactListPerson":{"properties":{"id":{"anyOf":[{"type":"integer"},{"type":"string"}],"title":"Id"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"},"name":{"type":"string","title":"Name"},"job_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Title"},"job_function_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Function Name"},"job_function_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Function Slug"},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url"},"organization_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Organization Id"},"organization_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization Name"},"organization_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization Slug"},"contact_info":{"anyOf":[{"$ref":"#/components/schemas/ContactListContactInfo"},{"type":"null"}]}},"type":"object","required":["id","url","name"],"title":"ContactListPerson"},"ContactListContactInfo":{"properties":{"emails":{"items":{"type":"string"},"type":"array","title":"Emails"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"requested":{"$ref":"#/components/schemas/ContactInfoRequested"}},"type":"object","required":["emails"],"title":"ContactListContactInfo","description":"Paid-API contact info for a contact-list person.\n\nDeliberately decoupled from the shared `ProfileContactInfo` (as\n`/people/enrich` already is): the shared model carries web-only fields (e.g.\nthe async-reveal `pending` flag, SMB-2070) that must not drift into the\nCadwyn-versioned paid response. This mirrors the shared model's current paid\ncontract exactly — `emails`, `phone`, `requested`."},"ContactInfoRequested":{"properties":{"email":{"type":"boolean","title":"Email","default":false},"phone":{"type":"boolean","title":"Phone","default":false}},"type":"object","title":"ContactInfoRequested"},"ApiFileResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Opaque file identifier."},"filename":{"type":"string","title":"Filename","description":"Filename shown to the user."},"media_type":{"type":"string","title":"Media Type","description":"IANA media type."},"kind":{"type":"string","enum":["organization_list","contact_list"],"title":"Kind","description":"The kind of data contained in the file."},"row_count":{"type":"integer","title":"Row Count","description":"Number of data rows in the file."},"columns":{"items":{"type":"string"},"type":"array","title":"Columns","description":"Column names in file order."},"size_bytes":{"type":"integer","title":"Size Bytes","description":"File size in bytes."},"download_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Download Url","description":"Authenticated Sumble URL where the user can download the file."}},"type":"object","required":["id","filename","media_type","kind","row_count","columns","size_bytes","download_url"],"title":"ApiFileResponse","description":"Metadata for a file created by the API for the user."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/contact-lists/{list_id}":{"get":{"tags":["contact-lists"],"summary":"Get contact list details","operationId":"get_contact_list__api_version__contact_lists__list_id__get","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"integer","title":"List Id"}},{"name":"file_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

***

## Create contact list

Create a new, empty contact list. Use the returned `id` to add people to it.

## POST /v9/contact-lists

> Create a contact list

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"CreateContactListRequest":{"properties":{"name":{"type":"string","title":"Name"}},"type":"object","required":["name"],"title":"CreateContactListRequest"},"CreateContactListResponse":{"properties":{"id":{"type":"integer","title":"Id"},"name":{"type":"string","title":"Name"},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"}},"type":"object","required":["id","name","url"],"title":"CreateContactListResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/contact-lists":{"post":{"tags":["contact-lists"],"summary":"Create a contact list","operationId":"create_contact_list__api_version__contact_lists_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContactListRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContactListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

***

## Add people to a list

Add people to an existing contact list by their Sumble person IDs. People already on the list are silently skipped. The response tells you how many were added and how many were already present.

One request can add up to 10,000 people. Larger batches are rejected with a validation error, so split them across requests.

On Free and Pro plans a list holds up to 10,000 people in total. A request that would take a list past that is rejected with a `403` and the error type `contact_list_full`, and nothing from it is added. Enterprise lists have no size limit.

You can obtain person IDs from the [People](/api/core-data/people) endpoint.

## POST /v9/contact-lists/{list\_id}/people

> Add people to a contact list

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"AddContactsRequest":{"properties":{"people_ids":{"items":{"type":"integer"},"type":"array","title":"People Ids"}},"type":"object","required":["people_ids"],"title":"AddContactsRequest"},"AddContactsResponse":{"properties":{"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"},"added":{"type":"integer","title":"Added"},"already_on_list":{"type":"integer","title":"Already On List"}},"type":"object","required":["url","added","already_on_list"],"title":"AddContactsResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/contact-lists/{list_id}/people":{"post":{"tags":["contact-lists"],"summary":"Add people to a contact list","operationId":"add_contacts_to_list__api_version__contact_lists__list_id__people_post","parameters":[{"name":"list_id","in":"path","required":true,"schema":{"type":"integer","title":"List Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddContactsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddContactsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


# Conversation history

Read your Ask Sumble conversations through the API or MCP. Both operations are free. They return only conversations you own, even if you can read or participate in other conversations shared through the web app.

## List conversations

`GET /v9/conversations?page=1` returns up to 30 conversations, most recently updated first. Each entry includes its `id`, `title`, `created_at`, `updated_at`, `message_count`, `turn_count`, and a `sumble_url` to open it in the web app. A new conversation can have a null title and no messages. Turn counts include user messages still waiting for an answer.

Pass the response's `next_page` as `page` to continue. A null `next_page` means there are no more results. Page numbers start at 1. Conversations updated between requests can move between pages.

## Read a conversation

`GET /v9/conversations/{conversation_id}` returns the same metadata and the transcript, oldest message first. It reads the saved transcript, so messages remain available after the assistant's working context expires or is shortened.

Long transcripts come back in pages of about 60,000 characters of message text. Pass the response's `next_message_offset` as `message_offset` to read the next page. A null `next_message_offset` means you have the last message. A single message longer than that limit comes back whole, on a page of its own.

Each message includes its text, role, timestamp, and any generated files. File entries include a filename, file id, and `download_url` when a standalone download page is available. When `download_url` is null, open the conversation's `sumble_url` and use its file download controls. These links require the user to sign in to Sumble. Files can expire independently of the transcript. Uploaded attachments are recorded by name only; their contents are not retained.

Where available, messages include `credits_charged`, `credits_refunded`, and `elapsed_seconds`. `credits_charged` is the net charge after refunds. Null values mean no accounting or timing record exists for that message. Reading a conversation does not charge these credits again.

A missing conversation or one owned by another user returns 404.

## MCP

Use `ListConversations` to find a conversation by title and date, then pass its id to `GetConversation` to read it. Both tools are free.


# Support

Report data quality issues and submit general support requests programmatically — the same flow used by the **Report data issue** button in the web app.

Both endpoints are free (no credits consumed) and authenticated the same way as the rest of the API. The reply-to address on every email is set to your account's email so the Sumble team can follow up with you directly.

## Report a data quality issue

Report incorrect, missing, or stale Sumble data. Routed to the Sumble data team for triage.

```bash
curl https://api.sumble.com/v9/support/data-quality \
  --request POST \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "message": "The employee count for Acme looks stale",
    "url": "https://sumble.com/org/acme",
    "page_title": "Acme | Sumble"
  }'
```

### Request body

| Field        | Type   | Required | Description                                        |
| ------------ | ------ | -------- | -------------------------------------------------- |
| `message`    | string | Yes      | Description of the issue. Max 5,000 characters.    |
| `url`        | string | No       | The Sumble URL the issue relates to, if any.       |
| `page_title` | string | No       | The title of the Sumble page the issue relates to. |

### Response

```json
{ "message": "Email sent successfully" }
```

## Create Data Quality Report

> Report a data quality issue. Routed to the data team for triage.

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"CreateDataQualityReportRequest":{"properties":{"message":{"type":"string","maxLength":5000,"title":"Message"},"url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Url"},"page_title":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Page Title"}},"type":"object","required":["message"],"title":"CreateDataQualityReportRequest"},"SupportRequestResponse":{"properties":{"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"SupportRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/support/data-quality":{"post":{"tags":["support"],"summary":"Create Data Quality Report","description":"Report a data quality issue. Routed to the data team for triage.","operationId":"create_data_quality_report__api_version__support_data_quality_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDataQualityReportRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportRequestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Submit a general support request

Submit an account, billing, or product question. Routed to the Sumble support inbox.

```bash
curl https://api.sumble.com/v9/support \
  --request POST \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "message": "How do I update my billing details?",
    "url": "https://sumble.com/account/billing"
  }'
```

### Request body

| Field     | Type   | Required | Description                                       |
| --------- | ------ | -------- | ------------------------------------------------- |
| `message` | string | Yes      | Description of the request. Max 5,000 characters. |
| `url`     | string | No       | The Sumble URL the request relates to, if any.    |

### Response

```json
{ "message": "Email sent successfully" }
```

## Create Support Request

> Submit a general support request.

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"CreateSupportRequestRequest":{"properties":{"message":{"type":"string","maxLength":5000,"title":"Message"},"url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Url"}},"type":"object","required":["message"],"title":"CreateSupportRequestRequest"},"SupportRequestResponse":{"properties":{"message":{"type":"string","title":"Message"}},"type":"object","required":["message"],"title":"SupportRequestResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/support":{"post":{"tags":["support"],"summary":"Create Support Request","description":"Submit a general support request.","operationId":"create_support_request__api_version__support_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSupportRequestRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportRequestResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


# MCP

With Sumble MCP, you can ask questions in natural language and get back structured data about organizations, technologies, job postings, and people - directly inside tools like Claude, ChatGPT, Cursor, Claude Code or Gemini CLI. Behind the scenes, your AI assistant calls Sumble's API on your behalf.

## Getting started

Sumble is listed in the [Claude](https://claude.ai/directory/connectors/sumble) and [ChatGPT](https://chatgpt.com/apps/sumble/asdk_app_69d6aed609708191a384fb6b59438690) app directories, so you can install it with one click on those platforms.

See this video to see how to find it in Claude

{% embed url="<https://youtu.be/-_kVxcGeACs?si=3knMpBfHlN2IASOP>" %}

## Compatibility

On Claude and ChatGPT you can install Sumble directly from the app directory. Cursor, Claude Code and Gemini CLI use a custom MCP connection.

| Platform | Base Availability                    | How to install                                                                                                                                           | Enterprise Requirements                                 |
| -------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| Claude   | Paid plans only                      | [Claude directory](https://claude.ai/directory/connectors/sumble) or custom connector — see [Claude setup](/api/mcp/mcp-claude)                          | Admin must enable connectors (Team/Enterprise)          |
| Cursor   | All plans                            | Custom MCP connection — see [Cursor setup](/api/mcp/mcp-cursor)                                                                                          | None (Available on all)                                 |
| ChatGPT  | Paid plans only                      | [ChatGPT directory](https://chatgpt.com/apps/sumble/asdk_app_69d6aed609708191a384fb6b59438690) or custom app — see [ChatGPT setup](/api/mcp/mcp-chatgpt) | Admin may need to enable apps (Business/Enterprise)     |
| Gemini   | Gemini CLI, Gemini Enterprise (beta) | Custom MCP connection — see [Gemini CLI setup](/api/mcp/mcp-gemini-cli) or [Gemini Enterprise setup](/api/mcp/mcp-gemini-enterprise)                     | Gemini Enterprise: beta, enabled per account on request |

{% hint style="info" %}
*Gemini support means the **Gemini CLI**, plus **Gemini Enterprise** in beta — the consumer Gemini web app and mobile apps do not support MCP connectors.*
{% endhint %}

## Setup instructions

Pick your platform for step-by-step setup:

* [Claude](/api/mcp/mcp-claude)
* [Cursor](/api/mcp/mcp-cursor)
* [Claude Code](/api/mcp/mcp-claude-code)
* [ChatGPT](/api/mcp/mcp-chatgpt)
* [Gemini CLI](/api/mcp/mcp-gemini-cli)
* [Gemini Enterprise](/api/mcp/mcp-gemini-enterprise) — beta, enabled per account on request

## Try it

Here are a few prompts to get you started:

> * Find all people who could be in the buying committee for Maintain at top facility\
>   management companies in CA
> * Which WHOOP job posts mention Hex? What teams use it? Who makes buying\
>   decisions around BI tools at Whoop?
> * Boston tech companies growing 20% YoY using Databricks and Looker, that have\
>   a data engineering team of less than 4?

## Available tools

### Organizations

In the staff-only custom-category preview, `FindMatchAndEnrichOrganizations` accepts `custom_technology_category` filters and custom slugs in `technology_category` entity selections. `GetOrganizationTechStack` accepts a `custom_technology_categories` list and adds their current primary technologies. The normal metric and per-returned-technology credit costs apply. See [Custom technology categories](/api/core-data/organizations#custom-technology-categories).

| Tool                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Credit cost                                                                                                        |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `FindMatchAndEnrichOrganizations` | Find, match, and enrich organizations in one call — search by advanced query or resolve a list of names/URLs/IDs; returns selected attributes and per-entity metrics (technology, jobs, teams, people). Search results exclude permanently closed organizations unless `include_closed` is set; match mode always resolves closed organizations. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return a download instead of inline organization rows                                                                                                                    | 1 credit per matched org + 1 per paid attribute + per-entity metric costs; confirmation required above 500 credits |
| `GetIntelligenceBrief`            | LLM-generated sales intelligence brief for a target account, synthesized by Google Gemini from Sumble's structured data                                                                                                                                                                                                                                                                                                                                                                                                                                                    | 50 credits per completed brief                                                                                     |
| `GetOrganizationSignals`          | Get recent sales signals (notable changes) for one organization by ID: new hires on tracked technologies, leadership moves, and hiring or technology adoption trends. Optional technology-slug filter. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the signals as a downloadable file instead of including the rows in the MCP response. Each signal includes a deep-link `sumble_url` and, where relevant, a `person_id` or `job_post_id` for follow-up research, plus `person_sumble_url` (the person's Sumble profile, the primary link) and `linkedin_url` | 1 credit per signal returned; confirmation required above 500 credits                                              |
| `GetOrganizationTechStack`        | Get an organization's CONFIRMED-USED technology stack, grouped by business function and technology category and restricted to technologies Sumble has confirmed are actually in use, not merely mentioned. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the stack as a downloadable file instead of including it in the MCP response; a `.csv` or `.xlsx` has one fixed-width row per confirmed-used evidence technology, a `.json` keeps the grouped structure                                                                                                 | 1 credit per technology returned; confirmation required above 500 credits                                          |

### Organization Lists

| Tool                         | Description                                                                                                                                                                                                                                                                                      | Credit cost                                                        |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `ListOrganizationLists`      | List saved organization lists with IDs, web app URLs, organization counts, read-only/deletable flags, deleted status, and Signals inclusion settings. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the lists as a downloadable file instead of including the rows in the MCP response | 1 credit per list                                                  |
| `GetOrganizationList`        | Get one organization list and its organizations. Pass a `.csv`, `.xlsx` or `.json` `file_name` to keep the list metadata and return file shape, size, and an authenticated Sumble download URL while omitting organization rows                                                                  | 1 credit per organization; confirmation required above 500 credits |
| `CreateOrganizationList`     | Create a new empty organization list                                                                                                                                                                                                                                                             | Free                                                               |
| `RenameOrganizationList`     | Rename an existing organization list, keeping its ID, URL, and organizations                                                                                                                                                                                                                     | Free                                                               |
| `AddOrganizationsToList`     | Add organizations to an existing list by ID or slug                                                                                                                                                                                                                                              | Free                                                               |
| `SetOrganizationListDeleted` | Soft-delete an organization list, or restore a deleted one                                                                                                                                                                                                                                       | Free                                                               |
| `SetOrganizationListSignals` | Include or exclude a list's accounts from future Signals delivery                                                                                                                                                                                                                                | Free                                                               |

### Signals

| Tool                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Credit cost                           |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `SearchSignals`                 | Search Sumble Signals across available accounts by signal IDs, organization IDs, person IDs, technologies, job functions, priorities, saved organization lists, or signal config IDs. Supports `limit`/`offset` pagination. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the matching signals as a downloadable file instead of including the rows in the MCP response. Nested matched technologies and suggested contacts contain compact JSON text in a `.csv` or `.xlsx`, and stay nested in a `.json` | 1 credit per signal returned          |
| `SearchPrioritySignals`         | Search Priority Signals digest items by source signal IDs, organization IDs, person IDs, job post IDs, your relevance feedback (`is_relevant`), or whether you wrote feedback (`has_feedback`); supports `limit`/`offset` pagination. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the matching items as a downloadable file instead of including the rows in the MCP response. Source ID arrays contain compact JSON text in a `.csv` or `.xlsx`, and stay nested in a `.json`                           | 1 credit per priority signal returned |
| `UpdatePrioritySignalRelevance` | Mark a priority signal (by its `id` from `SearchPrioritySignals`) relevant or not relevant, or clear the feedback                                                                                                                                                                                                                                                                                                                                                                                                    | Free                                  |
| `UpdatePrioritySignalFeedback`  | Record why a priority signal (by its `id` from `SearchPrioritySignals`) was or wasn't relevant, in your own words, or clear it. Sumble reads it when writing your future priority signals                                                                                                                                                                                                                                                                                                                            | Free                                  |
| `ListSignalConfigs`             | List the active standing rules that decide which signals you receive: name, type, priority, scope, lookback window, filter definition, recent count, and settings link. Filter active configs by type or priority, or look up config IDs (including authorized deleted configs) as a separate mode. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return configs as a downloadable file; `advanced_query` contains compact JSON text in a `.csv` or `.xlsx`, and stays nested in a `.json`. Read-only             | Free                                  |
| `GetSignalConfigHealth`         | Compare delivery, engagement, weekly activity, and not-relevant reasons for each visible signal config. Uses only your own deliveries, or aggregates across your customer's users when you are a customer admin. Compare configs relative to each other to spot broad, narrow, or low-value rules. Read-only                                                                                                                                                                                                         | Free                                  |

### Events

| Tool           | Description                                                                                                                                                                                                                                                                                                                                                   | Credit cost                  |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `SearchEvents` | Search conferences and industry events by period, location, keywords, and the people speaking at them (person IDs, employer, organization list, job function, job level, CRM status). Order by ICP relevance or date; supports `limit`/`offset` pagination. Each event includes up to 3 matching people, best fit to your ICP first, and a total people count | 1 credit per event returned  |
| `GetEvent`     | Get one event by ID with every person Sumble matched to it, best fit to your ICP first, narrowed by the same people filters except person IDs; supports `limit`/`offset` pagination                                                                                                                                                                           | 1 credit per person returned |

### Jobs

| Tool                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Credit cost                                                                                                      |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `FindMatchAndEnrichJobs` | Find, look up, and enrich job postings in one call — search by advanced query (with optional organization scoping) or enrich a list of job IDs; returns selected attributes (title, full description, location, posted date, organization, extracted technologies, teams, job functions, levels, projects) and optional related people (hiring managers and team members). Pass a `.csv`, `.xlsx` or `.json` `file_name` to return one row per job as a downloadable file instead of including the rows in the MCP response; technologies, teams, job functions, levels, projects, and related people contain compact JSON text in a `.csv` or `.xlsx`, and stay nested in a `.json` | 1 credit per job + 1 per paid attribute + 1 per related person returned; confirmation required above 500 credits |
| `LookupJobTitles`        | Resolve a list of job titles to their canonical job function and level. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the classifications in a downloadable file instead of including the rows in the MCP response                                                                                                                                                                                                                                                                                                                                                                                                                                                         | 1 credit per 100 matched titles                                                                                  |

### People

| Tool                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Credit cost                                                                                                                                                                                                                                                                                                                                                              |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `FindMatchAndEnrichPeople` | Find, match, and enrich people in one call — resolve person IDs, LinkedIn URLs, or emails, or search within organizations by advanced query; returns selected attributes (including the person's full experience history and profile summary in match mode), optional related people (inferred managers and direct reports), and optional email/phone contact reveals. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return one row per input or result as a downloadable file instead of inline people; unmatched inputs are retained, and nested technologies, experience, score features, managers, and direct reports contain compact JSON text in a `.csv` or `.xlsx`, and stay nested in a `.json`. Long-running requests may return `status: "running"` with a `request_id`; call the tool again with only that `request_id` to retrieve the result. Credits are charged when the completed result is first returned. | 1 credit per person + 1 per paid attribute + 1 per related person; 10 credits per first email reveal, 80 credits per first phone reveal — free on repeat reveals of the same type, or if the type is unavailable; resolving an input email to a person costs 20 credits per resolved email (emails that don't resolve are free); confirmation required above 500 credits |
| `SearchPeople`             | Find people by describing in natural language what they do, own, or know, such as responsibilities, projects, expertise, or the tools they use. Search everyone, or only the organizations you name, optionally including former employees. Pass location codes from `SearchLocations` in `locations` to search only people in those places. Results are ranked by relevance and can include partial matches. Request `person_score` to rate each person against your ICP. Set `requested_total` for the total number wanted, up to 1,000; it defaults to the page size, `limit`. Keep it unchanged while paging with `limit` and `offset`. Available on Sumble Pro and Enterprise plans. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return one row per person as a downloadable file instead of inline people                                                                                                            | 1 credit per person + 1 per paid attribute; confirmation required above 500 credits                                                                                                                                                                                                                                                                                      |

### Teams

| Tool                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Credit cost                                                                                                                        |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `FindMatchAndEnrichTeams` | Get the teams inside a company — the groups Sumble extracts from its job postings — by resolving a list of team IDs or searching within organizations by advanced query; returns selected attributes (owning organization, parent-team breadcrumbs, jobs count, technologies, job functions, locations, first and last activity, ICP team score), optional related people with a person–team confidence breakdown, and optional job postings with composable components. Teams are organization-scoped, so resolve company names to IDs with `FindMatchAndEnrichOrganizations` first; there is no parent/subsidiary roll-up | 1 credit per team + 1 per paid attribute + 1 per related person + 1 per job post returned; confirmation required above 500 credits |

### Contact Lists

| Tool                | Description                                                                                                                                                                                                                                                    | Credit cost                                                  |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `ListContactLists`  | List saved contact (people) lists with IDs and people counts. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the lists as a downloadable file instead of including the rows in the MCP response                                                       | 1 credit per list                                            |
| `GetContactList`    | Get one contact list and its people. Pass a `.csv`, `.xlsx` or `.json` `file_name` to keep the list metadata and return file shape, size, and an authenticated Sumble download URL. The file contains the person rows, which are omitted from the MCP response | 1 credit per person; confirmation required above 500 credits |
| `CreateContactList` | Create a new empty contact list                                                                                                                                                                                                                                | Free                                                         |
| `AddContactsToList` | Add people to an existing contact list by person ID                                                                                                                                                                                                            | Free                                                         |

### Technologies

| Tool                         | Description                                                                                                                                                                                                                                                                                 | Credit cost                           |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `SearchTechnologies`         | Look up technology names and slugs. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the matches as a downloadable file instead of including the rows in the MCP response                                                                                                            | 1 credit per search                   |
| `LookupTechnologies`         | Resolve a list of technology names, slugs, or aliases to canonical IDs, slugs, names, and categories. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the matches as a downloadable file; categories contain compact JSON text in a `.csv` or `.xlsx`, and stay nested in a `.json` | 1 credit per 100 matched technologies |
| `LookupTechnologyCategories` | Resolve category slugs or names to categories and their member technologies. The staff-only custom-category preview also returns your visible custom categories, marked with `is_custom: true`. Pass a `.csv`, `.xlsx` or `.json` `file_name` for a download                                | 1 credit per 100 matched categories   |

### Projects

| Tool             | Description                                                                                                                                                                                                               | Credit cost                       |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `LookupProjects` | Resolve a list of project names or slugs to canonical IDs, slugs, and names. Pass a `.csv`, `.xlsx` or `.json` `file_name` to return the matches as a downloadable file instead of including the rows in the MCP response | 1 credit per 100 matched projects |

### Locations

| Tool              | Description                                                                                                                                                                                                           | Credit cost                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `SearchLocations` | Find codes for the `hq_location` and `country` filters. Search names with `query`, list children with `parent`, or omit both fields to list top-level regions and countries. Region codes work only in `hq_location`. | 1 credit for a call with results. No credits for an empty result. |

### Support

| Tool                     | Description                                                                                                                                                                                      | Credit cost |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| `ReportDataQualityIssue` | Report a data quality or coverage issue — incorrect/missing/stale data, or a missing category, field, filter, project/signal type, taxonomy value, or data limit; routed to the Sumble data team | Free        |
| `SubmitSupportRequest`   | Submit a general account, billing, or access support request (not data or coverage); routed to the Sumble support team                                                                           | Free        |

### Database

| Tool          | Description                                                                                                                                                                                                                                                                                                                                        | Credit cost                                                                          |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `RunSqlQuery` | Run read-only SQL against Sumble's DuckDB (last resort). Set `file_name` to a `.csv`, `.xlsx` or `.json` filename for a download. LIST, STRUCT, and JSON values are compact JSON text in a cell of a `.csv` or `.xlsx`, and stay nested in a `.json`. A query that matches more than 1,000 rows fails: no rows are returned and nothing is charged | 1 credit per 100 bytes of query result data; confirmation required above 500 credits |
| `ListTables`  | List all tables and columns in the database                                                                                                                                                                                                                                                                                                        | Free                                                                                 |

### Account

| Tool                    | Description                                                                                                                                                                                                                                               | Credit cost |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `GetAccountInformation` | Check your credit balance, API key status, and plan info                                                                                                                                                                                                  | Free        |
| `GetMyCompanyProfile`   | Get your company's profile and target account intelligence profile. In the staff-only preview, `custom_technology_categories` also lists your visible custom categories with their slugs, names, members, and `is_custom: true`, independently of the ICP | Free        |

The custom-category preview is limited to Sumble staff and staff-impersonated sessions. These tools can read and filter categories but cannot create or edit them. The profile's `data` remains `null` when no ICP exists; the custom-category list is independent and can still contain entries. Use the exact returned custom slugs in filters and entity selections.

### Conversation history

These tools read your own Ask Sumble conversations. Conversations shared with you are excluded. See [Conversation history](/api/conversations) for response details.

| Tool                | Description                                                                                                                                       | Credit cost |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `ListConversations` | List conversations with titles, dates, and message and turn counts, newest first. Returns 30 per page with pagination                             | Free        |
| `GetConversation`   | Read a transcript, generated-file download links, attachment names, and available credit charges and refunds. Long transcripts come back in pages | Free        |

### Documentation

These serve this documentation site and additional product guidance, so your assistant can answer questions about how Sumble works without a web search. Pages outside this site have no URL.

| Tool                   | Description                                                                                  | Credit cost |
| ---------------------- | -------------------------------------------------------------------------------------------- | ----------- |
| `SearchDocumentation`  | Search the documentation and return matching page paths, titles, optional URLs, and excerpts | Free        |
| `ListDocumentation`    | List every documentation page, with its title and where it sits in the navigation            | Free        |
| `GetDocumentationPage` | Read one documentation page, by the path `ListDocumentation` returned                        | Free        |

## Credits

MCP calls consume credits from your Sumble account, just like the [REST API](/api/api). The structured tools (find, enrich) follow the same pricing as the corresponding API endpoints. SQL queries via the `RunSqlQuery` tool are priced at 1 credit per 100 bytes of query result data, so you pay only for the rows you get back. Pass a `file_name` ending in `.csv`, `.xlsx` for an Excel workbook, or `.json`, to receive those rows as a downloadable file instead of inline data. LIST, STRUCT, and JSON values are stored as compact JSON text in one cell of a `.csv` or `.xlsx`, and stay nested in a `.json`. A query that matches more than 1,000 rows fails without returning rows or charging credits: add a `LIMIT` of 1,000 or less, aggregate in SQL, or narrow the `WHERE` clause.

An MCP request that would cost more than 500 credits is refused. Nothing is charged and no data is returned. To go ahead, your assistant passes `allow_expensive_query`, which it should do only after asking you, and only for that one call: the next page, a refined query, or any other request above 500 credits needs your go-ahead again. When it asks, the assistant should also offer a small, cheaper sample so you can check the results before paying for all of them. Assistants that cannot pass the parameter have to narrow the request instead. The REST API is not affected.

You can check your balance at any time by asking your assistant, or visit [sumble.com/account](https://sumble.com/account). To purchase additional credits, go to [Account > Billing & Credits](https://sumble.com/account/billing?purchase_credits=true).

See [Credits](/get-started/credits) for details on monthly allocations and purchasing.


# Claude

{% hint style="info" %}
*Works on paid Claude plans. On Team and Enterprise, an admin may need to enable connectors. See* [*Compatibility*](/api/mcp#compatibility)*.*
{% endhint %}

Connect Sumble MCP to the Claude web and desktop apps, either with one click from the Claude directory or as a custom connector.

## Install from the Claude directory (recommended)

1. Open the Sumble connector in the [Claude directory](https://claude.ai/directory/connectors/sumble)
2. Click **Connect** (or **Add**)
3. Complete the auth flow
4. Use Sumble MCP in Claude chat

(Optional but suggested) Enable 'Allow access' to all endpoints. This prevents interruptions when an endpoint is used for the first time.

## Manual setup (custom connector)

{% hint style="info" %}
*Use this if your organization restricts the directory, or you prefer to add the connector manually.*
{% endhint %}

Video instructions [here](https://www.loom.com/share/8e4cc03e723f46ada0f40d56ecd80c96)

1. Go to Claude web app or desktop app (if desktop app - navigate to chat on the top)
2. Go to preferences (or `cmd + ,`) > Connectors -> Add a custom connector
3. Enter
   1. Name: `Sumble`
   2. Remote URL: [`https://mcp.sumble.com`](https://mcp.sumble.com/)
4. Complete the auth flow
5. Use Sumble MCP in Claude chat

Once connected, see [Try it](/api/mcp#try-it) for example prompts, [Available tools](/api/mcp#available-tools) for what each tool does, and [Credits](/api/mcp#credits) for how usage is billed.


# Cursor

{% hint style="info" %}
*Works on all Cursor plans*
{% endhint %}

Connect Sumble MCP to Cursor as a custom MCP server.

1. Go to Cursor settings (`Shift + CMD + J` on mac)
2. Navigate to 'Tools & MCP'
3. Click on New MCP Server (Add a Custom MCP Server)
4. Paste the JSON below

```
{
  "mcpServers": {
    "sumblemcp": { "type": "http", "url": "https://mcp.sumble.com" }
  }
}
```

5. Go back to Settings > 'Tools & MCP' > Click 'Connect'
6. Complete the auth flow
7. Use Sumble MCP in your Cursor chat

Once connected, see [Try it](/api/mcp#try-it) for example prompts, [Available tools](/api/mcp#available-tools) for what each tool does, and [Credits](/api/mcp#credits) for how usage is billed.


# Claude Code

{% hint style="info" %}
*Works on all plans of Claude Code*
{% endhint %}

Connect Sumble MCP to Claude Code from your terminal.

1. Run the following command in your terminal to install the MCP `claude mcp add --transport http sumble https://mcp.sumble.com --scope user`
2. Start Claude by running the `claude` command
3. Go to `/mcp` and find the sumble mcp and click enter
4. Complete auth and the MCP will be successfully setup

Once connected, see [Try it](/api/mcp#try-it) for example prompts, [Available tools](/api/mcp#available-tools) for what each tool does, and [Credits](/api/mcp#credits) for how usage is billed.


# ChatGPT

{% hint style="info" %}
*Works on paid ChatGPT plans. On Business and Enterprise, an admin may need to enable apps. See* [*Compatibility*](/api/mcp#compatibility)*.*
{% endhint %}

Connect Sumble MCP to ChatGPT, either with one click from the ChatGPT app directory or as a custom app.

## Install from the ChatGPT app directory (recommended)

1. Open the Sumble app in the [ChatGPT directory](https://chatgpt.com/apps/sumble/asdk_app_69d6aed609708191a384fb6b59438690)
2. Click **Connect** (or **Add**)
3. Complete the auth flow
4. Use Sumble MCP in your ChatGPT chat

## Manual setup (custom app)

{% hint style="info" %}
*Use this if your organization restricts the directory, or you prefer to create the app manually.*
{% endhint %}

[Video](https://www.loom.com/share/ee27e8e24d574e6fb0851d28e6564c17) instructions on how to add Sumble MCP.

1. Go to ChatGPT settings (`cmd + ,` on mac)
2. Navigate to 'Apps'
3. Click on 'Create App'
   1. Enter
      1. Name: `Sumble`
      2. MCP Server URL: `https://mcp.sumble.com`
   2. Accept conditions and continue
4. Complete the auth flow
5. Use Sumble MCP in your ChatGPT chat

Once connected, see [Try it](/api/mcp#try-it) for example prompts, [Available tools](/api/mcp#available-tools) for what each tool does, and [Credits](/api/mcp#credits) for how usage is billed.


# Gemini CLI

{% hint style="info" %}
*Works in the* [*Gemini CLI*](https://geminicli.com/) *on all plans. MCP servers are not supported in the Gemini web or mobile apps.*
{% endhint %}

Connect Sumble MCP to the Gemini CLI as a custom MCP server.

Sumble MCP uses the streamable HTTP transport, so it goes in the `httpUrl` field of the Gemini CLI's `mcpServers` configuration.

## Option 1: `gemini mcp add` (recommended)

1. Run the following command in your terminal:

```
gemini mcp add --transport http --scope user sumble https://mcp.sumble.com
```

2. Start the CLI by running `gemini`
3. Run `/mcp auth sumble` and complete the auth flow in your browser
4. Run `/mcp list` to confirm Sumble is connected, then use Sumble MCP in your Gemini CLI chat

## Option 2: edit `settings.json` manually

1. Open your Gemini CLI settings file:
   * User-wide: `~/.gemini/settings.json`
   * Project-only: `.gemini/settings.json` in your project directory
2. Add the `sumble` entry to the `mcpServers` object:

```json
{
  "mcpServers": {
    "sumble": {
      "httpUrl": "https://mcp.sumble.com"
    }
  }
}
```

3. Start the CLI by running `gemini`
4. Run `/mcp auth sumble` and complete the auth flow in your browser
5. Run `/mcp list` to confirm Sumble is connected, then use Sumble MCP in your Gemini CLI chat

The Gemini CLI discovers Sumble's OAuth configuration automatically and stores the resulting tokens in `~/.gemini/mcp-oauth-tokens.json`, refreshing them as needed. If your tools stop working, re-run `/mcp auth sumble`.

For more detail on MCP configuration options — tool filtering, timeouts, and per-project scopes — see Google's [MCP servers with Gemini CLI](https://geminicli.com/docs/tools/mcp-server/) documentation.

Once connected, see [Try it](/api/mcp#try-it) for example prompts, [Available tools](/api/mcp#available-tools) for what each tool does, and [Credits](/api/mcp#credits) for how usage is billed.


# Gemini Enterprise

{% hint style="info" %}
*Sumble MCP on Gemini Enterprise is in **beta** and available to select customers. Setup requires a Sumble OAuth client, which is not enabled on accounts by default — if you'd like to try it, contact your account executive or* [*support@sumble.com*](mailto:support@sumble.com) *and we'll turn it on for you.*
{% endhint %}

[Gemini Enterprise](https://cloud.google.com/gemini-enterprise) can connect to custom MCP servers as a data store. Once Sumble is connected, everyone using your Gemini Enterprise app can ask questions in natural language and get back Sumble's data on organizations, technologies, job postings, and people — the same [tools](/api/mcp#available-tools) available on every other MCP platform.

## Before you start

You will need:

* A Google Cloud project with Gemini Enterprise, and permission to create data stores in it. Allowing custom MCP servers (step 1 below) also requires permission to edit organization policies.
* The **OAuth clients (MCP)** section enabled on your Sumble account. Once we enable it, it appears at the bottom of [sumble.com/api-keys](https://sumble.com/api-keys).

The OAuth client only identifies the Gemini Enterprise app to Sumble. Each person using the connector still signs in with their own Sumble account, and their requests use their own credits.

## Step 1: Allow custom MCP servers in Google Cloud

The organization policy **Disable custom MCP server connector for Gemini Enterprise** (`discoveryengine-managed.disableCustomMcpServerConnector`) is enabled by default on Google Cloud projects, and while it is on, custom MCP servers cannot be added. Disable it for your project on the [organization policy page](https://console.cloud.google.com/iam-admin/orgpolicies/discoveryengine-managed.disableCustomMcpServerConnector;fromListPage=true) — you may need your organization's policy administrator to do this.

## Step 2: Create a Sumble OAuth client

1. Open [sumble.com/api-keys](https://sumble.com/api-keys)
2. Scroll to the **OAuth clients (MCP)** section
3. Under **Create OAuth client**, enter:
   1. Name: `Gemini Enterprise` (or anything meaningful to you)
   2. Redirect URI: `https://vertexaisearch.cloud.google.com/oauth-redirect`
4. Click **Create client**
5. Keep this tab open — you will copy the **Client ID** and **Client secret** into the Google Cloud console in the next step

## Step 3: Add Sumble as an MCP data store

1. In the [Google Cloud console](https://console.cloud.google.com/), search for **Gemini Enterprise** and open it
2. In the sidebar, click **Connected data stores**
3. Click **New data store**
4. On the **Custom MCP Server** card, click **Add MCP server**
5. Select **OAuth 2.0** as the authentication method
6. Fill in the form:
   * MCP Server URL: `https://mcp.sumble.com/`
   * Authorization URL: `https://mcp.sumble.com/authorize`
   * Token URL: `https://mcp.sumble.com/token`
   * Client ID: paste the Client ID from your Sumble OAuth client
   * Client Secret: paste the Client secret from your Sumble OAuth client
   * Scopes: leave empty
   * **Enable PKCE Support**: enabled
   * **Use HTTP Basic Authentication**: disabled
7. Click **Verify auth** and complete the sign-in flow with your Sumble account. You should see a confirmation that authentication worked
8. Click **Continue**
9. Enter a connector name (`Sumble` works) and click **Create**

## Step 4: Enable Sumble's tools

After the data store is created you land on its page.

1. In the left panel, click **Actions**
2. Click **Reload custom actions** and complete the Sumble sign-in when prompted
3. All the tools exposed by Sumble MCP appear in the list. Select the ones you want to enable — we recommend all of them — and click **Enable Actions**

## Step 5: Authorize the connector in Gemini Enterprise

1. Open your Gemini Enterprise app and click **Connectors**
2. Find the **Sumble** connector, click **Authorize**, and complete the sign-in flow with your Sumble account

Each person using the app authorizes the connector once with their own Sumble account.

## Try it

You are ready to ask Sumble questions from Gemini Enterprise. See [Try it](/api/mcp#try-it) for example prompts, [Available tools](/api/mcp#available-tools) for what each tool does, and [Credits](/api/mcp#credits) for how usage is billed.


# Search & discovery

Start here to find the right accounts. Sumble lets you filter millions of organizations by the technologies they use, the roles they're hiring for, and firmographics like industry, location, and size, then drill into any result.

* [Organization search](/web-app/search-discovery/organization-search) for precise, filter-driven targeting
* [Natural language search](/web-app/search-discovery/natural-language-search) to describe what you're looking for in plain English


# Organization search

Search for organizations at <https://sumble.com/orgs>

Searching for organizations on Sumble is simple and flexible. Sumble's data and expressive search ui allows you to find companies matching name, url, metadata, technographic, job function/level info, and project types the organization is working on; or any combination of them!

With filters you can quickly find specific organizations or lists of them to do further research into. Clicking on an organization row will bring you to the organization's Sumble profile page where you can gain more [Organization pages](/web-app/account-intelligence/organization-pages).

{% tabs %}
{% tab title="name" %}

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-72290b0abf86e18cf7180a87b4bd016378f4f940%2Fimage%20(2)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="account list" %}

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-059e3a0e084835f899d245da1fad4148218c57f1%2Fimage%20(71).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="url" %}

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-a619497845083d6f13d7ae177a44b94d8f350bee%2Fimage%20(3).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="metadata" %}

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-701ce342bad05e6d08d8fe772d635f898b9d1b36%2Fimage%20(2).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="technographics" %}

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-9dc525219e2f15588051af7e4ad8d7e9f9b4f719%2Fimage%20(1)%20(1)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="job function" %}

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-ef4a3e78b4417e9338d43a01cfcb397c87726767%2Fimage%20(4).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="project" %}

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-4ef6ab87df0ab94692226f8b210fd66f93347ef5%2Fimage%20(5).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

## Complex searches

Even complex searches are easy with Sumble. Let's look at a couple of examples.

US companies with 500-5000 people that use AWS and Postgres and have data scientists on staff.

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-623a02e64350a7c81d5151ab7c3c53af0259bc3a%2Fimage%20(16).png?alt=media" alt=""><figcaption></figcaption></figure>

B2B companies with sales operations staff that use Mailchimp/Constant Contact/Klaviyo.

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-0558a92fd5e8eae91e265ab0f7f7b2433bcb6af0%2Fimage%20(15).png?alt=media" alt=""><figcaption></figcaption></figure>

Companies doing a data infrastructure migration that use Spark/PySpark/Spark SQL and have been hiring for these skills within the last month.

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-f1050497fe38180f118eb6d9123b319a4bc911e3%2Fimage%20(17).png?alt=media" alt=""><figcaption></figcaption></figure>

## Filtering by your own CRM data

If your CRM is connected, fields from it can appear as extra columns on the organization table, with a filter on each column header. That lets you cross your own account data, such as tier or open pipeline, against any Sumble filter. See [Filter and sort by CRM data](/system-setup-and-configuration/crm/crm-columns).


# Natural language search

Available at <https://sumble.com/orgs>

Sumble's natural language search (labeled "Quick search" in the app) lets you describe what you're looking for in plain English instead of manually building filters. It translates your query into the appropriate combination of filters and navigates you to the matching results.

## How to use it

1. Click **Quick search** in the toolbar, or press `Cmd+K` (`Ctrl+K` on Windows), to open the natural language search overlay
2. Type your query in natural language
3. Press Enter — Sumble translates your query into filters and navigates to the results

## Example queries

* "Manufacturing companies doing cloud migrations in California"
* "Data engineers at Walmart who are managers or above"
* "US teams at JP Morgan Chase using Splunk"
* "Job posts at AstraZeneca doing GenAI projects"
* "Digital native companies (excluding IT services) based in California with fewer than 1000 employees using a cloud data warehouse"

## How it works

Natural language search parses your query and maps it to Sumble's structured filters — technologies, job functions, job levels, locations, industries, headcount ranges, account lists, and more. The results you see are the same as if you'd built the filters manually; the search just gets you there faster.

Your recent queries are saved in the overlay so you can quickly re-run past searches.

## When to use filters vs. natural language

Natural language search is useful for exploratory queries or when you know what you want but aren't sure which filters to combine. For routine searches that you run often, building filters directly gives you precise control and is slightly faster since there's no translation step.

Both approaches produce the same results — natural language search and the filter bar use the same underlying data.

## Availability

Natural language search is available to all users on Free, Pro, and Enterprise plans.


# Account intelligence

Once you've found an account, get the full picture. Every organization in Sumble comes with its technology footprint, hiring activity, team structure, and the signals that tell you when something is changing.

* [Organization pages](/web-app/account-intelligence/organization-pages) bring every data point about an account into one view
* [Hiring trends](/web-app/account-intelligence/hiring-trends) show how an account's priorities shift over time
* [Teams & org structure](/web-app/account-intelligence/teams) map who builds what inside the company
* [Intent signals](/web-app/account-intelligence/intent-signals) flag when an account starts to move


# Organization pages

A Sumble organization (org) page pulls back the curtain on org structure, team distribution, hiring trends, tech stack, and much more. Any filters that were used to find the org will populate on the page and filter down all relevant attributes. Let's take a look at everything that's available! We'll use [PayPal](https://sumble.com/orgs/paypal) as an example for the rest of this page.

### Metadata

At the top of an org page we'll find a quick summary of what the organization does and the metadata points Sumble has associated with it ([industry, headcount, HQ location, parent/subsidiaries](/our-data/organizations), alternate names, urls, linkedin pages, and [tags](/our-data/organizations#tags)).

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-80e55dd4db8252ec31c82c5fdc58dfd1c15bbbfa%2Fimage%20(22).png?alt=media" alt=""><figcaption></figcaption></figure>

Below that are tabs for teams, people, job functions, job posts and trends, plus the [intelligence brief](/web-app/account-intelligence/intelligence-brief). All filters on any of them (and from the page that brought you to this one) will apply to each of these tabs.

### Teams

The teams tab shows the organization's teams as a tree, with each team's job post count, last hiring activity and technologies. Filters narrow the tree and its counts. See [Teams & org structure](/web-app/account-intelligence/teams).

{% tabs %}
{% tab title="Without Filters" %}

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-aba8743bd03917d60353b42913211732e98a12dd%2Fimage%20(23).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="With Filters" %}

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-9817106d51c40636427475451ef245abed403187%2Fimage%20(24).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

### People

The people tab displays all the people we have profiles for in the organization. For each you'll find their name role in the organization, the category of job function Sumble attributes to that role, their level in the org, and location. By default this table is ordered with the highest levels at the top; you can change this by clicking on column headers. If filters are applied then the times and counts for each of these will be after the filters have been applied.

{% tabs %}
{% tab title="Without Filters" %}

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-a7d76900a36f9e329a74c347b8614999f1ebb31b%2Fimage%20(26).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="With Filters" %}

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-17dca0cb0dfc6660fe91dd913ec281a675eb1b44%2Fimage%20(25).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

### Job functions

The job function tab provides a different view into organization structure and people, this time grouping by job function. Sumble has a job function hierarchy which organizes like job functions into a tree. Each level of the tree contains a count of people in the org with that job function. Note: the sum of all child job functions within a job function group won't match the count for the group; this is because many people don't have roles that all us to extract fine grained job functions, so they get the more generic job functions when this happens.

{% tabs %}
{% tab title="Without Filters" %}

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-6241ca74d51233bc20bb35df9d22bcf3b3cb27bb%2Fimage%20(28).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="With Filters" %}

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-bb014ce2694de4315c4a30f6a77033ec748a66aa%2Fimage%20(30).png?alt=media" alt=""><figcaption><p>Note we cannot filter by a job function in this view</p></figcaption></figure>
{% endtab %}
{% endtabs %}

### Job Posts

Job posts are the source of Sumble's rich data, they're where we extract team information, job functions, and technographics; they enable us to construct temporal relationships as we continually process new jobs posts each day.

{% tabs %}
{% tab title="Without Filters" %}

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-446773f22d456d3713e75b5ed558526d59b2a0a4%2Fimage%20(31).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endtab %}

{% tab title="With Filters" %}

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-47d2cd3ac30b1d216faa4c2d219b23b61976ef88%2Fimage%20(32).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

### Trends

The trends view enables easy contextualization. Are the number of job posts with a target filter going up, going down, flat? Looking at trends graphs can provide insight that's very difficult to build when looking at individual data points.

{% tabs %}
{% tab title="Technologies" %}

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-4f13e83d425f18ba04662b8233b1b12b8c7d40bb%2Fimage%20(35).png?alt=media" alt=""><figcaption><p>Looks like cloud investment is growing independently of kubernetes usage, with GCP slowly loosing an advantage</p></figcaption></figure>
{% endtab %}

{% tab title="Job Functions" %}

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-2b79e6f52f8d513348fc68dff1464222dd54ef34%2Fimage%20(36).png?alt=media" alt=""><figcaption><p>Appears that engineering hiring has be relatively consistent over the last 9 month</p></figcaption></figure>
{% endtab %}
{% endtabs %}


# Intelligence brief

An intelligence brief answers five questions about an account: what's the angle, who to contact, what the tech intel says, which teams are the best fit, and what's changed recently. Each brief is built from your company's [ICP and sales context](/system-setup-and-configuration/admin-portal/icp-and-sales-context), so the angle it identifies and the contacts it prioritizes reflect your specific sales motion — not a generic company overview.

## Where to find it

Intelligence briefs are available on every organization page in Sumble. Open any org — from a search result, a signal in your feed, or an account list — and look for the **Intelligence brief** tab at the top of the page.

If a brief hasn't been generated yet, clicking the tab starts generation automatically.

## What's in a brief

Each brief covers five sections:

**What's the angle**

The single most interesting entry point for this account, drawn from everything else in the brief. Specific and actionable — a sentence or two on what makes this account worth pursuing and where to start.

**Who to contact**

The people at this organization scored against your ICP target profile, ranked by fit. Each contact links directly to their full profile in Sumble. Where your Salesforce integration is connected, the brief also shows which contacts are already in your CRM and which are net-new.

**The Intel**

How the organization's tech stack intersects with what you sell — competitive technologies in use, complementary tools they've adopted, and headcount trends in the job functions you target.

**Best fit teams**

The teams inside the organization most relevant to your sale, based on the technologies and job functions in their recent hiring. Helps you focus on the right part of the business rather than the org as a whole.

**Recent changes**

Signals Sumble has detected for this organization — technology adoption events, hiring accelerations, key new hires — drawn from your configured signal types, or from Sumble's automatic detection on Free and Pro plans.

## Freshness

Briefs stay cached until the information used to build them changes. When the newest input is more recent than the oldest section, Sumble refreshes the full brief in the background. You can continue exploring the rest of the page while it generates, and the brief updates when it is ready.

For programmatic access, intelligence briefs are also available via the [API](/api/intelligence/intelligence-briefs).


# Hiring trends

The Trends tab on [organization pages](/web-app/account-intelligence/organization-pages) shows how an organization's hiring activity has changed over time. It charts job post volume broken out by technology, job function, or other dimensions so you can see where a company is investing or pulling back.

Here's PayPal as an example: <https://sumble.com/orgs/paypal/trends/job\\_functions\\_people>

## What trends show

Trends display time-series charts of job post counts, typically over the last 12+ months. You can view trends by:

* **Technologies** — track adoption and decline of specific tools (e.g., see whether AWS or GCP mentions are growing)
* **Job functions** — see which departments are hiring more or fewer people over time

The charts are interactive — hover over data points to see exact counts, and use filters to focus on specific technologies or functions.

## Using trends for selling

Trends help you build a narrative around an organization's direction:

* A sustained increase in a technology's mentions signals investment and potential budget
* A decline in a competitor's technology could mean they're evaluating alternatives
* Growing headcount in a specific function suggests scaling challenges that your product might address
* A flat trend after a period of growth might indicate a plateau or a strategic shift

Combine trends with [intent signals](/web-app/account-intelligence/intent-signals) to understand both what's happening now and how it fits into a longer pattern.

## Availability

Trends are available on Pro and Enterprise plans. Free users see a limited view.

Trends data is computed daily from Sumble's historical job post archive, which spans multiple years for most covered organizations.


# Teams & org structure

The **Teams** tab on an organization page shows the company's teams as a tree. What a team is and how Sumble finds teams is in [Our data: Teams](/our-data/teams).

Here's PayPal as an example: <https://sumble.com/orgs/paypal/teams>

## Viewing teams

Teams are displayed on the **Teams** tab of any [organization page](/web-app/account-intelligence/organization-pages). They appear as an expandable tree that shows how teams relate to each other within the company.

For each team you'll see:

* **Job post count** — how many job posts Sumble has associated with the team
* **Last hiring activity** — when the team last had an active job post
* **Technologies** — the technologies the team's job posts mention

The tree also shows the organization's subsidiaries, because a subsidiary often works like a team of its parent.

## Filtering teams

The search bar filters apply to teams. When you add a technology or job function filter, the team tree updates to show only teams with matching job posts, and the counts reflect the filtered results.

This lets you answer questions like "Which teams at this company use Kubernetes?" or "Where is this company hiring data engineers?"

## Related teams

The team page lists related teams: teams that often appear together in job posts or use the same technologies. See [Related teams](/our-data/teams#related-teams).


# Intent signals

The [Signals page](https://sumble.com/signals) lists the signals Sumble found on your accounts: new technologies, projects, hiring changes, key hires and champion moves. What each signal type means is in [Our data: Signals](/our-data/signals).

The page used to be called the Feed. Links to `/feed` still open it.

## Which signals you get

On Free and Pro, Sumble works out what matters to you from your activity, with no setup:

* the organizations you view and research
* the technologies and job functions you filter by
* the searches you run and the results you open

The alerts icon <img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-725c4077b87d33f59e52c24c537d773050ca841c%2Falerts.png?alt=media" alt="" data-size="line"> appears in the left sidebar once Sumble has enough activity to go on.

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-92caa0f6dbff6af3a17cc77045f754e6eb3a834d%2Falert.png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

How many signals each plan gets is in [Plans & billing](/get-started/plans-and-billing). Enterprise customers choose their signal types, technologies, job functions and routing. See [Sumble Signals](/enterprise-services/sumble-signals), and [Tuning your signals](/web-app/account-intelligence/intent-signals/tuning-signals) to check how each configuration performs.

## Working with signals

On the Signals page you can:

* **Mark a signal relevant or not relevant.** Sumble uses this to improve the signals you get next.
* **Favorite a signal** to come back to it.
* **Filter** by signal type, priority, organization or date.
* **Click through** to the organization, job post or person behind the signal.

## Delivery

Signals reach you in the web app, in [Slack](/slack-agent/signals-alerts-in-slack) and in email digests. Manage delivery channels and frequency in [Account > Settings](https://sumble.com/account/settings). Enterprise customers can also send signals to their CRM, data warehouse or a webhook. See [Notifications](/system-setup-and-configuration/notifications).


# Tuning your signals

Every signal in your feed comes from a signal config. A config is a standing rule, such as "any job post at my accounts that mentions Kubernetes", with a filter over technologies, job functions and other attributes. A config that matches too much fills your feed with signals you skip. One that matches too little goes quiet for weeks. This page explains how to tell which is which and what to change.

You can ask Ask Sumble "which of my signals are noisy?" or "why am I getting so many Snowflake signals?". It reads the same numbers described here and points you to the config to change.

## What to look at

Ask Sumble reports these numbers for each config over the last 12 weeks by default:

| Number                                 | What it tells you                                                                                   |
| -------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Delivered                              | How many signals the config sent.                                                                   |
| Share of feed                          | This config's part of everything you received.                                                      |
| Click rate                             | Delivered signals you opened, favorited or gave feedback on.                                        |
| Positive rate                          | Delivered signals you opened, favorited or marked relevant, without marking them not relevant.      |
| Not relevant rate                      | Delivered signals you marked not relevant.                                                          |
| Not relevant reasons                   | The reasons you picked, such as `Not my geography`, with the most common values, such as `Germany`. |
| Weekly delivered and zero-signal weeks | How steady the config is, and how many weeks it sent nothing.                                       |

Reps see only the signals delivered to them. A customer admin whose configs are all shared across the company sees totals for everyone at the company. Otherwise the numbers cover only the admin's own signals.

## Compare configs with each other

There is no single good click rate. A first-mention technology signal is rare and usually worth a look. An any-mention signal at a large account fires every week and most of those posts are routine. So compare each config with your other configs rather than with a fixed number. A config with half the click rate of your others and a third of your feed deserves a look. The same click rate on a config that sends two signals a month probably doesn't.

Give a new config a few weeks before judging it. A handful of signals is not enough to say much.

## Too broad

Signs:

* A large share of your feed with a click rate well below your other configs.
* A high not relevant rate, especially when one reason dominates.

The dominant reason usually tells you what to change:

| Reason                                        | Likely fix                                                                                                                                                                                                                                                                 |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Not my geography`                            | On the account list, set **Countries to use for Signals** for the whole list or for one organization in it. The most common values show which countries to drop.                                                                                                           |
| `Not my account`                              | Check that account ownership in your CRM is current, since signals follow the account owner. To stop signals for an organization or its subsidiaries, turn off **Include this organization in Signals** or **Include subsidiaries in Signals** for it on the account list. |
| `Not a relevant tech`                         | Remove that technology from the config's filter. If the technology is relevant but the volume is too high, switch the config from any mention to first mention by company or team.                                                                                         |
| `Not a relevant project`                      | Remove that project from the config.                                                                                                                                                                                                                                       |
| `Not a target persona` or `Not a target team` | Narrow the job functions or job level in the config's filter.                                                                                                                                                                                                              |
| `Not a useful signal type`                    | Lower the config's priority or delete it.                                                                                                                                                                                                                                  |

When the feedback is free text, read the most common values. They often name the exact technology or team that doesn't belong.

## Too narrow

Signs:

* Many zero-signal weeks.
* Steady weeks followed by a long run of nothing, which can mean the filter no longer matches anything.

Possible fixes are adding related technologies or job functions, adding organizations, or using a longer lookback window. A first-mention config is quiet by design, so weigh zero-signal weeks against how rare the event is.

## Low value

A config that delivers every week but almost never gets a click or a relevant mark is still costing you attention. If nobody acts on it, narrow it or delete it. If your plan has a signal limit, a config that sends most of your feed can also use up the limit before your other configs run. Lowering its priority doesn't change that, so narrow the filter instead.

## Making the change

Open the config from **My Team > Configurations > Signal configurations**, or follow the link Ask Sumble gives you. Your company's admins can edit configs shared across the company, and you can edit configs you own. If you can't edit a config, send the change Ask Sumble suggests, with the numbers behind it, to one of your admins. [Signal configurations](/system-setup-and-configuration/admin-portal/signal-configurations) covers every field.


# People & contacts

Find the right person to reach and how to reach them. Search people by job function and seniority across any account, and surface the contacts most relevant to your deal.

* [People search](/web-app/people-contacts/people-search) to find people by role and reporting line
* [Relevant contacts](/web-app/people-contacts/relevant-contacts) to surface the people who matter on an account


# People search

People search lets you find professionals across all organizations in Sumble's database. Use it to build contact lists, identify decision-makers, or find people with specific skills and experience.

Access people search from the top navigation bar by selecting the **People** tab, or go directly to [sumble.com/people](https://sumble.com/people).

## Searching for people

People search uses the same filter bar as organization search. Available filters include:

| Filter           | What it matches                                                                                                            |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Text search**  | Person name                                                                                                                |
| **Technology**   | Skills listed on their profile                                                                                             |
| **Job function** | Current role, such as Data Engineer or Account Executive. See [job functions](/our-data/filter-reference#job-functions)    |
| **Job level**    | Seniority, from Individual Contributor up to CXO and Board Member. See [job levels](/our-data/filter-reference#job-levels) |
| **Location**     | Location from their profile                                                                                                |
| **Organization** | Current employer                                                                                                           |
| **Account list** | People at organizations in a specific account list                                                                         |

Filters combine with AND logic — adding both a technology and a job function shows people who match both criteria.

## Search results

Results display a table with each person's name, current title, organization, job function, job level, and location. The table is sorted by seniority by default, with the highest-level people first.

Click any column header to change the sort order.

## Person profiles

Clicking a person's name opens their profile, which includes:

* **Name and current title**
* **Organization** — linked to the organization page in Sumble
* **LinkedIn URL** — direct link to their LinkedIn profile
* **Job function and level** — as classified by Sumble
* **Location and country**
* **Experience history** — past roles with dates
* **Skills** — technologies and tools from their profile
* **Contact list membership** — which of your lists they belong to

## Adding people to contact lists

From search results or a person's profile, you can save people to [contact lists](/web-app/lists-monitoring/contact-lists):

* **From the results table** — enable the Actions column (click the `+` on the table header), then use **Add to List** on any row
* **From a profile** — click the list pill next to the Lists section and select a list or create a new one

See [Contact lists](/web-app/lists-monitoring/contact-lists) for more on creating and managing lists.

## People within organizations

You can also browse people within a specific organization on the [organization page](/web-app/account-intelligence/organization-pages). The People tab there shows the same information, scoped to that company and filtered by any search bar filters you've applied.

## Revealing contact emails

For people where contact data is available, you can reveal their email address or phone number. An email costs 10 credits and a phone 80, the first time you reveal them, and nothing when none is found. See [Credits](/get-started/credits) for details on credit costs and balances.


# Relevant contacts

Sumble surfaces relevant contacts throughout the platform so you can quickly identify the right people to engage at any organization. Rather than searching through LinkedIn or your CRM separately, you'll find people connected directly to the teams, job functions, and job posts you're already researching.

## Where contacts appear

### Within teams

When you drill into a team on an organization page, you'll see the people Sumble has associated with that team. This lets you identify who actually works on the team you're selling into — not just the department head, but the engineers, managers, and directors involved.

People shown on a team are matched based on their LinkedIn profile's current role and the team structure Sumble has extracted from job posts.

### By job function

The job functions tab on an organization page groups people by [job function](/our-data/filter-reference#job-functions). Within each function, people are ranked by seniority so you can quickly find decision-makers.

Use the job level filter in the search bar to narrow results to specific levels — for example, showing only Directors and above in a particular function.

### Associated with job posts

When viewing a job post, Sumble shows people who are likely connected to that hiring activity — members of the team that posted the job, people in the same function, or the hiring manager. This context helps you understand who is driving a hiring initiative and who might benefit from your product.

## Adding contacts to lists

From any place where people appear, you can add them to a [contact list](/web-app/lists-monitoring/contact-lists) for tracking and follow-up:

1. Click the list icon or the **Add to List** action next to a person
2. Select an existing list or create a new one
3. The person is saved with their current role and organization details

Contact lists are accessible from the left sidebar and can be exported. See [Contact lists](/web-app/lists-monitoring/contact-lists) for the full workflow.

## Connecting to people search

For broader searches beyond a single organization, use [People search](/web-app/people-contacts/people-search) to find contacts across all organizations matching your filters. You can filter by technology skills, job function, job level, and location to build targeted contact lists at scale.


# Lists & monitoring

Keep your targets organized and stay on top of what changes. Build lists of accounts and contacts, save the searches you run often, and let Sumble tell you when they change.

* [Account lists](/web-app/lists-monitoring/account-lists) and [Contact lists](/web-app/lists-monitoring/contact-lists) to organize your targets
* [Saved searches](/web-app/lists-monitoring/saved-searches) to rerun your go-to queries
* [Intent signals](/web-app/account-intelligence/intent-signals) to catch account changes as they happen


# Account lists

Account lists allow you to group, track, and filter by any number of organizations. Account lists can be created via import, organization searches, and a combination of the two.

An account list can be used as a filter in [Organization search](/web-app/search-discovery/organization-search).

Your account lists are available at <https://sumble.com/account-lists>

## Import account list

If you already have a list of accounts you want to bring into Sumble you can import it in a few steps.

1. Format your account list as a CSV with the columns
   * Organization name
   * Organization url
   * Organization location
2. Click the `Import Accounts` button in the upper right corner, or [click here](https://sumble.com/upload)
3. Click `Upload CSV file`
   1. If you have more than 1000 accounts you'll need to use this [tool](https://mightymerge.io/split-csv-files/) to split your file
4. Choose the columns in your CSV that map to the required columns
5. Validate the Sumble organization matches that are made
6. Click `Confirm`
7. Choose what list to add the accounts to, creating a new list if desired, or selecting an existing list to add these accounts to it

## Create account list from search

If you're using Sumble to find new accounts, you can create account list for the results of organization filters.

1. Filtering the organization page
2. Click the `Save as Account List` button at the bottom of the page
3. Choose the number of accounts to add to the list
4. Name the account list
5. Click `Save as Account List`

## Create account list from organization

If you've found an organization that you'd like to create a new list or add to a new list you can do so quickly.

1. Click the star icon, <img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-712b7223accb9b8571cc667c451e7ee4276d6893%2Fimage%20(72).png?alt=media" alt="" data-size="line">, next to the organization name in the organization table/organization page
2. If you'd like to add the organization to an existing list, select it. Otherwise, select `New list` from the menu that appears

![](https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-ac60db19f45da75ab68a60f999de89c7ad12180a%2Fimage%20\(73\).png?alt=media)

3. Name your list!

## Edit account list

There's no single edit button for a list — adding, removing, and deleting go through separate places:

* **Add accounts**: re-import a CSV and select the existing list in the last step (see [Import account list](#import-account-list) above), or click the star icon next to an organization's name and choose the list from the menu
* **Remove accounts**: open the list, select the accounts to remove with the checkboxes, then click `Remove from list`
* **Delete a list**: open the list and click the trash icon in the top right corner
* **Rename a list**: not possible in the web app yet. Ask [Ask Sumble](/web-app/ask-sumble) to rename it, or call the [Rename organization list](/api/lists/organization-lists) API endpoint.

## Using account lists

You can use account lists to filter organization search to only the account in a specific list(s).

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-059e3a0e084835f899d245da1fad4148218c57f1%2Fimage%20(71).png?alt=media" alt=""><figcaption></figcaption></figure>


# Contact lists

Contact lists help you keep track of key stakeholders across your accounts so you can engage with precision, not guesswork. Contact lists let you group and revisit the people who matter most. Instead of scrambling to remember who you reached out to or about that person you thought might be an influencer, you can save them to account list in Sumble.

Your contact lists are available at <https://sumble.com/lists>

## Create a contact list

### From the contact list menu

1. Go to the contact list menu on the right, <img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-2562bfb3fd0b7cf84293861450c01fe10977b06f%2Fimage%20(77).png?alt=media" alt="" data-size="line">
2. Click `New list`
3. Name the list

### From a person page

From any person page you can see which of your contact lists they are currently in and optionally add them to an existing/new list.

1. Click the pill next to the `List` section: <img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-353282fc8dd4684544516c34318044ca7fe75ac4%2Fimage%20(79).png?alt=media" alt="" data-size="line"> <img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-1bbc85f7d468a58802927897773fd84d47e53e7c%2Fimage%20(80).png?alt=media" alt="" data-size="line">
2. Click `Add to new List...`

![](https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-8b7270f54707a1e4b0840e0128b3fdddc868f6df%2Fimage%20\(81\).png?alt=media)

### From a person table

If you have the `Actions` column active on a person table you can add many contacts to a list/make a new list quickly

1. Click the `+` symbol on the right side of the people table header
2. Check `Actions`
3. Choose `Add to List`
4. Click `Add to new List...`

![](https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-8b7270f54707a1e4b0840e0128b3fdddc868f6df%2Fimage%20\(81\).png?alt=media)

## List size

On Free and Pro plans a contact list holds up to 10,000 people. Adding more than that fails and leaves the list as it was, so keep lists focused and split a large audience across several. Enterprise lists have no size limit.

## Use a contact list

Go to the contact list menu on the right, <img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-2562bfb3fd0b7cf84293861450c01fe10977b06f%2Fimage%20(77).png?alt=media" alt="" data-size="line"> , and select the list you want to inspect. You'll see all the people in the list with their information all together.

<figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-90f70dd51e3a3fe1293a685aa711202f39f59e4c%2Fimage%20(86).png?alt=media" alt=""><figcaption></figcaption></figure>


# Saved searches

Saved searches let you bookmark a combination of filters so you can return to them quickly without rebuilding the search each time.

## Saving a search

1. Apply your desired filters on the organization, people, or jobs search page
2. Click **Save Search** (or use the save icon in the search bar)
3. Name the search
4. The search is added to your saved searches list

## Accessing saved searches

Saved searches are available from the left sidebar under **Searches**, or directly at [sumble.com/searches](https://sumble.com/searches). Click any saved search to jump straight to the results with all filters applied.

## Managing saved searches

From the saved searches page you can:

* **Rename** a search to keep your list organized
* **Delete** a search you no longer need
* **Re-run** a search to see updated results with the latest data

Saved search results update automatically — the filters are saved, not the results, so you always see current data when you re-run a search.


# Data exports

Exports let you download search results from Sumble as CSV files. You can export organizations, people, or job postings.

## Export types

| Type              | Available from                               | Key columns included                                                         |
| ----------------- | -------------------------------------------- | ---------------------------------------------------------------------------- |
| **Organizations** | Organization search page                     | Name, domain, industry, headcount, HQ location, technologies, job functions  |
| **People**        | People search page, organization people tab  | Name, title, organization, job function, job level, location, LinkedIn URL   |
| **Jobs**          | Jobs search page, organization job posts tab | Title, organization, team, technologies, job function, location, date posted |

## How to export

1. Run a search and apply any filters you want
2. Click the **Export** button at the top of the results
3. Use the slider to select how many rows to include (up to 10,000)
4. Pick the columns you want, then review the credit cost shown. It reflects your row count and the paid columns you picked
5. Click **Export** to confirm and download the CSV

The export preview shows the first 10 rows so you can verify the data before committing credits.

If your CRM is connected, you can narrow an export by your own account data first. See [Filter and sort by CRM data](/system-setup-and-configuration/crm/crm-columns).

## Credit costs

You pay for what the export delivers. Each export is priced per row and per column, plus email and phone reveals for the contacts we find. When the export starts, Sumble charges the most it could cost. When it finishes, Sumble refunds the difference for rows it didn't return and emails or phones it didn't find.

The rates by export type:

* **Organizations** — 1 credit per row, plus 1 credit per row for each paid column you include. Name, Domain, Alternative names and Alternative domains are part of the row price. Every other column is paid. Seven columns are priced per term: Technologies, Primary vendors, Job functions, Projects, Job levels, Headcount growth YoY and Job posts growth YoY. They list the matching terms from your filters, such as the technologies you searched for, and appear only when there are some and their column is shown in the results table. Every term you pick costs 1 credit per row, however many columns it adds. The drawer starts with Name, Domain, Employees, Teams count, Tech jobs and Last job post ticked and no terms picked, so an export you leave as it is costs 5 credits per row.
* **People** — 1 credit per row, plus 1 credit per row for each paid column you include. Name and Role are part of the row price; every other column is paid. The drawer starts with Name, Role and Organization ticked, so an export you leave as it is costs 2 credits per row. Email and Phone add no column charge. They cost 10 and 80 credits for each one we find. Misses are free, and so are contacts you've already revealed.
* **Contact lists** — 1 credit per row, plus 1 credit per row for each paid column you include. Name, Role and Date added are part of the row price. Organization, LinkedIn URL, Teams, Job function, Start date, Job level, Location and Country are paid. The drawer starts with Name, Role, Date added and Organization ticked, so an export you leave as it is costs 2 credits per row. Email and Phone add no column charge. They cost 10 and 80 credits for each one we find. Misses are free, and so are contacts you've already revealed.
* **Jobs** — 1 credit per row, plus 1 credit per row for each paid column you include. Only the job title is part of the row price; every other column is paid. The drawer starts with Job title, Organization and Date & time pulled ticked, so an export you leave as it is costs 3 credits per row. It shows the total before you confirm.

See [Credits](/get-started/credits) for details on monthly allocations and purchasing additional credits.

## Export history

All your exports are saved at [Account > Exports](https://sumble.com/account/exports). You can re-download previously generated files from there.

## Row limits

Exports are limited to 10,000 rows per download. If your search returns more results than that, the export will include the top 10,000 by the current sort order. Adjust your filters to narrow the results if needed.

For larger data needs or automated access, see the [API](/api/api) or [System setup](/system-setup-and-configuration/system-setup).


# Ask Sumble

Research accounts, find prospects, analyze your pipeline, and run sales plays with the Sumble AI agent — directly in the web app.

{% hint style="warning" %}
**Beta** — Ask Sumble is actively being developed. Functionality may change.
{% endhint %}

Ask Sumble is an AI agent built into the Sumble web app. It combines Sumble's job market intelligence with web search, code execution, and file generation so you can research accounts, surface prospects, rank your book of business, and run sales plays — all in a conversational interface, without leaving your browser.

Ask Sumble runs on the same underlying agent as the [Slack Agent](/slack-agent/slack-agent), so everything you can do in Slack you can do here, with the added context of your Sumble account and the ability to generate and download files.

{% hint style="info" %}
Ask Sumble is available on Pro and Enterprise plans. [**Try it now →**](https://sumble.com/agent)
{% endhint %}

## What you can ask

Ask Sumble can answer anything that touches Sumble's data or general research. A few categories to get you started:

**Account research**

* "Give me an intelligence brief on Stripe."
* "What's the tech stack at Datadog? Which tools have they added in the last 6 months?"
* "Are there any hiring signals at Snowflake that suggest they're expanding into Europe?"

**Prospecting**

* "Find me 10 accounts that look like our top customer — data companies, 200–2,000 employees, hiring data engineers."
* "Which companies in fintech are actively hiring for Kafka? Pull their names, LinkedIn URLs, and employee counts."
* "Here's a list of accounts from our CRM. Which ones are showing buying signals in Sumble right now?"

**Pipeline and prioritization**

* "Rank these 20 accounts by hiring activity over the last 90 days."
* "Which of my open opportunities have grown their engineering headcount by more than 20% this year?"
* "Put together a quick battle card comparing how our three biggest prospects use Python versus Go."

**Sales play preparation**

* "Draft a personalized outreach email for the VP of Engineering at Acme based on their recent hiring trends."
* "Summarize the key signals for my top 5 accounts in a format I can paste into a slide."
* "Upload this spreadsheet of contacts and tell me which ones work at companies actively hiring for our category."

## Attaching files

You can attach files to any message and Ask Sumble will read them in-context. Supported formats include documents (PDF, Word, plain text, RTF), spreadsheets (Excel, OpenDocument, CSV), presentations (PowerPoint, OpenDocument), and images (PNG, JPEG, GIF, WebP).

Ask Sumble can also generate files for you — spreadsheets, CSVs, slide decks, Word documents, PDFs — and make them available to download directly in the conversation.

## Leaving a conversation to run

A longer question can take a few minutes, and you don't have to sit and watch it. Send the question and carry on working elsewhere in Sumble — the answer keeps being written to the conversation while you do.

When a conversation has been answered since you last looked at it, a green dot appears beside it in your conversation list, and Ask Sumble in the left-hand nav shows how many conversations are waiting. Both clear when you open the conversation.

## Sharing a conversation

Every conversation starts private to you. **Share** in the conversation header opens the audience picker:

* **Just me.** The default.
* **Everyone at your company.** Anyone signed in with an email address at your domain can open the link and read the conversation.
* **Anyone with the link.** Any signed-in Sumble user who has the link can read it. Only offered on paid plans with a company email address, and worth a moment's thought before you pick it.

Under the company-domain option there's a checkbox, **Let them reply in this chat**. Leave it off and colleagues can read the conversation but not add to it. Tick it and they can ask follow-up questions in the same thread, with the whole history behind them. That is the quickest way to hand a piece of research to a teammate without making them start again.

Two things to know about replies:

* Each reply costs credits to whoever sends it, not to whoever started the conversation.
* Every question is labelled with the name of the person who asked it, so the thread stays readable once more than one of you is in it.

Only the person who started a conversation can change who it's shared with or rename it. "Anyone with the link" never gets to reply; that audience is read-only whichever else you pick.

## Web search

When it's useful, Ask Sumble supplements Sumble data with live web results — for example, checking for recent news about a prospect or validating a claim about a company's product — and cites its sources.

## Memory

Ask Sumble maintains two layers of memory:

* **Conversation memory** — context carries across follow-up messages in the same conversation, so you can build on earlier answers without repeating yourself.
* **Persistent memory** — separately, Ask Sumble remembers your preferences, goals, and account context across different conversations. Share your ICP or priorities once, and it can draw on them the next time you start a new conversation.

## The model

Ask Sumble runs on **Claude Sonnet 5** by Anthropic.

### A note on AI accuracy

Like all large language models, Claude Sonnet 5 can occasionally produce incorrect, incomplete, or outdated information. Sumble's job market data is refreshed daily, but the model's general knowledge has a training cutoff and may not reflect the most recent events outside Sumble's dataset.

Use Ask Sumble as a research and synthesis tool, not as a source of record. Where possible, Ask Sumble links directly to the underlying Sumble records in its responses — organization pages, signal views, people profiles, job posts — so you can click through and verify what it's drawing from. For high-stakes decisions — pricing, legal, or financial — also verify against primary sources.

## Credits

Each answer costs credits: the AI work to plan and write it, plus the standard price of any Sumble data it looks up. A simple account summary costs little; an answer that runs many lookups, web searches or large files costs more. Sumble shows the cost of each answer when it finishes. How answers are priced is in [Credits: Ask Sumble](/get-started/credits#ask-sumble).


# Keyboard shortcuts

Sumble supports keyboard shortcuts throughout the web application for faster navigation.

## Search & filters

| Shortcut           | Action                                                   |
| ------------------ | -------------------------------------------------------- |
| `/`                | Focus the search input                                   |
| `Escape`           | Blur the search input                                    |
| `1`                | Open the technology filter                               |
| `2`                | Open the job function filter                             |
| `3`                | Open the project filter                                  |
| `4`                | Add another filter                                       |
| `0`                | Add another filter                                       |
| `R`                | Reset / remove the selected filter                       |
| Left / Right arrow | Switch between Individual Techs and Tech Categories tabs |
| Up / Down arrow    | Navigate between filter panel sections                   |

## Tables

| Shortcut        | Action                                  |
| --------------- | --------------------------------------- |
| Up / Down arrow | Navigate between table rows             |
| `J` / `K`       | Navigate between table rows (vim-style) |

## Signals

| Shortcut | Action                              |
| -------- | ----------------------------------- |
| `F`      | Toggle favorite on selected signals |
| `M`      | Open the mark-as menu               |
| `A`      | Mark as relevant                    |
| `N`      | Mark as not relevant                |
| `U`      | Mark as unread                      |

## Account lists

| Shortcut | Action                              |
| -------- | ----------------------------------- |
| `B`      | Add organization to an account list |


# Overview

Research accounts, find prospects, rank your book of business, and receive Signal alerts with the Sumble agent inside Slack.

The Sumble Slack app does two things:

* Gives each rep an AI agent that can research accounts, find prospects, rank your book of business, and analyze your sales plays directly in a Slack thread
* Delivers [Sumble Signals](/enterprise-services/sumble-signals) alerts to your team

Use it when you want account research inside Slack, AI prospecting and whitespace discovery, or Signal alerts routed to each rep automatically.

{% hint style="info" %}
The AI agent is available on Pro and Enterprise plans. Free plan users receive Signal alerts only.
{% endhint %}

## In this section

* [Querying Sumble from Slack](/slack-agent/querying-sumble-from-slack) — the AI agent: quick-start actions, example prompts, file attachments, memory, and credits.
* [Signal alerts in Slack](/slack-agent/signals-alerts-in-slack) — delivery options, priority filters, and alert content.

***

## How to set up the Slack agent

A Slack admin installs the app once for the workspace.

{% stepper %}
{% step %}

### Open the Slack integration page

Go to the [Slack integration](https://sumble.com/integrations/slack) page in Sumble.
{% endstep %}

{% step %}

### Add to Slack

If you are already connected, the page gives you a button to open Slack.

Otherwise, click the **Add to Slack** button and follow the steps the page describes. You may need to work with your Slack administrator to set things up.
{% endstep %}
{% endstepper %}

Once installed, Sumble matches workspace members to Sumble accounts by email.

Each matched user receives a welcome DM with quick-start options.

Individual users connect their own Slack account from the [Slack integration](https://sumble.com/integrations/slack) page.

{% hint style="success" %}
If your email doesn't match between Slack and Sumble, select your Slack user manually during setup. Sumble shows your team name so you can confirm the right workspace.
{% endhint %}

***

## Troubleshooting

### Not receiving alerts

* Check that your Slack account is connected on the [Slack integration](https://sumble.com/integrations/slack) page
* Confirm your Sumble email matches your Slack email, or complete the manual connection
* Make sure you haven't muted the Sumble app in Slack

Check your notification preferences in the **Home** tab too. You may have **Don't send any updates** selected.

### The AI agent is not responding

* The AI agent requires a Pro or Enterprise plan. Confirm your plan in [Account Settings](https://sumble.com/account/settings)
* Start a new message in the Sumble app DM, or open the **Home** tab and use a quick-start action
* Replies come in-thread. Check the thread on the original message if you don't see a response

### Need to reconnect

Go to the [Slack integration](https://sumble.com/integrations/slack) page to re-authorize.

***

## Slack permissions

Sumble asks for two sets of bot permissions. The required ones are what make the app work at all — alerts have to be delivered somewhere, and Sumble has to know which Slack member is which Sumble user. The optional ones each unlock one agent capability, and your Slack admin can decline any of them during installation without blocking the rest of the app.

### Required

| Scope              | What it's for                                   |
| ------------------ | ----------------------------------------------- |
| `chat:write`       | Send alerts and agent messages via DM           |
| `team:read`        | Display your team name during manual connection |
| `users:read`       | Map users between Slack and Sumble              |
| `users:read.email` | Match Slack users to Sumble users by email      |

### Optional

| Scope               | What it unlocks                                              | If declined                                             |
| ------------------- | ------------------------------------------------------------ | ------------------------------------------------------- |
| `im:history`        | Message the agent directly in the **Messages** tab           | The agent cannot receive DMs                            |
| `app_mentions:read` | Mention **@Sumble** in a channel or thread                   | The agent cannot receive channel or thread mentions     |
| `files:read`        | Read documents, spreadsheets, and images you attach          | The agent cannot read your uploads                      |
| `files:write`       | Generate files for you to download                           | The agent cannot return generated files                 |
| `chat:write.public` | Post alerts to a public channel the app hasn't been added to | Alerts to that channel need the app invited to it first |
| `reactions:write`   | Reserved for a future feature; unused today                  | No effect on any current feature                        |

{% hint style="info" %}
Declining an optional permission only turns off that one capability. Sumble shows which are active on the [Slack integration](https://sumble.com/integrations/slack) page and in the app's **Home** tab, each with a link to reinstall and authorize if you want to add it later.
{% endhint %}

{% hint style="info" %}
Need help? Contact <support@sumble.com>. Use of this integration is subject to Sumble's [Privacy Policy](https://sumble.com/privacy).
{% endhint %}

***

## FAQ

### What is the Sumble Slack agent?

The Sumble Slack agent is Sumble's AI assistant inside Slack for account research, prospecting, whitespace discovery, sales planning, and Signal alerts.

### Who can use the AI agent in Slack?

The AI agent is available on Pro and Enterprise plans.

Free plans can receive Signal alerts in Slack, but do not get agent access.

### Can the Slack agent research accounts and prospects?

Yes. You can ask it for company research, prospect discovery, account ranking, sales plays, and whitespace accounts directly in a Slack thread.

### Can the Slack agent read uploaded files?

Yes. The agent can read supported documents, spreadsheets, presentations, and images that you attach to a Slack message.

### How are Signal alerts routed in Slack?

Sumble uses your account ownership mapping so each rep receives alerts for their own book of business.


# Querying Sumble from Slack

Research accounts, find prospects, rank your book of business, and analyze sales plays with the Sumble AI agent inside Slack.

The Sumble Slack agent gives each rep a personal AI assistant that can research accounts, find prospects, rank your book of business, and analyze sales plays — all without leaving Slack.

Open the Sumble app in Slack and start a conversation, use one of the quick-start actions in the **Home** tab, or @-mention Sumble in any channel it's a member of. In a channel thread, everyone who posts there shares the same conversation with the agent, so a teammate can pick up where you left off.

{% hint style="info" %}
The AI agent is available on Pro and Enterprise plans. Free plan users receive [Signal alerts](/slack-agent/signals-alerts-in-slack) only.
{% endhint %}

## Quick-start actions

The **Home** tab includes four one-click actions:

| Action             | What it does                                                             |
| ------------------ | ------------------------------------------------------------------------ |
| Intelligence Brief | Research a company, including hiring trends, tech stack, and key signals |
| Find Prospects     | Surface new accounts that fit your ICP                                   |
| Rank Accounts      | Prioritize your current book of business                                 |
| Sales Plays        | Upload a document and get suggested next steps                           |

Click any action to start a thread, or ask the agent anything directly.

## Example prompts

From prospecting to expansion, the agent is built for every role in the revenue org:

* "Here's a list of event attendees. Look them up in Sumble and draft a follow-up email for each."
* "Check my accounts in Sumble and tell me the top five I should prioritize today."
* "Create a game plan for the Acme account."
* "Here are my top MQLs this week. What's their data tech stack — warehouses, ETL tools, etc. — and what's a good angle for outreach?"
* "Find me whitespace accounts that fit our ICP but aren't in our CRM."

## Attaching files

You can attach files directly to any Slack message and the agent reads them in-thread. Supported formats include documents (PDF, Word, plain text), spreadsheets (Excel, OpenDocument), presentations (PowerPoint, OpenDocument), and images (PNG, JPEG, GIF, WebP).

You can attach up to 5 files per message, each up to 500 KB. Files stay available for the duration of the thread, so you don't need to re-attach them in follow-up messages.

The agent can also generate files for you — for example a spreadsheet, slide deck, Word doc, or PDF report — and upload them back to the thread when you ask for one.

## Web search

When it's useful, the agent supplements Sumble data with live web results — for example, checking for recent news about an account — and cites its sources. This same web research also enriches your [priority signal digests](/slack-agent/signals-alerts-in-slack).

## Memory

The agent maintains two layers of memory:

* **Thread memory** — within a single Slack thread, context carries across follow-up messages for 14 days, so you can pick up a conversation days later and it will know where you left off.
* **Persistent memory** — separately, the agent remembers your preferences, goals, and account context across different threads and conversations, not just the one you're in. Share your ICP or priorities once and the agent can draw on them the next time you talk to it, even in a different channel or DM.

## Support and data quality

You can ask the agent to submit a support request or flag a data quality issue directly from the thread — no need to leave Slack.

## Credits

The Slack agent is priced the same way as Ask Sumble in the web app: each answer costs the AI work plus the standard price of any data it looks up. See [Credits: Ask Sumble](/get-started/credits#ask-sumble), and check your balance at [Account > Billing & Credits](https://sumble.com/account/billing).


# Signal alerts in Slack

Receive Sumble signals in Slack, routed to each rep's book of business automatically.

Sumble can send [signals](/our-data/signals) to each rep in Slack. Sumble uses your account ownership mapping to route them, so each rep only sees alerts for their own accounts.

{% hint style="info" %}
Signal alerts in Slack are available on all plans, including Free.
{% endhint %}

To install the Sumble app and connect your Slack account, see the [Slack Agent overview](/slack-agent/slack-agent).

## Delivery options

Each user picks how alerts arrive from the **Home** tab of the Sumble app in Slack:

* **Send updates to me directly.** Alerts arrive as DMs. This is the default.
* **Send updates to a public channel.** Alerts post to a shared channel so the team can see them.
* **Don't send any updates.** Turns off all Sumble notifications.

## Priority filter

Users can also choose which [priorities](/our-data/signals#priority) to receive:

* High priority only
* Medium and high priority
* All alerts

## Alert content

Each alert includes:

* the organization name, linked to its page in Sumble
* the signal type and what was detected
* the priority (high, medium or low)
* a link to the job post, person profile or trend behind it

When it adds to the insight, the agent may add recent public web results to a signal.

Alerts go out after each daily data refresh. Sumble doesn't send the same signal twice.

## Ask follow-up questions

Priority Signal digests post as one Slack message with the full text of your top signals and an "and N more" line for the rest. Reply to the message to ask the agent about any of them. It has the full signal detail, not just what the message shows, so you don't need to open Sumble. In a DM, just reply. In a shared channel, mention Sumble by name so it sees your reply.

## Not receiving alerts?

* Check that your Slack account is connected on the [Slack integration](https://sumble.com/integrations/slack) page.
* Confirm your Sumble email matches your Slack email, or complete the manual connection.
* Make sure you haven't muted the Sumble app in Slack.
* Check the **Home** tab in the Sumble app. You may have **Don't send any updates** selected.
* On Free and Pro, signals come from your activity on Sumble. If you haven't used it recently, you may get fewer.

If your Slack workspace changes or you need to re-authorize, reconnect from the [Slack integration](https://sumble.com/integrations/slack) page. More troubleshooting is in the [Slack Agent overview](/slack-agent/slack-agent).


# Overview

Tell us the problem you're trying to solve, and we'll build the solution into the systems your team already works in.

## You have a number to hit

And the data that could help you hit it is scattered everywhere.

Reps guess which accounts to call. Marketing builds target lists on stale data. And the buying signals that matter most — a new GenAI project, a competitor slipping out of the stack, a leadership change — stay buried in job posts you'll never see in time.

The data exists. Turning it into action inside the tools your team already uses is the hard part, and it's the kind of work nobody has time to own.

## That's where we come in

With Free and Pro, you do the work in the Sumble web app.

**Enterprise is different. You tell us the problem you're trying to solve, and we build the solution into the systems your team already works in** — wherever you sit in the go-to-market org.

We've done this with RevOps, Sales, Marketing, and Customer Success teams who came to us with a number and a process spread across a dozen tools. We meet them where they work.

## How it works

1. **Tell us the problem.** Account scoring, whitespace, ABM, lead enrichment, churn risk — whatever you're trying to move.
2. **We build it into your stack.** We do the matching, the custom logic, and the delivery, then keep it updated automatically.
3. **Your team executes** with the right accounts, the right people, and the right timing already in front of them.

## What we can help you solve

* **Account scoring & prioritization** — rank your book of business with custom logic and models built around your ICP.
* **Territory planning, TAM & market sizing** — size the market and plan coverage from custom scoring.
* **Whitespace & account penetration** — find accounts missing from your CRM, and measure how much room is left inside the ones you already have.
* **CRM enrichment & cleanup** — keep account records accurate, enriched, and de-duplicated on an ongoing basis.
* **ABM targeting & messaging** — build target lists and event and campaign audiences, and shape the message around what each account is actually building and hiring for.
* **Inbound & MQL lead enrichment** — enrich leads as they arrive, so reps know who matters before they reach out.
* **Account research for reps & AI workflows** — put deep account context in front of reps and the tools they already use.
* **Trigger & signal-based selling** — signals tuned to the specific plays you run, pushed to Salesforce, Snowflake, Slack, or wherever your reps work.
* **Competitive displacement** — spot accounts pulling a competitor out of their stack so you can win the swap.
* **Churn-risk & expansion monitoring** — watch existing accounts for risk and expansion signals before a renewal call.
* **Data licensing** — license Sumble's data to power your own systems and models.

And the list goes on.

If it's a GTM problem our data can touch, it's worth a conversation.

## Where it shows up

We deliver into the systems your team already uses.

| Destination                                                                           | Enrich | Signals |
| ------------------------------------------------------------------------------------- | ------ | ------- |
| [Salesforce](/system-setup-and-configuration/crm/salesforce-package)                  | Yes    | Yes     |
| [HubSpot](/system-setup-and-configuration/crm/hubspot)                                | Yes    | Yes     |
| [Snowflake](/system-setup-and-configuration/data-destinations/snowflake-share)        | Yes    | Yes     |
| [Databricks](/system-setup-and-configuration/data-destinations/databricks)            | Yes    | Yes     |
| [BigQuery](/system-setup-and-configuration/data-destinations/bigquery)                | Yes    | Yes     |
| [Blob store (GCS / S3)](/system-setup-and-configuration/data-destinations/blob-store) | Yes    | Yes     |
| [Webhooks](/system-setup-and-configuration/data-destinations/webhooks)                | No     | Yes     |
| [Slack](/slack-agent/signals-alerts-in-slack)                                         | No     | Yes     |
| Email                                                                                 | No     | Yes     |
| Sumble web app                                                                        | No     | Yes     |

***

Keep guessing, and you find out about the deal after it's gone. Or tell us the problem you're trying to solve, and we'll put the right accounts, people, and timing in front of your team in the tools they already use.

<a href="https://sumble.com/book-a-demo" class="button primary">Book a time to chat with us</a>


# Sumble Enrich

Your GTM teams shouldn't have to leave their own systems to use Sumble's data.

Sumble Enrich takes everything that's explorable in our [web app](/web-app/search-discovery) and delivers it straight into the tools your team already works in, with daily updates of the raw data for your accounts, plus aggregations and custom logic built specifically for your organization.

## What you can do with it

#### Revenue Operations

* **Account prioritization** — from aggregations and custom logic or models
* **Territory planning** — from custom scoring
* **Whitespace analysis** — identify accounts missing from your CRM
* **Account penetration** — measure how much whitespace sits *within* an account

#### Account-based marketing

* **Prioritize targets** for ABM campaigns
* **Inform the message** with what each account is actually building and hiring for

## Deep links so reps trust the data <a href="#deep-links" id="deep-links"></a>

We provide both raw enrichments and deep links back to our data, for two reasons:

* It lets everyone see the source behind every number.
* When deep links land in your CRM, anyone can open the underlying data directly. That builds trust in the data, and gives the extra context (the actual job posts and LinkedIn profiles) to inform their outreach.

For example:

* Alongside an enrichment saying there are 71 site reliability engineers at a company, we provide a deep link to a page showing all of them.
* Alongside a number like 406 teams doing cloud migrations, we provide a deep link to those teams.

## Account matching

We handle account matching. To do it, we need at least an account name or URL. The fields we use, and which ones are required, are listed under [Accounts in Data fields](/system-setup-and-configuration/data-fields#accounts).

<a href="https://sumble.com/book-a-demo" class="button primary">Book a time to chat with us</a>


# Sumble Signals

Your team can't watch every account. It's so easy to miss tech stack changes, churn signals, active projects because there's so much going on.

Sumble Signals watches for you. We detect the moment something shifts inside an account such as a new generative AI project, a competitor slipping out of the stack, a surge in hiring, a key leadership move, and then deliver it where it will drive action.

## Two ways to put signals to work

**As alerts to your reps.** We match each signal to the account owner and route it to Slack, Salesforce, HubSpot, email, or the Sumble app, so your team reaches out while the opportunity is live, not after it's gone.

**As data in your warehouse.** We can also push signals as a raw feed into your Snowflake share or data warehouse. From there, teams blend them with their own first-party data to power account scoring, feed broader data models, and automatically create tasks for reps on your logic, in your stack.

## Specific Signals

Signals Sumble includes the types below. What each one means is in [Our data: Signals](/our-data/signals).

| Category                         | Examples                                                                                                                                                                                                                             | Why It Matters to You                                                                                                                                                             |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1. Technology Adoption           | First-time a company mentions a technology in a job post; First-time a team mentions a technology in a job post; Any mention of a technology in a job post                                                                           | Identify companies and teams investing in modern infrastructure that is either complementary or competitive with your product                                                     |
| 2. Key Technology Projects       | Cloud cost optimization; Cloud migration; Data infrastructure migration; Design system migration; Digital transformation; Frontend migration; Generative AI projects; Microservices migration; Security infrastructure modernization | Identify when a company has major technology projects and are evaluating tools, have the budget to modernize, and are open to new solutions                                       |
| 3. Acceleration in Job Postings  | Increase in mentions of technology in job posts; Increase in job functions broken out by job function                                                                                                                                | Detect when a company is investing heavily, as there's likely a new budget, growing pains, and a potential need for your solution                                                 |
| 4. New Hires                     | New leadership hire broken out by job function or experience with a specific technology                                                                                                                                              | See when new leaders are hired as they often are brought in to drive change, which includes evaluating new tools and vendors, giving you an opportunity to influence their vision |
| 5. Growth in Headcount           | Increase in headcount broken out by job function                                                                                                                                                                                     | Reveal where companies are investing and scaling as they're likely facing new challenges and expanding budgets, creating an opportunity for your product                          |
| 6. Competitor Churn Signals      | Decrease in competitor usage; relevant digital transformation and migration activity; Decrease in mentions of a competitor; Deceleration of job posts                                                                                | Identify companies that may be dissatisfied with an existing solution and may be looking to replace it, giving you the chance to win their business                               |
| 7. Own Product Churn Signals     | Decrease in mentions of own product                                                                                                                                                                                                  | Flag when an account may be at risk of reducing or canceling their contract, giving you the opportunity to proactively engage and reestablish value                               |
| 8. Champion Alerts               | A champion, economic buyer or other contact you track in your CRM changes companies                                                                                                                                                  | Somebody who already knows and trusts your product moves companies                                                                                                                |
| 9. Keyword Tracking in Job Posts | Niche certifications or compliance needs (e.g. SOC2, HIPAA); Internal pain points (e.g. technical debt, scalability issues); Unique methodology mentions                                                                             | Find hidden opportunities standard filters miss. By tracking specific keywords, you can pitch solutions for the specific problems they are hiring to solve                        |

## Data Matching

We handle matching to identify which rep owns an account in order to route an alert. We can also just send a raw alert feed, matching our account ID to your account ID and allow you to handle the routing.

To route a signal to the rep who owns the account, Sumble needs your account list with an owner on each account, plus your users. The fields are in [Data fields](/system-setup-and-configuration/data-fields).

## Integration

We deliver alerts to:

* Email
* Sumble web application
* [Slack](/slack-agent/signals-alerts-in-slack)
* [Salesforce](/system-setup-and-configuration/crm/salesforce-package)
* [HubSpot](/system-setup-and-configuration/crm/hubspot)
* [Webhooks](/system-setup-and-configuration/data-destinations/webhooks)
* [Snowflake](/system-setup-and-configuration/data-destinations/snowflake-share), [Databricks](/system-setup-and-configuration/data-destinations/databricks), [BigQuery](/system-setup-and-configuration/data-destinations/bigquery) and [blob stores](/system-setup-and-configuration/data-destinations/blob-store)

We will add more alert integrations over time. Ask us about a new integration if you don't see it here.

<a href="https://sumble.com/book-a-demo" class="button primary">Book a time to chat with us</a>


# Overview

Connect Sumble to the tools your team already uses: your identity provider, CRM, data warehouse, and notification channels.

Set up Sumble to work inside your stack. Connect your identity provider, CRM, data warehouse, and notification channels so enriched data and signals land where your team already works.

* [Admin portal (My Team)](/system-setup-and-configuration/admin-portal) is where Enterprise admins manage users, scoring, signals and sales context.
* [Data fields](/system-setup-and-configuration/data-fields) lists the account and user fields Sumble needs from your CRM or data source.
* [Users & access](/system-setup-and-configuration/users-access) covers single sign-on with SSO / OIDC.
* [CRM](/system-setup-and-configuration/crm) syncs accounts, contacts, enrichment and signals with Salesforce and HubSpot.
* [Data destinations](/system-setup-and-configuration/data-destinations) share data with Snowflake, Databricks, BigQuery or a blob store, or send signals by webhook.
* [Notifications](/system-setup-and-configuration/notifications) shows where signals can reach your team.

To manage your plan, see [Plans & billing](/get-started/plans-and-billing).


# Admin portal (My Team)

My Team is where Enterprise admins manage users, scoring, signals, sales context and integrations for their company.

**My Team** is Sumble's admin portal for Enterprise customers. Open it at [sumble.com/my-team](https://sumble.com/my-team). The page heading is your company's name followed by "Dashboard".

Customer admins (people with an **Admin** seat) see every tab. Other paid users see only **Configurations**, where most settings are read-only for them. Some features are turned on per account. If you don't see a tab or section described here, ask your account team.

## Tabs

| Tab                | What it's for                                                                                     | Page                                                                          |
| ------------------ | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Dashboard**      | One card per area below, with a summary and a shortcut to edit it.                                | This page                                                                     |
| **Users**          | Invite people, assign seats, deactivate accounts and set credit pool caps. Turned on per account. | [Users & seats](/system-setup-and-configuration/admin-portal/users-and-seats) |
| **Activity**       | How your team uses Sumble.                                                                        | [Activity](#activity) below                                                   |
| **Configurations** | Your ICP, sales context, signal configurations, account scoring, contact scoring and enrichments. | See [Configurations](#configurations) below                                   |
| **Integrations**   | Connect Salesforce or HubSpot, choose read and write, and map fields.                             | [CRM](/system-setup-and-configuration/crm)                                    |
| **Webhooks**       | Send signals to your own systems. Turned on per account.                                          | [Webhooks](/system-setup-and-configuration/data-destinations/webhooks)        |

## Configurations

The Configurations tab has one collapsible section per setting:

| Section                    | What it controls                                                                                                                        | Page                                                                                                    |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Ideal Customer Profile** | The technologies, job functions, projects and org tags that define your best-fit customer. Every Sumble score is calculated against it. | [ICP & sales context](/system-setup-and-configuration/admin-portal/icp-and-sales-context)               |
| **Sales context**          | Company context Sumble uses to write signal summaries, briefs and outreach drafts.                                                      | [ICP & sales context](/system-setup-and-configuration/admin-portal/icp-and-sales-context#sales-context) |
| **Signal configurations**  | Which changes at your accounts become signals, and how important each one is.                                                           | [Signal configurations](/system-setup-and-configuration/admin-portal/signal-configurations)             |
| **Account scoring**        | How accounts rank against your ICP.                                                                                                     | [Account scoring](/system-setup-and-configuration/admin-portal/account-scoring)                         |
| **Contact scoring** (beta) | How people rank against your ICP. Turned on per account.                                                                                | [Contact scoring](/system-setup-and-configuration/admin-portal/contact-scoring)                         |
| **Enrichments**            | The fields Sumble writes back to your CRM or data share.                                                                                | [Enrichments](#enrichments) below                                                                       |

## Activity

The **Activity** tab covers everyone at your company with a Sumble account.

* **Usage** shows how many people were active in the last 7 or 28 days (pick the window from the dropdown), how that compares with a year ago, and a 12-month chart.
* **Top filters** shows the 12 technologies, job functions, projects and job description terms your team searched for most in the last 28 days. Click the filter icon on a person's row to see theirs.
* **Activity by user** lists each person with their activity count, when they were last seen, when they signed up, their top filters and top accounts, and their manager from your CRM. An activity is a search, a filter change or a similar action. **Export CSV** downloads the table.

## Enrichments

The **Enrichments** section shows which Sumble fields reach your CRM or data share: each destination table, how many fields it carries, how many of those Sumble writes back to your CRM on every sync, and when it last pushed. The section is read-only. To add or change enrichments, contact your account team. What Sumble can enrich is described in [Sumble Enrich](/enterprise-services/sumble-enrich).


# Users & seats

Invite teammates, assign seats, deactivate accounts and set credit pool caps.

The **Users** tab in [My Team](/system-setup-and-configuration/admin-portal) is where admins manage who has access. It appears once seat management is turned on for your company. If it's off, the Users card on the Dashboard says so; ask your account team to turn it on.

## Seat types

| Seat        | What it gives                                                                         |
| ----------- | ------------------------------------------------------------------------------------- |
| **Admin**   | Full access to Sumble, plus managing members and seats. Admins see every My Team tab. |
| **Premium** | Full access to Sumble.                                                                |
| **Basic**   | A free account that joins your organization without using a seat.                     |

The **Team Members** card shows how many Admin and Premium seats are assigned out of how many your plan covers. Deactivated accounts don't count. If you assign more seats than your plan covers, everyone keeps their access and Sumble shows a reminder to bring your plan in line. Some plans stop you at the limit instead; then ask your account team for more seats.

## Invite a teammate

1. Click **Add a member** on the Users tab, or **Invite member** on the Dashboard.
2. Under **Work email**, type the part of the address before the @. You can only invite people on your company's email domains; if you have several, pick the domain.
3. Pick a **Seat type**. Premium is selected by default.
4. Click **Send invite**.

Your teammate gets an email with a link. The seat applies when they accept. An invite expires after 14 days, and it doesn't hold a seat: if none is free when they accept, they join as Basic and you get an email.

Pending and expired invites appear at the top of the table. **Resend** sends a fresh email and restarts the 14 days; links in earlier emails stop working. **Cancel** withdraws the invite.

Someone who already has a Sumble account can't be invited. Give them a seat from the table instead.

## Change someone's seat

Click the **Seat type** button on their row, pick the new seat, and confirm.

* Moving someone to **Basic** frees their seat straight away. You can give it back at any time.
* Giving a seat to someone who pays for their own Pro plan cancels that subscription when they join your organization.
* You can't remove your own Admin seat. Another admin has to change it.

## Deactivate or reactivate someone

**Deactivate** signs the person out everywhere, stops their API keys and frees any seat they held. They can't sign in until you click **Reactivate**, which brings them back on a Basic account. Give them a seat afterwards if they need one.

## Company credit pool

If your company has a shared credit pool, the Users tab shows a **Company credit pool** card with the credits available, how many were used this term and when the pool expires. How the pool works is in [Credits](/get-started/credits#company-credit-pools).

Each member with a seat can draw up to a cap from the pool during the term:

* **Edit defaults** sets the cap for every Premium seat and every Admin seat: **Uncapped**, a **Custom cap** in credits, or **No pool access**.
* The **Pool cap** button on a row sets a different cap for one person. To set several at once, tick their rows and click **Set pool cap**. Choose **Use the default for their seat type**, a **Custom cap**, or **No pool access**.

Basic accounts, pending invites and deactivated accounts can't draw from the pool.


# ICP & sales context

Define your ideal customer profile and the sales context Sumble uses to write signals, briefs and outreach.

Both live on the **Configurations** tab in [My Team](/system-setup-and-configuration/admin-portal).

## Ideal Customer Profile

Your ideal customer profile (ICP) lists what makes an account a good fit for you. Every [Sumble score](/our-data/sumble-score) is calculated against it, and person and team scores use it too.

| Part                        | What it does                                                                                                                                                                            |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Technology categories**   | Groups of technologies your buyers run, such as Cloud Data Warehouse. Counts toward the Sumble score.                                                                                   |
| **Emphasized technologies** | A few individual technologies that make or break a fit. One on its own carries far more weight than it does inside a category, so keep this list short. Counts toward the Sumble score. |
| **Job functions**           | The teams and roles that buy from you. Counts toward the Sumble score.                                                                                                                  |
| **Projects**                | Initiatives that signal a strong fit, such as a cloud migration. Counts toward the Sumble score.                                                                                        |
| **Org tags**                | [Tags](/our-data/organizations#tags) that raise or lower an account's score.                                                                                                            |
| **Individual technologies** | Technologies that decide which people at an account rank as leads and how well each team matches. They don't change the Sumble score.                                                   |

### Edit the ICP

Click **Edit** in the Ideal Customer Profile section, make your changes in **Edit your ICP**, and click **Save**.

* **Admins:** changes apply as soon as you save. Account scores update on that night's run.
* **Everyone else:** the button reads **Report edits** and the drawer's button reads **Send for review**. Your company's admins review the change; if your company has no admin, Sumble does. You get an email when it's approved or rejected.

To reweight the score itself rather than change what's in the ICP, use the [account scoring wizard](/system-setup-and-configuration/admin-portal/account-scoring).

### Review edit requests

When someone sends ICP changes for review, admins see an amber bar in the ICP section. Click **View** to open **ICP Profile Edit Requests**. Additions are marked and removals are struck through. You can adjust the change before saving it, then click **Save changes** to apply it or **Reject** to turn it down. The drawer moves on to the next request.

## Sales context

Sales context is what Sumble knows about your company. Sumble uses it to write signal summaries and [intelligence briefs](/web-app/account-intelligence/intelligence-brief), to frame why an account matters, and to draft outreach emails in your voice. The more specific it is, the better the results.

| Field                                    | What to put in it                                                                                                |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Overview**                             | What you do, who you sell to and what makes you different.                                                       |
| **Products**                             | Your main products or services, with a line on each. Helps Sumble match job posts to the right product.          |
| **Sales plays**                          | Your key use cases or selling motions. Shapes how each alert frames the opportunity.                             |
| **Buyer personas**                       | Who buys and what each role cares about.                                                                         |
| **Competitive and technology landscape** | How you compete and what you sell alongside.                                                                     |
| **Anti-signals and disqualifiers**       | What rules an account out. The only field that counts against an account, so keep it to real disqualifiers.      |
| **Discovery questions**                  | Questions to ask a prospect. Write them as questions; Sumble reuses them as written in outreach and call prep.   |
| **Customer highlight**                   | Proof points you're happy to show a prospect. Sumble cites them in drafted outreach.                             |
| **Example outreach emails**              | Emails your best reps have sent. Drafts copy their tone and structure; without them, drafts use a generic voice. |

To change it, click **Edit** in the **Sales context** section, fill in the fields and click **Save changes**. If your company has several email domains, pick the domain first; each has its own sales context.

Admins can edit sales context. Other members see it read-only. Pro users without an Enterprise account can ask <support@sumble.com> to change theirs.


# Signal configurations

Create and manage the signal configurations that decide which signals your team gets.

A signal configuration is a standing rule, such as "any job post at my accounts that mentions Kubernetes". Each one produces [signals](/our-data/signals) of one type, at one priority, for the accounts your reps own. Manage them in the **Signal configurations** section of the **Configurations** tab in [My Team](/system-setup-and-configuration/admin-portal).

## Who can change them

* **Admins** on an Enterprise account with signals can create, edit, duplicate, reorder and delete configurations. Everyone at the company shares them.
* **Other Enterprise members** see them read-only.
* **Pro users** can edit or delete their own configurations, but not create new ones.
* **Champion alerts** are set up by Sumble. Ask your account team to change one.

## Create or edit a configuration

Click **Create Signal**, or click a row to edit it. In **Configure signal**:

| Field                                    | What it does                                                                                                                                                                                                                                              |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Signal name**                          | What reps see on the signal.                                                                                                                                                                                                                              |
| **Signal event type**                    | What kind of change triggers it, such as **First mention of tech in org**, **Recent hires in job function**, **Any mention of keyword in job listing** or **Funding round raised**. The types are explained in [Signals](/our-data/signals#signal-types). |
| **Filter**                               | Which events count: the technologies, job functions, projects, keywords, locations and other conditions. **Search with this filter** opens the matching search so you can check what it catches.                                                          |
| **Track increasing or decreasing trend** | For trend types, whether to alert on growth or decline.                                                                                                                                                                                                   |
| **Minimum job level**                    | For hires, job function and mention types, the most junior level that counts.                                                                                                                                                                             |
| **Priority**                             | High, medium or low. Reps can filter alerts by priority.                                                                                                                                                                                                  |
| **Sales play**                           | What your team should do when the signal appears.                                                                                                                                                                                                         |
| **Days to look back**                    | How far back to look for matching events.                                                                                                                                                                                                                 |

The **Signal preview** on the right shows examples that match. Click **Create signal** or **Save changes**.

**Duplicate** copies a configuration, and **Delete** removes it after you confirm.

## Order matters

Each rep gets a limited number of signals per run, and Sumble fills that budget from the top of the list down. Drag rows to put the configurations that matter most at the top, so a busy one lower down can't crowd them out.

## Check how a configuration performs

The **Frequency** column shows how many signals each configuration sent in the last 7 days. To find configurations that are too noisy or too quiet, see [Tuning your signals](/web-app/account-intelligence/intent-signals/tuning-signals).


# Account scoring

Use the account scoring wizard to choose what the Sumble score rewards and how much.

The **Account scoring** section of the **Configurations** tab in [My Team](/system-setup-and-configuration/admin-portal) shows how your accounts are ranked: the weight on each part of the score, how many accounts are scored, and a leaderboard. How the score is calculated is in [Sumble score](/our-data/sumble-score).

Admins change the score with the account scoring wizard. You need an [ICP](/system-setup-and-configuration/admin-portal/icp-and-sales-context#ideal-customer-profile) first; until you have one, **Get started** takes you there.

## Open the wizard

Click **Edit** in the Account scoring section, or on the Account scoring card on the Dashboard. The wizard has three steps. Click **Continue** and **Back** to move between them, or click a step's dot. Closing the wizard throws away unsaved changes.

On the right, **Live preview** re-scores a sample of your top accounts as you edit and shows the top 25. Its **Account status** column shows whether each account is a customer, a prospect or not in your CRM, so you can check the ranking against what you know. Click a row to see its score broken down.

### Step 1: Validate ICP components

These are the signals your score is built from. Remove anything that isn't a real fit and add what's missing:

* **Technology categories.** **Create new category** groups any technologies you choose into a category of your own.
* **Individual technologies.** One on its own carries far more weight than it does inside a category. Use it only for the few that make or break a fit.
* **Job functions.**
* **Projects.** Projects count only if your ICP also has technologies or technology categories.

### Step 2: Choose attributes to boost or penalize

Pick [org tags](/our-data/organizations#tags) that should raise an account's score (**Tags to boost**) or lower it (**Tags to penalize**). A new boost starts at +15% and a new penalty at −20%; you set the exact amounts in the next step.

Until you change anything here, Sumble picks these adjustments for you. Once you change them, the list is yours and Sumble stops adjusting it. To go back to Sumble's adjustments, ask your account team.

### Step 3: Set score weights

Under **Score factors**, set how much each part of the score counts. Each level adds up to 100%, and pinning a row keeps it fixed while you move the others.

* **Size**, **Growth & momentum** and **Concentration**. The default is 50 / 30 / 20.
* Under each, the families that feed it: **Technology categories**, **Individual technologies**, **Job functions** and **Projects** for Size and Concentration; **Job functions** and **Recent funding** for Growth & momentum.
* Under each family, one weight per item, such as each job function.

Under **Org attribute adjustments**, set the percentage for each tag you picked in step 2.

Click **Save changes**.

## When changes take effect

Saving updates your ICP straight away. Every account is re-scored in that night's run, and you get an email when the new scores are ready. Saving replaces the whole scoring setup, so if two admins edit at once, the last save wins.


# Contact scoring

Tune how people at your accounts are ranked against your ICP. Beta, turned on per account.

{% hint style="info" %}
Contact scoring is in beta and turned on per account. If you don't see it on the **Configurations** tab in [My Team](/system-setup-and-configuration/admin-portal), ask your account team.
{% endhint %}

Contact scoring ranks the people at your accounts against your [ICP](/system-setup-and-configuration/admin-portal/icp-and-sales-context#ideal-customer-profile), so reps see the best people to contact first. The score appears on an account's People tab, on the People page and in people exports. It is separate from the `person_score` the [People API](/api/core-data/people) returns.

## How a person is scored

A person's score adds up five factors, each weighted:

| Factor                       | Default weight | What it measures                                                                                                   |
| ---------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Job function & seniority** | 40             | Whether their role matches a persona in your ICP, placed higher in that persona's range the more senior they are.  |
| **Account fit**              | 25             | Their company's [Sumble score](/our-data/sumble-score). Everyone at a company shares it.                           |
| **Tech involvement**         | 15             | How much their company hires for your ICP technologies in their job function. Everyone in that function shares it. |
| **Location**                 | 15             | How many of the company's people are in the person's country, plus a match with the company's headquarters.        |
| **Skills**                   | 5              | Your ICP technologies on their own profile.                                                                        |

Only a persona match, tech involvement or skills can earn a score; location and account fit adjust it.

## Tune it

Click **Edit** in the **Contact scoring** section.

* Move the **Score factors** sliders to change the weights. They add up to 100.
* Under **Job-function bands**, **Seniority emphasis** sets how fast seniority moves someone up their persona's range; 0 puts everyone at the bottom. Each persona also has its own range.
* **Live preview** shows the top people at your best-scored accounts as you edit. Pick an account to see just its people.

Click **Save changes**. The new scores show the next time someone opens the People tab. **Reset to defaults** puts the weights back.

Only admins can change contact scoring.


# Data fields

The fields Sumble pulls from your CRM or data source to match accounts and users, and which ones are required.

Sumble matches the records you share to its own data. This page is the one list of the fields we use for each record type and which ones you must provide. The pages for [Salesforce](/system-setup-and-configuration/crm/salesforce-package), [HubSpot](/system-setup-and-configuration/crm/hubspot), [Snowflake](/system-setup-and-configuration/data-destinations/snowflake-share), [Databricks](/system-setup-and-configuration/data-destinations/databricks), [BigQuery](/system-setup-and-configuration/data-destinations/bigquery) and [blob stores](/system-setup-and-configuration/data-destinations/blob-store) link here.

Use whatever column or property names are natural for your system. If you connect Salesforce or HubSpot from **My Team > Integrations**, a customer admin maps the fields there. For a warehouse or file source, your Sumble account team maps them during setup.

## Accounts

Sumble uses these fields to match your accounts to organizations in its database.

| Field                      | Required | Description                                                                                                                                 |
| -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Account ID                 | Yes      | Unique identifier for your account.                                                                                                         |
| Account Name               | Yes      | The account's organization name.                                                                                                            |
| Account URL                | Yes      | Primary URL or domain of the account.                                                                                                       |
| Account Owner ID           | No       | User ID of the rep who owns the account. Needed to route signals and alerts to the owner; must match a User ID in the [users](#users) list. |
| Account LinkedIn URL       | No       | URL of the account's LinkedIn page.                                                                                                         |
| Country                    | No       | Country where the account's organization is headquartered.                                                                                  |
| Address                    | No       | Headquarters address of the account's organization.                                                                                         |
| Parent Account ID          | No       | Unique identifier of the account's parent organization.                                                                                     |
| Ultimate Parent Account ID | No       | Unique identifier of the account's top-level parent.                                                                                        |
| Alternate Names            | No       | Other names the account's organization is known by.                                                                                         |
| Alternate URLs             | No       | Other URLs associated with the account's organization.                                                                                      |

## Users

Users are the people on your team who own accounts, such as reps and account managers. Sumble uses them to map account owners to Sumble users, so each person sees signals and alerts for the accounts they own, sees account status and CRM data for their own accounts in the web app, and managers see their direct reports' accounts.

Sumble pulls users from Salesforce or HubSpot. If your accounts come from Snowflake, BigQuery, Google Cloud Storage or S3 instead, send a users table alongside them with one row per user.

| Field         | Required | Description                                                                       | Typical Salesforce field |
| ------------- | -------- | --------------------------------------------------------------------------------- | ------------------------ |
| User ID       | Yes      | Unique identifier for the user. Must match the Account Owner ID on your accounts. | `Id`                     |
| Name          | Yes      | The user's full name.                                                             | `Name`                   |
| Email         | Yes      | The user's work email address. Use the address the rep signs in to Sumble with.   | `Email`                  |
| Title         | No       | The user's job title.                                                             | `Title`                  |
| Manager ID    | No       | Unique identifier of the user's manager. Must match another user's User ID.       | `ManagerId`              |
| Manager Name  | No       | The manager's full name.                                                          | `Manager.Name`           |
| Manager Email | No       | The manager's work email address.                                                 | `Manager.Email`          |
| Manager Title | No       | The manager's job title.                                                          | `Manager.Title`          |

Sumble also keeps any other user fields you ask us to pull, such as a region or team. Tell us which ones during setup.

Each pull reads the full list. Users no longer in it are removed from the active user list. If a pull returns no users while Sumble already has some, Sumble skips the removal, so a broken source can't empty your user list.


# Users & access

Manage who can access your Sumble workspace and how they authenticate.

Configure single sign-on and automated user provisioning for your Sumble workspace.

* [SSO / OIDC](/system-setup-and-configuration/users-access/okta-sso-oidc)
* [SCIM provisioning](/system-setup-and-configuration/users-access/scim)


# SSO / OIDC

### Overview

Sumble supports Single Sign-On (SSO) via Okta, allowing your team to log in to Sumble using their existing Okta credentials. Once configured, users can authenticate through Okta instead of using email-based login methods.

Optionally, SSO can be enforced so that all users on your domain must log in through Okta, blocking Google OAuth and Magic Link authentication.

***

### Prerequisites

* Access to the Okta Admin Console
* An Okta plan that supports OIDC (OpenID Connect) applications

***

### Step 1: Create the Okta Application

1. In Okta Admin Console, go to **Applications** > **Create App Integration**
2. Select **OIDC - OpenID Connect** and **Web Application**
3. Set the **Sign-in redirect URI** to:

```
https://sumble.com/account/login/okta/callback
```

4. Under **Assignments**, assign the users or groups who should have access to Sumble
5. Complete the setup and copy the **Client ID** and **Client Secret**

***

### Step 2: Share Credentials with Sumble

Share the following with your Sumble contact:

* **Client ID**
* **Client Secret**
* **Issuer URL** — your Okta domain, e.g. `https://your-org.okta.com`

{% hint style="info" %}
The Issuer URL is just your Okta domain (the "Org Authorization Server").

If your organization has API Access Management and prefers to use a Custom Authorization Server, you can instead provide its Issuer URI (e.g. `https://your-org.okta.com/oauth2/default`). In that case, make sure the server's Access Policy allows the Sumble app and the `openid`, `email`, and `profile` scopes.
{% endhint %}

Your Sumble contact will configure SSO on your account and confirm when it's ready to test.

***

### Step 3: Add Sumble to Your Okta Dashboard (Optional)

After SSO is configured by Sumble, you can allow users to launch Sumble directly from their Okta app dashboard:

1. In Okta Admin Console, go to the Sumble application settings
2. Under **General** > **Login**, set:
   * **Login initiated by**: Either Okta or App
   * **Initiate login URI**: Your Sumble contact will provide this URL after setup
3. Save the settings
4. Users will now see Sumble in their Okta app dashboard

***

### SSO Enforcement

Once SSO has been successfully tested (at least one user must log in via Okta), you can optionally request that SSO be enforced for your organization. When enforcement is enabled:

* Google OAuth login is blocked for users on your domain
* Magic Link login is blocked for users on your domain
* All users must authenticate through Okta

To enable or disable SSO enforcement, contact your Sumble representative.


# SCIM provisioning

Let your identity provider create, update and deactivate Sumble users automatically.

With SCIM, your identity provider (Okta or Rippling) manages Sumble accounts for you. Assign someone to the Sumble app in the IdP and they get a Sumble account with a seat. Unassign them, or deactivate them in the IdP, and they lose access to Sumble the same minute, including any API keys and MCP connections they set up.

SCIM requires [Okta SSO](/system-setup-and-configuration/users-access/okta-sso-oidc). Require Okta has to be on before Sumble issues a SCIM token, because deactivating someone in the IdP only locks them out if the IdP is the only way in.

***

### What Sumble supports

* SCIM 2.0, Users resource only. No groups.
* Create, read, update (PUT and PATCH), deactivate (`active: false`) and delete.
* Filtering by `userName` and `externalId`, which is what the IdP uses to match people on its first import.

Google Workspace can't call a custom SCIM endpoint, so it is not supported.

***

### Step 1: Get a token from Sumble

Ask your Sumble contact to turn on SCIM provisioning. They will send you two values:

* The **SCIM connector base URL**: `https://sumble.com/api/scim/v2`
* A **bearer token**. It is shown once. If it is lost, your Sumble contact can rotate it, and the old one stops working.

***

### Step 2: Okta

1. In Okta Admin Console, go to **Applications** > **Create App Integration** and select **SAML 2.0**. Create a separate app in the same Okta org, named e.g. "Sumble SCIM". People still sign in through the OIDC app from [Okta SSO](/system-setup-and-configuration/users-access/okta-sso-oidc). This app only provisions accounts, so its SAML sign-in settings are never used. Use these placeholder values:
   * **Single sign-on URL**: `https://sumble.com/`
   * **Audience URI**: `sumble-scim`
   * **Application username**: Email
2. Open **General** > **App Settings** > **Edit** and set **Provisioning** to **SCIM**. Save.
3. On the new **Provisioning** tab, under **Integration**, set:

   * **SCIM connector base URL**: the base URL from step 1
   * **Unique identifier field for users**: `userName`
   * **Supported provisioning actions**: Push New Users, Push Profile Updates, Push User Deactivation, Import New Users and Profile Updates
   * **Authentication Mode**: HTTP Header
   * **Authorization**: the bearer token from step 1

   Paste the token on its own, without a `Bearer` prefix.
4. Click **Test Connector Configuration**. Okta reads Sumble's SCIM metadata and reports what it supports.
5. Save, then open **Provisioning** > **To App** and enable **Create Users**, **Update User Attributes** and **Deactivate Users**.
6. Optional: run **Import** once. Okta lists everyone who already has a Sumble account at your domains and links them to their Okta users, so nothing is created twice.
7. Assign people or groups to both the SCIM app and the OIDC SSO app. The SCIM app provisions their accounts, and the OIDC app lets them sign in.

#### Attribute mapping

Sumble reads these attributes. Everything else Okta sends is ignored.

| Okta attribute            | Sumble                                                                                 |
| ------------------------- | -------------------------------------------------------------------------------------- |
| `userName`                | Email address. Has to be at one of your Sumble domains. Can't be changed through SCIM. |
| `givenName`, `familyName` | Name                                                                                   |
| `displayName`             | Name, when the given and family names are not mapped                                   |
| `externalId`              | Okta's id for the user, used for matching                                              |
| `active`                  | Whether the person can sign in                                                         |

***

### Step 2: Rippling

1. In Rippling, open the Sumble app and start the **Custom SCIM** setup.
2. Enter the base URL and bearer token from step 1.
3. Map `userName` to the work email, and `givenName` and `familyName` to the name.
4. Turn on create, update and deactivate.

***

### What happens in Sumble

**A new user** gets a Sumble account on a Basic plan. If your seat subscription has a premium seat free, they take it straight away and start on Premium. If every licensed seat is taken, the account is created on Basic and a Sumble admin can assign a seat later from My Team. The IdP is never told no, so it does not keep retrying.

**Updates** to the name or `externalId` are applied as sent.

**Deactivating** someone, whether by unassigning them from the app, setting `active` to false, or deleting the user in the IdP, does the same thing as deactivating them from My Team:

* They can't sign in.
* Their open sessions end on their next request.
* Their API keys and MCP tokens stop working.
* Their seat is freed for someone else.
* Any open invitation for them is cancelled.

Their data stays. **Reactivating** them in the IdP lets them sign in again on Basic; a Sumble admin assigns a seat if they need one.

Sumble never hard-deletes an account through SCIM. To erase someone's data, contact Sumble.


# CRM

Connect Sumble to your CRM to sync accounts, contacts, and enrichment.

Connect Sumble to your CRM so enriched account and contact data flows directly into the systems your team already uses.

A customer admin connects the CRM from **My Team > Integrations** in Sumble. From the same panel they choose whether Sumble reads from the CRM, writes to it, or both, map your CRM fields to the [fields Sumble uses](/system-setup-and-configuration/data-fields), and disconnect. A company connects one CRM at a time.

* [Salesforce](/system-setup-and-configuration/crm/salesforce-package)
* [HubSpot](/system-setup-and-configuration/crm/hubspot)
* [Salesforce import](/system-setup-and-configuration/crm/salesforce-import): add Sumble organizations and people to Salesforce from the web app
* [Filter and sort by CRM data](/system-setup-and-configuration/crm/crm-columns)


# Salesforce

## Overview

Sumble's Salesforce integration enables bi-directional sync between your Salesforce instance and Sumble.

Sync from Salesforce to Sumble:

* **Account list** — Keep your Sumble account universe in sync with Salesforce
* **Account assignments** — Personalize the Sumble experience for your AEs and SDRs based on their assigned accounts
* **Contacts** — Enable champion tracking alerts and indicate whether contacts on Sumble are present in your CRM
* **CRM fields as columns** — Show Account fields, or values derived from related records, as filterable columns in Sumble. See [Filter and sort by CRM data](/system-setup-and-configuration/crm/crm-columns)

Sync from Sumble to Salesforce:

* **Custom enrichments** — Write firmographic and technographic enrichments relevant to your company back to Salesforce
* **Contacts/Leads** — Add contacts identified on Sumble back to your CRM
* **Signals** — Surface job changes, champion alerts, and other signals directly in Salesforce on Account records

Each feature can be enabled individually, with only the narrow set of permissions required for that feature assigned to the integration user. See [Salesforce permissions](/system-setup-and-configuration/crm/salesforce-package/salesforce-permissions) for the exact permissions each feature needs, and for the difference between the one-time setup admin and the ongoing integration user.

*Note: Requires Salesforce Enterprise Edition or higher to use Bulk API 2.0 functionality.*

***

## Managed Package

In addition to the data sync capabilities above, Sumble provides a managed package that adds:

* **Account Page Widget**: A Lightning component (Sumble Enrichments) that displays enrichment data directly on Account record pages, with deep links back to Sumble for detailed information:

  <figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-d2485a5048e4d5e7079fd6481835e253e9f263ac%2Fimage%20(92).png?alt=media" alt=""><figcaption></figcaption></figure>
* **Signals Custom Object**: A managed `Signal__c` object that stores signals — such as job changes, champion alerts, and recent hires — linked directly to Account records. Sumble populates these automatically.
* **Signals Tab**: A dedicated Sumble Signals tab where users can browse, filter, and group all signals for their assigned accounts:<br>

  <figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-bdccb015ed2dea682e767688175a7253e611c2ff%2Fimage%20(89).png?alt=media" alt=""><figcaption></figcaption></figure>
* **Account Signals Widget**: A Lightning component (Sumble Account Signals) that shows signals specific to an Account, embeddable on any Account record page:

  <figure><img src="https://591792295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fd8pAyUZEiTL25GKepCIo%2Fuploads%2Fgit-blob-954d5938a173c351464def18a8e1a1fd6cfb2a09%2Fimage%20(90).png?alt=media" alt=""><figcaption></figcaption></figure>
* **Admin Setup UI**: A configuration interface for connecting to Sumble and managing enrichment settings

***

## Step 1: Install the Package

1. Navigate to the installation URL: <https://login.salesforce.com/packaging/installPackage.apexp?p0=04tg8000000ESIzAAO>
2. Log in to your Salesforce org if prompted
3. Select "Install for All Users"
4. Click Install

> ***Who can do this:** You need the "Customize Application" or "Modify All Data" permission (Salesforce admin). This permission can be granted either through the user's profile or through an assigned permission set. Users without these permissions will see an "Administrator Access Required" message.*

✅ **How to know it worked:** You'll see a confirmation that the package installed successfully.

⚠️ **Don't stop here.** The package is installed but nothing is connected yet. Continue to Step 2.

***

## Step 2: Connect to Sumble

After installation, navigate to the **Sumble Setup** tab to configure the integration. The setup wizard guides you through three steps: Connect, Configure, and Complete.

You have two options for connecting:

#### Option A: Quick Setup

Use your current Salesforce user's credentials for the connection. This is the simplest way to get started.

1. On the Connect step, select **Quick Setup** and click **Connect to Sumble**
2. A popup window will open with the Sumble login page
3. Log in to your Sumble account and authorize the connection
4. The popup will close automatically and you'll see a success message

*Important: The Salesforce user who completes this OAuth flow is the user that Sumble will use to connect to your Salesforce instance.*

#### Option B: Integration User (Recommended for production)

Use a dedicated integration user for the Salesforce connection. This is recommended for production environments because the connection is tied to a service account rather than an individual user — it won't break if someone leaves the organization or changes roles.

The integration user setup is a two-step process:

**Part 1 — Salesforce to Sumble**: A Salesforce admin clicks **Set up with Integration User**, then clicks **Connect** on the first step. This registers your Salesforce org with Sumble. You'll see a green checkmark once the connection is established.

**Part 2 — Sumble to Salesforce**: Log into Salesforce as your dedicated integration user (a separate browser or incognito window works well). In that same browser, log into Sumble as a customer admin of your team, go to **My Team**, then the **Integrations** tab, open **Salesforce**, and connect it. When Salesforce asks you to sign in, use the integration user. Only customer admins can connect Salesforce to Sumble.

The setup page also shows a link for this step. It opens the same Salesforce panel in Sumble. This authorizes Sumble to access Salesforce using the integration user's credentials. Once complete, return to the Sumble Setup page and click **Continue to Configuration**.

*Tip: Create a dedicated Salesforce user (e.g., "Sumble Integration") with only the permissions Sumble needs — see* [*Salesforce permissions*](/system-setup-and-configuration/crm/salesforce-package/salesforce-permissions) *for the exact list, including which license types work. This keeps the integration independent of any individual's account.*

Once connected via either method, you'll see a green status bar showing the connected customer name and timestamp.

***

## Step 3: Configure

The Configure step has three sections:

#### Section 1: Select and Order Enrichments for Widget Display

Choose which enrichments appear in the Account page widget and their display order.

* Check/uncheck enrichments to show or hide them in the widget
* Use the up/down arrows to reorder enrichments
* New enrichments added to your Sumble account will appear automatically at the end of the list

#### Section 2: Choose Where to Store Enrichments

Select where Sumble should write enrichment data in Salesforce.

**Option A: Account custom fields (Default)**

* Enrichments are written directly to fields on the Account object
* Simplest setup—just map fields in Section 3

**Option B: Custom object**

* Enrichments are written to a related custom object
* Select your custom object from the dropdown
* See #custom-object-requirements below

#### Section 3: Map Enrichments to Salesforce Fields (Optional)

Map each enrichment to a specific Salesforce field for data sync.

* For each enrichment, select a destination Salesforce field from the dropdown
* Fields are shown with their API name, label, and type (e.g., Website (Website) - Text)
* Leave as "-- None --" to skip syncing that enrichment
* Each Salesforce field can only be mapped to one enrichment
* Enrichments with URLs also have a separate URL field you can map

Click **Save** when you're done configuring.

***

## Step 4: Complete

After saving, you'll see confirmation that setup is complete, along with instructions for adding widgets to Account pages.

***

### Adding Widgets to Account Pages

After completing setup, add the Sumble components to your Account page layout:

1. Navigate to any Account record page
2. Click the gear icon (⚙️) and select Edit Page
3. In the Lightning App Builder, find the Sumble components in the Components panel:
   * **Sumble Enrichments** — displays enrichment data for the account
   * **Sumble Account Signals** — displays signals for the account
4. Drag the desired component(s) onto your page layout
5. Click Save and Activate the page

Both widgets will automatically hide if there's no data for an Account, keeping your page clean.

***

## Custom Object Requirements

If you choose to write enrichments to a custom object instead of Account fields, your custom object must meet these requirements:

### Required Configuration

<table><thead><tr><th width="234">Requirement</th><th>Details</th></tr></thead><tbody><tr><td>Master-Detail Relationship</td><td>The custom object must have a Master-Detail relationship to the Account object</td></tr><tr><td>External ID Field</td><td>Must have a field named <code>External_Id__c</code></td></tr><tr><td>External ID Settings</td><td>The <code>External_Id__c</code> must be a `Text(18)` field and must be marked as both <strong>External ID</strong> and <strong>Unique ID</strong>.</td></tr></tbody></table>

***

## Disconnecting

To disconnect your Salesforce org from Sumble:

1. Navigate to the Sumble Setup tab
2. Click the Disconnect button in the green status bar
3. Confirm the disconnection

This will clear the stored credentials. You can reconnect at any time by clicking "Connect to Sumble" again.

## Signals

Sumble automatically populates signals in Salesforce — such as job changes, champion alerts, and new hires in key functions — directly on Account records.

Signals are stored in the managed **Sumble Signal** (`Signal__c`) custom object, which has a Master-Detail relationship to the Account object. Each signal includes details like the person's name, title, LinkedIn profile, and the organizations involved.

### Signals Tab

Navigate to the **Sumble Signals** tab to see all signals across your assigned accounts in a single feed.

* **Filter by priority** — Focus on high, medium, or low priority signals
* **Filter by type** — Show only specific signal types (e.g., champion alerts, job changes)
* **Group by type** — Toggle grouping to organize signals by category, with counts per type
* **Pagination** — Click "Load More" to see older signals

Signals are shown based on Account ownership. By default, you'll see signals for accounts where you are the Owner.

### Account Signals Widget

The **Sumble Account Signals** Lightning component can be added to any Account record page to show signals specific to that account.

* Displays signals with priority badges, person details, and links to LinkedIn and Sumble
* Supports the same priority and type filters as the Signals tab
* Includes pagination for accounts with many signals

### Priority Signals

Priority signals are the items from your Sumble digest: the raw signals at an account, read together and written up as one headline with an explanation. They are pushed to the same `Signal__c` object as raw signals, so they appear in the Signals tab, in the Account Signals widget, and in any report built on that object.

Priority signals are off until you ask for them. Before turning them on, check any Flows, triggers or reports you have built on `Signal__c`, since they will see the new type too. Then ask your Sumble contact to enable them.

* The signal type is `priority_signal`, and the name is **Priority signal**, so they form their own group when you group by type
* They are always **high** priority
* The headline is the title, the explanation is the digest's write-up, and the Sumble link opens the item in Sumble
* A priority signal is written for one person. It is pushed only to the accounts that person owns in your CRM, so account owners see the items written for them and not their colleagues'

### Configuring Signal Ownership (Admin)

By default, signals appear for accounts where the current user is the Account Owner. Administrators can expand this to include additional ownership fields:

1. Navigate to the **Sumble Signals** tab
2. Click the gear icon (⚙️) in the top-right corner to open the Signal Ownership Configuration
3. Select which Account fields determine signal visibility:
   * **OwnerId** (default) — the standard Account Owner field
   * **Custom user lookup fields** — e.g., `SDR_Owner__c`, `CSM__c`, or any custom Lookup(User) field on the Account object
4. Optionally enable **Include Account Team members** to show signals for accounts where the user is an Account Team member
5. Click **Save**

*Example: If you select OwnerId and SDR\_Owner\_\_c, both the Account Owner and the assigned SDR will see signals for that account on their Signals tab.*

***

## Account data + Sales Territories

Sumble uses these fields for account matching. The full list, including optional fields, is in [Accounts in Data fields](/system-setup-and-configuration/data-fields#accounts).

<table><thead><tr><th width="232.203125">Field</th><th width="89.875" data-type="checkbox">Required</th><th>Default field</th></tr></thead><tbody><tr><td>Account ID</td><td>true</td><td><code>Id</code></td></tr><tr><td>Account Name</td><td>true</td><td><code>Name</code></td></tr><tr><td>Account URL</td><td>true</td><td><code>Website</code></td></tr><tr><td>Account Linkedin URL</td><td>false</td><td></td></tr><tr><td>Country</td><td>false</td><td><code>BillingCountry</code></td></tr><tr><td>Parent Account ID</td><td>false</td><td><code>ParentId</code></td></tr><tr><td>Ultimate Parent Account ID</td><td>false</td><td></td></tr></tbody></table>

A customer admin sets which Salesforce field holds each of these in **Organization mappings** on the Salesforce panel of **My Team > Integrations**. The same panel has **User mappings**, the **Read** and **Write** toggles that control whether Sumble pulls from Salesforce, pushes to it, or both, and **Disconnect Salesforce**. If other fields are relevant, we can load those into Sumble as well.

To understand your sales team's account assignments, Sumble's app reads the following fields and objects:

* Account Owner (`Owner.Name` and `Owner.Email`)
* Custom fields for other roles (e.g. `SDR_Owner__r.Name` and `SDR_Owner__r.Email`)
* The `AccountTeamMembers` table, if used

The user fields Sumble pulls are listed under [Users in Data fields](/system-setup-and-configuration/data-fields#users).

By default, we'll pull all non-deleted Accounts. In practice, this is often a broader fetch than is intended to be enriched as there are often parking lot Accounts, or Accounts that are still being qualified. Let us know what filter we should use to limit those pulls. A common filter is to set up or reference a boolean field to determine what to enrich, though a SOQL WHERE clause on the Accounts sObject will work.

## Technical Details

#### Data retrieval (pull from Salesforce)

* Uses Bulk API 2.0 Query endpoint
* Resource usage:
  * Consumes up to 6 of 10,000 available daily jobs
  * Pulls only pre-configured fields
  * Downloads all accounts in the instance

#### Signals Sync

* Signals are synced to the managed `Signal__c` custom object
* Each signal is linked to an Account via a Master-Detail relationship
* Signals include metadata: type, priority (high/medium/low), person details, organization changes, LinkedIn URLs, and timestamps
* Priority signals are synced to the same object with type `priority_signal`, scoped to the accounts their reader owns
* Sumble manages the full lifecycle — signals are created and updated automatically

#### Data Updates (push from Sumble) <a href="#data-updates-push-from-sumble" id="data-updates-push-from-sumble"></a>

* Uses Bulk API 2.0 Ingest endpoint
* Processing details:
  * Submits jobs with up to 250k rows
  * Up to 6 updates per day for each organization
  * Example scale: For 1.2M accounts
    * Each run takes 5 jobs
    * Processes 7.2M of 150M available daily row updates
  * Updates custom fields on `Account` object

<a href="https://sumble.com/book-a-demo" class="button primary">Book a time to chat with us</a>


# Salesforce permissions

This page lists exactly what permissions Sumble needs in your Salesforce org, and — just as importantly — what it does **not** need.

## Two different users, two different permission sets

These are two separate roles with different requirements:

| Role                 | When                             | Needs                                                                                                |
| -------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Setup admin**      | During install and configuration | A Salesforce administrator — `Customize Application` *or* `Modify All Data`                          |
| **Integration user** | Every sync                       | **No administrator permissions.** `API Enabled` plus object/field access for the features you enable |

If your org restricts connected apps to pre-authorized users ("Admin approved users are pre-authorized"), also grant the integration user access to the **Sumble** connected app via its profile or permission set. Otherwise the OAuth authorization is refused.

***

## Setup admin (one-time)

The admin who installs and configures the package needs:

* `Customize Application` **or** `Modify All Data`. Either one is sufficient, and either can come from the user's **profile or an assigned permission set** — you do not need to hand the person a System Administrator profile.
* Salesforce itself additionally requires admin rights to install a managed package and to edit Lightning record pages (to place the Sumble widgets).

If you don't want to grant the admin these permissions permanently, assign a permission set containing `Customize Application` for the duration of setup and remove it afterwards. Once setup is complete, no one needs these permissions for day-to-day use. End users see the Account widgets and the Signals tab with no Sumble-specific permission at all as the package was installed wit&#x68;**"Install for All Users"**, which is what grants ordinary users access to the package's components.

***

## Integration user (ongoing)

### License and profile

Either of these works:

* **A standard Salesforce license** with the `Minimum Access - Salesforce` profile (or your own equivalent least-privilege profile). This will consume a license.
* **The `Salesforce Integration` (API-only) license** with the `Minimum Access - API Only Integrations` profile.

Best practices are to grant the actual permissions through a dedicated permission set (e.g. "Sumble Integration") rather than the profile — it keeps the grant auditable and easy to revoke.

#### Give the integration user an email address you can actually receive mail at

Sumble's connection is authorized once through a browser-based OAuth flow, so the integration user has to get through a Salesforce login and approval screen. Email matters twice:

* **Setting the password.** A new user gets a "set your password" link by email. Someone has to be able to open the link.
* **Verification codes.** If Salesforce doesn't recognize the browser or IP, it emails a verification code before letting the login through.

Use an address you control — an alias like `salesforce-admin+sumble@yourcompany.com` works well, and keeps the mail with whoever administers the integration. Its **Username** can be anything and doesn't have to match.

Open the password link in an incognito window so it doesn't collide with your own Salesforce session, sign in as the integration user there, retrieve any verification code from your inbox, and approve the Sumble authorization. If you can't get through the authorization at all, you can switch the user to a standard license or [talk to us](#notes) and we'll work through it with you.

### Object and field permissions by feature

The following features require the associated object permissions. This table will help you scope permission granularity for the integration user, if you choose.

| Feature                                      | Direction           | Objects                                                    | Object permissions                                                        |
| -------------------------------------------- | ------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------- |
| Account list sync                            | Salesforce → Sumble | `Account`                                                  | Read                                                                      |
| Sales rep / owner sync                       | Salesforce → Sumble | `User`                                                     | Read                                                                      |
| Account team assignments                     | Salesforce → Sumble | `AccountTeamMember`, `User`                                | Read                                                                      |
| Contacts / champion tracking                 | Salesforce → Sumble | `Contact`, `Lead`                                          | Read                                                                      |
| Derived fields from related records          | Salesforce → Sumble | whichever object the rule queries (commonly `Opportunity`) | Read                                                                      |
| Enrichments written to Account fields        | Sumble → Salesforce | `Account`                                                  | Read, Edit                                                                |
| Enrichments written to a custom object       | Sumble → Salesforce | your custom object, `Account`                              | Read + Create + Edit on the custom object; Read **and Edit** on `Account` |
| Signals                                      | Sumble → Salesforce | `sumble__Signal__c`, `Account`                             | Read + Create + Edit on `sumble__Signal__c`; Read and Edit on `Account`   |
| "Send to Salesforce" from the Sumble web app | Sumble → Salesforce | `Contact`, `Lead`, `Account`                               | Create (this uses a separate authorization — see below)                   |

* **Enrichments to a custom object / Signals** both write to an object with a **master-detail relationship to Account**, and Salesforce requires *write* access to the parent record to create or update a detail record. So these need `Edit` on `Account`, not just `Read`, even though no Account field is being changed.
* **Derived fields from related records** and the **champion-tracking query** are configured as Salesforce queries against objects of your choosing (for example, counting open opportunities per account). If your configuration uses these, the integration user needs `Read` on every object and field those queries touch as well.

**Field-level security** must also be granted if they are not granted at the object level:

* **Read** on every field mapped for the pull — at minimum `Id`, `Name`, `Website`, plus any `BillingCountry`, `ParentId`, owner lookup fields, and extra columns in your configuration. Also `IsDeleted` on `Contact`, and `IsDeleted` + `IsConverted` on `Lead`, which the sync filters on; and `TeamMemberRole` plus `User.Name` / `User.Email` / `User.Title` if account team assignments are synced.
* **Edit** on every destination field for the push — the fields you selected in the Sumble Setup field mapping, **plus the record keys the sync writes that aren't part of your field mapping**: `External_Id__c` and `Account__c` on a custom-object target, and `Name`, `sumble__External_Id__c`, `sumble__Account__c` on `sumble__Signal__c`.

If you're using a custom object for enrichments, its `External_Id__c` must be `Text(18)` and marked both **External ID** and **Unique**.

### Record visibility

Object permissions control *which objects*; your sharing model controls *which records*. A least-privilege integration user owns no records, so under a Private or Public Read Only org-wide default it will see almost nothing — the sync completes "successfully" and pulls a fraction of your accounts, or push writes fail with `INSUFFICIENT_ACCESS_OR_READONLY`.

Grant record access by whichever of these fits your security model:

* **`View All` on `Account`** (object-level, in the permission set) for read-only features, and **`Modify All` on `Account`** if Sumble writes enrichments or Signals back. These are per-object permissions — they are *not* the org-wide `View All Data` / `Modify All Data`.
* Or a **sharing rule** that shares the relevant accounts with the integration user (or a group it belongs to). Same for `Contact` / `Lead` if those are synced.

Note that `sumble__Signal__c` is a master-detail child of `Account`, so its record access is inherited from the parent Account — writing Signals requires edit access to the parent accounts.

### What Sumble never needs

* `Modify All Data` or `View All Data` (the per-object `View All` / `Modify All` above are narrower and are all that's needed)
* `Customize Application`, `View Setup and Configuration`, or `Manage Users`
* `Author Apex` or `Modify Metadata Through Metadata API Functions` — Sumble never creates or alters fields, objects, or any other metadata in your org
* **Any delete permission** — Sumble never deletes your records. Writes are updates and creates only.
* Access to any object beyond those in the table above. The only way that list grows is if your configuration includes a derived-field or champion-tracking query that references another object, which is something you configure with us explicitly.

***

## Troubleshooting

| Symptom                                                                      | Cause                                                                                                                                                                                                                                                                                                                 |
| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Administrator Access Required" on the Sumble Setup tab or Signals gear icon | The signed-in user has neither `Customize Application` nor `Modify All Data`. Note the check is cached — retest in a fresh incognito window after granting.                                                                                                                                                           |
| Integration user can't get through the OAuth login/approval screen           | The set-your-password link or the verification code went to a mailbox nobody can open. See [Give the integration user an email address you can actually receive mail at](#give-the-integration-user-an-email-address-you-can-actually-receive-mail-at). Affects the one-time authorization only, not ongoing syncing. |
| OAuth authorization refused                                                  | The Sumble connected app is restricted to pre-authorized users and hasn't been granted to this user.                                                                                                                                                                                                                  |
| `API_DISABLED_FOR_ORG` or API calls rejected outright                        | `API Enabled` missing from the integration user's profile/permission set.                                                                                                                                                                                                                                             |
| Sync returns far fewer accounts than the org contains                        | Record visibility, not object permissions — see [Record visibility](#record-visibility).                                                                                                                                                                                                                              |
| `INSUFFICIENT_ACCESS_OR_READONLY` on push                                    | Missing `Edit`/`Modify All` on `Account`, or missing field-level `Edit` on a mapped destination field.                                                                                                                                                                                                                |
| `INVALID_FIELD` on push                                                      | Field-level Read/Edit not granted on a mapped field, or the field doesn't exist on the target object.                                                                                                                                                                                                                 |
| Enrichments write, but no Signals appear                                     | Missing `Read`/`Create`/`Edit` on `sumble__Signal__c`, or no edit access to the parent accounts.                                                                                                                                                                                                                      |
| A single derived-field column is always empty, with no error                 | The query behind it references an object or field the integration user can't read. These fail quietly by design so one bad column can't stop the whole sync.                                                                                                                                                          |
| End users see "You do not have access to the Apex class…"                    | The package was installed for admins only rather than with **Install for All Users**.                                                                                                                                                                                                                                 |
| `INVALID_FIELD` naming `External_Id__c` on a custom-object target            | The field is missing, or isn't `Text(18)` marked External ID **and** Unique.                                                                                                                                                                                                                                          |

***

## Notes

* Bulk API 2.0 is required, so Salesforce **Enterprise Edition or higher** is needed.
* If your org enforces **Login IP Ranges**, note that Sumble's syncs run from Google Cloud and we do not currently publish a fixed egress IP range — talk to us before applying an IP restriction to the integration user.
* The web app's "Send to Salesforce" action uses its own authorization, separate from the sync integration user, and can be pointed at a different Salesforce user if you want record creation attributed separately.

<a href="https://sumble.com/book-a-demo" class="button primary">Book a time to chat with us</a>


# HubSpot

## HubSpot integration

### Overview

Sumble's HubSpot integration syncs data between your HubSpot instance and Sumble in both directions.

From HubSpot to Sumble:

* **Account list** -- Keep your Sumble account universe in sync with HubSpot Companies
* **Account assignments** -- Personalize Sumble for your reps based on HubSpot owner and user data
* **CRM fields as columns** -- Show Company properties as filterable columns in Sumble. See [Filter and sort by CRM data](/system-setup-and-configuration/crm/crm-columns)

From Sumble to HubSpot:

* **Enrichments** -- Write firmographic and technographic data back to HubSpot Company records (updates only, does not create new Companies)
* **Signals** -- Deliver Sumble signals to the matching Company as custom events, so they show up on the Company timeline and can drive workflows and reports

Each of these can be turned on independently. Signals also need the optional event permissions described below.

### How it works

Once connected, Sumble will:

1. Create a **Sumble Information** property group on your Company object
2. Create custom properties (prefixed with `sumble_`) for each enrichment you have asked us to write to your CRM
3. If you subscribe to signals and granted the event permissions, create a **Sumble Alert** custom event on the Company object
4. Sync data daily after the Sumble data pipeline completes

### Installation

#### Before you start

* You need a HubSpot account with **Super Admin** permissions (required to authorize third-party apps)
* You need an active Sumble Enterprise subscription
* You need to be a customer admin of your team in Sumble. Only customer admins can connect a CRM. If you aren't one, ask a customer admin to connect HubSpot, or to make you one.

#### Step 1: Start the connection

1. In Sumble, go to **My Team**, then the **Integrations** tab
2. Open **HubSpot** and click **Get started**

#### Step 2: Authorize in HubSpot

1. You'll be redirected to HubSpot's authorization screen
2. Select the HubSpot account you want to connect
3. Review the permissions (see Permissions below)
4. Click **Connect app**

#### Step 3: Confirm

After authorizing, you'll be sent back to the HubSpot panel on the Integrations tab, which shows the connected account.

#### Step 4: Choose what syncs

On the HubSpot panel:

* **Read** lets Sumble pull your Companies, users and, for champion tracking, Contacts.
* **Write** lets Sumble push enrichment and signals to HubSpot.

Keep at least one on. To stop both, disconnect instead.

Then check the **Organization mappings** and **User mappings**. They tell Sumble which HubSpot properties hold each [account and user field](/system-setup-and-configuration/data-fields). The standard properties are filled in for you. Change any that your HubSpot names differently, and save each section.

### Permissions

Sumble requests these HubSpot scopes during authorization:

| Scope                         | What it's for                                  |
| ----------------------------- | ---------------------------------------------- |
| `crm.objects.companies.read`  | Read Company records to match accounts         |
| `crm.objects.companies.write` | Write enrichment data to Company records       |
| `crm.objects.contacts.read`   | Read Contact records                           |
| `crm.objects.contacts.write`  | Write Contact data                             |
| `crm.objects.deals.read`      | Read Deal records                              |
| `crm.objects.deals.write`     | Write Deal data                                |
| `crm.objects.leads.read`      | Read Lead records                              |
| `crm.objects.leads.write`     | Write Lead data                                |
| `crm.objects.owners.read`     | Read owner assignments for territory mapping   |
| `crm.objects.users.read`      | Read HubSpot users for account assignment      |
| `crm.schemas.companies.write` | Create custom properties on the Company object |
| `crm.export`                  | Export Company and User records from HubSpot   |
| `crm.import`                  | Import enrichment data into HubSpot            |
| `business-intelligence`       | Read HubSpot analytics data                    |

Two additional scopes are requested as **optional** -- they power the signals feed, which writes Sumble signals to HubSpot as custom events (see Signals below):

| Scope                                            | What it's for                            |
| ------------------------------------------------ | ---------------------------------------- |
| `behavioral_events.event_definitions.read_write` | Define the Sumble Alert custom event     |
| `analytics.behavioral_events.send`               | Send Sumble signals as event occurrences |

{% hint style="info" %}
HubSpot's custom events API requires an **Enterprise** subscription on one of its Hubs. Because these two scopes are optional, you can still connect the core integration without them -- the CRM sync and enrichment push work as normal, and only the signals feed is skipped. If your HubSpot plan doesn't include custom events, leave these permissions unchecked during authorization.
{% endhint %}

Sumble only creates or modifies properties inside the **Sumble Information** property group. We never alter your existing HubSpot properties.

### Enrichment properties

After the first sync, a **Sumble Information** property group will appear on your Company records. It contains a custom property for each enrichment you have asked us to write to your CRM (technology usage, headcount trends, hiring signals, etc.). Some enrichments also come with a companion `_url` property linking to the evidence in Sumble, and a `_evidence` property holding the supporting detail as JSON. All properties are prefixed with `sumble_` — for example, an enrichment called "job\_count" appears as `sumble_job_count` in HubSpot.

You don't need to create any fields manually. When a new enrichment is enabled for your CRM, the corresponding property is created on the next sync. Not every enrichment on your account is written to HubSpot by default; tell your account team which ones you want in the CRM.

#### Where to find them

1. Open any Company record in HubSpot
2. Scroll to or search for the **Sumble Information** section in the left sidebar

These properties work like any other Company property -- you can use them in lists, workflows, and reports.

### Signals

If your account subscribes to [Sumble Signals](/enterprise-services/sumble-signals) and you granted the two optional event permissions, each signal is delivered to HubSpot as an occurrence of a custom event named **Sumble Alert** (`sumble_alert`) on the Company it relates to.

* The event's timestamp is when Sumble generated the signal. The job post's crawl date is carried separately in the `datetime_pulled` property.
* Event properties include the alert type, name and title, priority, location and country, sales angle, the Sumble organization id, name and URL, the job title, an explanation, the matched entities, and, for people signals, the person's name and LinkedIn URL plus their old and new organization.
* Only signals for Companies that exist in your HubSpot and matched a Sumble organization are delivered. Signals for organizations outside your CRM are not sent.
* Each run sends only signals newer than the last one delivered, so nothing is duplicated.

Find them on the Company record's activity timeline, or build lists, workflows, and reports on the Sumble Alert event under **Data Management > Event Management**.

### Creating Companies from Sumble

The daily sync never creates Companies. Separately, and only if you ask us to enable it, users in the Sumble web app can push an account that is not yet in your CRM straight to HubSpot from the account status chip. That creates one Company and records it as matched, so it starts receiving enrichments on the next sync.

Users can also push a person from the Sumble web app, which creates a HubSpot Contact associated to the matched Company. If a Contact with the same email already exists, Sumble links that Contact to the Company instead of creating a new one. The Contact push is off by default; a Sumble admin turns it on per customer. When champion tracking (below) is configured with a LinkedIn property, the push also writes the person's LinkedIn URL to that property so the Contact can be tracked.

### Champion tracking

Champion tracking watches the people already in your HubSpot for job changes. When a Contact you care about moves to a new company, that is often the best moment to reach out: you already have a relationship, and they now have a new budget and new problems. Sumble spots the move and, if you want, reflects it in HubSpot so the Contact is not left attached to a company they no longer work for.

It has two halves, both optional and off by default. Your Sumble account team configures them with you.

#### Pulling Contacts

Sumble pulls the Contacts you choose into its people tracking. You control which Contacts by giving us HubSpot property filters (for example, a lifecycle stage, a custom "champion" checkbox, or a list of owners), and Sumble pulls only the Contacts that match. Contacts need a LinkedIn URL in a property you tell us about; that is how Sumble recognizes the same person when they show up at a new employer. Contacts without one are pulled but cannot be tracked.

Each tracked Contact who changes jobs produces a people signal, delivered like any other [signal](#signals).

#### Syncing job changes back to HubSpot

When a tracked Contact moves to a company that is also in your HubSpot, Sumble can update your CRM. Pick one of two modes:

* **Update existing** -- Sumble edits the existing Contact: it updates the job title, refreshes the LinkedIn property if one is configured, and makes the new Company the Contact's primary association. The old Company stays associated so history is kept, but it is no longer primary.
* **Create new** -- Sumble leaves the original Contact untouched and creates a new Contact at the new Company, with first name, last name, job title, and the LinkedIn property. The new Contact is tracked from then on, so a second move is caught too.

In either mode, if the destination company is not in your HubSpot, nothing is written; you still get the signal.

The sync writes `firstname`, `lastname`, `jobtitle`, the LinkedIn property you configured, and the primary Company association. It also writes `email` and `phone`, but only when someone at your company already revealed them in Sumble in the last 30 days, and an email only when it is at the person's new company. The sync never reveals contact details itself, so it never spends your credits. When Sumble has no email or phone to send, it leaves the Contact's current values alone. If another Contact already has that email, Create new uses that Contact instead of making a second one, and Update existing leaves the email unchanged. The sync never writes owner and never deletes a Contact.

### Account matching

Sumble matches HubSpot Companies to organizations in the Sumble database. The exact HubSpot properties used are configured per customer, but the typical mapping is:

| Field             | Required                                                                     | Typical HubSpot property |
| ----------------- | ---------------------------------------------------------------------------- | ------------------------ |
| Company ID        | <ul class="contains-task-list"><li><input type="checkbox" checked></li></ul> | `hs_object_id`           |
| Company Name      | <ul class="contains-task-list"><li><input type="checkbox" checked></li></ul> | `name`                   |
| Company Domain    | <ul class="contains-task-list"><li><input type="checkbox" checked></li></ul> | `domain`                 |
| LinkedIn URL      | <ul class="contains-task-list"><li><input type="checkbox"></li></ul>         | `linkedin_company_page`  |
| Country           | <ul class="contains-task-list"><li><input type="checkbox"></li></ul>         | `country`                |
| Parent Company ID | <ul class="contains-task-list"><li><input type="checkbox"></li></ul>         | (if applicable)          |

If your HubSpot uses different property names, change them in **Organization mappings** on the HubSpot panel of **My Team > Integrations**. The full list of account fields, including the optional ones, is in [Data fields](/system-setup-and-configuration/data-fields#accounts).

### Sales territories

Sumble reads HubSpot owner assignments to personalize each user's experience. By default, it uses **HubSpot Owner** -- the Company's assigned owner.

Many teams spread account ownership across more than one owner property, such as an SDR, XDR, or CS owner. Those are custom properties rather than HubSpot standard ones, so tell us which properties you use during setup and we'll add them to the mapping. Each one you add gives the rep named on it the same account access as the Company owner.

These assignments determine which accounts each Sumble user sees signals and alerts for. To map owners to users, Sumble pulls the user fields listed under [Users in Data fields](/system-setup-and-configuration/data-fields#users).

### Data sync details

#### Pull (HubSpot to Sumble)

* Uses HubSpot's CRM Export API to pull Company records and User records, and Contact records when champion tracking is on
* Only downloads the configured mapping fields (see Account matching)
* Company data is used for account matching; User data is used for owner-to-rep mapping; Contact data is used for champion tracking

#### Push (Sumble to HubSpot)

* Uses HubSpot's batch Company update API, keyed on `hs_object_id`, in batches of 100. Nothing appears in your Imports history.
* **Updates existing Company records only** -- does not create new Companies in HubSpot
* Writes to properties in the **Sumble Information** group, plus any of your own Company properties that Sumble has mapped an enrichment to. Sumble never creates or redefines a mapped property.
* A mapped dropdown property only receives values that match one of its options, ignoring case, spaces, dots, dashes, underscores and slashes, so "Apollo.io" fills an option with the value `apollo_io`. An exact match, or one that differs only in case, wins first. If a value fits several options only after ignoring those separators, Sumble does not guess and leaves it out. For a multiple-checkboxes property each value is checked on its own. Sumble leaves out values that match no option, and if none match, the Company keeps the value it already has. Add the missing options in HubSpot to start receiving them.
* Champion tracking, when enabled, updates or creates individual Contacts as described above; it is the only part of the sync that touches Contacts
* Signals, when enabled, go through HubSpot's custom events API as **Sumble Alert** occurrences on the Company

### Disconnecting

A customer admin can disconnect from the HubSpot panel on **My Team > Integrations** with **Disconnect HubSpot**. Sumble stops syncing and removes its stored credentials.

You can also revoke access from HubSpot directly:

1. Go to **Settings > Integrations > Connected Apps**
2. Find **Sumble**
3. Click **Uninstall**

***

<a href="https://sumble.com/book-a-demo" class="button primary">Book a time to chat with us</a>


# Salesforce import

Individual users can push people from Sumble directly into Salesforce as Contacts or Leads. This is separate from the enterprise [Salesforce package](/system-setup-and-configuration/crm/salesforce-package) integration — it's a per-user feature for sending individual records to your Salesforce instance.

## How it works

1. Navigate to a person's profile on an organization page
2. Click the **Send to Salesforce** button
3. Choose whether to create a Contact or a Lead in Salesforce
4. Review the details and confirm

The person's name, title, organization, and LinkedIn URL are sent to your connected Salesforce instance. If your admin has configured custom field mappings, additional fields may be included.

## Setup

Salesforce import needs two things:

1. A customer admin turns it on from the Salesforce panel on **My Team > Integrations**, and chooses whether people can create Contacts, Leads or both.
2. Each user connects their own Salesforce account from [Account Settings](https://sumble.com/account/settings). This authorization is separate from the company's Salesforce integration.

Once connected, the Send to Salesforce button appears on person profiles throughout the platform.

## Contact vs. Lead

* **Contact** — Use when the person is associated with an existing Account in your Salesforce
* **Lead** — Use when you want to create a new lead record for follow-up

Your admin may have disabled one of these options depending on your team's Salesforce workflow.

## Enterprise Salesforce integration

For bulk data delivery, bi-directional sync, and enrichment of your Salesforce data, see the enterprise [Salesforce package](/system-setup-and-configuration/crm/salesforce-package) integration.


# Filter and sort by CRM data

Show fields from your CRM as columns on the Sumble organization table, then filter and sort by them.

Sumble can pull fields from your CRM and show them as extra columns on the organization table. Once a field is set up you can filter and sort Sumble's data by your own account data, so questions like "which accounts in my Tier 1 segment are hiring for Databricks" become a single search.

You don't set these up yourself. Tell us which fields you want during setup and we'll configure the mapping accordingly. See [Requesting a column](#requesting-a-column).

## What can become a column

| Your CRM   | What we can pull                                                                                                                               |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Salesforce | Any field on the `Account` object. We can also derive a value from a related object, for example the number of open opportunities per account. |
| HubSpot    | Any Company property.                                                                                                                          |

Common examples: account tier or segment, industry as your CRM records it, contract value, renewal quarter, open pipeline, a flag for strategic accounts.

## Column types

Every column has a type, which decides what you can do with it.

| Type    | Holds                                                        | Filter                            | Sort |
| ------- | ------------------------------------------------------------ | --------------------------------- | ---- |
| Enum    | A fixed set of text values, such as Tier 1 / Tier 2 / Tier 3 | Pick one or more values           | No   |
| Boolean | True or false                                                | Pick True or False                | No   |
| Number  | A number                                                     | Set a minimum, a maximum, or both | Yes  |
| Custom  | Any text, shown as-is                                        | No                                | No   |

Only Number columns can be sorted, because they are the only type with an order Sumble can rank by. Sorting runs highest to lowest first, and clicking again reverses it. Accounts with no value in that column sort last either way.

Use Custom for a field you want to read on the row but never filter by, such as a free-text account note.

## Turning a column on

CRM columns are off by default, so each user picks the ones they want.

1. Go to [organization search](/web-app/search-discovery/organization-search).
2. Click the `+` on the table header to open the column manager.
3. Your CRM columns are listed with your CRM's logo and the caption "from CRM".
4. Enable the ones you want.

## Filtering and sorting

Filters live on the column header. Click the filter icon on a CRM column, set your values, and click Apply.

A CRM filter is part of the search like any other Sumble filter, which means it:

* combines with every other filter, so you can cross your segment against technology, hiring, and headcount criteria
* can be kept as a [saved search](/web-app/lists-monitoring/saved-searches)
* can be turned into an [account list](/web-app/lists-monitoring/account-lists)
* applies to [exports](/web-app/data-exports), so an export covers only the matching accounts

## Who can see them

CRM columns are visible to users on a Sumble account with a connected CRM. If your account has no CRM connected, no CRM columns appear and nothing changes in the table.

## How the values stay current

Values refresh on your CRM sync. A field you edit in Salesforce or HubSpot appears in Sumble on the next sync.

## When one account maps to several CRM records

Your CRM can hold more than one record for the same company, for example a parent account and a subsidiary that both match one Sumble organization. Sumble picks one value per column:

* the value on the record marked as your customer account wins
* failing that, the first record with a value fills the cell
* for Number columns the highest value wins, which keeps the cell consistent with the sort order

## Account status is not a CRM column

The Customer / Prospect / Not in CRM chip comes from its own mapping: the CRM field that marks which accounts are already yours. Once that field is mapped, the chip appears across the app and the field itself is never offered in the column manager, because Sumble shows it as the status chip instead. Tell us which field you use and we'll add it to your mapping.

## Requesting a column

Let us know during setup, or through your account team at any point after, and we'll configure the mapping. For each column, tell us:

* the CRM object and the exact field or property name
* the label you want on the column header
* the type from the table above
* for an Enum, the list of values it can take
* for a Salesforce related-record field, what should be counted or summed and against which object

The column appears after the next sync.

## Troubleshooting

| Symptom                                 | Cause                                                                                                                                                                                                                                      |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| A column exists but every cell is empty | The Salesforce integration user cannot read that field. These fail quietly by design so one field cannot stop the whole sync. See [Salesforce permissions](/system-setup-and-configuration/crm/salesforce-package/salesforce-permissions). |
| A column has no filter on its header    | It is a Custom type column, which is display only. Ask us to change the type if you need to filter by it.                                                                                                                                  |
| A column cannot be sorted               | Only Number columns sort.                                                                                                                                                                                                                  |
| A value looks stale                     | Check the field in your CRM, then allow for the next sync.                                                                                                                                                                                 |


# Data destinations

Push Sumble data into your data warehouse or storage.

Deliver Sumble enrichment and signals straight into your data platform. A warehouse or file source can also send Sumble your accounts and a users list. The fields Sumble needs are in [Data fields](/system-setup-and-configuration/data-fields).

* [Snowflake](/system-setup-and-configuration/data-destinations/snowflake-share)
* [Databricks](/system-setup-and-configuration/data-destinations/databricks)
* [BigQuery](/system-setup-and-configuration/data-destinations/bigquery)
* [Blob store (GCS / S3)](/system-setup-and-configuration/data-destinations/blob-store)
* [Webhooks](/system-setup-and-configuration/data-destinations/webhooks)


# Snowflake

To set up a data share with us in Snowflake, follow these steps. You’ll be sharing with our Snowflake account `SUMBLE.AWS_US_EAST_1`.

## Prepare your data

Identify or create the Snowflake table/view with the data you’d like to share with us. Sumble matches your accounts on a set of fields, listed under [Accounts in Data fields](/system-setup-and-configuration/data-fields#accounts). Account ID, Account Name and Account URL are required. The rest are optional.

Use whatever column names are natural for your system. We'll handle the column matching from there.

## Users table

You can also share a users table or view so Sumble can attribute accounts to their owners and managers. Use whatever column names your system already has. See [Users table (account owners and managers)](/system-setup-and-configuration/data-fields#users) for the column contract.

## Identify your Snowflake region

Which region you’re in determines how you share data with us on Snowflake. If you’re in `AWS_US_EAST_1` , we use a data share directly. Otherwise, you'll create a private listing. An in-depth overview of Snowflake's data sharing capabilities can be found at [Snowflake's Data Sharing Documentation](https://docs.snowflake.com/en/user-guide/data-sharing-intro.html).

### Region: AWS\_US\_EAST\_1

1. Use the [`CREATE SHARE`](https://docs.snowflake.com/en/sql-reference/sql/create-share.html) command to create a new share.
2. Grant access to the specific database objects (schemas, tables, or views) that need to be shared.

```sql
CREATE SHARE my_share;
GRANT USAGE ON DATABASE my_database TO SHARE my_share;
GRANT USAGE ON SCHEMA my_database.my_schema TO SHARE my_share;
GRANT SELECT ON TABLE my_database.my_schema.my_table TO SHARE my_share;
```

3. Use [`ALTER SHARE`](https://docs.snowflake.com/en/sql-reference/sql/alter-share.html) to add the Sumble's account.

```sql
ALTER SHARE my_share ADD ACCOUNT = SUMBLE.AWS_US_EAST_1;
```

4. We'll accept the share and create a database from it.

### Region: Not AWS\_US\_EAST\_1

1. Create a [private data listing](https://docs.snowflake.com/en/user-guide/data-exchange-managing-data-listings#create-and-publish-a-data-listing).
2. Navigate to the *Data Products* > *Private Sharing* in Snowflake and click *Share* > *Publish to Specified Consumers* to configure a private listing.
   1. Select the data you’re sharing in this view
   2. Share with `SUMBLE.AWS_US_EAST_1`
3. Ensure data remains up-to-date: configure the frequency of data replication through the [auto-fulfillment settings](https://other-docs.snowflake.com/en/collaboration/provider-listings-auto-fulfillment#manage-other-auto-fulfillment-settings).

<a href="https://sumble.com/book-a-demo" class="button primary">Book a time to chat with us</a>


# Databricks

Sumble connects directly to your Databricks workspace to read your account data and write enriched results back as Delta tables.

## How it works

Sumble uses a direct SQL connection to your Databricks workspace (via the Databricks SQL API). The integration is bi-directional:

**Pull** — Sumble queries your account list from a table you specify (e.g., `main.customer_schema.accounts`). Column mappings translate your field names to Sumble's schema. This tells Sumble which organizations to match and enrich.

**Push** — After enrichment, Sumble writes the results as Delta tables in your Databricks workspace:

1. Parquet files are generated from the enrichment pipeline
2. Files are uploaded to intermediate cloud storage
3. Delta tables are created in a timestamped schema in your workspace
4. Tables are atomically swapped into your output schema, so you always see a complete, consistent dataset

## What gets delivered

Each pipeline run writes these tables to your output schema:

* Enriched organizations — your accounts matched to Sumble organizations with all configured enrichment columns
* Alerts feed — intent signals generated for your accounts
* Reference data — technologies, job functions, countries, and other lookup tables

Tables are replaced atomically with each run. Previous versions are retained briefly for rollback if needed.

## Update cadence

Data is refreshed daily after the Sumble data pipeline completes.

## Setup

Databricks integration requires an enterprise plan. To get started:

1. Provide Sumble with your Databricks workspace hostname, SQL warehouse HTTP path, and a Personal Access Token
2. Specify the input table containing your account list and the output schema for enriched data
3. Sumble maps your columns to the [account fields](/system-setup-and-configuration/data-fields#accounts) it needs
4. Choose which enrichments to include

<a href="https://sumble.com/book-a-demo" class="button primary">Book a time to chat with us</a>


# BigQuery

Sumble can read your account list from BigQuery and write enriched data back to BigQuery as tables.

## How it works

The two directions are independent — set up either one, or both.

**Pull** — Sumble reads your accounts (and optionally your contacts) from a table or view you specify, e.g. `my-project.sumble.accounts`. Column mappings translate your field names to Sumble's schema, so you can use whatever column names are natural for your system. Each run reads the current contents of the table; accounts that are no longer present are marked as removed on the Sumble side.

**Push** — After enrichment, Sumble loads the results into a BigQuery dataset you nominate, as one table per output table. Each table's contents are replaced in full when its load job commits, so you never read a partly-loaded table.

Sumble runs every BigQuery query and load job in **its own Google Cloud project**, so all BigQuery compute and storage-load costs are billed to Sumble, not to you. You never need to grant Sumble the BigQuery Job User (`roles/bigquery.jobUser`) role.

## Where the dataset lives

There are two ways to set this up. Pick whichever fits your data governance model — the data delivered is identical.

**Your dataset.** You create a dataset in your own Google Cloud project and grant Sumble's service account access to it. Your data never leaves your project, and you control retention and downstream access.

**Sumble's dataset.** Sumble creates a dataset in its project and grants a principal you nominate read access to it. Nothing to provision on your side — you just tell us which user, group, or service account should be able to read it.

### Access to grant

Sumble's service account is:

```
customer-data-share-sa@sumble-358418.iam.gserviceaccount.com
```

For a dataset in **your** project, grant that service account:

| Direction                          | Role                                               | Granted on                                               |
| ---------------------------------- | -------------------------------------------------- | -------------------------------------------------------- |
| Pull (Sumble reads your accounts)  | BigQuery Data Viewer (`roles/bigquery.dataViewer`) | The dataset holding your input table, or just that table |
| Push (Sumble writes enriched data) | BigQuery Data Editor (`roles/bigquery.dataEditor`) | The output dataset                                       |

For a dataset **hosted by Sumble**, you don't grant anything — send us the principal that should read it (a user, group, or service account email) and we'll grant it BigQuery Data Viewer on our side.

## Setup

BigQuery integration requires an enterprise plan.

### 1. Prepare your input table (pull only)

Identify or create the table or view holding the accounts you want Sumble to enrich. Sumble matches your accounts on a set of fields, listed under [Accounts in Data fields](/system-setup-and-configuration/data-fields#accounts). Account ID, Account Name and Account URL are required. The rest are optional.

Use whatever column names are natural for your system — we'll handle the column matching from there. Any additional columns you include can be carried through and used as context when matching your accounts to Sumble organizations.

Sumble reads whichever object you name, so this can be a table or a view. If the accounts you want enriched span several tables, or you only want to send us a subset, create a view in your own dataset and give us that instead.

### Users table (pull, optional)

You can also share a users table or view so Sumble can attribute accounts to their owners and managers. Column names can be whatever you use. Grant Sumble the same BigQuery Data Viewer access on the users table or its dataset. See [the users table column contract](/system-setup-and-configuration/data-fields#users) for the fields Sumble reads.

### 2. Create the output dataset (push only)

Create a dataset in the region you want the enriched data to live in:

```bash
bq --location=US mk --dataset my-project:sumble
```

Skip this step if you'd rather Sumble host the dataset.

### 3. Grant access

In the Google Cloud console: open **BigQuery**, select the dataset, click **Sharing → Permissions → Add principal**, enter Sumble's service account, and pick the role from the table above.

Or run the equivalent DCL statements from the BigQuery console (or `bq query --use_legacy_sql=false`):

```sql
-- Pull: let Sumble read your input dataset
GRANT `roles/bigquery.dataViewer`
ON SCHEMA `my-project.crm`
TO "serviceAccount:customer-data-share-sa@sumble-358418.iam.gserviceaccount.com";

-- Push: let Sumble write to your output dataset
GRANT `roles/bigquery.dataEditor`
ON SCHEMA `my-project.sumble`
TO "serviceAccount:customer-data-share-sa@sumble-358418.iam.gserviceaccount.com";
```

To keep read access as narrow as possible, you can grant Data Viewer on the single input table instead of the whole dataset:

```sql
GRANT `roles/bigquery.dataViewer`
ON TABLE `my-project.crm.accounts`
TO "serviceAccount:customer-data-share-sa@sumble-358418.iam.gserviceaccount.com";
```

### 4. Send Sumble the identifiers

To finish configuration we need:

* **For pull** — the fully-qualified input table or view, `project.dataset.table`, plus any contacts or users tables you're sharing.
* **For push** — the fully-qualified output dataset, `project.dataset`. If you'd like Sumble to host it, send the principal that should be granted read access instead.

Sumble then configures the column mappings for your account fields, you choose which enrichments to include, and syncs begin.

## What gets delivered

Each pipeline run writes these tables into the output dataset:

* `enriched_organizations` — your accounts matched to Sumble organizations, with all configured enrichment columns
* `alerts_feed` — intent signals generated for your accounts
* `enrichments` — a description of each enrichment column in the share
* `organizations` — the underlying Sumble organization records
* `top_whitespace` — high-potential organizations that aren't in your CRM (if enabled)

The exact set depends on what's configured for your account — any additional lookup or reference tables in your share land in the same dataset. Table names are stable across runs, and each table is replaced in full on every run.

Table and column names are lowercase. BigQuery table names are case-sensitive, so query `enriched_organizations`, not `ENRICHED_ORGANIZATIONS`.

Each table is replaced independently, so if a run fails partway through, some tables can briefly hold the previous run's data while others hold the current run's. This clears on the next successful run. If you join across tables and need them to agree, the `FOR SYSTEM_TIME AS OF` queries below let you read every table as of the same timestamp.

### Reading JSON columns

Columns that carry JSON — enrichment evidence columns, and fields such as `extra_content` and `match_details` where they're included in your share — are loaded as `STRING`, not BigQuery's native `JSON` type. Use `PARSE_JSON()` or `JSON_VALUE()` to read them:

```sql
SELECT
  account_id,
  JSON_VALUE(my_enrichment_evidence, '$.job_title') AS job_title
FROM `my-project.sumble.enriched_organizations`;
```

(If you also receive a Snowflake share, note that those same columns arrive there as `VARIANT`.)

### Reading a previous run

Replacing a table doesn't discard its previous contents. BigQuery keeps them for the dataset's time travel window — seven days by default — so you can read any table as it stood at an earlier point:

```sql
SELECT *
FROM `my-project.sumble.enriched_organizations`
FOR SYSTEM_TIME AS OF TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 2 DAY);
```

This is useful for comparing runs, or for reading several tables as of one timestamp. To keep a copy for longer than the time travel window, take a [table snapshot](https://cloud.google.com/bigquery/docs/table-snapshots).

## Update cadence

Data is refreshed daily, after the Sumble data pipeline completes.

<a href="https://sumble.com/book-a-demo" class="button primary">Book a time to chat with us</a>


# Blob store (GCS / S3)

Sumble can exchange data with you as files in object storage — Google Cloud Storage or Amazon S3. This is the simplest integration option: no API connections, no database credentials. You send us your account list as a CSV, and we write enriched data back as Parquet files that you can process however you want.

Both directions are optional and independent. Use one, the other, or both.

## What we deliver

Each pipeline run writes a set of Parquet files to your bucket:

* **Enriched organizations** — your accounts with all configured enrichment columns
* **Alerts feed** — intent signals generated for your accounts
* Additional tables as configured for your account

Files are standard Apache Parquet, readable by any tool that supports it (BigQuery, Athena, Snowflake, Spark, pandas, DuckDB, ClickHouse, etc.). Each run replaces the previous set of files.

## What you send us

To have Sumble enrich your accounts, put a CSV in the bucket at a fixed path and refresh it on your own schedule. We read the same path on every run.

* One row per account, with a header row
* Include the [account fields](/system-setup-and-configuration/data-fields#accounts) Sumble needs. Matching quality depends most on the website
* Either plain `.csv` or gzipped `.csv.gz`; we detect which
* Any extra columns you include are preserved and available for filtering

You can send a people/contact list, or a [users list](/system-setup-and-configuration/data-fields#users), the same way.

## Update cadence

Files are updated daily, after the Sumble data pipeline completes.

## Setup

The blob store integration requires an enterprise plan.

### Google Cloud Storage

1. Create a GCS bucket (or designate an existing one).
2. Grant Sumble's service account access to it — we'll give you the address.
3. Tell us the bucket name, and the path of your input CSV if you're sending one.

### Amazon S3

1. Create an S3 bucket (or designate an existing one).
2. Grant Sumble's IAM principal access to it with a bucket policy — we'll give you the ARN to use. Read access is enough if you only send us data; add write access for us to deliver enriched files.
3. Tell us the bucket name, its region, and the `s3://` URI of your input CSV if you're sending one.

If your security policy requires cross-account role assumption rather than a bucket policy, create an IAM role that trusts our principal, and give us the role ARN (and an external ID if you use one) instead.

### Amazon S3, Sumble-hosted

If you would rather not create a bucket, we deliver to one of ours: `s3://sumble-customer-data-shares/<your prefix>/` in `us-east-2`.

1. Tell us the AWS principal that will read the files: the ARN of the IAM role your warehouse or loader uses, or your account id. We grant it `s3:ListBucket` and `s3:GetObject` on your prefix only. Nothing else in the bucket is visible to it.
2. If you send us an account list, also tell us the principal that uploads it. We grant that one `s3:PutObject` under `<your prefix>/input/`. It can be the same principal as the reader.
3. Read with any S3 client as the reader principal; cross-account access needs no bucket of your own. Snowflake, Athena and Databricks external stages work the same way.
4. Upload your account list to `s3://sumble-customer-data-shares/<your prefix>/input/accounts.csv` and tell us the path. Overwrite the same key when it changes.

Files we deliver expire after 30 days, so load each delivery within that window. Files you upload under `input/` are kept until you replace them.

<a href="https://sumble.com/book-a-demo" class="button primary">Book a time to chat with us</a>


# Webhooks

Get an HTTPS POST from Sumble for each new signal and priority signal, and verify that it came from us.

{% hint style="info" %}
*Webhooks are in **beta** and available on the Enterprise plan. They're turned on per account. To try them, contact your account executive and we'll enable them for you.*
{% endhint %}

## What webhooks do

A webhook sends an HTTPS POST to an endpoint you run each time Sumble creates a new signal for your account. You can also subscribe to priority signals. Sumble checks for new events every five minutes, so an event usually reaches you within a few minutes of being created.

Admins with an Admin seat manage webhooks under **My Team > Webhooks**. Each delivered event costs one credit.

## Set up a webhook

If you don't see a **Webhooks** tab under **My Team**, webhooks aren't enabled for your account yet. Contact your account executive.

1. Go to **My Team > Webhooks** and click **New webhook**.
2. Fill in the fields:
   * **Name**: 1 to 100 characters, for your own reference.
   * **URL**: must start with `https://`, can't contain a username or password, and its host must resolve to a public IPv4 address.
   * **Event types**: **Signals**, **Priority signals**, or both.
   * **Signal types** and **priorities**: filters that apply to signals only. Priorities are high, medium, and low. Leave a filter empty to get everything.
   * **Burst threshold**: between 10 and 25,000. The default is 25,000. See [Held bursts](#held-bursts).
   * **Send events from**: **Now**, or **A past date** up to 90 days back. With a past date, Sumble shows how many matching events it will send before you save. See [Send past events](#send-past-events).
3. Save. Sumble shows the signing secret, which starts with `whsec_`. Copy it now, because it isn't shown again. If you lose it, [rotate it](#rotate-the-signing-secret).
4. Send a test to check your endpoint and your signature verification. See [Test events](#test-events).

With **Now**, a new webhook sends events created from the moment you save it. To get older events too, pick a past date when you create it, or rewind it later.

Each account can have up to 10 webhooks.

## Test events

Use **Send test** on a webhook to see what your endpoint will receive before real events arrive.

Pick **Raw signal** or **Priority signal**. For a raw signal, also pick a signal type, such as a champion movement or a funding round. Sumble sends a sample event built by the same code that builds real events, so its fields and groups match a real event of that type. A champion movement sample has a `person` group with the previous and new company, a job post sample has a `job` group, and so on.

Kinds and types your webhook doesn't subscribe to are marked **Not subscribed**. You can still send them, which helps when you build your handler before changing the subscription.

A test event has the real `type`, `signal.raw.created` or `signal.priority.created`, and `test` set to `true`. Real events always have `"test": false`. The data is fake: ids are `0`, the organization is "Example Corp", and Sumble links in the sample don't lead anywhere useful. Check `test` and skip side effects, such as creating a CRM record or alerting a rep, when it's `true`.

Tests are signed like real events. They're free, get one attempt with no retries, and are sent even while the webhook is paused. After a test, Sumble shows your endpoint's status code, the start of its response, and the JSON body it sent.

## Allow our IP addresses

Deliveries come from these two addresses, over IPv4 only:

* `8.231.165.219`
* `136.87.138.118`

Allow both, even if you only see traffic from one of them today. Having two lets us add capacity or replace an address without you changing your firewall.

An endpoint whose host has no IPv4 address, that is no A record, can't receive webhooks. Sumble rejects it when you save the webhook.

## What we send

Each delivery is a `POST` with a JSON body and these headers:

| Header              | Value                                                                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `content-type`      | `application/json`                                                                                                                 |
| `user-agent`        | `Sumble-Webhooks/1.0`                                                                                                              |
| `webhook-id`        | The event's id. Same as `id` in the body.                                                                                          |
| `webhook-timestamp` | When this attempt was signed, in Unix seconds.                                                                                     |
| `webhook-signature` | One or more signatures, separated by spaces, each in the form `v1,<signature>`. See [Verify the signature](#verify-the-signature). |

The three `webhook-` headers follow the [Standard Webhooks](https://www.standardwebhooks.com/) specification.

`webhook-id` stays the same when we retry an event and when you replay it, so you can use it to drop duplicates. `webhook-timestamp` changes on every attempt.

### The envelope

Every body has the same outer fields:

| Field               | Type                   | Null? | Meaning                                            |
| ------------------- | ---------------------- | ----- | -------------------------------------------------- |
| `id`                | string (UUID)          | No    | The event id. Same as the `webhook-id` header.     |
| `type`              | string                 | No    | `signal.raw.created` or `signal.priority.created`. |
| `schema_version`    | integer                | No    | Always `1` today.                                  |
| `created_at`        | string (ISO 8601, UTC) | No    | When Sumble created the event.                     |
| `webhook_config_id` | integer                | No    | The webhook this event was sent for.               |
| `test`              | boolean                | No    | `true` only for test sends.                        |
| `data`              | object                 | No    | A signal or a priority signal, described below.    |

A [test event](#test-events) has the same `type` and `data` shape as a real event, with `test` set to `true`.

### Signal (`signal.raw.created`)

This example is the test sample for a `technology_recent_hires` signal. A real delivery has the same shape, with real data and `"test": false`.

```json
{
  "id": "01a14300-0000-7000-8000-000000000001",
  "type": "signal.raw.created",
  "schema_version": 1,
  "created_at": "2026-10-16T12:00:00Z",
  "webhook_config_id": 42,
  "test": true,
  "data": {
    "signal": {
      "signal_id": 0,
      "type": "technology_recent_hires",
      "display_type": "Target persona hire",
      "priority": "medium",
      "title": "Example Corp hired Example Person as Senior Data Engineer",
      "explanation": "This is a sample signal sent by a webhook test.",
      "date": "2026-01-01T12:00:00Z",
      "sumble_url": "https://sumble.com/orgs/example-corp/signals/s/0"
    },
    "organization": {
      "organization_id": null,
      "organization_name": "Example Corp",
      "domain": "example.com"
    },
    "signal_config": {
      "signal_config_id": 0,
      "signal_config_name": "Sample signal config"
    },
    "match": {
      "matched_technologies": [
        { "name": "Snowflake", "slug": "snowflake", "label": null }
      ],
      "matched_projects": null,
      "job_function": "Data Engineer",
      "job_level": "Senior",
      "location": "Springfield, Illinois, United States",
      "country": "United States"
    },
    "person": {
      "person_id": 0,
      "name": "Example Person",
      "title": null,
      "linkedin_url": "https://www.linkedin.com/in/example-person",
      "sumble_url": "https://sumble.com/l/person/mk5tg8ysxj",
      "previous_organization_name": null,
      "previous_title": null,
      "new_organization_name": null,
      "new_title": null,
      "start_date": null
    },
    "job": null
  }
}
```

The body we send is compact JSON on one line. The example is formatted for reading.

`data` has these groups. A group that doesn't apply to the signal is `null`.

| Field           | Type   | Null? | Meaning                                                    |
| --------------- | ------ | ----- | ---------------------------------------------------------- |
| `signal`        | object | No    | The signal itself.                                         |
| `organization`  | object | No    | The organization the signal is about.                      |
| `signal_config` | object | Yes   | The signal config that produced it.                        |
| `match`         | object | Yes   | What the signal matched. `null` when nothing below is set. |
| `person`        | object | Yes   | The person involved, for people signals.                   |
| `job`           | object | Yes   | The job post, for job post signals.                        |

`signal`:

| Field          | Type              | Null? | Meaning                                                                     |
| -------------- | ----------------- | ----- | --------------------------------------------------------------------------- |
| `signal_id`    | integer           | No    | The signal's id in Sumble.                                                  |
| `type`         | string            | No    | The signal type, for example `technology_recent_hires` or `champion_alert`. |
| `display_type` | string            | No    | A readable label for the type.                                              |
| `priority`     | string            | No    | `high`, `medium`, or `low`. Champion alerts are always `high`.              |
| `title`        | string            | No    | A one-line summary.                                                         |
| `explanation`  | string            | Yes   | Why the signal matters.                                                     |
| `date`         | string (ISO 8601) | No    | When Sumble found the signal.                                               |
| `sumble_url`   | string            | Yes   | The signal's page on Sumble.                                                |

`organization`:

| Field               | Type    | Null? | Meaning                                                                   |
| ------------------- | ------- | ----- | ------------------------------------------------------------------------- |
| `organization_id`   | integer | Yes   | Sumble's organization id.                                                 |
| `organization_name` | string  | Yes   | The organization's name.                                                  |
| `domain`            | string  | Yes   | The domain of the matching account in your account list, if there is one. |

`signal_config`:

| Field                | Type    | Null? | Meaning                   |
| -------------------- | ------- | ----- | ------------------------- |
| `signal_config_id`   | integer | No    | The signal config's id.   |
| `signal_config_name` | string  | Yes   | The signal config's name. |

`match`:

| Field                  | Type   | Null? | Meaning                                                                                                |
| ---------------------- | ------ | ----- | ------------------------------------------------------------------------------------------------------ |
| `matched_technologies` | array  | Yes   | Technologies the signal matched. Each item has `name`, `slug`, and `label`, and `label` can be `null`. |
| `matched_projects`     | array  | Yes   | Projects the signal matched.                                                                           |
| `job_function`         | string | Yes   | The job function.                                                                                      |
| `job_level`            | string | Yes   | The job level.                                                                                         |
| `location`             | string | Yes   | The location.                                                                                          |
| `country`              | string | Yes   | The country.                                                                                           |

`person`:

| Field                        | Type    | Null? | Meaning                                               |
| ---------------------------- | ------- | ----- | ----------------------------------------------------- |
| `person_id`                  | integer | Yes   | Sumble's person id.                                   |
| `name`                       | string  | Yes   | The person's name.                                    |
| `title`                      | string  | Yes   | Their current title.                                  |
| `linkedin_url`               | string  | Yes   | Their LinkedIn profile.                               |
| `sumble_url`                 | string  | Yes   | Their page on Sumble.                                 |
| `previous_organization_name` | string  | Yes   | Where they worked before. Champion alerts only.       |
| `previous_title`             | string  | Yes   | Their previous title. Champion alerts only.           |
| `new_organization_name`      | string  | Yes   | Where they work now. Champion alerts only.            |
| `new_title`                  | string  | Yes   | Their new title. Champion alerts only.                |
| `start_date`                 | string  | Yes   | When they started the new role. Champion alerts only. |

`job`:

| Field         | Type    | Null? | Meaning                 |
| ------------- | ------- | ----- | ----------------------- |
| `job_post_id` | integer | No    | Sumble's job post id.   |
| `title`       | string  | Yes   | The job title.          |
| `location`    | string  | Yes   | The job's location.     |
| `sumble_url`  | string  | Yes   | The job post on Sumble. |

### Priority signal (`signal.priority.created`)

Sumble generates priority signals for each user with a seat on your account. Each one says who it was generated for in `user`. This example is the priority signal test sample.

```json
{
  "id": "01a14300-0000-7000-8000-000000000002",
  "type": "signal.priority.created",
  "schema_version": 1,
  "created_at": "2026-10-16T12:00:00Z",
  "webhook_config_id": 42,
  "test": true,
  "data": {
    "id": 0,
    "headline": "Example Corp is building a data platform team",
    "content": "This is a sample priority signal sent by a webhook test.",
    "generated_at": "2026-01-01T12:00:00Z",
    "sumble_url": "https://sumble.com/signals/priority/item/0",
    "signal_ids": [0],
    "user": {
      "id": 0,
      "email": "user@example.com",
      "name": "Example User"
    }
  }
}
```

| Field          | Type              | Null? | Meaning                        |
| -------------- | ----------------- | ----- | ------------------------------ |
| `id`           | integer           | No    | The priority signal's id.      |
| `headline`     | string            | No    | A one-line summary.            |
| `content`      | string            | No    | The full write-up.             |
| `generated_at` | string (ISO 8601) | No    | When Sumble generated it.      |
| `sumble_url`   | string            | No    | Its page on Sumble.            |
| `signal_ids`   | array of integers | No    | The signals it is based on.    |
| `user.id`      | integer           | No    | The user it was generated for. |
| `user.email`   | string            | No    | That user's email.             |
| `user.name`    | string            | Yes   | That user's name.              |

## Verify the signature

Anyone who learns your URL can send it a POST. Check the signature on every request before you trust it.

1. Read the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers.
2. Reject the request if the timestamp is more than 5 minutes away from your clock. This stops someone from replaying an old request.
3. Remove the `whsec_` prefix from your signing secret and base64-decode the rest. The result is the key.
4. Build the signed content: `{webhook-id}.{webhook-timestamp}.{body}`, where `body` is the **raw request body bytes**. Don't parse and re-serialize the JSON first; any change to the bytes breaks the signature.
5. Compute HMAC-SHA256 of the signed content with the key, and base64-encode the result.
6. Split `webhook-signature` on spaces. Accept the request if any `v1,<signature>` entry matches your result. Compare in constant time.

After you [rotate the secret](#rotate-the-signing-secret), the header carries two signatures for 24 hours, one per secret. A match on either is fine, so check every entry.

### Python

Uses only the standard library and needs Python 3.9 or later. Pass the header values and the raw body, for example `request.get_data()` in Flask or `await request.body()` in FastAPI.

```python
import base64
import hashlib
import hmac
import time

TOLERANCE_SECONDS = 5 * 60


def verify_webhook(secret: str, headers, body: bytes) -> bool:
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature")
    if not msg_id or not timestamp or not signatures:
        return False

    try:
        sent_at = int(timestamp)
    except ValueError:
        return False
    if abs(time.time() - sent_at) > TOLERANCE_SECONDS:
        return False

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed_content = f"{msg_id}.{timestamp}.".encode() + body
    expected = base64.b64encode(
        hmac.new(key, signed_content, hashlib.sha256).digest()
    ).decode()

    for entry in signatures.split(" "):
        version, _, signature = entry.partition(",")
        if version == "v1" and hmac.compare_digest(signature, expected):
            return True
    return False
```

### Node.js

Uses the built-in `crypto` module, no extra package. `body` must be the raw body as a `Buffer`, for example from `express.raw({ type: "application/json" })`. Node.js lower-cases incoming header names, so `req.headers` works as is.

```javascript
const crypto = require("node:crypto");

const TOLERANCE_SECONDS = 5 * 60;

function verifyWebhook(secret, headers, body) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;

  const sentAt = Number(timestamp);
  if (!Number.isInteger(sentAt)) return false;
  if (Math.abs(Date.now() / 1000 - sentAt) > TOLERANCE_SECONDS) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = crypto
    .createHmac("sha256", key)
    .update(`${id}.${timestamp}.`)
    .update(body)
    .digest();

  return signatures.split(" ").some((entry) => {
    const [version, signature] = entry.split(",", 2);
    if (version !== "v1" || !signature) return false;
    const received = Buffer.from(signature, "base64");
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}
```

You can also use one of the [Standard Webhooks libraries](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries), which do the same checks.

## Respond quickly

Answer with any 2xx status within 10 seconds, then do the work. Store the event and process it in the background if processing takes longer. A request that takes more than 10 seconds counts as a failure and is retried.

We don't follow redirects. A 3xx response counts as a failure, so give us the final URL.

Answer `410 Gone` to tell us to stop. We pause the webhook straight away and email your admins. A 410 to a test send doesn't pause anything.

## Retries and delivery guarantees

Any response other than 2xx or 410, and any connection error or timeout, counts as a failed attempt. We retry each event up to 20 attempts in total, over about 8 hours. The wait between attempts starts at 30 seconds, doubles each time, and levels off at 35 minutes. After the last attempt the event is marked failed. You can send it again with a [replay](#delivery-log-and-replay).

Delivery is at least once, and events can arrive in any order:

* The same event can arrive more than once. Use `webhook-id` to drop duplicates.
* Don't rely on order. Use the timestamps in the body if you need one.

## Held bursts

Each webhook has a burst threshold. We check for new events every five minutes. If one check finds more new events for a webhook than its threshold, we hold them instead of sending them and email your admins. Only events created in the last 24 hours count towards the threshold, so past events you ask for with a start date or a rewind are never held.

Held events show up on the webhook's **Deliveries** tab. For each held batch you can:

* **Send** it. Each event costs one credit when it's delivered.
* **Skip** it. Skipped events are never sent, and a replay won't send them either.

If you do nothing, we skip a held batch automatically after 7 days. You can only send held events while the webhook is active.

If your normal volume trips the threshold, raise it in the webhook's settings.

## Pauses

You can pause and resume a webhook at any time. While a webhook is paused, we don't send it any events. Test sends still go through.

We also pause a webhook automatically, and email your admins, when:

* Your endpoint has failed for 24 hours without accepting a single event, with at least 20 failed attempts in that time. Test sends don't count.
* Your endpoint answers `410 Gone`.
* The billing owner runs out of credits.
* The billing owner is no longer an admin, and no other admin can take over.

When you resume, you choose where to start:

* **From where it paused** sends everything that happened while the webhook was paused, oldest first. Each delivery costs one credit.
* **From now** skips everything that happened while it was paused.

If you resume a webhook that was paused for credits and the billing owner still has none, we pause it again.

## Delivery log and replay

The **Deliveries** tab lists the events from the last 30 days with their status, and you can filter by status and event type. Open an event to see its id (the `id` in the body and the `webhook-id` header) and its `type`, even before the first attempt. You also see each attempt, with the request we sent and the response we got. We keep attempt details for 90 days.

A replay sends the events from a time range again, with the same ids. The range can start before the 30 days the **Deliveries** tab shows. A receiver that drops duplicates on `webhook-id` skips the ones it already accepted. A replay covers events that were delivered, failed, or skipped because the webhook was paused or out of credits. It doesn't cover test sends or held events, and you can only replay while the webhook is active.

Re-sending an event you already paid for is free.

## Send past events

A webhook can send events from before it existed or from before a point you choose, up to 90 days back. There are two ways:

* **When you create it**: set **Send events from** to **A past date**.
* **Later**: on an active webhook, use **Rewind** and pick a date.

Either way, Sumble sends the events created since that date that match the webhook's filters and that it hasn't received yet. Events it already received aren't sent again; use [Replay](#delivery-log-and-replay) to resend those. Events that were skipped while the webhook was paused or out of credits are included.

Before you confirm, Sumble shows how many events it will send. Each costs one credit when it's delivered, and the billing owner must have enough credits for all of them. If they don't, pick a later date or narrow the filters. If more events match by the time you confirm, Sumble asks you to confirm the new count.

Delivery starts within five minutes, and a large range can take a while. Past events are never held as a burst.

## Credits and the billing owner

Each delivered event costs one credit, charged to the webhook's billing owner. The billing owner is the admin who created the webhook, and any admin can change it to another admin with an Admin seat.

We don't charge for failed attempts, test sends, or events that were already charged once.

If the billing owner leaves or loses their Admin seat, we move the webhook to another admin and email your admins. If no admin is left, we pause the webhook.

See [Credits](/get-started/credits) for how credits work.

## Rotate the signing secret

Click **Rotate signing secret** on the webhook. Sumble shows the new secret once. Copy it right away.

The old secret keeps working for 24 hours. During that time every delivery carries a signature made with each secret, so you can update your receiver without dropping events.

## What's not included

Webhook payloads don't include suggested contacts or account status. To get those, look the organization or person up with the [organizations](/api/core-data/organizations) and [people](/api/core-data/people) endpoints of the [Sumble API](/api/api).

There is no public API for managing webhooks. Set them up in **My Team > Webhooks**.


# Notifications

Choose where Sumble sends signals and alerts.

Sumble can deliver [signals](/our-data/signals) to your team in several places. Each one routes signals to the rep who owns the account, using the owner mapping described in [Data fields](/system-setup-and-configuration/data-fields#users).

| Channel        | Plans      | Set up                                                                                                    |
| -------------- | ---------- | --------------------------------------------------------------------------------------------------------- |
| Web app        | All        | Signals appear on the [Signals page](/web-app/account-intelligence/intent-signals).                       |
| Email          | All        | Digests of your latest signals. Manage them in [Account > Settings](https://sumble.com/account/settings). |
| Slack          | All        | [Signal alerts in Slack](/slack-agent/signals-alerts-in-slack)                                            |
| Salesforce     | Enterprise | [Salesforce](/system-setup-and-configuration/crm/salesforce-package)                                      |
| HubSpot        | Enterprise | [HubSpot](/system-setup-and-configuration/crm/hubspot)                                                    |
| Webhooks       | Enterprise | [Webhooks](/system-setup-and-configuration/data-destinations/webhooks)                                    |
| Data warehouse | Enterprise | [Data destinations](/system-setup-and-configuration/data-destinations)                                    |


# Overview

How Sumble secures customer data and the systems that process it.

## Infrastructure security

Sumble runs on Google Cloud Platform (GCP) with the following security measures:

* **Encryption in transit.** All data transmitted between clients and Sumble services uses TLS. Internal service-to-service communication is also encrypted.
* **Encryption at rest.** All databases and storage systems use GCP's default encryption at rest.
* **Network isolation.** Production databases are not accessible from the public internet. Access is restricted to authorized services within our GCP project.
* **Access controls.** Internal access to production systems follows the principle of least privilege. Administrative actions are logged to an audit trail.

## Authentication

* **User authentication.** Sumble uses JWT-based authentication. Users sign in with their email address via magic link or SSO (for enterprise customers using [Okta SSO](/system-setup-and-configuration/users-access/okta-sso-oidc)).
* **API authentication.** API access uses bearer tokens generated from the [API keys page](https://sumble.com/account/api-keys). Keys can be revoked at any time.
* **Enterprise SSO.** Organizations on enterprise plans can configure single sign-on through Okta OIDC so that employees authenticate through their corporate identity provider.

## Data handling

* **Customer data isolation.** Each customer's CRM data (accounts, contacts, enrichments) is logically isolated and only accessible to authorized users within that customer's organization.
* **Data retention.** Sumble retains user activity data and enrichment results for the duration of the customer relationship. Data can be deleted upon request.
* **No resale of customer data.** CRM data shared with Sumble for enrichment (account lists, contact lists) is used only for providing enrichment services back to that customer. It is not shared with other customers or sold.

## Compliance

* **SOC 2.** Sumble maintains SOC 2 compliance. Details are available through our trust center.
* **GDPR.** Sumble processes data in accordance with GDPR requirements. People data sourced from public professional profiles is handled in compliance with applicable data protection regulations.

## Responsible AI

Sumble uses machine learning models to extract structured data from job posts (entity extraction, relationship classification, job function classification). These models are trained on job market data and do not process personal communications, private documents, or sensitive personal information.

Sumble also uses third-party large language models (LLMs) in limited contexts — entity disambiguation, signal title generation, and the natural-language account intelligence briefs returned through the Sumble web app, REST API, and MCP server. These models are provided by the following LLM subprocessors: **Google** (Gemini), **OpenAI** (GPT), and **Anthropic** (Claude). The user-facing intelligence briefs surfaced through the MCP server are generated by Google's Gemini models. Only Sumble's structured business data and the prompt context required for the task are sent to these providers, and LLM outputs are validated against structured data.

## External resources

* [Trust center](https://trust.sumble.com/) — security documentation, compliance reports, and policies
* [System status](https://status.sumble.com/) — real-time system availability and incident history


