---
title: "Change a team's help desk settings"
method: PUT
path: "/products/help-desk/teams/{team_id}"
tags: ["help-desk"]
---

# Change a team's help desk settings

`PUT /products/help-desk/teams/{team_id}`

## Request

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

Set the team's alias and assignment mode. A team back on both defaults keeps no settings. Org admins only, from their own session; the organization must hold the help desk.

## Path parameters

- `team_id` string, required

## Request body

- HelpDeskTeamChange
  - `alias` string, nullable: 1 to 31 lowercase letters, digits and single hyphens, starting with a letter, and neither a reserved mailbox name nor one that reads as SparkVault; unique at the desk. Null returns the team to the default alias.
  - `assignment_mode` 'claim' | 'balanced'

## Response `200`

The team's settings as stored.

- object
  - `data` object, required
    - `team_id` string, required
    - `alias` string, required
    - `assignment_mode` 'claim' | 'balanced', required
  - `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 — the alias or the assignment mode is malformed, or the body names another field.
- `401`: AUTHENTICATION_ERROR — missing or invalid credentials.
- `403`: FORBIDDEN — the caller is not an org admin, or the credential is an API key or an impersonated session. HELP_DESK_SUBSCRIPTION_REQUIRED — the organization does not hold the help desk.
- `404`: NOT_FOUND — no such team in the organization.
- `409`: ALIAS_TAKEN — another team of the desk uses that alias. CONFLICT — the team's settings changed meanwhile; try again.

## Changes

- **2026-10-28** `a9a10e328ba5`: 20 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`
  - …16 more
- **2026-10-28** `56d7c265a77a`: 5 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`
  - …1 more
- **2026-10-22** `f5ac9c809ef7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sparkvault/apis/sparkvault-api/changes/products/help-desk/teams/:team_id/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)