---
title: "Put users in a team"
method: PUT
path: "/teams/{team_id}/members"
tags: ["teams"]
---

# Put users in a team

`PUT /teams/{team_id}/members`

## Request

- Base URL: `https://api.sparkvault.com/v1`
- URL: `https://api.sparkvault.com/v1/teams/{team_id}/members`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/sparkvault/apis/sparkvault-api/docs/teams/:team_id/members/put.ts> (a function with typed inputs; its response is checked against the schema)

Put up to 100 users in a team (org admins only), named by `user_ids`. A user is in one team at a time: a user in another team leaves it. Each user moves on their own, and the answer says what happened to each.

## Path parameters

- `team_id` string, required

## Response `200`

What the change did.

- object
  - `data` TeamMembersChanged, required: What a membership change did, user by user, and the team after it.
    - `team` Team, required: A team of the organization's users. A user is in at most one team.
      - `team_id` string, required: The team's id (`team_…`).
      - `name` string, required: Its name as given: one line, at most 60 characters, unique in the organization whatever its case.
      - `member_count` integer, required: How many users are in the team.
    - `added` string[]: PUT: the users put in the team, each leaving any team they were in.
    - `removed` string[]: DELETE: the users taken out of the team.
    - `unchanged` string[], required: The users already in the team (PUT), or not in it (DELETE).
    - `not_found` string[], required: Ids that name no user of the organization.
  - `meta` ResponseMeta: Envelope metadata present on every successful response.
    - `api_version` string
    - `request_id` string
    - `response_ms` integer
    - `timestamp` integer: Unix seconds.
    - `pools` object: Storage and bandwidth capacity snapshot for the account.
    - `billing` object
      - `past_due` boolean
    - `quota` object: This minute of the account request budget. Present on authenticated success responses that passed the throttle; absent otherwise.
      - `limit` integer
      - `used` integer
      - `remaining` integer
      - `resets_at` integer: Unix seconds.

## Other responses

- `400`: VALIDATION_ERROR — `user_ids` is not a list of 1 to 100 user ids.
- `401`: AUTHENTICATION_ERROR — missing or invalid credentials.
- `403`: FORBIDDEN — the caller is not an org admin, or the credential is not an interactive session.
- `404`: NOT_FOUND — the organization holds no such team.
- `409`: CONFLICT — other changes to a user or the team kept landing first. The users the answer would have listed before it stay moved; repeat the request.
- `429`: RATE_LIMIT_EXCEEDED — the account exceeded 5000 requests this minute. `Retry-After` carries the seconds to wait, and `details` carries limit/resets_at, plus `used` whenever the request was counted. A request refused because the limiter itself was unavailable reports no `used`.

## Changes

- **2026-10-28** `a9a10e328ba5`: 24 info
  - the response property `error/details` became required for the status `400`
  - the response property `error/details` became required for the status `401`
  - the response property `error/details` became required for the status `403`
  - the response property `error/details` became required for the status `404`
  - …20 more
- **2026-10-28** `56d7c265a77a`: 6 breaking
  - the response property `error/details` became nullable for the status `400`
  - the response property `error/details` became nullable for the status `401`
  - the response property `error/details` became nullable for the status `403`
  - the response property `error/details` became nullable for the status `404`
  - …2 more
- **2026-10-21** `9f5e902abd83`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sparkvault/apis/sparkvault-api/changes/teams/:team_id/members/put.md)

---

[API](https://skmtc.dev/sparkvault/apis/sparkvault-api.md) - [All operations](https://skmtc.dev/sparkvault/apis/sparkvault-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sparkvault/apis/sparkvault-api/revisions/97cfadccd0c0?raw)