Group API

Group API

Patients and clinicians may be assigned to groups. Groups are used for filtering and other purposes.

Groups are combined into the Group Tree (a hierarchy of groups). More precisely, groups are combined into two distinct Group Trees: Patient Groups and Provider Groups. Those two group trees do not intersect; i.e.: The provider cannot be assigned to a Patient Group and vice versa.

Each hospital has its own groups which also do not intersect.

In theory, a user may be assigned to any group(s)/subgroup(s), but our API respects the hierarchical structure, and users assigned to a subgroup will also be assigned to all of its parent groups. However, a user may be assigned to some parent groups but none of its subgroups.

Patient and Provider Group APIs are almost symmetric, although the Provider Group API is older and contains some outdated methods.

As read-only API methods are accessible by any registered user, methods which create/modify/delete groups are accessible by hospital admins. No other permissions (role functions) are checked!

Patient Groups API

Get Group Tree (new)

URL	GET https://{{host}}/api/v2/patients/groups/tree
Result	List<PatientsGroupResponse>

Returns either specified group with subgroups or a list of top-level groups with subgroups..

Query parameters

Name	Description	Type	Additional information
groupId	Id of the group to return subtree or null to return top-level groups.	integer	None.
maxDepth	Include maximum maxDepth levels of hiererchy. Non-positive values are considered as 1.	integer	Default value is 2147483647
subgroups	Blank-separated list of subgroups ids which should be included to the response regardless of maxDepth.	string	None.
includeMembers	Include patientIds of group members.	boolean	Default value is False

---

Get Complete Group Tree

Use v2/patients/groups/tree instead if the complete tree is not need.

URL	GET https://{{host}}/api/v2/patients/groups
Query parameters	no
Body	no
Result	List<PatientsGroupResponse>

Returns complete patient group tree along with patients assigned to each group. Result is a list of all top-level groups with members (patients) and subgroups.

Get Groups Assigned to Particular Patient

URL	GET https://{{host}}/api/v2/patients/groups
Query parameters	patientId=<int>
Body	no
Result	List<PatientsGroupResponse>

Returns a list of groups (at any hierarchy level) assigned to a patient with given patientId. No members or subgroups for groups are returned, only the groups themselves.

Get Particular Patients Group

URL	GET https://{{host}}/api/v2/patients/groups/{groupId}
Query parameters	includeMembers=<bool> (default true)
Body	no
Result	PatientsGroupResponse

Returns a group with specified groupId along with members and subgroups.

Create or Update Patients Group

URL	POST https://{{host}}/api/v2/patients/groups PUT https://{{host}}/api/v2/patients/groups/{groupId}
Query parameters	no
Body	PatientsGroupRequest
Result	PatientsGroupResponse

Creates (if groupId==null, for POST only) or updates (if groupId!=null) patients group. May change any parameter of the group, including parent group id, thus changing the groups' hierarchy. Cannot create subgroups.

This method is also able to assign patients to a group (PatientsIds property of the request body), but it is not recommended, because it cannot un-assign patients and is inconsistent with hierarchical group structure. Use "v2/patients/groups/patients" methods below instead.

Returns updated group definition with complete subtree (subgroups property) and assigned patients (members property).

Remove Patients Group

URL	DELETE https://{{host}}/api/v2/patients/groups/{groupId}
Query parameters	no
Body	no
Result	HTTP response code and string message

Removes the group with all its subgroups. If a group or any subgroup contains patients, request fails.

Assign Patients to Groups

URL	POST https://{{host}}/api/v2/patients/groups/patients PUT https://{{host}}/api/v2/patients/groups/patients
Query parameters	no
Body	int[] GroupsIds
int[] PatientsIds
Result	HTTP response code

Assigns all specified patients to all specified groups and their parents up to the top-level groups.

PUT method just adds specified patients to groups; POST completely replaces assigned patients in the groups.

Remove Patients from Groups

URL	DELETE https://{{host}}/api/v2/patients/groups/patients
Query parameters	no
Body	int[] GroupsIds
int[] PatientsIds
Result	HTTP response code

Removes all specified patients from all specified groups and their subgroups down to the terminal level groups.

PUT method just adds specified patients to groups; POST completely replaces assigned patients in the groups.

Provider Groups API

Warning. ClinicianId in this API is actually User.UserId, not HospitalStaffProfile.StaffId.

Get Complete Group Tree

URL	GET https://{{host}}/api/v2/clinicians/groups
Query parameters	no
Body	no
Result	List<ClinicianGroupResponse>

Returns complete provider groups tree along with providers assigned to each group. Result is a list of all top-level groups with members (providers) and subgroups.

Get Groups Assigned to Particular Provider

URL	GET https://{{host}}/api/v2/clinicians/groups
Query parameters	clinicianId=<int>
Body	no
Result	List<ClinicianGroupResponse>

Returns a list of groups (at any hierarchy level) assigned to a clinician with given clinicianId (which is actually userId ). No members or subgroups for groups are returned, only the groups themselves.

Get Particular Providers Group

URL	GET https://{{host}}/api/v2/clinicians/groups/{groupId}
Query parameters	no
Body	no
Result	ClinicianGroupResponse

Returns a group with specified groupId along with members and subgroups.

Create or Update Providers Group

URL	POST https://{{host}}/api/v2/clinicians/groups PUT https://{{host}}/api/v2/clinicians/groups/{groupId}
Query parameters	no
Body	ClinicianGroupRequest
Result	ClinicianGroupResponse

Creates (if groupId==null, for POST only) or updates (if groupId!=null) providers group. May change any parameter of the group, including parent group id, thus changing groups' hierarchy. Cannot create subgroups.

This method is also able to assign providers to a group (ClinicianIds is property of the request body), but it is not recommended, because it cannot un-assign providers and is inconsistent with hierarchical groups structure. Use "v2/clinicians/groups/clinicians" methods below instead.

Returns updated group definition with complete subtree (subgroups property) and assigned providers (members property).

Remove Providers Group

URL	DELETE https://{{host}}/api/v2/clinicians/groups/{groupId}
Query parameters	no
Body	no
Result	HTTP response code and string message

Removes the group with all its subgroups. If a group or any subgroup contains providers, request fails.

Assign Providers to Groups

URL	POST https://{{host}}/api/v2/clinicians/groups/clinicians
Query parameters	no
Body	int[] GroupsIds
int[] ClinicianIds
Result	HTTP response code

Assigns all specified providers to all specified groups and their parents up to the top level groups. Group assignment is completely replaced, so providers not in a list are removed from a group.

PUT method just adds specified providers to groups; POST completely replaces assigned providers in the groups.

Assign Providers to a Group

URL	PUT https://{{host}}/api/v2/ clinicians/groups/{groupId}/clinicians
Query parameters	no
Body	int[] ClinicianIds
Result	HTTP response code

Assigns all specified providers to a specified group and its parents up to the top level groups.

Remove Providers from a Group

URL	DELETE https://{{host}}/api/v2/clinicians/groups/{groupId}/clinicians
Query parameters	no
Body	int[] ClinicianIds
Result	HTTP response code

Removes all specified providers from a specified group and its subgroups down to the terminal level groups.

Remove Providers from a Group (obsolete)

URL	DELETE https://{{host}}/api/v2/clinicians/groups/{groupId}/clinicians/{clinicianId}
Query parameters	no
Body	int[] ClinicianIds
Result	HTTP response code

Removes specified provider from a specified group.

This method is not recommended, because it does not remove provider from subgroups. Use "v2/clinicians/groups/{groupId}/clinicians" above instead.