Events

An event on a location's calendar. Events appear as 'other' events on the calendar, they don't relate to other documents and are used purely to provide visibility of events outside of those managed through the CareHQ application.

The event object

Attributes

  • _id
    string

    A unique Id for the event.

  • created
    string

    The date/time the event was created.

  • end_date
    string

    The date the event ends.

  • end_time
    string

    The time the event ends.

  • location
    string

    The Id of the location this event is associated with.

  • modified
    string

    The date/time the group was modified.

  • start_date
    string

    The date the event starts.

  • start_time
    string

    The time the event starts.

  • title
    string

    A short description of the event.

The event object
{
    "_id": "66bfb4bc9ab4e3d6eb734922",
    "created": "2024-08-16 20:21:16",
    "end_date": "2024-08-18",
    "end_time": "13:00",
    "location": "66bfb4bb9ab4e3d6eb734900",
    "modified": "2024-08-16 20:21:16",
    "start_date": "2024-08-18",
    "start_time": "10:00",
    "title": "Open morning"
}

List all events

Return a list of calendar events.

Parameters

  • attributes
    optional
    default ['_id']

    A list of attributes to include for fetched objects.

  • filters-end_date
    optional

    A filter that accepts a date and filters events to those that start on or before the given date.

  • 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-location
    optional

    A filter that accepts a list of location Ids and filters events by the location they are associated with.

  • 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; title.

  • filters-start_date
    optional

    A filter that accepts a date and filters events to those that start on or after the given date.

  • 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
    • end_date_time
    • modified
    • start_date_time

Response

Returns a page of events.

GET
/v1/events
var events = apiClient.Request(
    HttpMethod.Get,
    "events",
    new MultiValueDict()
        .Add("attributes", "title", "start_date", "start_time")
        .Add("filters-location", locationId)
        .Add("sort_by", "start_date_time")
);
<?php

$events = $api_client->request(
    'GET',
    'events',
    [
        'attributes'=>['title', 'start_date', 'start_time'],
        'filters-location'=>$location_id,
        'sort_by'=>'start_date_time'
    ]
);
events = api_client(
    'GET',
    'events',
    params={
        'attributes': ['title', 'start_date', 'start_time'],
        'filters-location': location_id,
        'sort_by': 'start_date_time'
    }
)
events = api_client.request(
    'GET',
    'events',
    params: {
        'attributes' => ['title', 'start_date', 'start_time'],
        'filters-location' => location_id,
        'sort_by' => 'start_date_time'
    }
)
Response
{
    "item_count": 2,
    "items": [
        {
            "_id": "66bfb4bc9ab4e3d6eb734922",
            "start_date": "2024-08-18",
            "start_time": "10:00",
            "title": "Open morning"
        },
        {
            "_id": "66bfb4bc9ab4e3d6eb734920",
            "start_date": "2024-08-20",
            "start_time": null,
            "title": "CQC inspection"
        }
    ],
    "page": 1,
    "page_count": 1,
    "per_page": 10
}

Retrieve an event

Retrieve an event object.

Response

Returns an event object.

GET
/v1/events/<event_id>
var event = apiClient.Request(HttpMethod.Get, $"events/{eventId}");
<?php

$event = $api_client->request('GET', 'events/' . $event_id);
event = api_client('GET', f'events/{event_id}')
event = api_client.request('GET', "events/#{event_id}")
Response
{
    "_id": "66bfb4bc9ab4e3d6eb734922",
    "created": "2024-08-16 20:21:16",
    "end_date": "2024-08-18",
    "end_time": "13:00",
    "location": "66bfb4bb9ab4e3d6eb734900",
    "modified": "2024-08-16 20:21:16",
    "start_date": "2024-08-18",
    "start_time": "10:00",
    "title": "Open morning"
}