---
title: "List tenant specialties matching a classification and category"
method: GET
path: "/tenant-specialties/by-classification"
tags: ["Tenant Specialty"]
---

# List tenant specialties matching a classification and category

`GET /tenant-specialties/by-classification`

Returns tenant specialties for the current tenant that belong to a given classification source and category within that source.

**What it does:** Filters the tenant's specialty list by a classification taxonomy. For example, a classification source of `nucc` combined with a category of `Individual` returns only specialties belonging to that NUCC grouping. Both parameters are required, free-text strings — they are not validated against an enum or fixed value set, either in this service or the data layer.

**Aggregating across sources:** Pass `classificationSource=ALL` to return specialties matching the given `category` across every classification source configured for the tenant. Results are not deduplicated: the same specialty can legitimately belong to more than one classification source, and each occurrence is returned. `ALL` is handled by the underlying data layer, not validated or special-cased here — any other free-text value is still passed through unchanged, as before.

**Sort order:** Results are always returned sorted by specialty display name, ascending (case-sensitive, data-layer-enforced). This ordering applies to every `classificationSource` value, including `ALL`, and cannot be overridden by the caller — there is no sort query parameter.

**When to use:** Use this endpoint when you need specialties scoped to a specific taxonomy rather than the full tenant specialty list. Use `GET /tenant-specialties` when you need all specialties regardless of classification.

**How to call it:** Supply the required `tenant-id` header plus both `classificationSource` and `category` query parameters. Omitting either returns 400. Requires the `READ_TENANT_SPECIALTY` permission.

**What you get back:** A list of matching tenant specialty objects, sorted by display name ascending (see above), each including its `classificationSource`, `specialtyCategory`, and `taxonomyCode`. Results are served from a cache with a 5-minute TTL that is not invalidated on writes — a specialty created, updated, or deleted (including changes that affect `ALL`'s aggregated set) may take up to 5 minutes to be reflected here.

## Query parameters

- `category` string, required
- `classificationSource` string, required

## Headers

- `tenant-id` string, required

## Response `200`

The tenant specialties matching the given classification source (or, for `classificationSource=ALL`, the union across all sources, not deduplicated) and category, sorted by display name ascending. May reflect data up to 5 minutes stale (see caching note above).

- GetTenantSpecialtiesResponse
  - `totalCount` integer — Total number of tenant specialty records matching the query, before pagination. Note the underlying list endpoints return at most a single fixed page of results, so this may exceed the number of items in `data`.
  - `data` TenantSpecialtySchema[] — The page of matching tenant specialty records.
    - `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, `classificationSource`, or `category`.
- `401` — Unauthorized - the request is missing a valid JWT.
- `403` — Forbidden - the caller lacks the READ_TENANT_SPECIALTY permission for this tenant.
- `500` — Internal Server Error - an unexpected error occurred while retrieving the list.

---

[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)