Skip to main content

Practitioner

Endpoints for managing practitioner information and associations.

šŸ“„ļøList practitioners matching filter criteria

Returns a paginated list of practitioners matching the supplied filter criteria; all filters are combined with AND logic, and omitting a filter returns all practitioners accessible to the caller. Use this endpoint to search across practitioners by name, NPI, CAQH ID, external ID, type, roles, or delegation status ā€” for a single known practitioner, prefer `GET /practitioners/{id}` instead, and for bulk NPI lookup, supply multiple `npi` values (the response shape changes when NPI bulk-search mode is active, adding `identifiersSearched` and `matchedCount` fields). The `tenant-id` header identifies which tenant's data is queried; include the `X-PII-View: true` header to receive PII fields, which requires the `practitioner read:pii` permission ā€” callers without it receive 403. The `size` parameter's default of 2 is intentional, and unlike the NPI bulk-search and roster-ID list parameters, api-layer does not enforce any maximum on `size` ā€” it is passed through unclamped.

šŸ“„ļøCreate a new practitioner for the tenant

Creates a new practitioner record scoped to the requesting tenant. Use this when onboarding a new provider who does not yet exist in the system; if the practitioner already exists for this tenant, the server returns 409 ā€” use `PUT /practitioners/{id}` to update an existing record instead. The request body accepts three payload shapes: a wrapped object with a top-level `data` field, a direct practitioner object, or an extended form that also includes `groups` and `networks` for simultaneous association; the payload is validated against the practitioner JSON schema before persistence. Tenant UDF values go under `data.userDefinedFields`, keyed by the field names returned by `GET /udf-schemas/entity-type/practitioner`; UDF keys sent at the top level of the practitioner object are rejected with 400. Creating a practitioner here does not itself trigger a downstream credentialing workflow.

šŸ“„ļøUpdate effective date on a group-location-network specialty

Updates the effective start date on a practitioner's specialty association at the group-location-network level. Use this when the effective date on an existing group-level location-network specialty record needs correction; this operates at the most specific level of the specialty hierarchy (group, then location, then network) ā€” for the location-only level use `PUT /practitioners/group-practitioner-location-specialties/effective-date`, and for the group level use `PUT /practitioners/group-practitioner-specialties/effective-date`. The target specialty association must already exist.

šŸ“„ļøCorrect specialty on a group-location-network specialty record

Replaces the specialty identifier on a practitioner specialty association at the group-location-network level. This is a data-correction operation ā€” it does not trigger termination events, lifecycle changes, or downstream workflow notifications. Use it when the wrong specialty was linked at this level and the record needs correcting in place without triggering a termination cycle; for corrections at the group-location level without a network, use `PATCH /practitioners/group-practitioner-location-specialties/specialty` instead. The specialty association record must already exist, and the replacement specialty must be a valid, active tenant specialty.

šŸ“„ļøUpdate effective date on a group-location specialty

Updates the effective start date on a practitioner's specialty association at the group-location level, without network specificity. Use this when the effective date on an existing group-level location specialty record needs correction; for the more specific group-location-network level, use `PUT /practitioners/group-practitioner-location-network-specialties/effective-date`, and for the group-only level, use `PUT /practitioners/group-practitioner-specialties/effective-date`. The target specialty association must already exist.

šŸ“„ļøCorrect specialty on a group-location specialty record

Replaces the specialty identifier on a practitioner specialty association at the group-location level. This is a data-correction operation ā€” it does not trigger termination events or lifecycle changes. Use it when the wrong specialty was linked at the group-location level and needs correcting without triggering a termination cycle; for the more specific group-location-network level, use `PATCH /practitioners/group-practitioner-location-network-specialties/specialty` instead. The specialty association must already exist, and the replacement specialty must be a valid tenant specialty.

šŸ“„ļøUpdate effective date on a group network-participation specialty

Updates the effective start date on a practitioner's specialty association at the group network-participation level. Use this when the effective date on an existing group-level network-participation specialty record needs correction; this targets network participation specialty records specifically, so for location-network specialties use `PUT /practitioners/group-practitioner-location-network-specialties/effective-date` instead. The target specialty association must already exist.

šŸ“„ļøUpdate effective date on a group-level practitioner specialty

Updates the effective start date on a practitioner's specialty association at the group level. Use this when the effective date on an existing group-level specialty record needs correction; this is the broadest specialty level, so for location or network specificity use the corresponding `group-practitioner-location-specialties` or `group-practitioner-location-network-specialties` endpoints instead. The target specialty association must already exist.

šŸ“„ļøCorrect a role key on a practitioner-location record

Renames an existing role key on the specified practitioner-location association record (for example, renaming `PCP` to `Specialist`) while preserving all existing role metadata such as `effectiveDate` and `terminationDate`. This is a data-correction operation ā€” it does not trigger termination events or lifecycle changes. Use it when a role was recorded with the wrong key at the group-practitioner-location level and needs correcting in place; for correcting a role key at the core practitioner level, use `PATCH /practitioners/{id}/roles/correct` instead. `{id}` is the GroupPractitionerLocation record identifier, obtained from the practitioner's location relationship data, and the role key being renamed must already exist on the record.

šŸ“„ļøRemove a role from a practitioner-location record

Removes a role key from the specified practitioner-location association record and from all associated location-network assignment records for that location. Use this to fully remove a role at the group-practitioner-location level; this is not a termination, it deletes the role key entirely. For terminating a role (setting a termination date) on a specific network assignment, use `PUT /practitioners/practitioner-role-assignments/{id}/terminate` instead. `{id}` is the GroupPractitionerLocation record identifier, and the role being removed must exist on the record. This endpoint does not apply the active-credentialing/monitoring-workflow guard used by `PUT /practitioners/terminate`.

šŸ“„ļøSet termination date on a single practitioner role assignment

Sets the `terminationDate` on a single role entry within a practitioner's location-network assignment. This operation is scoped to a single role in a single assignment and does not cascade to any parent records ā€” the location-network assignment itself, the network participation record, or the practitioner's main termination status. Use it when a specific role held at a particular location-network pairing has ended but the practitioner's other roles and assignments remain active; for practitioner-wide termination, use `PUT /practitioners/terminate` instead. `{id}` is the location-network assignment (TGLPN) identifier obtained from the practitioner's relationship data, and the target role key must exist within that assignment; 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 as a legacy-record accommodation.

šŸ“„ļøBulk upload supporting documents to multiple practitioners

Uploads one or more files exactly once each and links them as shared supporting-document attachments (source: 'Bulk') to every selected practitioner. Practitioners may be selected explicitly via certifyPractitionerIds (JSON string form field), or via isSelectAll=true plus a filter JSON string (same encoding as GET /practitioners). When isSelectAll is true, certifyPractitionerIds is ignored; when false, filter is ignored. Target set size is capped (default 1000; see api-layer.practitioner.bulk-document-upload.max-practitioners). HTTP 200 is returned for both full and partial success: per-file and per-practitioner outcomes are reported independently in the response body. When the feature kill switch is off, the endpoint returns 404 with an empty body (CP-32986).

šŸ“„ļøUpdate an existing tenant practitioner specialty record

Updates fields on an existing practitioner specialty record at the tenant level. Use this when one or more attributes of a practitioner's tenant-level specialty association need to be changed. The request body must include the ID of the specialty record to update. In practice, `effectiveDate` is the only field this endpoint can change ā€” it is merged onto a copy of the existing stored record, with every other stored attribute preserved as-is.

šŸ“„ļøCorrect specialty on a tenant practitioner specialty record

Replaces the specialty identifier on a tenant practitioner specialty record. This is a data-correction operation ā€” it does not trigger termination events, lifecycle changes, or downstream notifications. Use it when the wrong specialty was recorded and needs correcting without invoking the termination lifecycle; do not use it to end a practitioner's association with a specialty, use `PUT /practitioners/tenant-practitioner-specialties/terminate` for that. The specialty record must already exist, and the replacement specialty must be a valid, active tenant specialty.

šŸ“„ļøTerminate a practitioner specialty with optional cascade

Terminates a practitioner's tenant-level specialty association and optionally propagates the termination to related specialty records at the group, location, and network levels. Use this when a practitioner's specialty should be ended; to correct a wrongly recorded specialty rather than end it, use `PATCH /practitioners/tenant-practitioner-specialties/specialty` instead. The base request requires `tenantPractitionerSpecialtyId` and `terminationDate`; cascading to the group level is optional via a `groupTerminations` list, each entry requiring only `tenantGroupPractitionerId` plus optional scope-narrowing IDs. This endpoint does not apply the active-credentialing/monitoring-workflow guard used by `PUT /practitioners/terminate`, so it never returns a 409 for that reason.

šŸ“„ļøTerminate a practitioner with cascade

Terminates a practitioner and applies the appropriate termination cascade based on the supplied `terminationType`; different termination types update different sets of records and follow different cascade rules. Use this when a practitioner's engagement is ending in full or in part ā€” for terminating a single role at a specific location-network assignment, use `PUT /practitioners/practitioner-role-assignments/{id}/terminate`, and for ending a specialty only, use `PUT /practitioners/tenant-practitioner-specialties/terminate`. The request body must include `terminationType`; an active credentialing or monitoring workflow blocks termination with a 409 response until the workflow is resolved (except `FULL_EXIT`, which bypasses this guard). The 9 supported `terminationType` values are: `GROUP` (requires `tenantPractitionerId`, `tenantGroupId`, `terminationDate`; terminates the group membership plus all network, location, and location-network associations under it, optionally narrowed to one network via `networkId`), `NETWORK` (requires `networkId`; terminates the network participation and cascades to all location-network associations under that network), `GROUP_LOCATIONS` (requires `tenantGroupLocationId`; terminates that location association, and additionally cascades to end network enrollment at that location only when both the `practitioner.termination.group-locations.cascade-network.enabled` config flag is on and the request sends `acknowledgedLocationNetworkTermination=true` ā€” omitting it keeps the legacy GPL-only termination, not an error), `LOCATION_NETWORK` (requires `tenantGroupLocationPractitionerNetworkId`, or the `tenantGroupLocationId`/`networkId` pair; terminates that location-network record and cascades only to its location-network specialties), `NETWORK_SPECIALTY` and `GROUP_SPECIALTY` (identical cascade logic; each independently terminates the network-participation specialty when `tenantGroupPractitionerNetworkId`/`tenantGroupPractitionerSpecialtyId` are supplied and/or the location-network specialty when `tenantGroupLocationPractitionerNetworkId`/`tenantGroupPractitionerLocationSpecialtyId` are supplied, skipping whichever pair is absent rather than erroring), `GROUP_LOCATION_SPECIALTY` (independently terminates the group-location specialty when `tenantGroupPractitionerLocationId`/`tenantPractitionerSpecialtyId` are supplied and/or the location-network specialty when the same network-specialty ID pair above is supplied), `INFERRED_LOCATION` (requires `tenantGroupLocationId` but NOT `tenantGroupId` ā€” terminates all group and network relationships at that location across every group the practitioner belongs to there; multiple matches are expected and all are terminated, not an error), and `FULL_EXIT` (**`certifyPractitionerId` is MANDATORY** ā€” this is the only termination type that does not use `tenantPractitionerId`; a request with `terminationType=FULL_EXIT` and no `certifyPractitionerId` returns 400. `tenantGroupId` and every other scope field must also be omitted ā€” wipes every group, network, and location relationship the practitioner has). `INFERRED_LOCATION` and `FULL_EXIT` may return 400 if not yet available for the calling tenant, when `tenantGroupLocationId` is missing for `INFERRED_LOCATION`, or when `certifyPractitionerId` is missing for `FULL_EXIT`. `INFERRED_LOCATION` additionally returns 400 when the practitioner has no active relationships matching the request at that location at all ā€” unlike the 404 the 7 legacy types return when their scoped association isn't found. `FULL_EXIT` has no equivalent 'nothing found' error: a practitioner with zero group/network relationships still succeeds with 200 ā€” there's nothing to cascade-terminate at the group level, but the practitioner and CorePractitioner crosswalk are still expired and any active credentialing/monitoring work is still cancelled.

šŸ“„ļøRoll back an accidental practitioner termination

Reverses a termination that should not have happened (CP-37299): removes the termination date, reason and informed-date from EVERY level they were set for this practitioner ā€” core slice, tenant practitioner, group, group-network, location, location-network and location-network-specialty rows ā€” and regenerates each row's stored status from its surviving effective date, so relationships read Active or Pending again instead of Inactive.

šŸ“„ļøRetrieve the CAQH data fetched from PDQS for a practitioner

Returns the CAQH PDQS (Provider Data Quality Solution) data for the practitioner identified by `{caqhProviderId}` (the CAQH provider ID), if that data has already been pulled into our system. If it hasn't been pulled in yet, this returns 404 -- the CAQH PDQS pipeline must be triggered to fetch the practitioner's data before it can be retrieved from this endpoint. The response is trimmed to `certifyId`, `caqhProviderId`, and `data` (the actual CAQH profile payload, e.g. `practitionerInformation`, `practitionerLicense`, etc.); no pipeline/ingestion metadata or other internal fields are included. Any `ssn` field nested in `data` is masked to only the last 4 digits (e.g. `*****1234`) by default. Send the `X-PII-View: true` header to receive the unmasked SSN; this requires practitioner PII read permission (`READ_PRACTITIONER_PII`) for the tenant and returns 403 otherwise.

šŸ“„ļøUpdate effective dates on a practitioner-group association

Updates the effective start date and/or termination date for a practitioner's association with a specific group, optionally cascading the date change to the practitioner's network participation records within that group. Use this when the dates on an existing practitioner-group association need to be corrected or extended; the `certifyPractitionerId` and `certifyGroupId` path parameters identify the association. The practitioner-group association must already exist, and if `terminationDate` is provided, it must be after `effectiveDate`. Cascading is not purely controlled by `cascadeToNetworkParticipation`: if `networkId` is supplied, the network-scoped cascade always happens regardless of the flag; without `networkId`, cascade only happens when `cascadeToNetworkParticipation` is `true`. Past dates are allowed for both `effectiveDate` and `terminationDate`.

šŸ“„ļøList a practitioner's scope event log

Returns the scope events (today: state and line of business terminations) recorded for a practitioner in the caller's tenant (CP-41646), newest first. `{certifyPractitionerId}` is the `certifyPractitionerId`. Each entry carries the scope, event type, effective date, reason text, source and roster linkage, plus `slicesWritten`, the contributing slices the event was applied to (empty when none were recorded). The practitioner's NPI and the tenant id are not returned.

šŸ“„ļøRetrieve a single practitioner by ID

Returns the full practitioner record for the specified `certifyPractitionerId`. Use this when you have a known `certifyPractitionerId` and need the complete practitioner data object; to search across practitioners by name, NPI, or other attributes, use `GET /practitioners` instead, and for relationship data such as groups, networks, or locations, see the `/relationships/*` sub-resources. `{id}` is the `certifyPractitionerId` assigned at creation; include the `X-PII-View: true` header to receive PII fields, which requires the `practitioner read:pii` permission. Which fields are actually withheld or nulled when PII is not requested is decided entirely by the downstream data-access layer ā€” api-layer only forwards the flag and enforces the permission gate. This response never includes an `ssn` field; the SSN is exposed only via `GET /practitioners/{id}/ssn`. `terminationDate` and `terminationReason` are present only if the practitioner has been terminated (e.g. via `PUT /practitioners/terminate`); absent otherwise.

šŸ“„ļøManage board certifications for a practitioner

Updates, creates, or deletes board certification records for the specified practitioner; supply an array of certification items where each item includes an `action` field indicating the operation to perform (`create`, `update`, or `delete`). Use this to synchronize the complete set of board certifications for a practitioner ā€” adding new certifications, modifying existing ones, or removing certifications that are no longer valid; operations are applied per-item based on the `action` field. `{id}` is the `certifyPractitionerId`. Submitting an empty array wholesale-clears the entire board-certifications section with no confirmation step ā€” there is no null/empty guard on this endpoint.

šŸ“„ļøRetrieve the core practitioner record by ID

Returns the core practitioner record for the specified identifier from the tenant source. Use this to retrieve low-level core record data as opposed to the enriched operational view returned by `GET /practitioners/{id}`. `{id}` is a crosswalk ID, not the `certifyPractitionerId`; the handler looks the record up directly by tenant source and crosswalk ID, a different lookup mechanism than `GET /practitioners/{id}`, and applies no enrichment ā€” no `credentialingStatus` or `nextCredentialingDate` derivation, and no operational-view overlay merge.

šŸ“„ļøManage DEA records for a practitioner

Updates, creates, or deletes DEA (Drug Enforcement Administration) registration records for the specified practitioner; supply an array of DEA record items where each item includes an `action` field indicating the operation to perform (`create`, `update`, or `delete`). Use this to manage a practitioner's DEA registrations ā€” for example, when a new registration is issued, an existing registration expires or changes, or a registration is revoked; DEA registrations govern controlled-substance prescribing authority. `{id}` is the `certifyPractitionerId`. Submitting an empty array wholesale-clears the entire DEA-records section with no confirmation step ā€” there is no null/empty guard on this endpoint.

šŸ“„ļøReplace education and training records for a practitioner

Replaces the practitioner's education and training records using per-item create, update, or delete actions. Submitting an empty array removes all education and training entries for this practitioner ā€” this is a destructive, full-array replacement that cannot be partially reversed in the same call. Use this to synchronize a practitioner's education history, such as medical schools, residencies, and fellowships, with the authoritative source; for targeted removal of a single entry, send an explicit `delete` action with the stable row ID rather than submitting an empty array. `{id}` is the `certifyPractitionerId`, each item in the array must include an `action` field, and stable row IDs are required for `update` and `delete` actions.

šŸ“„ļøUpdate practitioner facility associations within a group

Associates the practitioner with one or more facilities within a group, creating new associations or updating existing ones; this endpoint follows upsert semantics, so existing associations are updated in place rather than replaced wholesale. Use this when adding the practitioner to a facility or updating facility-specific data; the request body must include a `groupId` to scope the associations. `{id}` is the `certifyPractitionerId`, and the group identified by `groupId` in the request body must already be associated with the practitioner. Only the facilities present in the request are upserted ā€” facilities already associated with the practitioner but omitted from the request are left unchanged, not removed.

šŸ“„ļøManage licenses for a practitioner

Updates, creates, or deletes license records for the specified practitioner; supply an array of license items where each item includes an `action` field indicating the operation to perform (`create`, `update`, or `delete`). Use this to synchronize a practitioner's professional licenses ā€” adding newly issued licenses, modifying existing license details such as state, expiration, or status, or removing licenses that are no longer valid. `{id}` is the `certifyPractitionerId`. Submitting an empty array wholesale-clears the entire licenses section with no confirmation step ā€” there is no null/empty guard on this endpoint.

šŸ“„ļøUpdate practitioner network associations within a group

Associates the practitioner with one or more networks within a group, creating or updating TenantGroupPractitionerNetwork relationships, following upsert semantics. Use this when adding the practitioner to a network or updating network-specific association data in bulk; the request body must include a `groupId` to scope the associations, and for associating with a single network with additional group-creation side effects, use `POST /practitioners/{id}/networks` instead. `{id}` is the `certifyPractitionerId`, and the group identified by `groupId` in the request body must already be associated with the practitioner. Only the networks present in the request are upserted ā€” networks already associated with the practitioner but omitted from the request are left unchanged, not removed. Each entry in `networks` accepts a required `networkId` and a free-form `networkData` object.

šŸ“„ļøAssociate practitioner with one or more networks

Associates the practitioner with one or more networks within a group in a single atomic batch. If the practitioner is not yet associated with the specified group, the group association is also created as part of the same request. Use this when onboarding a practitioner to a set of networks within a group; for updating existing network association attributes in bulk, use `PUT /practitioners/{id}/networks` instead. `{id}` is the `certifyPractitionerId`, the request body must include a `groupId`, and the specified networks must belong to that group.

šŸ“„ļøUpdate practitioner overview and core identity fields

Updates the practitioner's overview information, including core identity fields such as name and NPI. Use this when basic practitioner identity or profile attributes need to be changed; for updating the full practitioner record, use `PUT /practitioners/{id}` instead. `{id}` is the `certifyPractitionerId`, and a 409 is returned if an initial credentialing workflow conflict is detected. Unlike `PUT /practitioners/{id}`, this endpoint is a true partial update: the service fetches the existing core record and merges only the explicitly-provided fields on top of it, distinguishing an omitted field from one explicitly set to null.

šŸ“„ļøGet all relationship data for a practitioner

Returns all relationship data for the specified practitioner. The response format depends on the `transformed` query parameter: when `false` (default), the response is a raw nested relationship structure; when `true`, it is a flattened format with deduplicated networks, groups, locations, specialties, and related metadata. Use this when you need a comprehensive view of a practitioner's entire relationship graph; for individual relationship types, use the more targeted `/relationships/groups`, `/relationships/locations`, or `/relationships/networks` endpoints instead. `{id}` is the `certifyPractitionerId`.

šŸ“„ļøList groups in a practitioner's relationship graph

Returns all groups that the practitioner belongs to, including core group attributes such as name, NPI, TIN, and active status, plus metadata for each group. Use this when you need groups with their full attribute data as part of the practitioner's relationship graph; to retrieve just group membership without the attribute detail, use `GET /practitioners/{practitionerId}/groups` instead. `{id}` is the `certifyPractitionerId` and the caller must hold the `READ_PRACTITIONER` permission.

šŸ“„ļøList locations in a practitioner's relationship graph

Returns a paginated list of group_practitioner_locations (GPL) associations for the practitioner, each including relationship context such as the group, tenant group location, and any linked location-network (TGLPN) records. Use this when you need location data with relationship context; for a simpler list without relationship graph data, use `GET /practitioners/{practitionerId}/locations` instead. `{id}` is the `certifyPractitionerId`. This endpoint previously returned unstructured raw relationship data and is now a typed, paginated response (breaking change as of 2026-07-01); the operationId retains its legacy plural form for OpenAPI stability even though the underlying method is `getPractitionerLocationRelationships`. Terminated associations are included; none of the available filters (`certifyGroupId`, `networkId`, `locationSearch`) filter by termination status.

šŸ“„ļøList networks in a practitioner's relationship graph

Returns all networks the practitioner belongs to, as part of the practitioner's full relationship graph. Use this when you need network data with relationship context such as group membership or location linkages; for a flat list of network memberships without graph context, use `GET /practitioners/{id}/networks` instead. `{id}` is the `certifyPractitionerId`. Terminated associations are included; this endpoint does not filter by termination status.

šŸ“„ļøUpsert roles at the core and group-location level

Updates the practitioner's roles at the core practitioner level and, optionally, at the group-practitioner-location level. Each role entry in the request is upserted ā€” added if not present, updated if already present; roles are not deleted by omission, so to remove a role use `PATCH /practitioners/{id}/roles/remove` instead. Use this when adding or modifying practitioner roles; for renaming a role key as a data correction, use `PATCH /practitioners/{id}/roles/correct`. `{id}` is the `certifyPractitionerId`. Each entry requires `role` (validated against a runtime role allowlist) and at least one of `effectiveDate`/`terminationDate`; `groupPractitionerLocationId` is optional and controls whether the entry is also applied at the location level ā€” if omitted, only the core practitioner record is updated.

šŸ“„ļøCorrect a role key on the core practitioner record

Renames an existing role key on the core practitioner record (for example, renaming `PCP` to `Specialist`) while preserving the associated role metadata such as `effectiveDate` and `terminationDate`. This is a data-correction operation ā€” it does not trigger termination events or lifecycle changes. Use it when a role key was recorded incorrectly at the core practitioner level and needs correcting without invoking the termination lifecycle; for correcting a role at a specific group-practitioner-location record, use `PATCH /practitioners/practitioner-locations/{id}/roles/correct` instead. `{id}` is the `certifyPractitionerId`, and the role key being renamed must already exist on the core practitioner record.

šŸ“„ļøRemove a role from the core practitioner record

Removes a role key from the core practitioner record; the role is set to null and stripped, so it will no longer be included when the practitioner's profile is composed from source records. Use this to permanently remove a role at the core practitioner level ā€” this is not a termination, it removes the role entry entirely rather than setting a termination date. For terminating a role at a specific location-network assignment, use `PUT /practitioners/practitioner-role-assignments/{id}/terminate`; for removing a role at the group-practitioner-location level, use `PATCH /practitioners/practitioner-locations/{id}/roles/remove`. `{id}` is the `certifyPractitionerId`, and the role key being removed must exist on the core practitioner record.

šŸ“„ļøUpdate a practitioner's Social Security Number

Updates the Social Security Number for the specified practitioner. This operation requires elevated permission (`PRACTITIONER_UPDATE_SSN`) beyond standard practitioner update access. Use this only when the SSN on record is incorrect or needs to be set for the first time; SSN is sensitive PII, so access is restricted and audited. `{id}` is the `certifyPractitionerId`. The SSN must be exactly 9 plain digits with no dashes or spaces. This operation always writes ā€” there is no read-then-compare, so resubmitting the same value still performs a write.

šŸ“„ļøReplace all supporting documents for a practitioner

Replaces the practitioner's entire supporting-documents array with the submitted list; this is a full-array replace, not a per-item action-based update ā€” there is no `action` or document-id field in the request, and every submitted item is persisted as the new array. To remove a document, resubmit the array without it; to add a new document without resubmitting the whole array, use `POST /practitioners/{id}/supporting-documents` instead. `{id}` is the `certifyPractitionerId`.

šŸ“„ļøUpload a new supporting document for a practitioner

Uploads and creates a new supporting document for the specified practitioner using a `multipart/form-data` request. Use this when attaching a new document, such as a license, certification, or credential, to a practitioner record for the first time; to update or delete an existing document, use `PUT /practitioners/{id}/supporting-documents` instead. `{id}` is the `certifyPractitionerId`. The request must be `multipart/form-data` with the following fields: `file` (required, the document binary), `fileType` (the document category), `state` (optional), and `expirationDate` (optional). `fileType` is a free-text string with no allowlist enforced. The file is stored in Google Cloud Storage, in a bucket configured per environment.

šŸ“„ļøCreate or update a practitioner-group association

Creates or updates the association between a practitioner and a group as an upsert: if the practitioner is already associated with the group the existing association is updated, otherwise a new association is created. The request body is validated against the TenantGroupPractitioner schema before persistence. Use this when enrolling a practitioner in a group or updating group-level association attributes; note that this operation uses PUT with upsert semantics, so it returns 200 (not 201) even when creating a new association. `{practitionerId}` is the `certifyPractitionerId`, `{groupId}` is the group identifier, and the request body must conform to the `TenantGroupPractitioner` schema.

šŸ“„ļøAssociate or update practitioner locations within a group

Associates the practitioner with one or more locations within the specified group, or updates existing location associations. Each location entry may include `locationData` with an `npi` field as a single string or array of strings for multi-NPI locations. Use this when adding the practitioner to locations within a group, or when updating group-practice location details such as location NPIs; this endpoint handles both creation and update of `GroupPractitionerLocation` relationships and optionally also creates `TenantGroupLocationPractitionerNetwork` relationships for location-specific networks. `{practitionerId}` is the `certifyPractitionerId`, and `{groupId}` in the path must match the `groupId` in the request body ā€” a mismatch returns 400.

šŸ“„ļøList hospital affiliations for a practitioner

Returns the hospital affiliations recorded for the specified practitioner. Source values are normalized to canonical short labels: `MANUAL`, `ROSTER`, or `CAQH`. Use this to retrieve all hospital affiliations linked to a practitioner record; this endpoint is feature-gated, and if the hospital affiliations feature is not enabled for the tenant, the server returns 403. `{practitionerId}` is the `certifyPractitionerId`, and the hospital affiliations feature must be enabled for the tenant.

šŸ“„ļøAdd a hospital affiliation to a practitioner

Creates a new hospital affiliation entry on the practitioner record; the server assigns a stable UUID v4 as the affiliation identifier and returns the full affiliation in the response body. Use this when a practitioner gains a new hospital affiliation that needs to be recorded; no `Location` header is returned in the 201 response, so use the `id` field in the response body to reference the created affiliation. `{practitionerId}` is the `certifyPractitionerId`, and the hospital affiliations feature must be enabled for the tenant (403 returned if not). Only `name` and `type` are required; all other fields are optional, and `endDate` must be on or after `startDate` when both are supplied.

šŸ“„ļøPartially update a practitioner hospital affiliation

Applies a partial update to the specified hospital affiliation; only the fields included in the request body are modified, and absent fields are left unchanged. Use this when one or more attributes of an existing hospital affiliation need to be corrected or updated without replacing the entire record. `{practitionerId}` is the `certifyPractitionerId`, `{affiliationId}` is the UUID assigned by the server when the affiliation was created, and the hospital affiliations feature must be enabled for the tenant. The updatable field set matches `HospitalAffiliationResponse` (the same class returned by the GET and POST endpoints), and the merge is checked against the same case-insensitive `(name, type)` duplicate-detection used on create.

šŸ“„ļøRemove a hospital affiliation from a practitioner

Permanently removes the specified hospital affiliation from the practitioner record. Use this when a hospital affiliation is no longer valid and should be removed; this is a hard delete, and the affiliation cannot be recovered after deletion. `{practitionerId}` is the `certifyPractitionerId`, and `{affiliationId}` is the UUID assigned by the server when the affiliation was created, returned in the `POST` response. The hospital affiliations feature must be enabled for the tenant.

šŸ“„ļøUpdate practitioner location associations within a group

Creates or updates the practitioner's location associations within a group, following upsert semantics ā€” existing associations are updated in place. Each location entry may include `locationData` with an `npi` field as a single string or array of strings; omitted fields are preserved when merging with existing data. Use this when adding the practitioner to locations or updating location-specific data such as group-practice location NPIs; the request body must include a `groupId` to scope the associations. `{practitionerId}` is the `certifyPractitionerId`, and the group identified by `groupId` in the request body must already be associated with the practitioner. Only the locations present in the request are upserted ā€” locations already associated with the practitioner but omitted from the request are left unchanged, not removed.

šŸ“„ļøUpdate practitioner data at a location-network assignment

Updates the practitioner's data for a specific location-network assignment, including effective dates, panel status, whether the practitioner is accepting new patients, roles, specialties, languages, and office hours. Use this when location-network specific attributes for a practitioner need to be changed; if `applyToAllNetworks` is true in the request body, the update is applied to all networks the practitioner is linked to at this location, with the `{networkId}` path parameter used for routing only rather than restricting the scope. `{networkId}` is used once for an existence check regardless of the flag; the actual network set to update is otherwise determined by a query scoped only to the location, except as a fallback (when that query returns nothing) where it falls back to just `{networkId}`. `{practitionerId}` is the `certifyPractitionerId`, and the practitioner must already be associated with the specified location and network.

šŸ“„ļøUpdate NPI and participation date at a location-network

As of CP-36570: updates only the practitioner-agnostic TenantGroupLocationNetwork `addressType2Npi` array (NPI + participation date, supports multiple NPIs per location-network) ā€” no TenantGroupLocationPractitionerNetwork row is written by this endpoint anymore. `{practitionerId}` and the practitioner's association with the location/network are still validated for authorization/existence scoping, but the write itself is location-network scoped, not per-practitioner ā€” NPI is a location-network attribute and cannot be edited at the practitioner-location level alone. Preferred: pass `npiEntries` with the location-network's complete NPI set ā€” it REPLACES the stored `addressType2Npi` array, so an NPI omitted from the list is deleted (the only way to remove one) and an entry without `npiParticipationDate` is stored with no date. Deprecated: the scalar `npi`/`npiParticipationDate` fields still work ā€” pass `null` for either to leave that value unchanged, repeat the call to add/update additional NPIs, `npi` is required to disambiguate `npiParticipationDate` when more than one NPI exists ā€” but they are mutually exclusive with `npiEntries` in the same request. `{practitionerId}` is the `certifyPractitionerId`.

šŸ“„ļøList specialties associated with a practitioner

Returns all specialties the specified practitioner is associated with at the tenant level. Use this to retrieve a practitioner's specialty list; for the raw tenant practitioner specialty records with their internal IDs needed for deletion or correction operations, see the operations under `/tenant-practitioner-specialties`, and for creating a new specialty association, use `POST /practitioners/{practitionerId}/specialties`. `{practitionerId}` is the `certifyPractitionerId`. Terminated associations are included; this endpoint does not filter by termination status.

šŸ“„ļøAssociate a practitioner with a specialty

Associates the practitioner with a specialty at the tenant level, with best-effort cascade to group, location, and network levels. The practitioner-level specialty is always attempted first; lower-level associations are created on a best-effort basis, and failures at those levels do not cause the overall request to fail. Use this when a practitioner gains a new specialty that should be recorded across all applicable levels. `{practitionerId}` is the `certifyPractitionerId`, and the request body must identify the specialty to associate: either `tenantSpecialtyId` or `practitionerRole` must be present, and `data` is required only when `tenantSpecialtyId` is supplied.

šŸ“„ļøPermanently delete a practitioner specialty and dependents

Permanently and irreversibly deletes the specified practitioner specialty record along with all dependent specialty records at the group-location and group-location-network levels, in a single atomic transaction; this cannot be undone. Use it only when a specialty record must be completely removed, for example when it was created in error ā€” to end a specialty with a termination date instead (reversible, preserves history), use `PUT /practitioners/tenant-practitioner-specialties/terminate`. `{practitionerId}` is the `certifyPractitionerId`, and `{tpsId}` is the internal identifier for the `TenantPractitionerSpecialty` record, obtained from the specialty list returned by `GET /practitioners/{practitionerId}/specialties` or related queries. The specialty must not be the primary specialty (`isPrimary=true`); attempting to delete the primary specialty returns an error.