Certifyos Practitioner API

openapi: 3.2.0
info:
  description: API for Certify application
  title: Certify API Layer Practitioner 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: Practitioner
  description: Endpoints for managing practitioner information and associations.
paths:
  /practitioners:
    get:
      summary: Find Practitioner by filter criteria with pagination
      description: Returns a paginated list of Practitioner based on filter criteria. Supports offset-based (page/size) pagination. Multiple filters are combined with AND logic.
      operationId: practitionerFindMany
      tags:
      - Practitioner
      parameters:
      - description: Search by Caqh Provider Id
        name: caqhProviderId
        in: query
        schema:
          type: string
      - description: Filter by delegation status (Direct or Delegated)
        name: delegationStatus
        in: query
        schema:
          type: string
      - description: Search by External Id
        name: externalId
        in: query
        schema:
          type: string
      - description: 'Filter criteria as JSON (must be URL encoded). Multiple filters are combined with AND logic.


          **Filterable Fields:**

          - `credentialingStatus` (String): Workflow status (eq, neq, in, nin, contains)

          - `data.lineOfBusiness` (Array): Line of business values (in, nin)

          - `data.userDefinedFields.*` (Any): User-defined fields with dot notation (eq, neq, in, nin, contains)

          - `data.*` (Any): Any data field (eq, neq, in, nin, contains, gt, gte, lt, lte)


          **Operations:**

          - String: `eq`, `neq`, `in`, `nin`, `contains`

          - Array: `in`, `nin` (use `in` for arrays, not `eq`)

          - Numeric/Date: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`


          **Examples:**

          ```json

          {"credentialingStatus":{"eq":"PSV_READY"}}

          {"credentialingStatus":{"in":["PSV_READY","PSV_COMPLETED"]}}

          {"data.lineOfBusiness":{"in":["MEDICARE","MEDICAID"]}}

          {"data.userDefinedFields.market":{"in":["MARKET1","MARKET2"]}}

          {"credentialingStatus":{"eq":"PSV_READY"},"data.lineOfBusiness":{"in":["MEDICARE"]}}

          ```


          **Notes:**

          - Filter must be URL encoded when sent as query parameter

          - `tenantId` from header always takes precedence (cannot be overridden)

          - Credentialing status derived from latest workflow timeline event

          - String operations are case-sensitive

          '
        name: filter
        in: query
        schema:
          type: string
      - description: Search by Practitioner First Name
        name: firstName
        in: query
        schema:
          type: string
      - description: Search by Practitioner Last Name
        name: lastName
        in: query
        schema:
          type: string
      - description: Filter by licensed states (comma-separated list of state codes)
        name: licensedStates
        in: query
        schema:
          type: string
      - description: 'Search by NPI. May contain one or more values for bulk search (copy-paste): separate with comma, newline, tab, semicolon, or space. When one or more NPI values are provided via this parameter, the response includes optional identifiersSearched, matchedCount, notFoundCount, unmatchedIdentifiers. When the query parameter is omitted (standard list request), those fields are null.'
        name: npi
        in: query
        schema:
          type: string
      - description: Page number for offset-based pagination (0-based index). Defaults to 0 if not specified.
        name: page
        in: query
        schema:
          type: integer
          format: int32
          default: '0'
      - description: Search by Practitioner Roles (comma-separated list)
        name: practitionerRoles
        in: query
        schema:
          type: string
      - description: Search by Practitioner Type (comma-separated list)
        name: practitionerType
        in: query
        schema:
          type: string
      - description: Number of items per page in offset-based pagination. Defaults to 2 if not specified.
        name: size
        in: query
        schema:
          type: integer
          format: int32
          default: '2'
      - description: Filter by states to credential (comma-separated list of state codes)
        name: statesToCredential
        in: query
        schema:
          type: string
      - description: Include PII in response; requires practitioner read:pii permission
        in: header
        name: X-PII-View
        schema:
          type: string
      - name: tenant-id
        in: header
        schema:
          type: string
      responses:
        '200':
          description: List of Practitioner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedPractitionerGetResponse'
        '400':
          description: Bad request - Invalid pagination parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json: {}
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json: {}
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
      security:
      - jwt: []
    post:
      summary: Create a new practitioner
      description: Creates a new practitioner for the request tenant.
      operationId: practitionerCreate
      tags:
      - Practitioner
      parameters:
      - name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        description: Practitioner data as JSON
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePractitionerRequest'
        required: true
      responses:
        '201':
          description: Practitioner successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PractitionerCreateResponse'
        '400':
          description: Invalid request body (e.g., schema validation failed), or unsupported source type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json: {}
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json: {}
        '409':
          description: Conflict - Practitioner already exists for this tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
        '500':
          description: Internal server error during request processing (e.g., network timeout, etc.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
      security:
      - jwt: []
  /practitioners/group-practitioner-location-network-specialties/effective-date:
    put:
      summary: Update effective date of a practitioner location network specialty at group level
      description: Updates the effective date of a practitioner location network specialty association at the group level
      operationId: updateGroupPractitionerLocationNetworkSpecialtyEffectiveDate
      tags:
      - Practitioner
      parameters:
      - name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGroupPractitionerLocationNetworkSpecialtyEffectiveDateRequest'
        required: true
      responses:
        '200':
          description: Practitioner location network specialty effective date successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonNode'
        '400':
          description: Invalid request body or missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
        '404':
          description: Group practitioner location network specialty not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
        '500':
          description: Internal server error during request processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
      security:
      - jwt: []
  /practitioners/group-practitioner-location-network-specialties/specialty:
    patch:
      summary: Correct the specialty at the practitioner-location-network level
      description: Resolves the FK chain from TenantGroupPractitionerLocationNetworkSpecialty through GroupPractitionerLocationSpecialty to the parent TenantPractitionerSpecialty and replaces its tenant_specialty_id. Does not trigger termination events.
      operationId: correctGroupPractitionerLocationNetworkSpecialty
      tags:
      - Practitioner
      parameters:
      - name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CorrectLocationNetworkSpecialtyRequest'
        required: true
      responses:
        '200':
          description: Specialty corrected successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonNode'
        '400':
          description: Bad request - Invalid input
          content:
            application/json: {}
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json: {}
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json: {}
        '404':
          description: Group practitioner location network specialty not found
          content:
            application/json: {}
        '409':
          description: Conflict - Practitioner already has this specialty
          content:
            application/json: {}
        '500':
          description: Internal server error
          content:
            application/json: {}
      security:
      - jwt: []
  /practitioners/group-practitioner-location-specialties/effective-date:
    put:
      summary: Update effective date of a practitioner location specialty at group level
      description: Updates the effective date of a practitioner location specialty association at the group level
      operationId: updateGroupPractitionerLocationSpecialtyEffectiveDate
      tags:
      - Practitioner
      parameters:
      - name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGroupPractitionerLocationSpecialtyEffectiveDateRequest'
        required: true
      responses:
        '200':
          description: Practitioner location specialty effective date successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonNode'
        '400':
          description: Invalid request body or missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
        '404':
          description: Group practitioner location specialty not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
        '500':
          description: Internal server error during request processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
      security:
      - jwt: []
  /practitioners/group-practitioner-location-specialties/specialty:
    patch:
      summary: Correct the specialty at the practitioner-location level
      description: Resolves the FK chain from GroupPractitionerLocationSpecialty to the parent TenantPractitionerSpecialty and replaces its tenant_specialty_id. Does not trigger termination events.
      operationId: correctGroupPractitionerLocationSpecialty
      tags:
      - Practitioner
      parameters:
      - name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CorrectLocationSpecialtyRequest'
        required: true
      responses:
        '200':
          description: Specialty corrected successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonNode'
        '400':
          description: Bad request - Invalid input
          content:
            application/json: {}
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json: {}
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json: {}
        '404':
          description: Group practitioner location specialty not found
          content:
            application/json: {}
        '409':
          description: Conflict - Practitioner already has this specialty
          content:
            application/json: {}
        '500':
          description: Internal server error
          content:
            application/json: {}
      security:
      - jwt: []
  /practitioners/group-practitioner-network-participation-specialties/effective-date:
    put:
      summary: Update effective date of a practitioner network participation specialty at group level
      description: Updates the effective date of a practitioner network participation specialty association at the group level
      operationId: updateGroupPractitionerNetworkParticipationSpecialtyEffectiveDate
      tags:
      - Practitioner
      parameters:
      - name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGroupPractitionerNetworkParticipationSpecialtyEffectiveDateRequest'
        required: true
      responses:
        '200':
          description: Practitioner network participation specialty effective date successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonNode'
        '400':
          description: Invalid request body or missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
        '404':
          description: Group practitioner network participation specialty not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
        '500':
          description: Internal server error during request processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
      security:
      - jwt: []
  /practitioners/group-practitioner-specialties/effective-date:
    put:
      summary: Update effective date of a practitioner specialty at group level
      description: Updates the effective date of a practitioner specialty association at the group level
      operationId: updateGroupPractitionerSpecialtyEffectiveDate
      tags:
      - Practitioner
      parameters:
      - name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGroupPractitionerSpecialtyEffectiveDateRequest'
        required: true
      responses:
        '200':
          description: Practitioner specialty effective date successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonNode'
        '400':
          description: Invalid request body or missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
        '404':
          description: Group practitioner specialty not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
        '500':
          description: Internal server error during request processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
      security:
      - jwt: []
  /practitioners/practitioner-locations/{id}/roles/correct:
    patch:
      summary: Correct a practitioner role key on a group-practitioner-location record
      description: Renames an existing role key in practitionerRolesMap on a group_practitioner_location record (e.g., PCP -> Specialist) while preserving the inner map (effectiveDate, terminationDate). Does not trigger termination events or lifecycle changes.
      operationId: correctLocationRole
      tags:
      - Practitioner
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PractitionerRoleCorrectionRequest'
        required: true
      responses:
        '200':
          description: Location role corrected successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PractitionerRolesUpdateResponse'
        '400':
          description: Bad request - Invalid role or role not found
          content:
            application/json: {}
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json: {}
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json: {}
        '404':
          description: Location not found
          content:
            application/json: {}
        '409':
          description: Conflict - New role already exists on location
          content:
            application/json: {}
        '500':
          description: Internal server error
          content:
            application/json: {}
      security:
      - jwt: []
  /practitioners/practitioner-locations/{id}/roles/remove:
    patch:
      summary: Remove a practitioner role at the location level
      description: Removes a role key from practitionerRolesMap on a group_practitioner_location record and all associated tenant_group_location_practitioner_network records for that location.
      operationId: removePractitionerLocationRole
      tags:
      - Practitioner
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemovePractitionerRoleRequest'
        required: true
      responses:
        '200':
          description: Location role removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PractitionerRolesUpdateResponse'
        '400':
          description: Bad request - Invalid role or role not found on location
          content:
            application/json: {}
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json: {}
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json: {}
        '404':
          description: Location not found
          content:
            application/json: {}
        '500':
          description: Internal server error
          content:
            application/json: {}
      security:
      - jwt: []
  /practitioners/practitioner-role-assignments/{id}/terminate:
    put:
      summary: Terminate a practitioner role at a network location assignment
      description: Sets the terminationDate on a single role entry inside practitionerRolesMap of a TenantGroupLocationPractitionerNetwork (TGLPN) record. Does not cascade to the parent TGLPN record status, TenantGroupPractitionerNetwork, or the practitioner's main termination. The response echoes tglpnId, role (canonical casing), and terminationDate only; terminationInformedDate and terminationReason are accepted and persisted but not returned. If the role's stored effectiveDate cannot be parsed as a valid ISO date, the termination-before-effective constraint is skipped and the request succeeds; this preserves forward progress for legacy records with malformed effectiveDate values.
      operationId: terminatePractitionerRole
      tags:
      - Practitioner
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TerminatePractitionerRoleRequest'
        required: true
      responses:
        '200':
          description: Role terminated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TerminatePractitionerRoleResponse'
        '400':
          description: Bad request - invalid role value, terminationDate before effectiveDate, or role not found in practitionerRolesMap
          content:
            application/json: {}
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json: {}
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json: {}
        '404':
          description: TGLPN record not found
          content:
            application/json: {}
        '409':
          description: Conflict - role is already terminated
          content:
            application/json: {}
        '500':
          description: Internal server error
          content:
            application/json: {}
      security:
      - jwt: []
  /practitioners/tenant-practitioner-specialties:
    put:
      summary: Update a tenant practitioner specialty
      description: Updates an existing tenant practitioner specialty record by ID
      operationId: updateTenantPractitionerSpecialty
      tags:
      - Practitioner
      parameters:
      - name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTenantPractitionerSpecialtyRequest'
        required: true
      responses:
        '200':
          description: Tenant practitioner specialty successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonNode'
        '400':
          description: Invalid request body or missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
        '404':
          description: Tenant practitioner specialty not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
        '500':
          description: Internal server error during request processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
      security:
      - jwt: []
  /practitioners/tenant-practitioner-specialties/specialty:
    patch:
      summary: Correct the specialty on a tenant practitioner specialty record
      description: Replaces the tenant_specialty_id on a TenantPractitionerSpecialty record in data-correction mode. Does not trigger termination events or lifecycle changes.
      operationId: correctTenantPractitionerSpecialty
      tags:
      - Practitioner
      parameters:
      - name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CorrectPractitionerSpecialtyRequest'
        required: true
      responses:
        '200':
          description: Specialty corrected successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonNode'
        '400':
          description: Bad request - Invalid input
          content:
            application/json: {}
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json: {}
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json: {}
        '404':
          description: Tenant practitioner specialty not found
          content:
            application/json: {}
        '409':
          description: Conflict - Practitioner already has this specialty
          content:
            application/json: {}
        '500':
          description: Internal server error
          content:
            application/json: {}
      security:
      - jwt: []
  /practitioners/tenant-practitioner-specialties/terminate:
    put:
      summary: Terminate a tenant practitioner specialty with cascading support
      description: Terminates a tenant practitioner specialty and optionally cascades the termination to related specialties at the group, location, and network levels.
      operationId: terminateTenantPractitionerSpecialty
      tags:
      - Practitioner
      parameters:
      - name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PractitionerSpecialtyTerminationRequest'
        required: true
      responses:
        '200':
          description: Tenant practitioner specialty terminated successfully
          content:
            application/json: {}
        '400':
          description: Bad request - Invalid input
          content:
            application/json: {}
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json: {}
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json: {}
        '404':
          description: Tenant practitioner specialty not found
          content:
            application/json: {}
        '500':
          description: Internal server error
          content:
            application/json: {}
      security:
      - jwt: []
  /practitioners/terminate:
    put:
      summary: Terminate practitioner from network/location/group_locations
      description: Accepts terminationType and updates relevant records with termination details.
      operationId: terminatePractitioner
      tags:
      - Practitioner
      parameters:
      - name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TerminationRequest'
        required: true
      responses:
        '200':
          description: Termination updated
          content:
            application/json: {}
        '400':
          description: Bad request - Invalid input
          content:
            application/json: {}
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json: {}
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json: {}
        '404':
          description: Association not found
          content:
            application/json: {}
        '409':
          description: Conflict - Termination blocked by active credentialing or monitoring workflows
          content:
            application/json: {}
        '500':
          description: Internal server error
          content:
            application/json: {}
      security:
      - jwt: []
  /practitioners/{certifyPractitionerId}/groups/{certifyGroupId}/effective-date:
    put:
      summary: Update effective dates for practitioner-group association
      description: Updates the effective start date and/or termination date for a practitioner-group association. Optionally cascades the date change to network participation based on the cascadeToNetworkParticipation flag. If terminationDate is provided, it must be after the effectiveDate.
      operationId: updatePractitionerGroupEffectiveDate
      tags:
      - Practitioner
      parameters:
      - description: Certify group ID
        in: path
        required: true
        name: certifyGroupId
        schema:
          type: string
          pattern: \S
      - description: Certify practitioner ID
        in: path
        required: true
        name: certifyPractitionerId
        schema:
          type: string
          pattern: \S
      - name: tenant-id
        in: header
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePractitionerGroupEffectiveDateRequest'
        required: true
      responses:
        '200':
          description: Practitioner-group effective date successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonNode'
        '400':
          description: Invalid request body, missing required parameters, or validation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
        '404':
          description: Practitioner-group association not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
        '500':
          description: Internal server error during request processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError1'
      security:
      - jwt: []
  /practitioners/{id}:
    put:
      summary: Update a practitioner
      description: Updates an existing practitioner based on the practitioner ID.
      operationId: practitionerUpdate
      tags:


# --- truncated at 32 KB (386 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/certifyos/refs/heads/main/openapi/certifyos-practitioner-api-openapi.yml