Teams

Find and enrich teams

The single endpoint for working with teams — the groups Sumble extracts from an organization's job postings (for example "Platform Engineering" or "Data Science") and organizes into a per-organization hierarchy. Provide either a list of team IDs to resolve (list mode) or an organization-scoped filter (search mode), and compose exactly which attributes you get back per team.

Input

Provide exactly one of:

• teams — a list of up to 1,000 teams to resolve, each identified by its Sumble team_id (for example the team_ids returned on the extracted teams of the job posts endpoint). Returns one row per entry, in input order.

• filter — the teams to return: one or more organization_ids (up to 1,000), optionally narrowed by an advanced query (technologies, technology categories, job functions, hiring period) and a since date. Teams are returned for the listed organizations only — there is no parent/subsidiary roll-up, so pass subsidiary organization IDs explicitly to include their teams.

In filter mode, limit (default 10, max 200) and offset page through results, and order_by_column sorts by jobs_count, first_activity, last_activity, or score (default jobs_count, descending). Sorting by score requires exactly one organization in scope and an ICP configured for your account. since windows the activity-based metrics (jobs_count, first_activity, last_activity) to postings on or after that date; the aggregated lists below remain all-time. List mode returns teams in input order.

Composable response

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

• attributes — a list of team attributes, or "all". Available: organization, breadcrumbs (the team's parent chain), jobs_count, technology_list, job_function_list, location_list, first_activity, last_activity, and score. team_id, name, and sumble_url are always included for free.

  • score is your ICP match score (0–100) for the team — a Great / Good / Possible fit bucket with its per-feature contribution breakdown. Like the people endpoint's person_score, it requires filter mode with exactly one organization in scope and an ICP configured; "all" includes it opportunistically when those requirements are met.

• related_people — the people associated with each team, each with a person–team confidence breakdown. Choose which person attributes to return (the same attributes as the people endpoint, excluding the contact details email/phone) and a per-team cap max_per_team (default 10, max 100). Available in both modes, for up to 25 teams per request.

• job_posts — the job postings mentioning each team. Choose which components to return — job_details, technologies, job_functions, job_level, or "all" — a per-team cap max_per_team (default 10, max 100), and an optional since window. Full description text is not available here; fetch it from the job posts endpoint using the returned job_ids.

Results are always a flat list; breadcrumbs gives each team's parent chain (for example Engineering → Platform → SRE). A team's job metrics count postings that mention it directly or via a child team, so one posting can count toward several teams.

Credit cost

Charged per matched team (list mode) or per returned team (search mode). Unmatched inputs are free.

Per team the cost is:

• 1 base credit, plus:

• 1 credit per paid attribute requested (score counts as one paid attribute), plus

• 1 credit per related person returned, plus

• 1 credit per job post returned.

For example, returning 10 teams with 3 paid attributes and 5 related people each costs 10 × (1 + 3 + 5) = 90 credits. The API checks affordability up front and returns HTTP 402 before doing any work you can't pay for.

Unified teams endpoint

post

Authorizations

api_token

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

teamsinteger[] · min: 1 · max: 1000 · nullableOptional

List of Sumble team ids to retrieve and enrich. One result row per entry, in input order. Mutually exclusive with filter.

limitinteger · min: 1 · max: 200Optional

Maximum number of teams to return (filter mode only; ignored when teams is provided).

Default: 10

offsetinteger · max: 10000Optional

Number of results to skip (filter mode only; ignored when teams is provided).

Default: 0

order_by_columnstring · enum · nullableOptional

Column to order by (filter mode only): jobs_count, first_activity or last_activity. Default: jobs_count.

Possible values:

order_by_directionstring · enum · nullableOptional

Sort direction; DESC when omitted.

Possible values:

Responses

200

Successful Response

application/json

idstring · uuidRequired

credits_usedintegerRequired

credits_remainingintegerRequired

matched_countinteger · nullableOptional

List mode only: how many input ids matched a Sumble team.

totalintegerRequired

source_data_urlstring · uri · min: 1 · max: 2083 · nullableOptional

422

Validation Error

application/json

post/v9/teams

HTTPcURLJavaScriptPython

POST /v9/teams HTTP/1.1
Host: api.sumble.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 343

{
  "teams": [
    1
  ],
  "filter": {
    "organization_ids": [
      1
    ],
    "query": {
      "query": "text"
    },
    "since": "text"
  },
  "select": {
    "attributes": [
      "organization"
    ],
    "related_people": {
      "attributes": [
        "name"
      ],
      "max_per_team": 10
    },
    "job_posts": {
      "components": [
        "job_details"
      ],
      "max_per_team": 10,
      "since": "text"
    }
  },
  "limit": 10,
  "offset": 0,
  "order_by_column": "jobs_count",
  "order_by_direction": "ASC"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "credits_used": 1,
  "credits_remaining": 1,
  "teams": [
    {
      "input": 1,
      "team_id": 1,
      "name": "text",
      "sumble_url": "https://example.com",
      "attributes": {
        "organization": {
          "organization_id": 1,
          "name": "text",
          "sumble_url": "https://example.com"
        },
        "breadcrumbs": [
          {
            "team_id": 1,
            "name": "text",
            "slug": "text",
            "sumble_url": "https://example.com"
          }
        ],
        "jobs_count": 1,
        "technology_list": [
          {
            "name": "text",
            "slug": "text",
            "used": false,
            "jobs_count": 1
          }
        ],
        "job_function_list": [
          {
            "name": "text",
            "slug": "text",
            "jobs_count": 1
          }
        ],
        "location_list": [
          {
            "name": "text",
            "jobs_count": 1
          }
        ],
        "first_activity": "2026-07-16T02:29:08.749Z",
        "last_activity": "2026-07-16T02:29:08.749Z",
        "score": {
          "value": 1,
          "fit": "text",
          "components": [
            {
              "name": "text",
              "slug": "text",
              "match_type": "text",
              "contribution": 1
            }
          ]
        }
      },
      "related_people": [
        {
          "person_id": 1,
          "sumble_url": "https://example.com",
          "confidence": {
            "score": 1,
            "matched_features": [
              {
                "match_type": "team",
                "name": "text",
                "slug": "text",
                "is_parent": false,
                "score": 1
              }
            ]
          },
          "attributes": {
            "name": "text",
            "email": "text",
            "phone": "text",
            "linkedin_url": "https://example.com",
            "job_title": "text",
            "job_function": "text",
            "job_level": "text",
            "location": "text",
            "country": "text",
            "current_employer": {
              "organization_id": 1,
              "name": "text",
              "start_date": "text",
              "sumble_url": "https://example.com"
            },
            "technologies": [
              {
                "name": "text",
                "slug": "text"
              }
            ],
            "person_score": {
              "value": 1,
              "skill_contribution": 1,
              "job_function_contribution": 1,
              "seniority_contribution": 1,
              "matched_features": [
                {
                  "name": "text",
                  "slug": "text",
                  "match_type": "technology",
                  "contribution": 1
                }
              ]
            }
          }
        }
      ],
      "job_posts": [
        {
          "job_id": 1,
          "sumble_url": "https://example.com",
          "attributes": {
            "title": "text",
            "description": "text",
            "location": "text",
            "posted_date": "2026-07-16T02:29:08.749Z",
            "organization": {
              "organization_id": 1,
              "name": "text",
              "domain": "text",
              "sumble_url": "https://example.com"
            },
            "technologies": [
              {
                "name": "text",
                "slug": "text",
                "used": true,
                "sumble_url": "https://example.com"
              }
            ],
            "teams": [
              {
                "team_id": 1,
                "name": "text",
                "slug": "text",
                "sumble_url": "https://example.com"
              }
            ],
            "job_functions": [
              {
                "name": "text",
                "slug": "text",
                "sumble_url": "https://example.com"
              }
            ],
            "job_levels": [
              {
                "name": "text"
              }
            ],
            "projects": [
              {
                "name": "text",
                "slug": "text",
                "goal": "text",
                "sumble_url": "https://example.com"
              }
            ]
          }
        }
      ]
    }
  ],
  "matched_count": 1,
  "total": 1,
  "source_data_url": "https://example.com"
}