> For the complete documentation index, see [llms.txt](https://docs.sumble.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sumble.com/api/core-data/organizations.md).

# 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.

### Closed organizations

Some organizations in Sumble are marked **permanently closed** (shut down, dissolved, or bankrupt with no successor). The two modes treat them differently:

* **Match mode** still resolves closed organizations — if your CRM account maps to a company that has since shut down, you want to know, not get a silent non-match. Request the `status` attribute (`active` or `closed`) and `status_reason` (a free-text explanation for non-active statuses) to identify them; each is a paid attribute like any other.
* **Search mode** excludes closed organizations from results by default — a query like "companies with 100+ employees" never returns dead companies. Set `include_closed: true` to include them (for example, to find which organizations matching a filter have shut down), and request `status` / `status_reason` to tell them apart.

When filtering, **`match_source`** controls what evidence lets an organization match a job-side filter (technology, job function, hiring location, and similar):

* **`any`** (default) — an org matches if the evidence appears in **either** its job posts **or** the skills its employees list on LinkedIn. For example, `technology EQ 'laravel'` matches a company that posts Laravel jobs *or* simply employs people who list Laravel as a skill.
* **`job_post`** — restricts matches to **job-post evidence only**, so an org that matches solely because an employee lists the technology (with no job posts mentioning it) is excluded. Use this when you want companies that are actively *hiring for* a technology rather than merely *staffed with* people who know it. This scopes matching only; per-entity `people_count` metrics still report all people at the matched org.

### Composable response

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

* **`attributes`** — baseline company attributes such as `employee_count`, `industry`, `jobs_count`, `teams_count`, `headquarters_country`, `sumble_score`, `status`/`status_reason`, funding fields, the parent/subsidiary ids, and the scope-consistent count totals (`jobs_count_rollup` / `jobs_count_no_rollup`, `teams_count_rollup` / `teams_count_no_rollup`, `people_count_rollup` / `people_count_no_rollup`). `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. Technology, job function, and project selections also expose the record-scope `job_post_count_no_rollup`, `team_count_no_rollup`, and `people_count_no_rollup` (technology and job function only for people). Each rollup metric also includes a deep link to view the underlying data in Sumble.

#### Subsidiary rollup scope

Entity metrics and the `*_rollup` attributes include the whole organization hierarchy — the organization **and all of its subsidiaries**. The `*_no_rollup` variants count only the organization's own records, excluding subsidiaries. To compute a consistent share (for example, the fraction of an org's teams that work on a given technology), take the numerator and denominator from the **same scope**: `team_count ÷ teams_count_rollup` (with subsidiaries) or `team_count_no_rollup ÷ teams_count_no_rollup` (own records only). The legacy `jobs_count` and `teams_count` attributes remain for backward compatibility but come from a different source; prefer the `*_rollup` / `*_no_rollup` attributes when computing ratios against entity metrics.

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

### 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 /v9/organizations

> Unified organizations endpoint

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

***

## Organization signals

Recent signals for a single organization — champion movements, recent hires and promotions, technology and product mentions, projects and initiatives, and technology or job function trends — now have their own page: see [Organization signals](/api/core-data/organizations/organization-signals.md).