Certifyos Specialty API

openapi: 3.2.0
info:
  description: API for Certify application
  title: Certify API Layer Specialty API
  version: 1.0.0
servers:
- url: http://localhost:9000
  description: Local Development Server
- url: https://api-service.staging.certifyos.com
  description: Staging Server
- url: https://api-service.internal.certifyos.com
  description: Internal Server
- url: https://api-service.test.certifyos.com
  description: Test Server
- url: https://api-service.demo.certifyos.com
  description: Demo Server
- url: https://api-service.certifyos.com
  description: Production Server
tags:
- name: Specialty
  description: Endpoints for managing medical specialties.
paths:
  /specialties:
    get:
      summary: List medical specialties for a tenant
      description: 'Returns a page of medical specialty records (platform-defined specialties, not NUCC taxonomy entries) scoped to the calling tenant.


        **When to use:** Use this endpoint to populate specialty pickers or to browse available specialties. For a single specialty by ID use `GET /specialties/{id}`; for NUCC taxonomy lookups use `GET /specialties/nuccByTaxonomy/{taxonomyCode}`.


        **Preconditions:** Requires the `READ_SPECIALTY` permission. The `tenant-id` header must be supplied on every request.


        **Results:** Returns an object with a `totalCount` field and a `data` array of specialty objects. This endpoint currently returns a fixed first page of up to 10 records; `offset`/`limit` query parameters are not exposed. The `name` parameter is accepted but is not currently applied by the service — supplying a value has no effect on the results returned.'
      operationId: getSpecialties
      tags:
      - Specialty
      parameters:
      - description: Specialty name to filter by. Currently accepted but not applied by the service — has no effect on the returned results.
        example: Cardiology
        in: query
        name: name
        schema:
          type: string
      - name: tenant-id
        in: header
        schema:
          type: string
        required: true
      responses:
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - User does not have required permissions
        '500':
          description: Internal Server Error - An unexpected error occurred
        '200':
          description: A page of up to 10 specialty records for the tenant, with the total matching count.
          content:
            application/json:
              examples:
                getSpecialties:
                  value:
                    totalCount: 2
                    data:
                    - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                      data:
                        name: Cardiology
                        classificationSource: NUCC
                        specialtyCategory: Individual
                        taxonomyCode: 207RC0000X
                    - id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                      data:
                        name: Neurology
                        classificationSource: NUCC
                        specialtyCategory: Individual
                        taxonomyCode: 2084N0400X
              schema:
                $ref: '#/components/schemas/GetSpecialtiesResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
      security:
      - jwt: []
    post:
      summary: Create a new medical specialty record
      description: 'Creates a new medical specialty record for the tenant and returns the created object with server-assigned fields.


        **When to use:** Use this endpoint to add a new specialty to the tenant''s catalog. For NUCC taxonomy-specific entries use `POST /specialties/nucc` instead.


        **Preconditions:** Requires the `CREATE_SPECIALTY` permission. The `tenant-id` header must be supplied. The request body must include a `data` object that is validated against the Specialty JSON Schema before the record is stored — a validation failure returns 400. The body may optionally include `nuccSpecialtyId`, `abmsSpecialtyId`, and `hsdSpecialtyId` to associate the specialty with external taxonomy references; all three are optional and independent of one another.


        **Result:** On success returns 201 with the created specialty object, including the server-assigned `id` (a UUID-format string generated by the data layer). Not idempotent — repeat calls with the same payload create duplicate records. Errors: 400 is returned either for request-body JSON Schema validation failure or for a downstream data-layer error.'
      operationId: createSpecialty
      tags:
      - Specialty
      parameters:
      - name: tenant-id
        in: header
        schema:
          type: string
        required: true
      requestBody:
        content:
          application/json:
            examples:
              createSpecialty:
                value:
                  data:
                    name: Cardiology
                    classificationSource: NUCC
                    specialtyCategory: Individual
                    taxonomyCode: 207RC0000X
            schema:
              $ref: '#/components/schemas/CreateSpecialtyRequest'
        required: true
      responses:
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - User does not have required permissions
        '500':
          description: Internal Server Error - An unexpected error occurred
        '201':
          description: The specialty was created; the response body is the new record with its server-assigned ID.
          content:
            application/json:
              examples:
                createSpecialty:
                  value:
                    id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    data:
                      name: Cardiology
                      classificationSource: NUCC
                      specialtyCategory: Individual
                      taxonomyCode: 207RC0000X
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Server-assigned UUID-format specialty identifier.
                  data:
                    $ref: https://schemas.certifyos.com/entities/Specialty.schema.json
        '400':
          description: The request body failed Specialty JSON Schema validation, or a downstream data-layer error occurred.
          content:
            application/json:
              examples:
                createSpecialtyInvalid:
                  value:
                    errors:
                    - data.classificationSource is required
                    errorDetails:
                      field: data.classificationSource
                      message: is required
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
      security:
      - jwt: []
  /specialties/nucc:
    post:
      summary: Create a NUCC taxonomy specialty entry
      description: 'Creates a new NUCC (National Uniform Claim Committee) taxonomy specialty entry for the tenant. NUCC specialties represent standardized provider taxonomy codes used in claim and credentialing workflows, and are distinct from the general medical specialties managed via `POST /specialties`.


        **When to use:** Use this endpoint when you need to add a tenant-level NUCC taxonomy specialty record. For general (non-NUCC) specialties use `POST /specialties`.


        **Preconditions:** Requires the `CREATE_SPECIALTY` permission. The `tenant-id` header must be supplied. The request body contains only a `data` object, which is validated against the NuccSpecialty JSON Schema before storage — a schema violation returns 400. The `createdBy` and `updatedBy` audit fields are both automatically set to the authenticated user''s ID from the JWT at creation time; they are not accepted in the request body.


        **Result:** Returns 201 with the created NUCC specialty object, including the server-assigned `id` (a UUID-format string generated by the data layer). Not idempotent — repeat calls create duplicate entries. 400 is returned for either JSON Schema validation failure or a downstream data-layer error.'
      operationId: createNuccSpecialty
      tags:
      - Specialty
      parameters:
      - name: tenant-id
        in: header
        schema:
          type: string
        required: true
      requestBody:
        content:
          application/json:
            examples:
              createNuccSpecialty:
                value:
                  data:
                    classification: Allopathic & Osteopathic Physicians
                    specialization: Cardiology
                    category: Individual
                    displayName: Cardiology
                    specialtyNuccTaxonomyCode: 207RC0000X
            schema:
              $ref: '#/components/schemas/CreateNuccSpecialtyRequest'
        required: true
      responses:
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - User does not have required permissions
        '500':
          description: Internal Server Error - An unexpected error occurred
        '201':
          description: The NUCC specialty entry was created; the response body is the new record with its server-assigned ID.
          content:
            application/json:
              examples:
                createNuccSpecialty:
                  value:
                    id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                    createdAt: '2026-07-22'
                    createdBy: auth0|64f1a2b3c4d5e6f7a8b9c0d1
                    updatedAt: '2026-07-22'
                    updatedBy: auth0|64f1a2b3c4d5e6f7a8b9c0d1
                    data:
                      classification: Allopathic & Osteopathic Physicians
                      specialization: Cardiology
                      category: Individual
                      displayName: Cardiology
                      specialtyNuccTaxonomyCode: 207RC0000X
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Server-assigned NUCC specialty identifier.
                  createdAt:
                    type: string
                    format: date
                    description: Date the record was created.
                  createdBy:
                    type: string
                    description: ID of the user who created the record.
                  updatedAt:
                    type: string
                    format: date
                    description: Date the record was last updated.
                  updatedBy:
                    type: string
                    description: ID of the user who last updated the record.
                  data:
                    $ref: https://schemas.certifyos.com/entities/NuccSpecialty.schema.json
        '400':
          description: The request body failed NuccSpecialty JSON Schema validation, or a downstream data-layer error occurred.
          content:
            application/json:
              examples:
                createNuccSpecialtyInvalid:
                  value:
                    errors:
                    - data.displayName is required
                    errorDetails:
                      field: data.displayName
                      message: is required
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
      security:
      - jwt: []
  /specialties/nuccByTaxonomy/{taxonomyCode}:
    get:
      summary: Look up a NUCC specialty by taxonomy code
      description: 'Returns the first NUCC specialty record whose taxonomy code matches the supplied value, scoped to the calling tenant.


        **When to use:** Use this endpoint to resolve a known NUCC taxonomy code (from the NUCC Health Care Provider Taxonomy standard, e.g. `207RC0000X`) to the tenant''s internal NUCC specialty record. To retrieve a specialty by its internal ID use `GET /specialties/{id}`.


        **Preconditions:** Requires the `READ_SPECIALTY` permission. The `tenant-id` header must be supplied. `taxonomyCode` is matched by exact, case-sensitive string equality against the stored value; no fixed length or character-set format is enforced by the API.


        **Result:** Returns the first matching NUCC specialty record. If multiple records share the same taxonomy code, only the first of up to 10 matches is returned; the selection order is not guaranteed. Read-only — no side effects.'
      operationId: getNuccSpecialtyByTaxonomyCode
      tags:
      - Specialty
      parameters:
      - description: NUCC taxonomy code to look up (NUCC Health Care Provider Taxonomy standard, e.g. `207RC0000X`). Matching is exact and case-sensitive.
        example: 207RC0000X
        in: path
        required: true
        name: taxonomyCode
        schema:
          type: string
      - name: tenant-id
        in: header
        schema:
          type: string
        required: true
      responses:
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - User does not have required permissions
        '500':
          description: Internal Server Error - An unexpected error occurred
        '200':
          description: The first NUCC specialty record matching the given taxonomy code.
          content:
            application/json:
              examples:
                getNuccSpecialtyByTaxonomyCode:
                  value:
                    id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                    createdAt: '2026-07-22'
                    createdBy: auth0|64f1a2b3c4d5e6f7a8b9c0d1
                    updatedAt: '2026-07-22'
                    updatedBy: auth0|64f1a2b3c4d5e6f7a8b9c0d1
                    data:
                      classification: Allopathic & Osteopathic Physicians
                      specialization: Cardiology
                      category: Individual
                      displayName: Cardiology
                      specialtyNuccTaxonomyCode: 207RC0000X
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Server-assigned NUCC specialty identifier.
                  createdAt:
                    type: string
                    format: date
                    description: Date the record was created.
                  createdBy:
                    type: string
                    description: ID of the user who created the record.
                  updatedAt:
                    type: string
                    format: date
                    description: Date the record was last updated.
                  updatedBy:
                    type: string
                    description: ID of the user who last updated the record.
                  data:
                    $ref: https://schemas.certifyos.com/entities/NuccSpecialty.schema.json
        '404':
          description: No NUCC specialty exists with the given taxonomy code for this tenant.
          content:
            application/json:
              examples:
                nuccSpecialtyNotFound:
                  value:
                    error: 'NuccSpecialty not found for taxonomy code: 207RC0000X'
      security:
      - jwt: []
  /specialties/{id}:
    put:
      summary: Fully replace an existing specialty record
      description: 'Performs a full replacement of the specialty record with the given ID. All fields of the specialty are overwritten with the values supplied in the request body; omitted optional fields revert to their default or null values.


        **When to use:** Use this endpoint when you need to update one or more fields of an existing specialty. Because this is a full-replace operation (not a partial update), you must supply the complete desired state of the resource in the request body.


        **Preconditions:** Requires the `UPDATE_SPECIALTY` permission. The `tenant-id` header must be supplied. The request body `data` object is validated against the Specialty JSON Schema before the update is applied; a validation failure returns 400.


        **Result:** Returns 200 with the updated specialty object reflecting the new state. A nonexistent `id` and a JSON Schema validation failure both currently surface as 400 Bad Request with the same generic error shape — the response body does not distinguish between the two causes. Idempotent with respect to the same complete payload — repeating the call with identical data leaves the resource unchanged.'
      operationId: updateSpecialty
      tags:
      - Specialty
      parameters:
      - description: ID of the specialty to update (server-assigned UUID-format string).
        in: path
        required: true
        name: id
        schema:
          type: string
      - name: tenant-id
        in: header
        schema:
          type: string
        required: true
      requestBody:
        content:
          application/json:
            examples:
              updateSpecialty:
                value:
                  data:
                    name: Cardiology
                    classificationSource: NUCC
                    specialtyCategory: Individual
                    taxonomyCode: 207RC0000X
            schema:
              $ref: '#/components/schemas/CreateSpecialtyRequest'
        required: true
      responses:
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - User does not have required permissions
        '500':
          description: Internal Server Error - An unexpected error occurred
        '200':
          description: The specialty was fully replaced; the response body is the updated record.
          content:
            application/json:
              examples:
                updateSpecialty:
                  value:
                    id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    data:
                      name: Cardiology
                      classificationSource: NUCC
                      specialtyCategory: Individual
                      taxonomyCode: 207RC0000X
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Server-assigned UUID-format specialty identifier.
                  data:
                    $ref: https://schemas.certifyos.com/entities/Specialty.schema.json
        '400':
          description: The specialty ID does not exist for this tenant, or the request body failed Specialty JSON Schema validation, or a downstream data-layer error occurred.
          content:
            application/json:
              examples:
                updateSpecialtyInvalid:
                  value:
                    errors:
                    - data.classificationSource is required
                    errorDetails:
                      field: data.classificationSource
                      message: is required
              schema:
                $ref: '#/components/schemas/BadRequestErrorResponse'
      security:
      - jwt: []
    get:
      summary: Fetch a single specialty by its ID
      description: 'Returns the specialty record with the given ID, scoped to the calling tenant.


        **When to use:** Use this endpoint to retrieve a specific specialty when you already have its ID (for example, from a `POST /specialties` response or from a list returned by `GET /specialties`). For NUCC taxonomy lookups use `GET /specialties/nuccByTaxonomy/{taxonomyCode}`.


        **Preconditions:** Requires the `READ_SPECIALTY` permission. The `tenant-id` header must be supplied. `id` is the server-assigned specialty identifier — a UUID-format string generated by the data layer on creation.


        **Result:** Returns the specialty object for the matched record. Read-only — no side effects.'
      operationId: getSpecialty
      tags:
      - Specialty
      parameters:
      - description: ID of the specialty to retrieve (server-assigned UUID-format string).
        in: path
        required: true
        name: id
        schema:
          type: string
      - name: tenant-id
        in: header
        schema:
          type: string
        required: true
      responses:
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - User does not have required permissions
        '500':
          description: Internal Server Error - An unexpected error occurred
        '200':
          description: The specialty record matching the given ID.
          content:
            application/json:
              examples:
                getSpecialty:
                  value:
                    id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    data:
                      name: Cardiology
                      classificationSource: NUCC
                      specialtyCategory: Individual
                      taxonomyCode: 207RC0000X
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Server-assigned UUID-format specialty identifier.
                  data:
                    $ref: https://schemas.certifyos.com/entities/Specialty.schema.json
        '404':
          description: No specialty exists with the given ID for this tenant.
          content:
            application/json:
              examples:
                specialtyNotFound:
                  value:
                    error: 'Specialty not found: 3fa85f64-5717-4562-b3fc-2c963f66afa6'
      security:
      - jwt: []
    delete:
      summary: Permanently delete a specialty record
      description: 'Permanently removes the specialty record with the given ID from the tenant''s catalog. This action is irreversible.


        **When to use:** Use this endpoint to remove a specialty that is no longer needed. Deleting a specialty does not cascade to any other record: it does not remove or modify tenant, practitioner, group, or facility associations that reference it. If any such association still references the specialty, the deletion is rejected (409) rather than leaving those associations dangling.


        **Preconditions:** Requires the `DELETE_SPECIALTY` permission. The `tenant-id` header must be supplied. `id` must refer to an existing specialty for the tenant; if it does not, 404 is returned.


        **Result:** Returns 204 with no response body on success — a single, synchronous operation with no other side effects. Not idempotent — deleting an already-deleted specialty returns 404, not 204.'
      operationId: deleteSpecialty
      tags:
      - Specialty
      parameters:
      - description: ID of the specialty to delete (server-assigned UUID-format string).
        in: path
        required: true
        name: id
        schema:
          type: string
      - name: tenant-id
        in: header
        schema:
          type: string
        required: true
      responses:
        '401':
          description: Unauthorized - Authentication required
        '403':
          description: Forbidden - User does not have required permissions
        '500':
          description: Internal Server Error - An unexpected error occurred
        '204':
          description: The specialty was deleted. No response body.
        '404':
          description: No specialty exists with the given ID for this tenant.
          content:
            application/json:
              examples:
                specialtyNotFound:
                  value:
                    error: 'Specialty not found: 3fa85f64-5717-4562-b3fc-2c963f66afa6'
        '409':
          description: The specialty is still referenced by an existing tenant specialty association and cannot be deleted. Remove or terminate the referencing association first.
          content:
            application/json:
              examples:
                specialtyInUse:
                  value:
                    errors:
                    - httpStatus: 409
                      reason: FOREIGN_KEY_CONSTRAINT_VIOLATION
                      title: Foreign Key Constraint Violation
                      detail: Specialty 3fa85f64-5717-4562-b3fc-2c963f66afa6 is still referenced by one or more tenant specialty associations
      security:
      - jwt: []
components:
  schemas:
    CreateNuccSpecialtyRequest:
      type: object
      properties:
        data:
          $ref: https://schemas.certifyos.com/entities/NuccSpecialty.schema.json
          type: object
    BadRequestErrorResponse:
      type: object
      description: Standard error response structure for 400 Bad Request validation and client errors
      properties:
        errors:
          type: array
          examples:
          - - Validation failed
            - Required field missing
          items:
            type: string
          description: List of error messages
        errorDetails:
          type: object
          description: Detailed error information with specific validation failures
    GetSpecialtiesResponse:
      type: object
      properties:
        totalCount:
          type: integer
          format: int64
        data:
          $ref: https://schemas.certifyos.com/entities/Specialty.schema.json
          type: object
    CreateSpecialtyRequest:
      type: object
      properties:
        nuccSpecialtyId:
          type: string
        abmsSpecialtyId:
          type: string
        hsdSpecialtyId:
          type: string
        data:
          $ref: https://schemas.certifyos.com/entities/Specialty.schema.json
          type: object
  securitySchemes:
    jwt:
      type: http
      description: JWT Authentication - Provide only the raw token without Bearer prefix
      scheme: bearer
      bearerFormat: JWT
x-provenance:
  method: harvested
  publisher: Certifyos
  source: https://api-service.internal.certifyos.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)