openapi: 3.2.0
info:
description: API for Certify application
title: Certify API Layer Group 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: Group
description: APIs for managing group entities
paths:
/groups:
get:
summary: Find Group by filter criteria with pagination
description: Returns a paginated list of all Groups. Supports both offset-based (page/size) pagination.
operationId: groupFindMany
tags:
- Group
parameters:
- description: Search by Affiliation
name: affiliation
in: query
schema:
type: string
- description: Search by Group name
name: name
in: query
schema:
type: string
- description: Search by NPI
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: 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: Search by TIN
name: tin
in: query
schema:
type: string
- description: Search by Type
name: type
in: query
schema:
type: string
- name: tenant-id
in: header
schema:
type: string
responses:
'200':
description: List of Groups
content:
application/json:
schema:
$ref: '#/components/schemas/PagedResponse'
'401':
description: Unauthorized - User is not authenticated
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
security:
- jwt: []
post:
summary: Create a new group
description: Creates a new group for the request tenant. Supports associating multiple networks during creation.
operationId: groupCreate
tags:
- Group
parameters:
- description: Parent healthcare organization ID (optional)
example: parent-org-123
required: false
name: parentHealthcareOrgId
in: query
schema:
type: string
- name: tenant-id
in: header
schema:
type: string
requestBody:
description: Group data as JSON
content:
application/json:
schema:
$ref: '#/components/schemas/CreateGroupRequest'
required: true
responses:
'201':
description: Group successfully created
content:
application/json:
schema:
$ref: '#/components/schemas/GroupCreateResponse'
'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: {}
'500':
description: Internal server error during request processing (e.g., network timeout, etc.)
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
security:
- jwt: []
/groups/locations/{locationId}/networks:
patch:
summary: Update effective date for all group location network associations
description: Updates the effective date for ALL network associations linked to the specified group location. All networks associated with the location will be updated. The effectiveDate is required and must be in YYYY-MM-DD format.
operationId: updateGroupLocationNetworkDates
tags:
- Group
parameters:
- description: Group Location ID (tenantGroupLocationId)
example: tgl-123
required: true
name: locationId
in: path
schema:
type: string
- name: tenant-id
in: header
schema:
type: string
requestBody:
description: Request containing effectiveDate to update
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateGroupLocationNetworkDatesRequest'
required: true
responses:
'200':
description: Group location network effective date successfully updated
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateGroupLocationNetworkDatesResponse'
'400':
description: Invalid request body or missing required parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
'404':
description: Group location or networks 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: []
post:
summary: Associate a group location with networks
description: Associates an existing group location with one or more networks.
operationId: associateGroupLocationNetworks
tags:
- Group
parameters:
- description: Group Location ID (tenantGroupLocationId)
example: loc-123
required: true
name: locationId
in: path
schema:
type: string
- name: tenant-id
in: header
schema:
type: string
requestBody:
description: Networks to associate with the group location
content:
application/json:
schema:
$ref: '#/components/schemas/AssociateGroupLocationNetworksRequest'
required: true
responses:
'201':
description: Group location successfully associated with networks
content:
application/json:
schema:
$ref: '#/components/schemas/AssociateGroupLocationNetworksResponse'
'400':
description: Invalid request body or missing required 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: {}
'404':
description: Group location or network 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: []
/groups/locations/{locationId}/networks/terminate:
put:
summary: Terminate a group location from networks
description: Terminates a group location from one or more networks by updating TenantGroupLocationNetwork rows. Does not cascade to TenantGroupLocationPractitionerNetwork or other entities.
operationId: terminateGroupLocationFromNetwork
tags:
- Group
parameters:
- description: Group Location ID (tenantGroupLocationId)
example: loc-123
required: true
name: locationId
in: path
schema:
type: string
- name: tenant-id
in: header
schema:
type: string
requestBody:
description: Request containing network IDs to terminate from
content:
application/json:
schema:
$ref: '#/components/schemas/TerminateGroupLocationFromNetworkRequest'
required: true
responses:
'200':
description: Successfully terminated group location from networks
content:
application/json:
schema:
$ref: '#/components/schemas/TerminateGroupLocationFromNetworkResponse'
'400':
description: Bad request - Invalid input or validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
'401':
description: Unauthorized - Authentication required
content:
application/json: {}
'403':
description: Forbidden - Insufficient permissions
content:
application/json: {}
'404':
description: Group location or network not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
security:
- jwt: []
/groups/locations/{locationId}/terminate:
put:
summary: Terminate a group location
description: Terminates a group location from a group. This cascades termination to all related relationships including networks, practitioners, and specialties. User consent must be confirmed before proceeding.
operationId: terminateGroupLocation
tags:
- Group
parameters:
- description: Group Location ID (tenantGroupLocationId)
example: loc-123
required: true
name: locationId
in: path
schema:
type: string
- name: tenant-id
in: header
schema:
type: string
requestBody:
description: Request containing termination details and user consent
content:
application/json:
schema:
$ref: '#/components/schemas/TerminateGroupLocationRequest'
required: true
responses:
'200':
description: Successfully terminated group location
content:
application/json:
schema:
$ref: '#/components/schemas/TerminateGroupLocationResponse'
'400':
description: Bad request - Invalid input, validation error, or consent not confirmed
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
'401':
description: Unauthorized - Authentication required
content:
application/json: {}
'403':
description: Forbidden - Insufficient permissions
content:
application/json: {}
'404':
description: Group location not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
security:
- jwt: []
/groups/{groupId}/locations:
put:
summary: Update group location details
description: Updates location details for multiple locations within a group following the roster ingestion pattern. Updates the data field of TenantGroupLocation entities.
operationId: updateGroupLocations
tags:
- Group
parameters:
- description: ID of the group (certify group ID)
required: true
name: groupId
in: path
schema:
type: string
- name: tenant-id
in: header
schema:
type: string
requestBody:
description: Request containing locations to update
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateGroupLocationsRequest'
required: true
responses:
'200':
description: Successfully updated group location details
content:
application/json:
schema:
$ref: '#/components/schemas/GroupLocationUpdateResponse'
'400':
description: Bad request - Invalid input or validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
'401':
description: Unauthorized - Authentication required
content:
application/json: {}
'403':
description: Forbidden - Insufficient permissions
content:
application/json: {}
'404':
description: Group or location not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
security:
- jwt: []
post:
summary: Add new location to group
description: Adds a new location to a group following the roster ingestion pattern. Creates CoreLocation, GroupLocation, TenantGroupLocation, and optionally CoreEntityAddress and LocationEntityAddress entities.
operationId: addGroupLocation
tags:
- Group
parameters:
- description: Group ID (certifyGroupId)
example: group-123
required: true
name: groupId
in: path
schema:
type: string
- name: tenant-id
in: header
schema:
type: string
requestBody:
description: Location data to add to the group
content:
application/json:
schema:
$ref: '#/components/schemas/AddGroupLocationRequest'
required: true
responses:
'201':
description: Successfully added location to group
content:
application/json:
schema:
$ref: '#/components/schemas/AddGroupLocationResponse'
'400':
description: Bad request - Invalid input or validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
'401':
description: Unauthorized - Authentication required
content:
application/json: {}
'403':
description: Forbidden - Insufficient permissions
content:
application/json: {}
'404':
description: Group not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
security:
- jwt: []
/groups/{groupId}/networks:
put:
summary: Update group network associations
description: Updates a group's network associations following the roster ingestion pattern. Associates a group with one or more networks, creating or updating TenantGroupNetwork relationships.
operationId: updateGroupNetworks
tags:
- Group
parameters:
- description: ID of the group (certify group ID)
required: true
name: groupId
in: path
schema:
type: string
- name: tenant-id
in: header
schema:
type: string
requestBody:
description: Request containing networks to update
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateGroupNetworksRequest'
required: true
responses:
'200':
description: Successfully updated group network associations
content:
application/json:
schema:
$ref: '#/components/schemas/GroupNetworkUpdateResponse'
'400':
description: Bad request - Invalid input or validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
'401':
description: Unauthorized - Authentication required
content:
application/json: {}
'403':
description: Forbidden - Insufficient permissions
content:
application/json: {}
'404':
description: Group or network not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
security:
- jwt: []
/groups/{groupId}/networks/terminate:
patch:
summary: Terminate group participation in networks
description: Terminates TenantGroupNetwork for the group and cascades to TenantGroupPractitionerNetwork and TenantGroupLocationNetwork only (CP-28229). Does not modify core group, practitioner, or location membership rows.
operationId: terminateGroupNetworks
tags:
- Group
parameters:
- description: ID of the group (certify group ID)
required: true
name: groupId
in: path
schema:
type: string
- name: tenant-id
in: header
schema:
type: string
requestBody:
description: Networks to terminate and termination metadata
content:
application/json:
schema:
$ref: '#/components/schemas/TerminateGroupNetworksRequest'
required: true
responses:
'200':
description: Successfully terminated group network participation
content:
application/json:
schema:
$ref: '#/components/schemas/TerminateGroupNetworksResponse'
'400':
description: Bad request - Invalid input or validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
'401':
description: Unauthorized - Authentication required
content:
application/json: {}
'403':
description: Forbidden - Insufficient permissions
content:
application/json: {}
'404':
description: Group or network association not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
security:
- jwt: []
/groups/{id}:
put:
summary: Update a group
description: Updates an existing group based on the group ID.
operationId: groupUpdate
tags:
- Group
parameters:
- description: Group ID
example: '1234567890'
required: true
name: id
in: path
schema:
type: string
- name: tenant-id
in: header
schema:
type: string
requestBody:
description: Group data as JSON
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateGroupRequest'
required: true
responses:
'200':
description: Group successfully updated
content:
application/json:
schema:
$ref: '#/components/schemas/GroupResponse'
'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: {}
'404':
description: Group not found
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: []
get:
summary: Get a group value by their ID
description: Returns a single group by their ID
operationId: groupGet
tags:
- Group
parameters:
- description: Group ID
example: '1234567890'
required: true
name: id
in: path
schema:
type: string
- name: tenant-id
in: header
schema:
type: string
responses:
'200':
description: Group successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/JsonNode'
'404':
description: Group not found with the given ID for tenant
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
security:
- jwt: []
/groups/{id}/practitioners:
post:
summary: Associate practitioners with a group
description: Associates one or more practitioners with a group. Optionally associates practitioners with specific group locations.
operationId: associateGroupPractitioners
tags:
- Group
parameters:
- description: Group ID (tenantGroupId)
example: group-123
required: true
name: id
in: path
schema:
type: string
- name: tenant-id
in: header
schema:
type: string
requestBody:
description: Practitioners to associate with the group
content:
application/json:
schema:
$ref: '#/components/schemas/AssociateGroupPractitionersRequest'
required: true
responses:
'201':
description: Practitioners successfully associated with the group
content:
application/json:
schema:
$ref: '#/components/schemas/AssociateGroupPractitionersResponse'
'400':
description: Invalid request body or missing required 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: {}
'404':
description: Group, practitioner, or location 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: []
/groups/{id}/relationships/all:
get:
summary: Get all the relationships of the group
description: Get all the relationships of the group
operationId: getAllGroupRelationships
tags:
- Group
parameters:
- description: Group ID
example: '1234567890'
required: true
name: id
in: path
schema:
type: string
- name: tenant-id
in: header
schema:
type: string
responses:
'200':
description: All the relationships that the group belongs to successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/JsonNode'
'401':
description: Unauthorized - Authentication required
content:
application/json: {}
'403':
description: Forbidden - Insufficient permissions
content:
application/json: {}
'404':
description: Group not found with the given ID for tenant
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
security:
- jwt: []
/groups/{id}/specialties:
put:
summary: Update a group specialty
description: Updates the effective date and/or termination date of an existing group specialty.
operationId: groupUpdateSpecialty
tags:
- Group
parameters:
- description: Group ID
example: '1234567890'
required: true
name: id
in: path
schema:
type: string
- name: tenant-id
in: header
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateGroupSpecialtyRequest'
required: true
responses:
'200':
description: Group 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: Group specialty not found with the given ID for tenant
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: []
patch:
summary: Batch add and update group specialties
description: Adds new and/or updates existing group specialties in a single request. Updates modify existing TenantGroupSpecialty records while additions create new specialty associations.
operationId: manageGroupSpecialties
tags:
- Group
parameters:
- description: Group ID
required: true
name: id
in: path
schema:
type: string
- name: tenant-id
in: header
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ManageGroupSpecialtiesRequest'
required: true
responses:
'200':
description: Group specialties successfully managed
content:
application/json:
schema:
$ref: '#/components/schemas/ManageGroupSpecialtiesResponse'
'400':
description: Invalid request body or missing required parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
'500':
description: Internal server error
content:
application/json: {}
security:
- jwt: []
post:
summary: Add a specialty to a group
description: Adds a new specialty to an existing group. Optionally can also add the specialty to a specific group location.
operationId: groupAddSpecialty
tags:
- Group
parameters:
- description: Group ID
example: '1234567890'
required: true
name: id
in: path
schema:
type: string
- name: tenant-id
in: header
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateGroupSpecialtyRequest'
required: true
responses:
'201':
description: Group specialty successfully created
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 not found with the given ID for tenant
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: []
/groups/{id}/specialties/terminate:
post:
summary: Terminate group specialties from network participation
description: Terminates one or more specialties from a group for network participation. Applies effective-dated termination at group–network association; optionally at group-location and group-level. Previous state is preserved for audit.
operationId: terminateGroupSpecialties
tags:
- Group
parameters:
- description: Group ID
example: '1234567890'
required: true
name: id
in: path
schema:
type: string
- name: tenant-id
in: header
schema:
type: string
requestBody:
description: 'Termination request. Required: specialtyIds (standard Specialty IDs), terminationEffectiveDate, acknowledgementConfirmed. Optional: networkIds (standard Network IDs), terminationInformedDate, terminationReason, terminateAtGroupLocationSpecialties, terminateAtGroupLevel. All IDs are standard (certify) identifiers only.'
content:
application/json:
schema:
$ref: '#/components/schemas/TerminateGroupSpecialtyRequest'
required: true
responses:
'200':
description: Group specialties successfully terminated
content:
application/json:
schema:
$ref: '#/components/schemas/TerminateGroupSpecialtyResponse'
'400':
description: Bad request - Invalid input, validation error, or acknowledgement not confirmed
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError1'
'401':
description: Unauthorized - Authentication required
content:
application/json: {}
'403':
description: Forbidden - Insufficient permissions
content:
application/json: {}
'404':
description: Group or group specialty not found
# --- truncated at 32 KB (95 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/certifyos/refs/heads/main/openapi/certifyos-group-api-openapi.yml