---
title: "Unified teams endpoint"
method: POST
path: "/v9/teams"
tags: ["teams"]
---

# Unified teams endpoint

`POST /v9/teams`

## Request body

- FindTeamsRequest
  - `teams` integer[], nullable — List of Sumble team ids to retrieve and enrich. One result row per entry, in input order. Mutually exclusive with `filter`.
  - `filter` TeamsFilter
    - `organization_ids` integer[], required — Sumble organization ids to search within. Teams are returned for these organizations only — no parent/subsidiary roll-up. Unknown ids simply match no teams.
    - `query` Query
      - `query` string, required
    - `since` string, nullable — Only count activity (jobs_count, first/last activity) on or after this date (YYYY-MM-DD). Does not affect the aggregated technology / job-function / location lists, which are all-time.
  - `select` TeamsSelect, required
    - `attributes` union — Team attributes to include, or 'all' for every available attribute. Off by default. 'all' includes `score` only when it is available (an ICP configured for your account) — otherwise it is skipped, not an error. Note that 'all' grows — and its cost grows — as new attributes are added to the endpoint.
      - string[]
      - 'all'
    - `related_people` TeamRelatedPeopleSelection
      - `attributes` union — Person-level attributes to include for each related person, or 'all' for every attribute available here. Contact attributes (email, phone) and `person_score` are not available here; `confidence` (the person-team match score breakdown) is only available here.
        - string[]
        - 'all'
      - `max_per_team` integer — Maximum related people returned per team.
    - `job_posts` JobPostsSelection
      - `components` union — Job components to return per posting, or 'all' for every available component. Mirrors the unified jobs endpoint: `job_details` (title, location, posted date), `technologies`, `job_functions`, `job_level`. Never includes the full description (fetch that from the jobs endpoint with the returned job ids).
        - string[]
        - 'all'
      - `max_per_team` integer — Maximum job postings returned per team.
      - `since` string, nullable — Only return job postings pulled on or after this date (YYYY-MM-DD).
  - `limit` integer — Maximum number of teams to return (filter mode only; ignored when `teams` is provided).
  - `offset` integer — Number of results to skip (filter mode only; ignored when `teams` is provided).
  - `order_by_column` 'jobs_count' | 'first_activity' | 'last_activity' | 'score', nullable — Column to order by (filter mode only): `jobs_count`, `first_activity` or `last_activity`. Default: jobs_count.
  - `order_by_direction` 'ASC' | 'DESC', nullable — Sort direction; DESC when omitted.

## Response `200`

Successful Response

- FindTeamsResponse
  - `id` string, uuid, required
  - `credits_used` integer, required
  - `credits_remaining` integer, required
  - `teams` TeamResultRow[], required
    - `input` integer, nullable — The input team id this row corresponds to (list mode only).
    - `team_id` integer, nullable — Absent when the input id didn't match a Sumble team.
    - `name` string, nullable
    - `sumble_url` string, uri, nullable — Link to the team's Sumble page.
    - `attributes` TeamAttributes
      - `organization` TeamOrganization
        - `organization_id` integer, required
        - `name` string, nullable
        - `sumble_url` string, uri, nullable — Link to the organization's Sumble profile page.
      - `breadcrumbs` TeamBreadcrumb[], nullable — Parent-team chain from the root to this team.
        - `team_id` integer, nullable
        - `name` string, required
        - `slug` string, nullable
        - `sumble_url` string, uri, nullable — Link to the ancestor team's Sumble page.
      - `jobs_count` integer, nullable
      - `technology_list` TeamTechnology[], nullable — Technologies the team uses, aggregated from its job postings (all-time).
        - `name` string, required
        - `slug` string, required
        - `used` boolean — True when the team's postings indicate the technology is used, not merely mentioned.
        - `jobs_count` integer, nullable — Job postings mentioning this technology for the team.
      - `job_function_list` TeamJobFunction[], nullable — Job functions the team hires for, aggregated from its job postings (all-time).
        - `name` string, required
        - `slug` string, required
        - `jobs_count` integer, nullable — Job postings hiring for this job function for the team.
      - `location_list` TeamLocation[], nullable — Locations where the team operates, derived from its job postings (all-time).
        - `name` string, required
        - `jobs_count` integer, nullable — Job postings for the team in this location.
      - `first_activity` string, date-time, nullable — Earliest job posting mentioning the team.
      - `last_activity` string, date-time, nullable — Latest job posting mentioning the team.
      - `score` TeamScore
        - `value` number, required — How well the team matches your ideal customer profile (ICP), 0-100.
        - `fit` string, nullable — Qualitative fit bucket (e.g. 'Great', 'Good', 'Possible').
        - `components` TeamScoreComponent[] — The matched features behind the score, highest contribution first.
          - `name` string, nullable
          - `slug` string, nullable
          - `match_type` string, required
          - `contribution` number, required — Points of the 0-100 score attributable to this feature.
    - `related_people` TeamRelatedPersonRow[], nullable — People associated with the team. Present (possibly empty) when `select.related_people` is requested and the team matched; absent otherwise.
      - `person_id` integer, required
      - `sumble_url` string, uri, required — Link to the person's Sumble profile page.
      - `confidence` TeamMembershipConfidence
        - `score` number, required — How strongly this person relates to the team, based on shared team, job-function, technology, location and title-embedding signals. Unrelated to the ICP-based team `score` attribute.
        - `matched_features` TeamMembershipFeature[] — The specific matched features behind the score.
          - `match_type` 'team' | 'job_function' | 'technology' | 'location' | 'embedding', required
          - `name` string, nullable
          - `slug` string, nullable
          - `is_parent` boolean
          - `score` number, required — Share of the match score attributable to this feature.
      - `attributes` PersonAttributes
        - `name` string, nullable
        - `email` string, nullable — Revealed work email (match mode only). The first successful reveal per person costs 10 credits; repeat reveals while active are free.
        - `phone` string, nullable — Revealed phone number (match mode only). The first successful reveal per person costs 80 credits; repeat reveals while active are free.
        - `linkedin_url` string, uri, nullable
        - `job_title` string, nullable
        - `job_function` string, nullable
        - `job_level` string, nullable
        - `location` string, nullable
        - `country` string, nullable
        - `current_employer` CurrentEmployer
          - `organization_id` integer, required
          - `name` string, nullable
          - `start_date` string, nullable — Start of the person's current role (YYYY-MM).
          - `sumble_url` string, uri, nullable — Link to the organization's Sumble profile page.
        - `technologies` PersonTechnology[], nullable — Technologies from the skills on the person's LinkedIn profile, normalized to Sumble's technology catalog. The slug can be used in `filter.query` (technology EQ '<slug>'). Empty when none of the profile's skills map to a known technology.
          - `name` string, required
          - `slug` string, required
        - `person_score` PersonScore
          - `value` number, required — How well the person matches your ideal customer profile (ICP), 0-100. Sum of the three contributions below.
          - `skill_contribution` number, required — Points from technologies the person uses that match your ICP.
          - `job_function_contribution` number, required — Points from the person's job function matching your ICP.
          - `seniority_contribution` number, required — Points from the person's job level (seniority).
          - `matched_features` PersonScoreFeature[], required — The matched technologies and job functions behind the skill and job-function contributions, highest contribution first.
            - `name` string, required
            - `slug` string, required
            - `match_type` 'technology' | 'job_function', required
            - `contribution` number, required — Points of the 0-100 score attributable to this feature.
    - `job_posts` TeamJobPostRow[], nullable — Job postings mentioning the team. Present (possibly empty) when `select.job_posts` is requested and the team matched; absent otherwise.
      - `job_id` integer, required
      - `sumble_url` string, uri, nullable — Link to the job posting's Sumble page.
      - `attributes` JobAttributes
        - `title` string, nullable
        - `description` string, nullable
        - `location` string, nullable
        - `posted_date` string, date-time, nullable
        - `organization` JobOrganization
          - `organization_id` integer, required
          - `name` string, nullable
          - `domain` string, nullable
          - `sumble_url` string, uri, nullable — Link to the organization's Sumble profile page.
        - `technologies` JobTechnology[], nullable — All technologies extracted from the posting; empty list when requested but none were extracted.
          - `name` string, required
          - `slug` string, required
          - `used` boolean, required — True when the posting indicates the technology is used by the team, not merely mentioned.
          - `sumble_url` string, uri, nullable — The posting organization's jobs page filtered to this technology.
        - `teams` JobTeam[], nullable — Teams extracted from the posting; empty list when requested but none were extracted.
          - `team_id` integer, required
          - `name` string, required
          - `slug` string, required
          - `sumble_url` string, uri, nullable — Link to the team's Sumble page.
        - `job_functions` AppSchemasPaidApiJobsUnifiedJobFunction[], nullable — Job functions classified from the posting; empty list when requested but none were classified.
          - `name` string, required
          - `slug` string, required
          - `sumble_url` string, uri, nullable — The posting organization's jobs page filtered to this job function.
        - `job_levels` AppSchemasPaidApiJobsUnifiedJobLevel[], nullable — Seniority levels classified from the posting; empty list when requested but none were classified.
          - `name` string, required
        - `projects` JobProject[], nullable — Projects extracted from the posting; empty list when requested but none were extracted.
          - `name` string, required
          - `slug` string, required
          - `goal` string, nullable
          - `sumble_url` string, uri, nullable — The posting organization's jobs page filtered to this project.
  - `matched_count` integer, nullable — List mode only: how many input ids matched a Sumble team.
  - `total` integer, required
  - `source_data_url` string, uri, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/sumble/apis/sumble-api.md) · [All operations](https://skmtc.net/sumble/apis/sumble-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sumble/sumble-api/revisions/fbfd97abec00/schema)