---
title: "Save the routing rules"
method: PUT
path: "/products/help-desk/routing-rules"
tags: ["help-desk"]
---

# Save the routing rules

`PUT /products/help-desk/routing-rules`

## Request

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

Save the whole ordered list against the `version` the admin loaded: a rule without `rule_id` is new, and a saved rule missing from the list is removed. At most 100 rules; one save adds, changes or removes at most 99. Rules run once, when a request is created, and the first enabled rule that matches wins. Org admins only, from their own session; the organization must hold the help desk.

## Request body

- object
  - `rules` HelpDeskRoutingRuleInput[], required
    - `rule_id` string, nullable: The rule this is; absent or null for a new rule.
    - `name` string, required
    - `enabled` boolean
    - `match` 'all' | 'any', required
    - `domains` string[]
    - `include_subdomains` boolean
    - `keywords` string[]
    - `actions` HelpDeskRoutingActions, required: What a matching rule does to a new request; at least one.
      - `team_id` string: The team the request goes to.
      - `add_tags` string[]: Tags the request gets, stored in lowercase.
      - `set_priority` 'urgent' | 'high' | 'normal' | 'low'
  - `version` integer, required: The `version` the list was loaded at; 0 before the first save.

## Response `200`

The rules as saved.

- object
  - `data` HelpDeskRoutingRules, required
    - `version` integer, required: The version a save is made against; 0 before the first save.
    - `rules` HelpDeskRoutingRule[], required: In order: the first enabled rule that matches wins.
      - `rule_id` string, required
      - `name` string, required
      - `enabled` boolean, required
      - `match` 'all' | 'any', required
      - `domains` string[], required
      - `include_subdomains` boolean, required
      - `keywords` string[], required
      - `actions` HelpDeskRoutingActions, required: What a matching rule does to a new request; at least one.
        - `team_id` string: The team the request goes to.
        - `add_tags` string[]: Tags the request gets, stored in lowercase.
        - `set_priority` 'urgent' | 'high' | 'normal' | 'low'
    - `shadowed_rule_ids` string[], required: Enabled rules an earlier enabled rule always wins over, so they never match.
  - `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 — a rule is malformed (`details.rule` is its position), names a team that is not the organization's, appears twice, or names a `rule_id` the desk does not hold; or the save changes more than 99 rules.
- `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.
- `409`: CONFLICT — the rules changed since they were loaded; reload them and try again.

## Changes

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

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