Groups

Groups provide a mechanism to group data, for example locations might be grouped by region, care enquiries by the source referrer.

The group object

Attributes

  • _id
    string

    A unique Id for the group.

  • archived
    boolean

    Flag indicating if the group is currently archived.

  • created
    string

    The date/time the group was created.

  • description
    string

    A description of the groups.

  • group_type
    string

    The group's designated group type. Groups are organized by type with different types of group being used as options for different fields within CareHQ. The following group types are supported; absence_reason, action_tag, comms_tag, competitor, competitor_type, complaint_subject_matter, day_care_session_type, enquiry_close_reason, leave_reason, location_contact_tag, location_group, sales_channel, referrer_type, referrer, room_feature, ledger, ledger_expense_category.

  • modified
    string

    The date/time the group was modified.

  • name
    string

    The group's name.

  • nominal_code
    string

    A nominal code assigned to an expense category.

  • parent_group
    string

    The Id of the group's parent group. Some groups are further grouped under a parent group, if so then a parent group Id will be present.

  • protected
    string

    A flag indicating if the group is protected. Protected groups cannot be updated or deleted. They can be renamed on request by a member of the CareHQ team.

The group object
{
    "_id": "66bfb4bb9ab4e3d6eb7348f8",
    "archived": false,
    "created": "2024-08-16 20:21:15",
    "description": null,
    "group_type": "location_group",
    "modified": "2024-08-16 20:21:15",
    "name": "North",
    "nominal_code": null,
    "parent_group": null,
    "protected": null
}

List all groups

Return a list of groups setup for your account on CareHQ.

Parameters

  • attributes
    optional
    default ['_id']

    A list of attributes to include for fetched objects.

  • filters-archived
    optional
    default no

    A filter that allows groups that are currently archived to be included or excluded.

    • unset
    • yes
    • no
  • filters-group_type
    optional

    A filter that accepts a list of group types and filters groups by their type.

    • absence_reason
    • action_tag
    • comms_tag
    • competitor
    • competitor_type
    • complaint_subject_matter
    • day_care_session_type
    • enquiry_close_reason
    • leave_reason
    • location_contact_tag
    • location_group
    • sales_channel
    • referrer_type
    • referrer
    • room_feature
    • ledger
    • ledger_expense_category
  • filters-ids
    optional

    A filter that accepts a list of Ids and filters the items returned to those with an Id in the list.

  • filters-modified_after
    optional

    A filter that accepts a date/time and filters the items returned to those modified after the date/time.

  • filters-modified_before
    optional

    A filter that accepts a date/time and filters the items returned to those modified before the date/time.

  • filters-q
    optional

    A case insensitive keyword filter applied to the following fields; name.

  • page
    optional
    default 1

    The page number to fetch.

  • per_page
    optional
    default 10

    The number of items to return per page.

  • sort_by
    optional
    default _id

    A list of fields the returned items can be sorted by. Fields prefixed with minus (-) sign are sorted in descending order.

    • _id
    • created
    • modified
    • name

Response

Returns a page of groups.

GET
/v1/groups
var groups = apiClient.Request(
    HttpMethod.Get,
    "groups",
    new MultiValueDict()
        .Add("attributes", "name")
        .Add("filters-group_types", locationGroup)
);
<?php

$groups = $api_client->request(
    'GET',
    'groups',
    [
        'attributes'=>['name'],
        'filters-group_types'=>['location_group']
    ]
);
groups = api_client(
    'GET',
    'groups',
    params={
        'attributes': ['name'],
        'filters-group_types': ['location_group']
    }
)
groups = api_client.request(
    'GET',
    'groups',
    params: {
        'attributes' => ['name'],
        'filters-group_types' => ['location_group']
    }
)
Response
{
    "item_count": 111,
    "items": [
        {
            "_id": "66bfb4bb9ab4e3d6eb73481e",
            "name": "Appointment"
        },
        {
            "_id": "66bfb4bb9ab4e3d6eb734820",
            "name": "Day trip"
        },
        {
            "_id": "66bfb4bb9ab4e3d6eb734822",
            "name": "Hospital admission"
        },
        {
            "_id": "66bfb4bb9ab4e3d6eb734824",
            "name": "Resident sign out"
        },
        {
            "_id": "66bfb4bb9ab4e3d6eb734826",
            "name": "Finance"
        },
        {
            "_id": "66bfb4bb9ab4e3d6eb734828",
            "name": "Care home"
        },
        {
            "_id": "66bfb4bb9ab4e3d6eb73482a",
            "name": "Home care"
        },
        {
            "_id": "66bfb4bb9ab4e3d6eb73482c",
            "name": "Hospice"
        },
        {
            "_id": "66bfb4bb9ab4e3d6eb73482e",
            "name": "Quality of care"
        },
        {
            "_id": "66bfb4bb9ab4e3d6eb734830",
            "name": "Staff behaviour"
        }
    ],
    "page": 1,
    "page_count": 12,
    "per_page": 10
}

Retrieve a group

Retrieve a group object.

Response

Returns a group object.

GET
/v1/groups/<group_id>
var group = apiClient.Request(HttpMethod.Get, $"groups/{groupId}");
<?php

$group = $api_client->request('GET', 'groups/' . $group_id);
group = api_client('GET', f'groups/{group_id}')
group = api_client.request('GET', "groups/#{group_id}")
Response
{
    "_id": "66bfb4bb9ab4e3d6eb7348f8",
    "archived": false,
    "created": "2024-08-16 20:21:15",
    "description": null,
    "group_type": "location_group",
    "modified": "2024-08-16 20:21:15",
    "name": "North",
    "nominal_code": null,
    "parent_group": null,
    "protected": null
}