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

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

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

### Composable response

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

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

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

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

### Custom technology categories

These endpoints can read and filter custom categories, but cannot create or edit them.

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

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

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

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

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

### Subsidiary rollup scope

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

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

### Sorting

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

Three sorts take a parameter:

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

### File output

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

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

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

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

### Credit cost

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

Per organization the cost is:

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

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

## POST /v9/organizations

> Unified organizations endpoint

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"EnrichOrganizationsRequest":{"properties":{"organizations":{"anyOf":[{"items":{"$ref":"#/components/schemas/MatchOrganizationInput"},"type":"array","maxItems":1000,"minItems":1},{"type":"null"}],"title":"Organizations","description":"List of organizations to resolve and enrich. Mutually exclusive with `filter`."},"filter":{"anyOf":[{"$ref":"#/components/schemas/Query"},{"type":"null"}],"description":"Advanced query selecting the organizations to return. Mutually exclusive with `organizations`."},"include_closed":{"type":"boolean","title":"Include Closed","description":"Filter mode only: include organizations marked permanently closed (`status` = 'closed') in the results — they are excluded by default. Request the `status` / `status_reason` attributes to identify which results are closed. Not valid with `organizations` (direct lookups always resolve closed organizations).","default":false},"select":{"$ref":"#/components/schemas/Select","description":"Dictates exactly which columns are returned."},"limit":{"type":"integer","maximum":200,"minimum":1,"title":"Limit","description":"Maximum number of results to return.","default":10},"offset":{"type":"integer","maximum":10000,"minimum":0,"title":"Offset","description":"Number of results to skip.","default":0},"file_name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"File Name","description":"(v9 only) Return a downloadable file instead of inline `organizations`. Must end in `.csv`, `.xlsx` for Excel, or `.json`."},"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","ai_token_spend_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 its employees' LinkedIn/Coresignal profiles: the skills they list, and where they are based. `job_post` restricts matches to job-post evidence only, so an org that matches solely through its employees is excluded, such as one whose employees list the technology but whose job posts never mention it, or one with staff in the `country` location but no job posts there. Applies to all job-side filters (technology, job function, `country`, 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","description":"Advanced query. Canonical categories use technology_category; custom categories use custom_technology_category with a custom:<slug> value."}},"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_fit","sumble_url","linkedin_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","funding_last_round_investors","revenue","revenue_currency","revenue_usd","revenue_usd_rate_year","revenue_usd_rate_source","revenue_basis","revenue_as_of","revenue_status","revenue_source","revenue_sources","revenue_note","revenue_is_floor","revenue_annual_is_floor","revenue_annual","revenue_annual_status","revenue_fiscal_year","revenue_fiscal_year_end","revenue_quarter","revenue_quarter_status","revenue_quarter_fiscal_year","revenue_quarter_fiscal_period","revenue_quarter_end","revenue_growth_yoy","revenue_annual_source","revenue_quarter_source","revenue_growth_sources","revenue_attribution","revenue_acquired_by_id","revenue_acquired_by_name","revenue_acquired_on","revenue_estimate_usd","revenue_estimate_basis","revenue_estimate_basis_note","revenue_estimate_low","revenue_estimate_high","revenue_estimate_as_of","revenue_estimate_source","revenue_estimate_source_url"]},"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. For type technology_category, use a canonical slug or a custom:<slug> from your category lookup."},"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","description":"Organizations returned by the request. Empty when `file_name` was provided; download the rows from `file` instead."},"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"},"file":{"anyOf":[{"$ref":"#/components/schemas/ApiFileResponse"},{"type":"null"}],"description":"(v9 only) Download metadata for the file requested with `file_name`."}},"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_fit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sumble Fit"},"sumble_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sumble Url"},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin 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)."},"funding_last_round_investors":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Funding Last Round Investors","description":"Investor names in the latest funding round, lead investors first. LLM-extracted from press coverage of the round; null when the coverage named no investor."},"revenue":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Revenue","description":"Latest annual revenue as the organization reported it (company filings, registers, charity and tax returns, regulators), in whole units of `revenue_currency`, rounded. See `revenue_basis` for how it was computed. Null when Sumble has no reported figure for the organization, which is most organizations (see `revenue_estimate_usd` for an estimate that covers almost all of them). Also null when `revenue_status` is 'hidden' or 'acquired'. It can be a floor, the least the company said its revenue was: when `revenue_is_floor` is true (`revenue_note` then starts 'At least this much'), report it as 'at least $X' or '$X+', not as an exact figure, and don't treat it as an upper bound when filtering."},"revenue_currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Currency","description":"ISO 4217 currency code that the revenue amounts are in, e.g. USD."},"revenue_usd":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Revenue Usd","description":"`revenue` in whole US dollars. Amounts in other currencies are converted at the average exchange rate for the year the figure covers (see `revenue_usd_rate_year` and `revenue_usd_rate_source`). Null when `revenue` is null or there is no rate for the currency. A floor in `revenue` (see there) is a floor here too."},"revenue_usd_rate_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Revenue Usd Rate Year","description":"Year of the average exchange rate that converted `revenue_usd`. It can be up to 2 years from the figure's own year when that year's rate isn't published yet. Null for USD figures and when there is no rate."},"revenue_usd_rate_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Usd Rate Source","description":"Where the rate behind `revenue_usd` came from: 'world_bank' (the World Bank's official yearly average), 'fixed_conversion' (a retired currency at its fixed euro conversion rate) or 'llm' (an estimated yearly average, used only for a currency the World Bank publishes no rate for). Null for USD figures and when there is no rate."},"revenue_basis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Basis","description":"How `revenue` was computed: 'ttm' (trailing 12 months: the last fiscal year plus this year's year-to-date minus last year's), 'annual' (the latest fiscal year), 'quarter_annualized' (the latest quarter times 4, an estimate used when no fiscal year ended within a year before that quarter), 'arr' (annual recurring revenue the company stated publicly, as of `revenue_as_of`) or 'run_rate' (a revenue run rate the company stated publicly: current revenue, annualized). Say 'estimated' when reporting a 'quarter_annualized' figure, and call an 'arr' or 'run_rate' figure ARR or run rate, not revenue for a year."},"revenue_as_of":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Revenue As Of","description":"End date of the period the latest figure covers (ISO YYYY-MM-DD). Set even when `revenue` is null because the figure is hidden or the company was acquired, so it shows how old the last report is."},"revenue_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Status","description":"Whether `revenue` is shown. 'current': `revenue_as_of` is at most 18 months old for a source that reports every quarter (SEC filers, US banks), 12 for a figure the company stated publicly, 24 for most that report yearly, longer for a few slow publishers. 'stale': older than that, up to 36 months for most sources; the figure is returned but out of date. 'hidden': older than that; `revenue`, `revenue_usd`, `revenue_sources` and `revenue_note` are null. 'acquired': the company was acquired in a deal announced on or after `revenue_as_of`, so it stopped reporting on its own; the same fields are null, and the acquirer is in `revenue_acquired_by_id`. Null when there is no revenue figure."},"revenue_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Source","description":"Data source of the revenue fields, such as 'sec_companyfacts' (US SEC filings), 'irs_990' (US nonprofits), 'uk_companies_house_accounts' or 'esef_xbrl_org' (European ESEF annual reports). New sources may be added."},"revenue_sources":{"anyOf":[{"items":{"$ref":"#/components/schemas/RevenueSourceFiling"},"type":"array"},{"type":"null"}],"title":"Revenue Sources","description":"The documents `revenue` is computed from, with links. Cite them when reporting `revenue`; for a figure the company stated publicly, `quote` holds the sentence it was read from. A 'ttm' figure lists three: the fiscal year, this year's year-to-date and last year's year-to-date. Null when `revenue_status` is 'hidden' or 'acquired'."},"revenue_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Note","description":"One sentence on what `revenue` is when that needs saying, such as a bank's net revenue, a charity's total income, a self-reported figure, an ARR or run rate, or a floor ('At least this much: ...'). Pass it on when quoting `revenue`. Null for a plain revenue figure, and when `revenue` is null."},"revenue_is_floor":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Revenue Is Floor","description":"True when `revenue` (and `revenue_usd`) is a floor: the company said only that revenue passed that amount ('over $50M', 'surpassed $300M ARR'), shown in the web app as $50M+. Report it as 'at least $X'. False when the figure is exact. Null when `revenue` is null."},"revenue_annual_is_floor":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Revenue Annual Is Floor","description":"True when `revenue_annual` is a floor: the company said only that its fiscal-year revenue passed that amount. It can differ from `revenue_is_floor`, as when an exact ARR headline sits next to an 'over $X' fiscal year. False when the figure is exact. Null when `revenue_annual` is null."},"revenue_annual":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Revenue Annual","description":"Revenue for the latest full fiscal year, in whole units of `revenue_currency`. Null when `revenue_annual_status` is 'hidden'."},"revenue_annual_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Annual Status","description":"'current', 'stale' or 'hidden' for `revenue_annual`, by the age of `revenue_fiscal_year_end`, with the thresholds of `revenue_status`. An acquisition doesn't change it. When it is 'hidden', `revenue_annual`, `revenue_fiscal_year` and `revenue_fiscal_year_end` are null."},"revenue_fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Revenue Fiscal Year","description":"Fiscal year of `revenue_annual`."},"revenue_fiscal_year_end":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Revenue Fiscal Year End","description":"End date of the fiscal year in `revenue_annual`."},"revenue_quarter":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Revenue Quarter","description":"Revenue for the latest reported quarter, in whole units of `revenue_currency`. Null when `revenue_quarter_status` is 'hidden'."},"revenue_quarter_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Quarter Status","description":"'current', 'stale' or 'hidden' for `revenue_quarter`, by the age of `revenue_quarter_end`, with the thresholds of `revenue_status`. When it is 'hidden', the `revenue_quarter` fields are null."},"revenue_quarter_fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Revenue Quarter Fiscal Year","description":"Fiscal year of `revenue_quarter`."},"revenue_quarter_fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Quarter Fiscal Period","description":"Fiscal quarter of `revenue_quarter`, e.g. 'Q3'."},"revenue_quarter_end":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Revenue Quarter End","description":"End date of the quarter in `revenue_quarter`."},"revenue_growth_yoy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revenue Growth Yoy","description":"Year-over-year revenue growth as a fraction (0.12 = 12%). Compares the latest quarter with the same quarter a year earlier, or the latest fiscal year with the one before when no newer quarter exists. Null when `revenue` is null and when there is no earlier figure from the same source under the same definition of revenue."},"revenue_annual_source":{"anyOf":[{"$ref":"#/components/schemas/RevenueSourceFiling"},{"type":"null"}],"description":"The document `revenue_annual` comes from, with its link (and, for a figure the company stated publicly, the sentence it was read from in `quote`). Null when `revenue_annual` is null or `revenue_annual_status` is 'hidden'."},"revenue_quarter_source":{"anyOf":[{"$ref":"#/components/schemas/RevenueSourceFiling"},{"type":"null"}],"description":"The filing `revenue_quarter` comes from, with its link. Null when `revenue_quarter` is null or `revenue_quarter_status` is 'hidden'."},"revenue_growth_sources":{"anyOf":[{"items":{"$ref":"#/components/schemas/RevenueSourceFiling"},"type":"array"},{"type":"null"}],"title":"Revenue Growth Sources","description":"The documents `revenue_growth_yoy` compares, with links: the current and prior figures, or the sentence where the company stated its growth (`quote`, `stated_growth`). Cite them when reporting growth. Null when `revenue_growth_yoy` is null and when `revenue_status` is 'hidden' or 'acquired'."},"revenue_attribution":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Attribution","description":"The licence attribution the source of the reported figures asks for wherever they are shown, such as the Open Government Licence line for UK Companies House accounts. Show it next to any reported revenue figure you pass on. Null for a source that asks for none."},"revenue_acquired_by_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Revenue Acquired By Id","description":"Sumble organization id of the acquirer in the newest acquisition Sumble knows of for this company. Set whatever `revenue_status` is: a company that kept filing after the deal keeps its figure."},"revenue_acquired_by_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Acquired By Name","description":"Name of the acquirer in `revenue_acquired_by_id`."},"revenue_acquired_on":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Revenue Acquired On","description":"Announcement date of the acquisition in `revenue_acquired_by_id` (ISO YYYY-MM-DD)."},"revenue_estimate_usd":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Revenue Estimate Usd","description":"Sumble's revenue estimate in whole US dollars per year. A reported figure where one passed review (company registers, annual reports, charity returns, regulators, SEC filings, the org's own statements), converted at its fiscal year's average exchange rate; otherwise a model of revenue per employee times Sumble's estimate of total employees. `revenue_estimate_basis` says which. Returned only where the reported `revenue` is missing or weak: null when `revenue_status` is 'current', or 'stale' with a basis other than 'derived' (a 'derived' estimate carries the stale figure forward by headcount growth, so both come back). Also null when `revenue_status` is 'acquired' (its revenue is part of the acquirer's) and for general government bodies without a reported figure."},"revenue_estimate_basis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Estimate Basis","description":"Where `revenue_estimate_usd` comes from: 'reported' (a figure the org or a regulator reported), 'derived' (computed from reported figures, such as an older reported figure carried forward by headcount growth), 'adjusted' (the model, moved by a reported floor, ceiling or subsidiary figure) or 'model' (the model alone)."},"revenue_estimate_basis_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Estimate Basis Note","description":"One line on the figures behind `revenue_estimate_usd`, for display. When the reported figure behind a 'reported' or 'derived' estimate is a floor, it says 'at least' before the figure, and a 'derived' estimate built on a floor says it may be low."},"revenue_estimate_low":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Revenue Estimate Low","description":"Low end of the model's 80% range in whole US dollars (10th percentile). The range is the model's, so with a 'reported' or 'derived' basis it can sit away from `revenue_estimate_usd`. Null when the model gives no range."},"revenue_estimate_high":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Revenue Estimate High","description":"High end of the model's 80% range in whole US dollars (90th percentile). Null when the model gives no range."},"revenue_estimate_as_of":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Revenue Estimate As Of","description":"Date `revenue_estimate_usd` describes (ISO YYYY-MM-DD): for a 'reported' basis, the end of the reported figure's period; for 'derived', the date the figure was carried forward to. Null when the basis is 'model' or 'adjusted'."},"revenue_estimate_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Estimate Source","description":"Source of the figure behind `revenue_estimate_usd`, such as 'uk_companies_house_accounts'. Null when the basis is 'model' or 'adjusted'. New sources may be added."},"revenue_estimate_source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Estimate Source Url","description":"Link to the source of the figure behind `revenue_estimate_usd`. Null when the basis is 'model' or 'adjusted', and for some sources without a lasting link."},"cloud_spend_estimate_millions_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cloud Spend Estimate Millions Usd"},"ai_token_spend_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ai Token Spend Usd"}},"type":"object","title":"Attributes"},"RevenueSourceFiling":{"properties":{"role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Role","description":"What the figure is used for. In `revenue_sources`: 'fiscal_year', 'year_to_date', 'prior_year_to_date', 'quarter', or 'statement' for an ARR or run rate the company stated publicly. In `revenue_growth_sources`: 'current' and 'prior' for the two figures compared, or 'stated' for a growth rate the company stated."},"period_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Type","description":"'annual', 'quarterly', 'ytd' (year to date), or 'arr' for an ARR or run rate the company stated publicly."},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year"},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period","description":"Fiscal period label, such as 'FY' or 'Q3'. A label ending in '+' ('FY+', 'ARR+', 'RR+') marks a floor: revenue was at least this `revenue`."},"period_start":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Period Start"},"period_end":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Period End"},"revenue":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Revenue","description":"Revenue for the period, in whole units of `revenue_currency`."},"document_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Type","description":"Kind of filing, such as the SEC form ('10-K', '10-Q', '10-K/A'), 'ESEF' for a European annual report or '990' for a US nonprofit's return."},"filed_on":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Filed On","description":"Date the filing was published. Null for most ESEF reports."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Link to the document. Cite it when reporting the figure."},"quote":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quote","description":"For a figure the company stated publicly (`revenue_source` 'searched_revenue'), the sentence it was read from at `url`. Quote it as the proof when citing the figure. Null for a filing."},"stated_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Stated Growth","description":"The growth rate `quote` states, as a fraction (0.12 = 12%). Null when the sentence states none."}},"type":"object","title":"RevenueSourceFiling","description":"One document a revenue figure or growth rate comes from: a filing, a\nregister entry, or the page where the company stated the figure publicly."},"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"},"ApiFileResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Opaque file identifier."},"filename":{"type":"string","title":"Filename","description":"Filename shown to the user."},"media_type":{"type":"string","title":"Media Type","description":"IANA media type."},"kind":{"type":"string","enum":["organization_list","contact_list","job_title_lookup","sql_query","signal_search","priority_signal_search","signal_config_list","project_lookup","technology_search","technology_lookup","technology_category_lookup","organization_lists","contact_lists","organization_tech_stack","people","jobs","organizations"],"title":"Kind","description":"The kind of data contained in the file."},"row_count":{"type":"integer","title":"Row Count","description":"Number of records in the file: rows in a .csv or .xlsx, top-level objects in a .json."},"columns":{"items":{"type":"string"},"type":"array","title":"Columns","description":"Column names in file order for a .csv or .xlsx; the top-level keys of the objects in a .json."},"size_bytes":{"type":"integer","title":"Size Bytes","description":"File size in bytes."},"download_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Download Url","description":"Authenticated Sumble URL where the user can download the file."}},"type":"object","required":["id","filename","media_type","kind","row_count","columns","size_bytes","download_url"],"title":"ApiFileResponse","description":"Metadata for a file created by the API for the user."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/organizations":{"post":{"tags":["organizations"],"summary":"Unified organizations endpoint","operationId":"enrich_organizations_unified__api_version__organizations_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichOrganizationsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichOrganizationsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Closed organizations

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

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

## Tags

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

## CVM revenue licensing

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