--- title: "Read the help desk settings" method: GET path: "/products/help-desk/settings" tags: ["help-desk"] --- # Read the help desk settings `GET /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) The desk's settings, with the version a change is made against and the vault its requests are sealed in; null until the first activation. Any member, from their own session: an API key or an impersonated session is refused. An organization whose help desk subscription lapsed still reads them. ## Response `200` The settings; null until the desk's first activation. - 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 - `401`: AUTHENTICATION_ERROR — missing or invalid credentials. - `403`: FORBIDDEN — the credential is an API key or an impersonated session: the help desk is worked from a member's own session. HELP_DESK_SUBSCRIPTION_REQUIRED — a change that needs the help desk, on an organization that does not hold it. ## Changes - **2026-10-28** `a9a10e328ba5`: 8 info - 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 `meta` became required for the status `401` - the response property `meta` became required for the status `403` - …4 more - **2026-10-28** `56d7c265a77a`: 2 breaking - the response property `error/details` became nullable for the status `401` - the response property `error/details` became nullable for the status `403` - **2026-10-27** `ac44ec1f8cfa`: 1 breaking, 3 info - removed the required property `data/oneOf[#/components/schemas/HelpDeskSettings]/customer_storage_cap_bytes` from the response with the `200` status - added the required property `data/oneOf[#/components/schemas/HelpDeskSettings]/customer_upload_limit_bytes` to the response with the `200` status - added the required property `data/oneOf[#/components/schemas/HelpDeskSettings]/feedback_negative_url` to the response with the `200` status - added the required property `data/oneOf[#/components/schemas/HelpDeskSettings]/feedback_positive_url` to the response with the `200` status - **2026-10-22** `f5ac9c809ef7`: 1 info - endpoint added [Operation history](https://skmtc.dev/sparkvault/apis/sparkvault-api/changes/products/help-desk/settings/get.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)