Home visits

A visit by a care seeker to a location (care home) either in-person or via a virtual format (such video call).

Endpoints

The home visit object

Attributes

  • _id
    string

    A unique Id for the home visit.

  • anonymized
    string

    The date/time the home visit was anonymized (if anonymized).

  • assigned_to
    string

    The user the home visit is assigned to.

  • cancelled
    string

    The date/time the home visit was cancelled (if cancelled).

  • care_enquiry
    string

    The Id of the care enquiry this home visit has been booked for.

  • completed
    string

    The date/time the home visit was completed (if completed).

  • created
    string

    The date/time the home visit was created.

  • date_time
    string

    The date/time of the visit.

  • host
    string

    The host for the visit designated by their role at the location; manager, deputy_manager, administrator, receptionist, senior_carer, carer, customer_relations_adviser, nurse, other.

  • location
    string

    The Id of the location this home visit is to.

  • modified
    string

    The date/time the home visit was modified.

  • notes
    string

    Notes regarding the visit.

  • service_user_contact
    string

    The Id of the service user contact who will attend the home during the visit. This is optional, if not specified then the care seeker associated with the care enquiry will be attending.

  • visit_type
    string

    The type of visit booked; in_person, virtual.

The home visit object 
{
    "_id": "66bfb4c09ab4e3d6eb735681",
    "anonymized": null,
    "assigned_to": "66bfb4bb9ab4e3d6eb73490c",
    "cancelled": null,
    "care_enquiry": "66bfb4c09ab4e3d6eb73567f",
    "completed": "2024-08-11 15:30:00",
    "created": "2024-08-16 20:21:20",
    "date_time": "2024-08-11 14:30:00",
    "host": "manager",
    "location": "66bfb4bb9ab4e3d6eb734900",
    "modified": "2024-08-16 20:21:20",
    "notes": "",
    "service_user_contact": null,
    "visit_type": "in_person"
}

Create a home visit

Unless suppressed creating a home visit will if possible send a confirmation email to the care seeker regarding their visit.

Parameters

  • assigned_to
    optional

    The Id of the user the home visit is assigned to. If you do not specify a user then CareHQ will allocate the home visit to the user the care enquiry is assigned to.

  • care_enquiry
    required

    The Id of the care enquiry the home visit relates to.

  • date_time
    required

    The date/time the home visit is booked for.

  • host
    required

    The job title of the staff member who will host the visit.

    • manager
    • deputy_manager
    • administrator
    • receptionist
    • senior_carer
    • carer
    • customer_relations_adviser
    • nurse
  • notes
    optional

    Any notes regarding the visit.

  • service_user_contact
    optional

    The Id of the service user contact that will attend the visit (if not specified then the care seeker for the care enquiry will be recorded as the attendee).

  • suppress_email
    optional

    Flag indicating if the email sent to care seekers confirming their visit should be suppressed.

  • visit_type
    required
    • in_person
    • virtual

Response

Returns the home visit object created.

PUT
/v1/home-visits
var homeVisit = apiClient.Request(
    HttpMethod.Put,
    "home-visits",
    null,
    new MultiValueDict()
        .Add("care_enquiry", care_enquiry_id)
        .Add("date_time", visit_date_time)
        .Add("host", "manager")
        .Add("notes", "Care seeker has requested to view ground floor rooms.")
        .Add("visit_type", "in_person")
);

<?php

$comment = $api_client->request(
    'PUT',
    'home-visits',
    NULL
    [
        'care_enquiry'=>$care_enquiry_id,
        'date_time'=>$visit_date_time,
        'host'=>'manager',
        'notes'=>'Care seeker has requested to view ground floor rooms.',
        'visit_type'=>'in_person'
    ]
);

home_visit = api_client(
    'PUT',
    'home-visits',
    data={
        'care_enquiry': care_enquiry_id,
        'date_time': visit_date_time,
        'host': 'manager',
        'notes': 'Care seeker has requested to view ground floor rooms.',
        'visit_type': 'in_person'
    }
)

home_visit = api_client.request(
    'PUT',
    'home-visits',
    data: {
        'care_enquiry' => care_enquiry_id,
        'date_time' => visit_date_time,
        'host' => 'manager',
        'notes' => 'Care seeker has requested to view ground floor rooms.',
        'visit_type' => 'in_person'
    }
)
Response 
{
    "_id": "66bfb4d9c3d53f8d1dead159",
    "assigned_to": "66bfb4bb9ab4e3d6eb734906",
    "cancelled": null,
    "care_enquiry": "66bfb4d99ab4e3d6eb73601a",
    "completed": null,
    "created": "2024-08-16 20:21:45",
    "date_time": "2024-08-18 11:00:00",
    "host": "manager",
    "location": "66bfb4bb9ab4e3d6eb734900",
    "modified": "2024-08-16 20:21:45",
    "notes": "Care seeker has requested to view ground floor rooms.",
    "service_user_contact": null,
    "visit_type": "in_person"
}

List all home visits

Return a list of home visits booked for care seekers.

Parameters

  • attributes
    optional
    default ['_id']

    A list of attributes to include for fetched objects.

  • filters-anonymized
    optional
    default unset

    A filter that allows home visits to be filtered by whether the visit is anonymized.

    • unset
    • yes
    • no
  • filters-assigned_to
    optional

    A filter that accepts a list of user Ids and filters home visits by the user they are assigned.

  • filters-cancelled
    optional
    default unset

    A filter that allows home visits to be filtered by whether the visit is cancelled.

    • unset
    • yes
    • no
  • filters-care_enquiry
    optional

    A filter that accepts a list of care enquiry Ids and filters home visits by the enquiry the visit has been booked for.

  • filters-completed
    optional
    default unset

    A filter that allows home visits to be filtered by whether the visit is completed.

    • unset
    • yes
    • no
  • filters-end_date
    optional

    A filter that accepts a date and filters home visits to those booked before or on the end 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 home visits by the location they are to.

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

  • filters-start_date
    optional

    A filter that accepts a date and filters home visits to those booked after or on the start date.

  • filters-visit_type
    optional

    A filter that allows home visits to be filtered by type.

    • in_person
    • virtual
  • 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

Response

Returns a page of home visits.

GET
/v1/home-visits
var homeVisits = apiClient.Request(
    HttpMethod.Get,
    "home-visits",
    new MultiValueDict()
        .Add("attributes", "care_enquiry", "date_time", "host", "notes")
        .Add("filters-cancelled", "no")
        .Add("filters-completed", "no")
);

<?php

$home_visits = $api_client->request(
    'GET',
    'home-visits',
    [
        'attributes'=>['care_enquiry', 'date_time', 'host', 'notes'],
        'filters-cancelled'=>'no',
        'filters-completed'=>'no'
    ]
);

home_visits = api_client(
    'GET',
    'home-visits',
    params={
        'attributes': ['care_enquiry', 'date_time', 'host', 'notes'],
        'filters-cancelled': 'no',
        'filters-completed': 'no'
    }
)

home_visits = api_client.request(
    'GET',
    'home-visits',
    params: {
        'attributes'=>['care_enquiry', 'date_time', 'host', 'notes'],
        'filters-cancelled'=>'no',
        'filters-completed'=>'no'
    }
)
Response 
{
    "item_count": 23,
    "items": [
        {
            "_id": "66bfb4bf9ab4e3d6eb73532a",
            "care_enquiry": "66bfb4bf9ab4e3d6eb735328",
            "date_time": "2022-12-02 12:52:00",
            "host": "manager",
            "notes": ""
        },
        {
            "_id": "66bfb4bf9ab4e3d6eb73534a",
            "care_enquiry": "66bfb4bf9ab4e3d6eb735348",
            "date_time": "2022-12-11 10:18:00",
            "host": "deputy_manager",
            "notes": ""
        },
        {
            "_id": "66bfb4bf9ab4e3d6eb7353a8",
            "care_enquiry": "66bfb4bf9ab4e3d6eb7353a6",
            "date_time": "2023-01-27 16:24:00",
            "host": "deputy_manager",
            "notes": ""
        },
        {
            "_id": "66bfb4bf9ab4e3d6eb7353e1",
            "care_enquiry": "66bfb4bf9ab4e3d6eb7353df",
            "date_time": "2023-03-12 16:22:00",
            "host": "manager",
            "notes": ""
        },
        {
            "_id": "66bfb4bf9ab4e3d6eb73547b",
            "care_enquiry": "66bfb4bf9ab4e3d6eb735479",
            "date_time": "2023-06-02 14:35:00",
            "host": "manager",
            "notes": ""
        },
        {
            "_id": "66bfb4bf9ab4e3d6eb73548a",
            "care_enquiry": "66bfb4bf9ab4e3d6eb735488",
            "date_time": "2023-06-16 14:13:00",
            "host": "manager",
            "notes": ""
        },
        {
            "_id": "66bfb4bf9ab4e3d6eb73548e",
            "care_enquiry": "66bfb4bf9ab4e3d6eb73548c",
            "date_time": "2023-06-28 10:08:00",
            "host": "manager",
            "notes": ""
        },
        {
            "_id": "66bfb4bf9ab4e3d6eb73549c",
            "care_enquiry": "66bfb4bf9ab4e3d6eb73549a",
            "date_time": "2023-07-04 13:42:00",
            "host": "manager",
            "notes": ""
        },
        {
            "_id": "66bfb4bf9ab4e3d6eb7354c2",
            "care_enquiry": "66bfb4bf9ab4e3d6eb7354c0",
            "date_time": "2023-08-01 08:20:00",
            "host": "manager",
            "notes": ""
        },
        {
            "_id": "66bfb4bf9ab4e3d6eb7354db",
            "care_enquiry": "66bfb4bf9ab4e3d6eb7354d9",
            "date_time": "2023-08-18 09:46:00",
            "host": "manager",
            "notes": ""
        }
    ],
    "page": 1,
    "page_count": 3,
    "per_page": 10
}

Retrieve a home visit

Retrieve a home visit object.

Response

Returns a home visit object.

GET
/v1/home-visits/<home_visit_id>
var homeVisit = apiClient.Request(
    HttpMethod.Get,
    $"home-visits/{homeVisitId}"
);

<?php

$home_visit = $api_client->request(
    'GET',
    'home-visits/' . $home_visit_id
);

home_visit = api_client('GET', f'home-visits/{home_visit_id}')

home_visit = api_client.request('GET', "home-visits/#{home_visit_id}")
Response 
{
    "_id": "66bfb4c09ab4e3d6eb735681",
    "anonymized": null,
    "assigned_to": "66bfb4bb9ab4e3d6eb73490c",
    "cancelled": null,
    "care_enquiry": "66bfb4c09ab4e3d6eb73567f",
    "completed": "2024-08-11 15:30:00",
    "created": "2024-08-16 20:21:20",
    "date_time": "2024-08-11 14:30:00",
    "host": "manager",
    "location": "66bfb4bb9ab4e3d6eb734900",
    "modified": "2024-08-16 20:21:20",
    "notes": "",
    "service_user_contact": null,
    "visit_type": "in_person"
}

Update a home visit

Home visits can only be updated if they are pending (not cancelled or completed).

Unless suppressed updating the date/time of a home visit will if possible send a confirmation email to the care seeker regarding their new visit time.

Parameters

  • assigned_to
    required

    The Id of the user the home visit is assigned to. If you do not specify a user then CareHQ will allocate the home visit to the user the care enquiry is assigned to.

  • date_time
    required

    The date/time the home visit is booked for.

  • host
    required

    The job title of the staff member who will host the visit.

    • manager
    • deputy_manager
    • administrator
    • receptionist
    • senior_carer
    • carer
    • customer_relations_adviser
    • nurse
  • notes
    optional

    Any notes regarding the visit.

  • suppress_email
    optional

    Flag indicating if the email sent to care seekers confirming their visit should be suppressed.

  • visit_type
    required
    • in_person
    • virtual

Response

Returns the home visit object updated.

PATCH
/v1/home-visits/<home_visit_id>
var action = apiClient.Request(
    HttpMethod.Patch,
    $"home-visits/{home_visit_id}",
    null,
    new MultiValueDict()
        .Add("date_time, visitDateTime)
);

<?php

$comment = $api_client->request(
    'PATCH',
    'home-visits/' . home_visit_id,
    NULL
    ['date_time'=>visit_date_time]
);

home_visit = api_client(
    'PATCH',
    f'home-visits/{home_visit_id}',
    data={'date_time': visit_date_time}
)

action = api_client.request(
    'PATCH',
    "home-visits/#{home_visit_id}",
    data: {
        'date_time'=>visit_date_time
    }
)
Response 
{
    "_id": "66bfb4d99ab4e3d6eb736022",
    "assigned_to": "66bfb4bb9ab4e3d6eb734906",
    "cancelled": null,
    "care_enquiry": "66bfb4d99ab4e3d6eb73601e",
    "completed": null,
    "created": "2024-08-16 20:21:45",
    "date_time": "2024-08-18 12:00:00",
    "host": "manager",
    "location": "66bfb4bb9ab4e3d6eb734900",
    "modified": "2024-08-16 20:21:45",
    "notes": "Care seeker has requested to view ground floor rooms.",
    "visit_type": "in_person"
}

Cancel a home visit

Response

Returns the home visit object cancelled.

PATCH
/v1/home-visits/<home_visit_id>/cancel
var homeVisit = apiClient.Request(
    HttpMethod.Patch,
    $"home-visits/{homeVisitId}/cancel"
);

<?php

$home_visit = $api_client->request(
    'PATCH',
    'home-visits/' . home_visit_id . '/cancel'
);

home_visit = api_client(
    'PATCH',
    f'home-visits/{home_visit_id}/cancel'
)

home_visit = api_client.request(
    'PATCH',
    "home-visits/#{home_visit_id}/cancel"
)
Response 
{
    "_id": "66bfb4d89ab4e3d6eb73600c",
    "assigned_to": "66bfb4bb9ab4e3d6eb734906",
    "cancelled": "2024-08-16 20:21:44",
    "care_enquiry": "66bfb4d89ab4e3d6eb736008",
    "completed": null,
    "created": "2024-08-16 20:21:44",
    "date_time": "2024-08-18 11:00:00",
    "host": "manager",
    "location": "66bfb4bb9ab4e3d6eb734900",
    "modified": "2024-08-16 20:21:44",
    "notes": "Care seeker has requested to view ground floor rooms.",
    "visit_type": "in_person"
}

Mark a home visit as complete

Response

Returns the home visit object completed.

PATCH
/v1/home-visits/<home_visit_id>/complete
var homeVisit = apiClient.Request(
    HttpMethod.Patch,
    $"home-visits/{homeVisitId}/complete"
);

<?php

$comment = $api_client->request(
    'PATCH',
    'home-visits/' . home_visit_id . '/complete'
);

home_visit = api_client(
    'PATCH',
    f'home-visits/{home_visit_id}/complete'
)

home_visit = api_client.request(
    'PATCH',
    "home-visits/#{home_visit_id}/complete"
)
Response 
{
    "_id": "66bfb4d99ab4e3d6eb736015",
    "assigned_to": "66bfb4bb9ab4e3d6eb734906",
    "cancelled": null,
    "care_enquiry": "66bfb4d99ab4e3d6eb736011",
    "completed": "2024-08-16 20:21:45",
    "created": "2024-08-16 20:21:45",
    "date_time": "2024-08-18 11:00:00",
    "host": "manager",
    "location": "66bfb4bb9ab4e3d6eb734900",
    "modified": "2024-08-16 20:21:45",
    "notes": "Care seeker has requested to view ground floor rooms.",
    "visit_type": "in_person"
}