--- title: "Change the help desk settings" method: PUT path: "/products/help-desk/settings" tags: ["help-desk"] --- # Change the help desk settings `PUT /products/help-desk/settings` ## Request - Base URL: `https://api.sparkvault.com/v1` - URL: `https://api.sparkvault.com/v1/products/help-desk/settings` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Change the settings `patch` names, against the `version` the admin loaded: a save made after another one landed is refused and writes nothing. A patch that changes nothing answers the settings as they stand. Changing `customer_auth_preference` ends every customer session started before it. Selecting `custom_domain` needs the desk active and the domain prepared (POST /domains/{domain}/help-desk: its ownership verified, a subdomain, sending and web ready); null clears it. Each change to a domain spends one of the organization's 10 sending-domain selections an hour, shared with Notify's `email.sending_domain`. Org admins only, from their own session; the organization must hold the help desk. ## Request body - HelpDeskSettingsChange - `patch` object, required: The settings to change, any of them. `operator_display` and `branding` merge into what they hold. A field sent with the value it holds changes nothing. - `customer_auth_preference` 'identity' | 'email_pin' - `operator_display` object - `name_format` 'first_last_initial' | 'full_name' | 'generic' - `avatar_mode` 'authsv' | 'generic' - `generic_label` string - `status_after_reply` 'waiting_on_customer' | 'open' - `auto_assign_on_first_reply` boolean - `customer_can_mark_resolved` boolean - `feedback_positive_url` string, uri, nullable: An absolute HTTPS URL without credentials, or null to remove the follow-up link. - `feedback_negative_url` string, uri, nullable: An absolute HTTPS URL without credentials, or null to remove the follow-up link. - `email_content_mode` 'full' | 'notify_only' - `accept_email_replies` boolean - `custom_domain` string, nullable: One of the organization's domains prepared for the help desk (POST /domains/{domain}/help-desk), or null for none. - `customer_upload_limit_bytes` integer, nullable - `branding` object - `color` string, nullable: A color as #rrggbb, or null for the default. - `version` integer, required: The `version` of the settings the change was made against. ## Response `200` The settings as written. - object - `data` HelpDeskSettings, required: A help desk's settings, as its settings page reads them. - `vault_id` string, nullable, required: The vault the desk's requests are sealed in. - `activated_at` integer, nullable, required: Unix seconds: the last activation. Null while the first one has not finished. - `deactivated_at` integer, nullable, required: Unix seconds: the deactivation since the last activation. Null while the desk is active. - `customer_auth_preference` 'identity' | 'email_pin', required: How the desk asks its customers to sign in: identity (Secure Identity) or email_pin (a code mailed to them). GET /products/help-desk/settings/status says how they sign in now. - `operator_display` HelpDeskOperatorDisplay, required: How the desk shows its operators to customers. - `name_format` 'first_last_initial' | 'full_name' | 'generic', required: first_last_initial: the first name and last initial each operator sets (prefilled from their name); full_name: the member's name; generic: `generic_label` for everyone. An operator with no name to show shows `generic_label`. - `avatar_mode` 'authsv' | 'generic', required: authsv: each operator's Secure Identity avatar; generic: one silhouette for everyone. - `generic_label` string, required: The name shown where no operator's name is. - `status_after_reply` 'waiting_on_customer' | 'open', required: The status an operator's public reply moves a request to. - `auto_assign_on_first_reply` boolean, required: Whether the first operator to reply on an unassigned request is assigned it. - `customer_can_mark_resolved` boolean, required: Whether customers may close their own requests as resolved. - `feedback_positive_url` string, uri, nullable, required: Optional HTTPS follow-up link shown after a customer saves positive feedback. Null keeps the customer in the help desk. - `feedback_negative_url` string, uri, nullable, required: Optional HTTPS follow-up link shown after a customer saves negative feedback. No ticket or customer data is appended. - `email_content_mode` 'full' | 'notify_only', required: full: update emails carry the message; notify_only: they say only that the request changed, and link to it. - `accept_email_replies` boolean, required: Whether customers may answer by replying to an update email. - `custom_domain` string, nullable, required: The organization's own domain the desk answers at, beside its help.sv address; null for none. - `customer_upload_limit_bytes` integer, nullable, required: Maximum total pending and attached upload bytes per customer across all requests. Null (the default) leaves customer usage unlimited within the account storage plan. - `branding` object, required - `color` string, nullable, required: The portal's accent color, as #rrggbb; null for the default. - `version` integer, required: The version a change is made against (PUT /products/help-desk/settings). - `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 — `version` or a field of `patch` is malformed, or `patch` names a field the settings do not have (`details.unknown`). - `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 — `custom_domain` is not one of the organization's own domains. - `409`: CONFLICT — the settings changed since they were loaded; reload them and try again. HELP_DESK_NOT_ACTIVE — the desk was never activated, or a custom domain was selected while it is not active. DOMAIN_NOT_READY — `custom_domain` is not prepared for the help desk yet (`details.domain`, `details.product` help_desk). - `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`. RATE_LIMIT_EXCEEDED is also the answer once the organization has made its 10 sending-domain selections this hour; `Retry-After` carries the seconds until the budget reopens. - `503`: EMAIL_SETUP_BUSY — another request is setting up the organization's email (`Retry-After` carries 5 seconds), or email setup is busy right now; repeat the request in a moment. INTERNAL_ERROR — this deployment cannot send the help desk's email. ## Changes - **2026-10-28** `a9a10e328ba5`: 28 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` - …24 more - **2026-10-28** `56d7c265a77a`: 6 breaking, 1 info - 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` - …3 more - **2026-10-27** `ac44ec1f8cfa`: 1 breaking, 1 warning, 6 info - removed the required property `data/customer_storage_cap_bytes` from the response with the `200` status - removed the request property `patch/customer_storage_cap_bytes` - added the new optional request property `patch/customer_upload_limit_bytes` - added the new optional request property `patch/feedback_negative_url` - …4 more - **2026-10-22** `f5ac9c809ef7`: 1 info - endpoint added [Operation history](https://skmtc.dev/sparkvault/apis/sparkvault-api/changes/products/help-desk/settings/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)