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

### 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","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, 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)."}},"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"},"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":{"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"}},"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"},"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"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sumble.com/api/core-data/organizations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.