# 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.
Get startedCreate your account, explore the web app, and make your first API call./pages/yOQ1os6cyzIlr9Wd0B6E
API ReferenceFind, enrich, and match organizations and people programmatically./pages/M0uCGeanapoFj90yfUGt
Use the MCP serverConnect AI assistants directly to Sumble data with the MCP integration./pages/KLH6XuEHsUssUZW6C1i4
## Common tasks
Quick startGo from signup to your first search result in minutes./pages/A4HZdCmXZzm5TVmari5Y
Track signalsGet notified when target accounts show buying intent through hiring activity./pages/jkLa2cs83hqUISDo6gzA
Find organizationsQuery companies by technology stack, industry, location, and more./pages/Tgdx2tQiqkDPQMBz0viJ
Enrich contactsRetrieve email addresses and phone numbers for people at target accounts./pages/WAJxrUQ7c1jDd5TfFZqP
IntegrationsConnect Sumble to your CRM, data warehouse, notifications, and identity provider./pages/m134c2X8ZYJPMXfcw9kV
Understand creditsLearn how API credits are consumed and how to track your usage./pages/uzgJ7LwttP4sXWO6VVLs
# 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. Book a call # 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 steps require a Pro plan or an active free trial. {% 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. Free plan users receive up to 7 signals per week. Pro users receive up to 20 signals per day. {% endstep %} {% step %} ### Generate your first API key API access is available on Pro and Enterprise 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 -X POST https://sumble.com/paid-api/organizations/find \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"filters": {"technologies": ["react"]}, "limit": 5}' ``` Replace `YOUR_API_KEY` with the key you generated in the previous step. A successful response looks like this: ```json { "id": "0199f400-4123-7eca-9082-be2c94676bfc", "credits_used": 5, "credits_remaining": 9895, "total": 48291, "organizations": [ { "id": 1726684, "name": "Acme Corp", "domain": "acme.com", "industry": "Information", "total_employees": 320, "headquarters_country": "US", "url": "https://sumble.com/l/org/TH2y9mGkRr1q" } ] } ``` 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 %} # 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" %}
{% endtab %} {% tab title="Person Profile" %}
{% endtab %} {% endtabs %} ## Derived data * Headcount * Location * Sourced from [GeoNames](https://www.geonames.org/), licensed under CC BY 4.0 * Industry * Parent-Subsidiary relationships * Attributes * B2B/B2C * IT Services * Digital Native * Teams and org structure * Technologies * Projects * Job functions: people & job posts * Job levels: people & job posts ## 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: hundreds of thousands 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. # 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 * [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/v6/ ``` ### 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/v6/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 ## 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. | | [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 | | Technologies find | 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 | 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](/web-app/exports-credits/credits-and-exports) for details on monthly allocations and purchasing additional 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. ## 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 | # 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=v6 ``` 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=v6" \ -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. # 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. * [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. ### Composable response The `select` block dictates exactly which attributes return — nothing is mandatory: * **`attributes`** — baseline company attributes such as `employee_count`, `industry`, `jobs_count`, `teams_count`, `headquarters_country`, `sumble_score`, funding fields, and the parent/subsidiary ids. `id`, `name`, `slug`, `url`, and `sumble_url` are always included for free. * **`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. Each result also includes a deep link to view the underlying data in Sumble. ### 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`, and `sumble_url` 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 /v6/organizations > Unified organizations endpoint ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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`."},"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."}},"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","headquarters_country","sumble_score","sumble_url","parent_id","subsidiary_ids","tags","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."}},"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"},"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"},"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"},"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":{"/v6/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"}}}}}}}}} ``` *** ## Organization signals 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/v6/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`. ### Credit cost 1 credit per signal returned. Organizations with no returned signals do not consume credits. ## GET /v6/organizations/{organization\_id}/signals > Get organization signals ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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"},"suggested_contacts":{"anyOf":[{"$ref":"#/components/schemas/SuggestedContacts"},{"type":"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":{"/v6/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"}}}}}}}}} ``` # People ## Find, match, and enrich people The single endpoint for working with people. Provide either a **list of people** to resolve (list mode) or an **organization-scoped filter** (search mode), 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. * **`filter`** — the organizations whose people to return: `organization_ids` (up to 1,000) and/or a saved `organization_list_id`, optionally narrowed by an advanced `query` (job functions, technologies, job levels, locations, and more). Covers the previous `find` flow. 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. ### 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`, `person_score`, 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. * `person_score` is your ICP match score (0–100) with its contribution breakdown. 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`** — inferred managers and/or direct reports for each matched person. Choose the `direction` (`managers`, `direct_reports`) and which attributes to return for them. Available in list mode only, for up to 25 people per request. ### 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. ## POST /v6/people > Unified people endpoint ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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."}},"additionalProperties":false,"type":"object","required":["select"],"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/'. 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."}},"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"},"people":{"items":{"$ref":"#/components/schemas/PersonRow"},"type":"array","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":{"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","people","total"],"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 ''). 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":{"/v6/people":{"post":{"tags":["people"],"summary":"Unified people endpoint","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. ### 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 /v6/jobs > Unified jobs endpoint ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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 ''). 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":{"/v6/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 /v6/teams > Unified teams endpoint ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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 ''). 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":{"/v6/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 # 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. ### Credit cost 1 credit per request that returns at least one technology. Requests with no matches do not consume credits. ## POST /v6/technologies/find > Find technologies by name ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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":{"/v6/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). ### Credit cost 1 credit per 100 matched technologies. Unmatched inputs do not consume credits. ## POST /v6/technologies/lookup > Look up technologies by name, slug, or alias ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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":{"/v6/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. 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. ### Credit cost 1 credit per 100 matched categories. Unmatched inputs do not consume credits. ## POST /v6/technologies/categories/lookup > Look up technology categories by slug or name ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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":{"/v6/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. ### Credit cost 1 credit per 100 matched projects. Unmatched inputs do not consume credits. ## POST /v6/projects/lookup > Look up projects by name ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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":{"/v6/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. ### Credit cost 1 credit per 100 matched titles. Unmatched titles do not consume credits. ## POST /v6/jobs/title-lookup > Look up the function and level for job titles ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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":{"/v6/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"}}}}}}}}} ``` # 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 * [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. ## Search signals Search by any combination of signal IDs, organization IDs, person IDs, technology slugs, job function names, priorities, and saved organization list 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/v6/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] } }' ``` 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. ### 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`. For person-movement signals, `subtitle` may include a normalized start-date label such as `Started Jun 2026` or `Starting Jul 2026`. 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`, `linkedin_url`, and a relevance `score` from 1 to 10 (higher is a stronger match) — and a `sumble_url` linking to all matching people for the job post. ### 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. ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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."}},"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."}},"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"},"suggested_contacts":{"anyOf":[{"$ref":"#/components/schemas/SuggestedContacts"},{"type":"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":{"/v6/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.","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, and job post 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. Priority Signals are AI-generated summaries of the highest-priority signals in your account feed. Each result includes the digest item headline and content, a URL to view the digest in Sumble, source `signal_ids`, and searchable `organization_ids`, `person_ids`, and `job_post_ids` derived from the source signals. ```bash curl https://api.sumble.com/v6/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] } }' ``` ### Response The response contains a `priority_signals` array. Each priority signal includes `url`, `signal_ids`, `headline`, `content`, `date`, `organization_ids`, `person_ids`, and `job_post_ids`. The `date` is returned as `YYYY-MM-DD`. ### 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 20 priority signals based on the specified filters, or omit filters to simply return the latest. ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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."}},"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."}},"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":{"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"}},"type":"object","required":["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":{"/v6/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 20 priority signals based on the specified filters, or omit filters to simply return the latest.","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"}}}}}}}}} ``` # 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. ### Credit cost Completed intelligence briefs cost 50 credits. HTTP `202` pending responses do not consume credits. ## GET /v6/organizations/{organization\_id}/intelligence-brief > Retrieve the intelligence brief for an organization ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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":{"/v6/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 | | 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. ## GET /v6/organization-lists > List organization lists ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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":{"/v6/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. Use the `list_id` returned from the list endpoint. ## GET /v6/organization-lists/{list\_id} > Get organization list details ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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"}},"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"}},"type":"object","title":"OrganizationListOrganization"},"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":{"/v6/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"}}],"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 /v6/organization-lists > Create an organization list ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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":{"/v6/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"}}}}}}}}} ``` *** ## 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 /v6/organization-lists/{list\_id}/organizations > Add organizations to a list ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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":{"/v6/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":"v6"},"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":{"/v6/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":"v6"},"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":{"/v6/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. ## GET /v6/contact-lists > List contact lists ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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":{"/v6/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. ## GET /v6/contact-lists/{list\_id} > Get contact list details ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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"}},"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/sumble__db__schemas__people__ProfileContactInfo"},{"type":"null"}]}},"type":"object","required":["id","url","name"],"title":"ContactListPerson"},"sumble__db__schemas__people__ProfileContactInfo":{"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":"ProfileContactInfo"},"ContactInfoRequested":{"properties":{"email":{"type":"boolean","title":"Email","default":false},"phone":{"type":"boolean","title":"Phone","default":false}},"type":"object","title":"ContactInfoRequested"},"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":{"/v6/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"}}],"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 /v6/contact-lists > Create a contact list ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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":{"/v6/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. You can obtain person IDs from the [People](/api/core-data/people) endpoint. ## POST /v6/contact-lists/{list\_id}/people > Add people to a contact list ```json {"openapi":"3.1.0","info":{"title":"Sumble API","version":"v6"},"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":{"/v6/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"}}}}}}}}} ``` # 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/v6/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":"v6"},"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":{"/v6/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/v6/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":"v6"},"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":{"/v6/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 Desktop, Cursor, or ChatGpt. Behind the scenes, your AI assistant calls Sumble's API on your behalf. ## Getting started Sumble is now 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="" %} ## Compatibility On Claude and ChatGPT you can install Sumble directly from the app directory. Cursor and Claude Code use a custom MCP connection. It is possible in these LLMs | Platform | Base Availability | How to install | Enterprise Requirements | | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | | Claude | Paid plans only | [Claude directory](https://claude.ai/directory/connectors/sumble) or custom connector | Admin must enable connectors (Team/Enterprise) | | Cursor | All plans | Custom MCP connection | None (Available on all) | | ChatGPT | Paid plans only | [ChatGPT directory](https://chatgpt.com/apps/sumble/asdk_app_69d6aed609708191a384fb6b59438690) or custom app | None (Available on all) | | Gemini | Not available | N/A | N/A | ## Claude instructions {% hint style="info" %} *Works on Claude Pro and above plans. Enterprise users may need to contact their admin to enable adding connectors.* {% endhint %} ### 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 ## Cursor instructions {% hint style="info" %} *Works on all Cursor plans* {% endhint %} 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 ## Claude Code instructions {% hint style="info" %} *Works on all plans of Claude Code* {% endhint %} 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 ## ChatGPT instructions {% hint style="info" %} *Works on ChatGPT Pro and above plans. Enterprise users may need to contact their admin to enable using apps* {% endhint %} ### 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 ## 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 | 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) | 1 credit per matched org + 1 per paid attribute + per-entity metric costs | | `GetIntelligenceBrief` | LLM-generated sales intelligence brief for a target account, synthesized by Google Gemini from Sumble's structured data | 50 credits per completed brief | ### 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 | 1 credit per list | | `GetOrganizationList` | Get one organization list and the organizations in it, including each organization's Sumble profile URL and own website URL | 1 credit per organization | | `CreateOrganizationList` | Create a new empty organization list | 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, or saved organization lists | 1 credit per signal returned | | `SearchPrioritySignals` | Search Priority Signals digest items by source signal IDs, organization IDs, person IDs, or job post IDs | 1 credit per priority signal 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) | 1 credit per job + 1 per paid attribute + 1 per related person returned | | `LookupJobTitles` | Resolve a list of job titles to their canonical job function and level | 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, optional related people (inferred managers and direct reports), and optional email/phone contact reveals | 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 | ### Contact Lists | Tool | Description | Credit cost | | ------------------- | ------------------------------------------------------------ | ------------------- | | `ListContactLists` | List saved contact (people) lists with IDs and people counts | 1 credit per list | | `GetContactList` | Get one contact list and the people in it | 1 credit per person | | `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 | 1 credit per search | | `LookupTechnologies` | Resolve a list of technology names, slugs, or aliases to canonical IDs, slugs, names, and categories | 1 credit per 100 matched technologies | | `LookupTechnologyCategories` | Resolve a list of technology category slugs or names to their canonical categories and constituent technologies | 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 | 1 credit per 100 matched projects | ### Support | Tool | Description | Credit cost | | ------------------------ | ------------------------------------------------------------------------------------------------ | ----------- | | `ReportDataQualityIssue` | Report incorrect, missing, or stale Sumble data; routed to the Sumble data team for triage | Free | | `SubmitSupportRequest` | Submit a general account, billing, or product support request; routed to the Sumble support team | Free | ### Database | Tool | Description | Credit cost | | ------------- | ------------------------------------------------------- | ---------------------------------- | | `RunSqlQuery` | Run read-only SQL against Sumble's DuckDB (last resort) | 1 credit per 100 bytes of response | | `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 | 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 response data. 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 > Purchase](https://sumble.com/account/purchase). See [Credits](/web-app/exports-credits/credits-and-exports) for details on monthly allocations and purchasing. # 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 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" %}
{% endtab %} {% tab title="account list" %}
{% endtab %} {% tab title="url" %}
{% endtab %} {% tab title="metadata" %}
{% endtab %} {% tab title="technographics" %}
{% endtab %} {% tab title="job function" %}
{% endtab %} {% tab title="project" %}
{% 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.
B2B companies with sales operations staff that use Mailchimp/Constant Contact/Klaviyo.
Companies doing a data infrastructure migration that use Spark/PySpark/Spark SQL and have been hiring for these skills within the last month.
# Natural language search Sumble's natural language search (labeled "Magic Filter" 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 the sparkle icon in the search bar 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 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, alternate names, urls, linkedin pages, and attributes).
Below that we'll see 5 tabs: teams, people, job functions, job posts, trends. 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 presents a drop down tree structure that allows you to explore how Sumble relates teams it knows about in the org. Subsidiaries are included as teams in this view because there are lots of situations where the two ideas are equivalent and we prefer showing as much likely relevant information as possible. For each team/subsidiary in the tree you'll find how many job posts Sumble has records associated with the team, when they were hiring last, and what technologies the team uses. 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" %}
{% endtab %} {% tab title="With Filters" %}
{% 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" %}
{% endtab %} {% tab title="With Filters" %}
{% 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" %}
{% endtab %} {% tab title="With Filters" %}

Note we cannot filter by a job function in this view

{% 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" %}
{% endtab %} {% tab title="With Filters" %}
{% 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" %}

Looks like cloud investment is growing independently of kubernetes usage, with GCP slowly loosing an advantage

{% endtab %} {% tab title="Job Functions" %}

Appears that engineering hiring has be relatively consistent over the last 9 month

{% endtab %} {% endtabs %} # 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. ## 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 Teams on Sumble represent the organizational units within a company — engineering teams, product groups, business units, and subsidiaries. Sumble extracts team structures from job posts and maps them into a hierarchy for each organization. ## 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 mentioned in the team's job posts Subsidiaries are included in the teams view because in practice they often function as teams, and showing them together gives you a more complete picture of the organization. ## 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 Sumble also identifies related teams — teams that frequently appear together in job posts or share technology overlap. This helps you discover adjacent teams that might also be relevant to your outreach. ## How teams are extracted Team names are extracted from job posts using Sumble's NER models. Common patterns include the team or department name appearing in the job title or description (e.g., "Senior Engineer, Infrastructure Platform" maps to the "Infrastructure Platform" team). Names are normalized across variations so that "Infra Platform" and "Infrastructure Platform" resolve to the same team. # Intent signals Intent signals are changes detected in an organization's hiring activity that indicate a potential selling opportunity. Sumble generates these automatically by analyzing job posts, people profiles, and technology usage across hundreds of thousands of organizations every day. Signals surface on the [Signals page](https://sumble.com/signals) and can be delivered via [Slack](/system-setup-and-configuration/notifications/slack-alerts), email, or directly in the Sumble web application. ## Signal types ### Technology adoption Sumble tracks when organizations start mentioning technologies in their job posts. These signals come in three forms: **First mention by company**: a technology appears in an organization's job posts for the first time ever. This is a strong indicator that the company is evaluating or adopting a new tool. **First mention by team**: a technology appears in a specific team's job posts for the first time, even if other teams at the company already use it. This catches expansion within organizations. **Any mention**: any new job post at a configured organization mentions a technology you're tracking. Useful for monitoring ongoing activity at key accounts. ### Key technology projects Signals fire when organizations post jobs related to major technology initiatives: * Cloud migration * Cloud cost optimization * Data infrastructure migration * Design system migration * Digital transformation * Frontend migration * Generative AI projects * Microservices migration * Security infrastructure modernization These indicate budget allocation and active evaluation of new solutions. ### Acceleration in job postings Detects statistically significant changes in hiring volume for specific technologies or job functions over a 12-month window. A surge in Kubernetes job posts, for example, signals a company scaling its infrastructure investment. Both increases and decreases are tracked — a drop in mentions of a competitor's technology can be as useful as a spike in your own. ### New hires Fires when a person with specific technology skills or in a target job function starts a new role at a tracked organization. Signals distinguish between leadership hires (Manager and above) and individual contributor hires. New leaders often bring in tools they've used before, making this a strong signal for outreach. ### Growth in headcount Tracks when organizations are growing or shrinking specific job functions over time. Requires a meaningful change (both percentage and absolute) to avoid false positives. ### Competitor churn signals Combines decreasing mentions of a competitor's technology with related migration projects. When a company is moving away from a competitor, these signals help you time your outreach. ### Own product churn signals The inverse of competitor churn — flags when a customer may be reducing usage of your product, giving you the chance to re-engage proactively. ### Champion alerts Tracks key contacts (champions) and alerts you when they change companies. A person who already knows your product at a new organization is a natural warm lead. Champion tracking requires enterprise configuration. See [Sumble Signals](/enterprise-services/sumble-signals) for setup details. ### Keyword tracking Monitors job posts for specific terms that standard filters don't cover: niche certifications (SOC 2, HIPAA), internal pain points (technical debt, scalability), or methodology mentions. This catches opportunities that standard technology or job function filters would miss. ## Signal tiers | Plan | Signal volume | Configuration | | ---------- | ---------------- | --------------------------------------------------------------------------------------------------------------------- | | Free | Up to 8 per week | Auto-detected from your browsing activity | | Pro | Up to 20 per day | Auto-detected from your browsing activity | | Enterprise | Unlimited | Fully configurable signal types, technologies, job functions, and routing – with native database and CRM integrations | On Free and Pro, Sumble learns what matters to you from your activity on the platform — the organizations you view, the technologies you filter by, and the searches you run. Enterprise customers configure signals explicitly through [Sumble Signals](/enterprise-services/sumble-signals). ## How signals are generated 1. Sumble processes new job posts and people data multiple times per day 2. Each new data point is checked against signal rules (automatic or configured) 3. Matching signals are created with a priority level (high, medium, or low) 4. Signals are routed to the relevant user based on account ownership 5. Delivery happens through the configured channels (web app, Slack, email) ## Working with signals On the [Signals page](https://sumble.com/signals), you can: * **Mark signals as relevant or not relevant** — this improves future signal quality * **Favorite signals** to revisit later * **Filter by signal type, priority, or organization** * **Click through** to the underlying organization, job post, or person profile For enterprise signal configuration, routing, and integration details, see [Sumble Signals](/enterprise-services/sumble-signals). # 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 category (Engineering, Sales, Marketing, etc.) | | **Job level** | Seniority (Individual Contributor, Manager, Director, VP, C-Suite) | | **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 email data is available, you can reveal their email address. This costs 10 credits per contact. See [Credits](/web-app/exports-credits/credits-and-exports) 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 their role category (Engineering, Sales, Marketing, etc.). 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 surface updates through your feed and alerts. * [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 * [Feed](/web-app/lists-monitoring/feed) and [Alerts](/web-app/lists-monitoring/intent-alerts) 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). ## 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 of desired ## 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, , 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 ![](/files/j8T3fRYmTFTVM97sMBhB) 3. Name your list! ## Using account lists You can use account lists to filter organization search to only the account in a specific list(s).
# 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. ## Create a contact list ### From the contact list menu 1. Go to the contact list menu on the right, 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: 2. Click `Add to new List...` ![](/files/uMlORSMYkZc1ZtFJSplV) ### 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...` ![](/files/uMlORSMYkZc1ZtFJSplV) ## Use a contact list Go to the contact list menu on the right, , and select the list you want to inspect. You'll see all the people in the list with their information all together.
# 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. # Feed The Feed is Sumble's stream of intent signals and alerts for your accounts. It is now called **Signals** and lives at [sumble.com/signals](https://sumble.com/signals). If you have bookmarks or links pointing to `/feed`, they will automatically redirect to the Signals page. ## What you'll find The Signals page shows all alerts Sumble has generated based on your activity and account configuration: * **Technology adoption** — companies mentioning a technology for the first time * **New hires** — key people joining tracked organizations * **Hiring trends** — acceleration or deceleration in job posting volume * **Project signals** — organizations starting cloud migrations, GenAI projects, and other initiatives * **Champion alerts** — tracked contacts changing companies (enterprise only) For a full breakdown of signal types, see [Intent signals](/web-app/account-intelligence/intent-signals). ## Filtering signals You can filter the feed by: * Signal type * Priority (high, medium, low) * Organization * Date range Use the **Mark as relevant** and **Mark as not relevant** actions to improve future signal quality. ## Related pages * [Intent signals](/web-app/account-intelligence/intent-signals) — detailed breakdown of all signal types * [Intent alerts](/web-app/lists-monitoring/intent-alerts) — how alerts are generated and delivered * [Sumble Signals](/enterprise-services/sumble-signals) — enterprise signal configuration # Alerts Intent alerts notify you when Sumble detects a selling opportunity in your accounts. As you use Sumble, the platform learns what matters to you — the organizations you research, the technologies you filter by, and the searches you run — and starts surfacing relevant [intent signals](/web-app/account-intelligence/intent-signals) automatically. Once you've logged enough activity, the alerts icon appears in the left sidebar. Click it to see all the alerts Sumble has found for you.
## How Sumble learns what matters Sumble tracks your activity to build a profile of what's relevant to you: * Organizations you view and research * Technologies and job functions you filter by * Searches you run and results you interact with This activity is used to generate personalized alerts without any manual configuration. Enterprise customers can also configure signals explicitly — see [Sumble Signals](/enterprise-services/sumble-signals). ## Alert delivery Alerts are delivered through multiple channels: * **In-app** — the Signals page at [sumble.com/signals](https://sumble.com/signals) * **Slack** — direct messages or a shared channel (requires [Slack integration](/system-setup-and-configuration/notifications/slack-alerts)) * **Email** — periodic digests with your latest alerts ## Managing alerts On the Signals page you can: * **Mark as relevant** — tells Sumble this type of alert is useful to you * **Mark as not relevant** — helps Sumble improve future alert quality * **Favorite** — save an alert for later reference * **Click through** — jump to the underlying organization, job post, or person profile ## Configuring preferences Alert preferences can be managed from [Account > Settings](https://sumble.com/account/settings), where you can control delivery channels and frequency. ## Alert limits by plan | Plan | Alert volume | Configuration | | ---------- | ---------------- | ------------------------------------------------------------------------------ | | Free | Up to 8 per week | Automatic | | Pro | Up to 20 per day | Automatic | | Enterprise | Unlimited | Fully configurable — see [Sumble Signals](/enterprise-services/sumble-signals) | Enterprise customers can configure specific signal types, target technologies, job functions, and routing rules. See [Sumble Signals](/enterprise-services/sumble-signals) for the full configuration and integration details. # Exports & credits Get Sumble's data into the rest of your stack, and understand what it costs. Export search results and lists to CSV, and track how credits are consumed as you go. * [Data exports](/web-app/exports-credits/data-exports) to pull results into your own tools * [Credits](/web-app/exports-credits/credits-and-exports) to see how usage is metered # 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, URL, 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. Review the credit cost shown — it reflects your filters and row count 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. ## Credit costs Export costs depend on the type and filters applied: * **Organizations** — 5 credits per row, per filter term (technologies, job functions, projects). Minimum 5 credits per row. Technology categories count each individual technology. * **People** — 1 credit per person * **Jobs** — 3 credits per job See [Credits](/web-app/exports-credits/credits-and-exports) 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 [Enterprise integrations](broken://pages/YjcfetgOJo18E1nL3aaV). # Credits Credits are how Sumble meters access to data exports, API calls, and contact enrichment. Browsing the web application is free — credits are only consumed when you extract data from the platform. ## How credits work Every action that extracts data costs a certain number of credits. The cost depends on the type of data and how many filter terms you apply. ### Credit costs | Action | Cost | | --------------------------- | ----------------------------------------------------------------------------------------------------- | | **Organization export** | 5 credits per row, per filter term (technology, job function, or project). Minimum 5 credits per row. | | **People API** | 1 credit per person returned | | **Jobs API** | 3 credits per job returned | | **Organization API** | 5 credits per row, per filter term (same as exports) | | **Organization enrich API** | 5 credits per technology found | | **Email reveal** | 10 credits per contact | Technology categories count each technology in the category as a separate filter term. For example, a category containing 3 technologies costs 15 credits per row. ### Monthly allocations | Plan | Monthly credits | | ---------- | --------------- | | Free | 500 | | Pro | 9,900 | | Enterprise | Custom | Monthly credits reset each billing cycle. ### Purchasing additional credits If you need more credits beyond your monthly allocation: 1. Go to [Account > Purchase](https://sumble.com/account/purchase) 2. Select a credit package using the slider 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://calendly.com/d/cnzk-sjk-q38/sumble). ## Exporting data Exports let you download organization, people, or job data as CSV files. ### Export workflow 1. Apply filters on the organizations, people, or jobs search page 2. Click the **Export** button 3. Adjust the number of rows using the slider (maximum 10,000 rows) 4. Review the credit cost shown — it reflects your current filters and row count 5. Click **Export** to confirm 6. Your CSV will download with a preview of the columns included ### Export history View your past exports at [Account > Exports](https://sumble.com/account/exports). You can re-download previously generated files from there. ### What's included in exports Exports include the columns visible in your current search results view. The exact fields depend on the data type: * **Organizations** — name, URL, industry, headcount, HQ location, technologies, and more * **People** — name, title, organization, job function, job level, location, LinkedIn URL * **Jobs** — title, organization, team, technologies, job function, location, date posted ## Frequently asked questions **Are credits tied to individual accounts?**\ Yes. Credits cannot be shared between users. For team-wide credit management, contact sales about enterprise packages. **Can I get a refund on credits?**\ Credits are non-refundable. **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 > Credit Usage](https://sumble.com/account/usage) to view your credit usage and remaining balance. **What happens if I run out of credits?**\ You can still browse the web application freely. Exports, API calls, and email reveals will be unavailable until your credits reset or you purchase more. **Do enterprise integrations use credits?**\ No. Enterprise data integrations (Snowflake, Salesforce, HubSpot, Databricks) are separate from the credit system. See [Enterprise services](/enterprise-services/enterprise-services) for details. # 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 to be enabled for your organization by an admin. The setup involves: 1. Connecting a Salesforce account from [Account Settings](https://sumble.com/account/settings) with OAuth 2. An admin enabling the import feature for your organization 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. # 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 Account Settings Go to [Account Settings](https://sumble.com/account/settings) in Sumble. {% endstep %} {% step %} ### Add to Slack Click the **Add to Slack** button. {% endstep %} {% step %} ### Install the app Follow the prompts to install the Sumble app in your workspace. {% 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 [Account Settings](https://sumble.com/account/settings). {% 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 in [Account Settings](https://sumble.com/account/settings) * 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 [Account Settings](https://sumble.com/account/settings) and click the Slack button again to re-authorize. *** ## Slack permissions | Scope | What it's for | | ------------------- | ----------------------------------------------- | | `chat:write` | Send alerts and agent messages via DM | | `chat:write.public` | Post alerts to public channels when configured | | `files:read` | Read files attached to agent messages | | `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 | {% hint style="info" %} Need help? Contact . 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, or use one of the quick-start actions in the **Home** tab. {% 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. ## Memory The agent maintains memory within each Slack thread for 14 days. As you share context like your ICP, key accounts, and priorities, it builds on it across follow-up messages — so you can pick up a conversation days later and it will know where you left off. ## Credits Each agent response consumes credits from your plan's monthly allowance, based on the tools and data lookups involved. More complex requests use more credits than a simple account lookup. See the [MCP tools reference](/api/mcp) for per-tool credit costs, and check your remaining credits in [Account Settings](https://sumble.com/account/settings). *** For setup, permissions, troubleshooting, and FAQ, see the [Slack Agent overview](/slack-agent/slack-agent). # Signal alerts in Slack Receive Sumble Signals alerts in Slack, routed to each rep's book of business automatically. Sumble Signals alerts can be delivered to each rep's Slack account automatically. Sumble uses your account ownership mapping to route them, so each rep only sees alerts for their own book of business. {% hint style="info" %} Signal alerts in Slack are available on all plans, including Free. {% endhint %} ## Delivery options Each user configures alert delivery from the **Home** tab in the Sumble app: * **Direct messages** — alerts arrive as DMs. This is the default. * **Public channel** — alerts post to a shared channel for team visibility. * **Off** — disables all Sumble notifications. ## Priority filter Users can filter alerts by priority: * High priority only * Medium and high priority * All alerts ## Alert content Each alert includes the organization name, signal type and description, priority level, and a link to the relevant job post, person profile, or trend. Alerts are delivered after each daily pipeline run. Duplicate signals are suppressed. ## Not receiving alerts? * Check that your Slack account is connected in [Account Settings](https://sumble.com/account/settings). * Confirm your Sumble email matches your Slack email, or complete the manual connection. * Make sure you haven't muted the Sumble app in Slack. * Review your notification preferences in the **Home** tab — you may have **Off** selected. *** For workspace setup and notification configuration, see [Slack alert setup](/system-setup-and-configuration/notifications/slack-alerts). For setup and the full agent reference, see 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.
IntegrationEnrichSignals
Snowflake sharetruetrue
Salesforce packagetruetrue
HubSpottruetrue
Databricks Delta Sharingtruetrue
Push to blob storetruetrue
Emailfalsetrue
Sumble Web Applicationfalsetrue
*** 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. Book a time to chat with us # 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 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.
FieldRequiredDescription
Account IDtrueunique identifier for your account
Account Nametrueaccount's organization name
Account URLtrueprimary URL or domain associated with the account
Account Linkedin URLfalseURL of linkedin page associated with the account
Countryfalseaccount's organization headquarter country
Parent Account IDfalseunique identifier of account's parent organization
Ultimate Parent Account IDfalseunique identifier of account's most parent organization
Alternate Namesfalseother names the account's organization is known by
Alternate URLsfalseother URLs associated with the account's organization
Book a time to chat with us # 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: | 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 | Contact connected to a previous closed-won opportunity; A power user who hasn't used the product for a certain period of time | 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. ### Fields for matching | Field | Priority | Notes | | -------------------------- | -------- | ----------------------------- | | Account ID | Required | To match to your account list | | Account Owner | Required | | | Account Name | High | | | Account URL | High | | | Headquarters Country | Medium | Billing country also works | | Account Linkedin URL | Low | | | Parent Account ID | Low | If account is a subsidiary | | Ultimate Parent Account ID | Low | If account is a subsidiary | ## Integration We deliver alerts to: * Email * Sumble web application * [Slack](/system-setup-and-configuration/notifications/slack-alerts) * [Databricks](/system-setup-and-configuration/data-destinations/databricks) * [Snowflake share](/system-setup-and-configuration/data-destinations/snowflake-share) * [Salesforce](/system-setup-and-configuration/crm/salesforce-package) * [HubSpot](/system-setup-and-configuration/crm/hubspot) We will add more alert integrations over time. Ask us about a new integration if you don't see it here. Book a time to chat with us # 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. * [Users & access](/system-setup-and-configuration/users-access) — SSO / OIDC * [CRM](/system-setup-and-configuration/crm) — sync accounts, contacts, and enrichment to Salesforce and HubSpot * [Data destinations](/system-setup-and-configuration/data-destinations) — push data to Snowflake, Databricks, or a blob store * [Notifications](/system-setup-and-configuration/notifications) — route signal alerts to Slack * [Plans & billing](/system-setup-and-configuration/pricing) — manage your plan # Users & access Manage who can access your Sumble workspace and how they authenticate. Configure single sign-on for your Sumble workspace. * [SSO / OIDC](/system-setup-and-configuration/users-access/okta-sso-oidc) # 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. # 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. * [Salesforce](/system-setup-and-configuration/crm/salesforce-package) * [HubSpot](/system-setup-and-configuration/crm/hubspot) # 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 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. *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:
* **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:
* **Account Signals Widget**: A Lightning component (Sumble Account Signals) that shows signals specific to an Account, embeddable on any Account record page:
* **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: 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). 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). Then visit the URL shown on the setup page — it will look like: ``` https://sumble.com/integrations/salesforce/start?org_id= ``` 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 the minimum required API permissions. 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
RequirementDetails
Master-Detail RelationshipThe custom object must have a Master-Detail relationship to the Account object
External ID FieldMust have a field named External_Id__c
External ID SettingsThe External_Id__c must be a `Text(18)` field and must be marked as both External ID and Unique ID.
*** ## 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 ### 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 the follow fields for account matching:
FieldRequiredDefault field
Account IDtrueId
Account NametrueName
Account URLtrueWebsite
Account Linkedin URLfalse
CountryfalseBillingCountry
Parent Account IDfalseParent Id
Ultimate Parent Account IDfalse
If there's other fields that are potentially relevant, we can load those into Sumble's system 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 ## Technical Details #### Data Retrieval (pull from Sumble) * 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 * Sumble manages the full lifecycle — signals are created and updated automatically #### Data Updates (push from Sumble) * 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 Book a time to chat with us # 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 From Sumble to HubSpot: * **Enrichments** -- Write firmographic and technographic data back to HubSpot Company records (updates only, does not create new Companies) Each of these can be turned on independently. ### 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 on your account 3. 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 #### Step 1: Start the connection 1. Go to [sumble.com/integrations/hubspot/start](https://sumble.com/integrations/hubspot/start) 2. Log in to Sumble if prompted #### 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 Sumble. You should see **"HubSpot is connected"**. No further configuration is needed. Sumble starts syncing automatically. ### 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 | 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 on your account (technology usage, headcount trends, hiring signals, etc.). 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 new enrichments are added to your Sumble account, the corresponding properties are created on the next sync. #### 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. ### 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 |
| `hs_object_id` | | Company Name |
| `name` | | Company Domain |
| `domain` | | LinkedIn URL |
| `linkedin_company_page` | | Country |
| `country` | | Parent Company ID |
| (if applicable) | If your HubSpot instance uses non-standard property names for any of these, let us know during setup and we'll configure the mapping accordingly. ### Sales territories Sumble reads HubSpot owner assignments to personalize each user's experience. By default, it uses: * **HubSpot Owner** -- the Company's assigned owner * **SDR Owner** -- a custom property, if configured These determine which accounts each Sumble user sees signals and alerts for. If your team uses different fields for account ownership, we can set up custom mappings. ### Data sync details #### Pull (HubSpot to Sumble) * Uses HubSpot's CRM Export API to pull Company records and User records * 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 #### Push (Sumble to HubSpot) * Uses HubSpot's CRM Import API * Sends enrichment data as CSV imports keyed on `hs_object_id` * **Updates existing Company records only** -- does not create new Companies in HubSpot * Only writes to properties in the **Sumble Information** group ### Disconnecting To disconnect, contact your Sumble account team. We'll revoke stored credentials and stop syncing. You can also revoke access from HubSpot directly: 1. Go to **Settings > Integrations > Connected Apps** 2. Find **Sumble** 3. Click **Uninstall** *** Book a time to chat with us # Data destinations Push Sumble data into your data warehouse or storage. Deliver Sumble enrichment and signals straight into your data platform. * [Snowflake](/system-setup-and-configuration/data-destinations/snowflake-share) * [Databricks](/system-setup-and-configuration/data-destinations/databricks) * [Blob store / GCS](/system-setup-and-configuration/data-destinations/blob-store) # 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 uses the follow fields for matching
FieldRequiredDescription
Account IDtrueunique identifier for your account
Account Nametrueaccount's organization name
Account URLtrueprimary URL or domain associated with the account
Account Linkedin URLfalseURL of linkedin page associated with the account
Countryfalseaccount's organization headquarter country
Parent Account IDfalseunique identifier of account's parent organization
Ultimate Parent Account IDfalseunique identifier of account's most parent organization
Alternate Namesfalseother names the account's organization is known by
Alternate URLsfalseother URLs associated with the account's organization
Use whatever column names are natural for your system — we’ll handle the column matching from there. ## 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). Book a time to chat with us # 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 configures column mappings for your account fields (account ID, name, URL, etc.) 4. Choose which enrichments to include Book a time to chat with us # Blob store / GCS Sumble can export enriched data as Parquet files directly to your Google Cloud Storage (GCS) bucket. ## Overview The blob store integration is a one-way push: Sumble writes Parquet files to a GCS bucket you control. This is the simplest integration option — no API connections, no database credentials. You get raw files that you can process however you want. ## What gets delivered 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 * **Reference data** — technologies, job functions, countries, and other lookup tables Files are standard Apache Parquet format, readable by any tool that supports it (BigQuery, Spark, pandas, DuckDB, etc.). ## Update cadence Files are updated daily after the Sumble data pipeline completes. Each run replaces the previous set of files. ## Setup GCS integration requires an enterprise plan. To get started: 1. Create a GCS bucket (or designate an existing one) for Sumble to write to 2. Grant Sumble's service account write access to the bucket 3. Sumble configures the export and begins daily syncs Book a time to chat with us # Notifications Configure where Sumble sends alerts and signal notifications. Choose how your team receives Sumble alerts and intent signals. * [Slack alert setup](/system-setup-and-configuration/notifications/slack-alerts) # Slack alert setup Deliver Sumble Signals alerts to reps in Slack. Slack signal alerts deliver [Sumble Signals](/enterprise-services/sumble-signals) to reps in Slack. Sumble uses your account ownership mapping to route alerts, so each rep only sees their own book of business. For app setup, account connection, and AI agent features, see the [Slack Agent overview](/slack-agent/slack-agent). ### Delivery options Each user can choose how they receive Slack alerts: * **Direct messages** — alerts are sent as DMs to the individual rep. This is the default. * **Public channel** — alerts are posted to a shared channel for team visibility. * **Off** — disables all Sumble notifications. Users manage alert preferences from the **Home** tab in the Sumble app. ### Priority filter Users can filter alerts by priority: * **High priority** — only receive high-priority alerts * **Medium and high priority** — receive medium- and high-priority alerts * **All alerts** — receive all alerts ### Alert content Each Slack alert includes: * The organization name and a link to the organization page in Sumble * The signal type and a description of what was detected * Priority level (high, medium, or low) * A link to the relevant job post, person profile, or trend data ### Alert frequency Alerts are delivered after each daily pipeline run. Duplicate signals are suppressed. ### Troubleshooting #### Not receiving alerts * Verify your Slack account is connected in [Account Settings](https://sumble.com/account/settings) * Check that your Sumble email matches your Slack email, or that you've completed the manual connection * Make sure you haven't muted the Sumble app in Slack * Check your notification preferences in the Sumble app's **Home** tab — you may have selected **Don't send any updates** * Alerts are generated based on your activity on Sumble — if you haven't used the platform recently, signal generation may be limited #### Need to reconnect If your Slack workspace changes or you need to re-authorize, reconnect from [Account Settings](https://sumble.com/account/settings). # Plans & billing Sumble serves the whole go-to-market org, & our three plans map to how deep you want to go. ## 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. Use Enterprise to: | Team | What we solve | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | **RevOps** | Score and prioritize accounts, size TAM and whitespace, and keep CRM records accurate and enriched on an ongoing basis. | | **Sales** | Put account research and live triggers in front of reps and their AI workflows, and surface displacement openings against competitors. | | **Marketing** | Build ABM target lists, event and campaign audiences, and enrich inbound leads as they arrive. | | **Customer Success** | Watch existing accounts for churn risk and expansion signals before they reach a renewal call. | You have a number to hit. Tell us what it is, and we'll help you drive it. [Talk to sales →](https://calendly.com/d/cnzk-sjk-q38/sumble) # 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