---
title: "Replace a tenant specialty's data in full"
method: PUT
path: "/tenant-specialties/{id}"
tags: ["Tenant Specialty"]
---

# Replace a tenant specialty's data in full

`PUT /tenant-specialties/{id}`

Replaces the stored data for an existing tenant specialty. This is a full-replacement operation — fields not included in the request body are cleared, not preserved.

**What it does:** Overwrites the tenant specialty identified by `{id}` with the supplied payload. The data layer performs a replace, not a merge, so callers must supply all fields they wish to retain.

**When to use:** Use this to update any attribute of a tenant specialty after it has been created.

**How to call it:** Supply the required `tenant-id` header and the tenant specialty `id` as a path segment (an opaque, server-assigned string). The request body is validated against the `TenantSpecialty` JSON Schema on the `data` field; validation failures return 400. The same request schema is used as for `POST`. Requires the `UPDATE_TENANT_SPECIALTY` permission. Returns 404 if no specialty with the given `id` exists for the supplied `tenant-id` — the record is looked up before any write is attempted.

**What you get back:** On success (200) the full updated tenant specialty object is returned. This operation is idempotent — sending the same payload twice produces the same state.

## Path parameters

- `id` string, required

## Headers

- `tenant-id` string, required

## Request body

- CreateTenantSpecialtyRequest
  - `specialtyId` string, required — Identifier of the global specialty this tenant specialty is based on. Required and must reference an existing global specialty; a missing or blank value is rejected with 400 before any other validation runs.
  - `data` TenantSpecialtySchema — Represents a specialty associated with a tenant.
    - `displayName` string, required — Display name for the specialty.
    - `description` string — Detailed description of the specialty.
    - `changeReason` string — Reason for any change to the specialty.

## Response `200`

The full tenant specialty object after replacement.

- object
  - `id` string
  - `tenantId` string
  - `specialtyId` string
  - `data` TenantSpecialtySchema — Represents a specialty associated with a tenant.
    - `displayName` string, required — Display name for the specialty.
    - `description` string — Detailed description of the specialty.
    - `changeReason` string — Reason for any change to the specialty.

## Other responses

- `400` — Missing `tenant-id` header, or `data` failing TenantSpecialty JSON Schema validation.
- `401` — Unauthorized - the request is missing a valid JWT.
- `403` — Forbidden - the caller lacks the UPDATE_TENANT_SPECIALTY permission for this tenant.
- `404` — No tenant specialty exists with the given `id` for the supplied `tenant-id`.
- `500` — Internal Server Error - an unexpected error occurred while replacing the record.

---

[API](https://skmtc.net/certifyos/apis/certify-api-layer.md) · [All operations](https://skmtc.net/certifyos/apis/certify-api-layer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/certifyos/certify-api-layer/revisions/563848e0ecc0/schema)