Service users

A person who uses the services of the care provider, this might be a resident at a residential/nursing home or a client of a home care or live-in care service.

The service user object

Attributes

  • _id
    string

    A unique Id for the service user.

  • account_code
    string

    The service user's account code (used when exporting invoices to an accounts package).

  • anonymized
    string

    The date/time the service user was anonymized (if anonymized).

  • assistance_with_dressing
    boolean

    Flag indicating that the service user requires assistance with dressing.

  • assistance_with_eating
    boolean

    Flag indicating that the service user requires assistance with with eating.

  • assistance_with_medication
    boolean

    Flag indicating that the service user requires assistance with taking medication.

  • assistance_with_personal_care
    boolean

    Flag indicating that the service user requires assistance with personal care.

  • bill_self_for_expenses
    boolean

    Flag indicating that invoices for expenses should be billed to the service user themselves.

  • billing_comms_preference
    list of strings

    The billing party's preference for receiving billing related commsemail, post.

  • billing_enabled
    boolean

    A flag indiciating if billing is enabled for the service user.

  • billing_party_for_expenses
    string

    The service user contact that should be billed for the service user's expenses.

  • created
    string

    The date/time the service user was created.

  • day_care_deactivated
    string

    The date/time at which the service user left the day care service at the location.

  • day_care_leaving_notes
    string

    Any notes recorded when the user was discharged from day care.

  • day_care_reason_for_leaving
    string

    The reason for leaving given when/if the service user was discharged from day care.

  • day_care_status
    string

    The status of the service user as a day care user; active, inactive.

  • day_care_use
    string

    The use of day care by the service user; exclusive, inclusive, not_used.

  • deactivated
    string

    The date/time at which the service user was deactivated (left the location, if they have left).

  • dementia
    boolean

    Flag indicating that the service user has dementia.

  • dementia_challenging_behaviour
    boolean

    Flag indicating that the service user has dementia with challenging behaviour.

  • dementia_prone_to_wander
    boolean

    Flag indicating that the service user has dementia and is prone to wander.

  • dob
    string

    The service user's date of birth.

  • email_invoices_to
    list of strings

    A list of email addresses to send invoices (and related documents) to.

  • end_of_life_care
    boolean

    Flag indiciating the service user is receiving end of life (palliative) care.

  • first_name
    string

    The service user's first name.

  • fnc_application_date
    string

    The date FNC was applied for for the service user.

  • fnc_application_status
    string

    The status of any FNC (NHS-funded nursing care) application for the service user; not_applicable, applied_for, granted, declined.

  • funding_at_risk
    string

    Date/Time indicating if and when the service user's funding was flagged as at risk.

  • funding_type
    string

    The type of funding in place for the service user; private, local_authority, local_authority_top_up, chc, chc_lifestyle, block_bed, dta_spot, not_sure.

  • future_billing_disabled
    boolean

    A flag indicating that while billing is enabled for the service user they cannot appear as an option for new contracts or invoices.

  • genders
    list of strings

    A list of predefined service user's genders: male, female, non_binary, transgender, intersex.

  • genders_other
    string

    If one or more of the service users genders are not present in the predefined gender set then additional gender terms can be given in as other genders.

  • given_age
    integer

    The age given for the service user if the date of birth isn't known.

  • has_direct_debit_mandate
    boolean

    A flag indicating if the service user has an direct debit mandate in place (in any state, pending, active or pending cancellation).

  • invoices_service_user_id_fields
    list of strings

    A list of fields to identify a service user with when generating a line item for the service user in an invoice for the service useraccount_code, full_name, initials, nhs_number, patient_id, ref.

  • large_print_requested_for_billing
    boolean

    A flag indicating that the billing party wants to receive billing comms (invoices, statements, etc.) in larger print.

  • last_name
    string

    The service user's last name.

  • leaving_notes
    string

    Any notes recorded when the user was discharged.

  • location
    string

    The Id of the location this service user is a client of.

  • lon_lat
    list of floats

    The geographical position of the service user as longitude/latitude coordinates.

  • min_ledger_balance
    integer

    A minimum ledger balance (in pence) below which a balance alert for this service user should be sent. If set, this balance overrides the min balance set for service users against the account.

  • mobile
    string

    The service user's mobile number.

  • mobility_bed_bound
    boolean

    Flag indicating that the service user is bed bound.

  • mobility_can_walk_unaided
    boolean

    Flag indicating that the service user can walk unaided.

  • mobility_requires_aid_or_hoist
    boolean

    Flag indicating that the service user requires a hoist or aid getting out of bed.

  • mobility_uses_stick
    boolean

    Flag indicating that the service user uses a walking stick.

  • mobility_uses_wheelchair
    boolean

    Flag indicating that the service user uses a wheelchair.

  • modified
    string

    The date/time the service user was modified.

  • nhs_number
    string

    The service user's NHS number.

  • notes
    string

    Any additional notes regarding the service user.

  • patient_id
    string

    A generic Id, (or code, reference, etc.) for the service user.

  • payment_method
    string

    The method the billing party is expected to use for making paymentscard, cash, cheque, standing_order, direct_debit, bac.

  • postal_address
    hash

    The service user's postal address.

    • postal_address.address_1
      string

      Address line 1 (e.g. house name/number).

    • postal_address.address_2
      string

      Address line 2 (e.g. street).

    • postal_address.town
      string

      Town, city or village.

    • postal_address.county
      string

      County.

    • postal_address.postcode
      string

      Postal code.

    • postal_address.country
      string

      Country.

  • preferred_name
    string

    A name preferred by the service user.

  • reason_for_leaving
    string

    The reason for leaving given when/if the service user was discharged.

  • ref
    string

    A unique numeric reference for the service user.

  • registered_blind
    boolean

    Flag indicating that the service user is registered as blind.

  • send_balance_alert
    boolean

    Flag indicating that a balance alert should be sent for the service user when their balance is low.

  • service
    string

    The service the service user requires; residential_home, nursing_home, learning_disability_care, bariatric_care, specialist_care, home_care, live_in_care.

  • source_care_enquiry
    string

    The Id of the care enquiry the service user was converted from.

  • status
    string

    The service user's current status; pending, active, inactive.

  • street_address
    hash

    The service user's street address.

    • street_address.address_1
      string

      Address line 1 (e.g. house name/number).

    • street_address.address_2
      string

      Address line 2 (e.g. street).

    • street_address.town
      string

      Town, city or village.

    • street_address.county
      string

      County.

    • street_address.postcode
      string

      Postal code.

    • street_address.country
      string

      Country.

  • title
    string

    The service user's title.

  • transferred_from
    string

    The Id of the service user this service user was duplicated from when transferred to this location.

  • visually_impaired
    boolean

    Flag indicating that the service user is visually impaired.

The service user object
{
    "_id": "66bfb4c09ab4e3d6eb735790",
    "account_code": "AM0404",
    "anonymized": null,
    "assistance_with_dressing": true,
    "assistance_with_eating": true,
    "assistance_with_medication": false,
    "assistance_with_personal_care": true,
    "bill_self_for_expenses": true,
    "billing_comms_preference": null,
    "billing_enabled": true,
    "billing_party_for_expenses": null,
    "created": "2024-08-16 20:21:20",
    "day_care_deactivated": null,
    "day_care_leaving_notes": null,
    "day_care_reason_for_leaving": null,
    "day_care_status": "inactive",
    "day_care_use": "not_used",
    "deactivated": null,
    "dementia": false,
    "dementia_challenging_behaviour": null,
    "dementia_prone_to_wander": null,
    "dob": null,
    "email_invoices_to": null,
    "end_of_life_care": false,
    "first_name": "Anna",
    "fnc_application_date": null,
    "fnc_application_status": null,
    "funding_at_risk": null,
    "funding_type": "chc",
    "future_billing_disabled": null,
    "genders": [
        "female"
    ],
    "genders_other": null,
    "given_age": 100,
    "has_direct_debit_mandate": null,
    "invoices_service_user_id_fields": null,
    "large_print_requested_for_billing": null,
    "last_name": "Murphy",
    "leaving_notes": "",
    "location": "66bfb4bb9ab4e3d6eb734900",
    "lon_lat": null,
    "min_ledger_balance": null,
    "mobile": null,
    "mobility_bed_bound": null,
    "mobility_can_walk_unaided": true,
    "mobility_requires_aid_or_hoist": null,
    "mobility_uses_stick": null,
    "mobility_uses_wheelchair": null,
    "modified": "2024-08-16 20:21:20",
    "nhs_number": null,
    "notes": "Anna is mobile but her legs feel heavy and she tends to shuffle/furniture walk. Anna prefers not to use a frame but does have one and she will need help standing as it is an effort.\n\nAnna needs support with personal care and dressing.",
    "patient_id": null,
    "payment_method": "cash",
    "postal_address": null,
    "preferred_name": null,
    "reason_for_leaving": null,
    "ref": "404",
    "registered_blind": null,
    "send_balance_alert": null,
    "service": "nursing_home",
    "source_care_enquiry": null,
    "status": "active",
    "street_address": {
        "address_1": "",
        "address_2": "",
        "country": "",
        "county": "",
        "postcode": "",
        "town": ""
    },
    "title": "",
    "transferred_from": null,
    "visually_impaired": false
}

List all service users

Return a list of service users.

Parameters

  • attributes
    optional
    default ['_id']

    A list of attributes to include for fetched objects.

  • filters-anonymized
    optional
    default unset

    A filter that allows service users to be filtered by whether the enquiry is anonymized.

    • unset
    • yes
    • no
  • filters-day_care_status
    optional

    A filter that accepts a list of status a day care service user can be in and filters service users by their current day care status.

    • active
    • inactive
  • filters-day_care_use
    optional

    A filter that accepts a list of a day care uses and filters service users by their current use of day care.

    • exclusive
    • inclusive
    • not_used
  • 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 service users by the location they are a client of.

  • 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; ref, full_name.

  • filters-status
    optional

    A filter that accepts a list of status a service user can be in and filters service users by their current status.

    • pending
    • active
    • inactive
  • 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
    • full_name

Response

Returns a page of service users.

GET
/v1/service-users
var serviceUsers = apiClient.Request(
    HttpMethod.Get,
    "service-users",
    new MultiValueDict()
        .Add("attributes", "ref", "first_name", "last_name")
        .Add("filters-day_care_use", "not_used")
        .Add("filters-status", "pending", "active")
        .Add("sort_by", "full_name")
);
<?php

$service_users = $api_client->request(
    'GET',
    'service-users',
    [
        'attributes'=>['ref', 'first_name', 'last_name'],
        'filters-day_care_use'=>['not_used'],
        'filters-status'=>['pending', 'active'],
        'sort_by'=>'full_name'
    ]
);
service_users = api_client(
    'GET',
    'service-users',
    params={
        'attributes': ['ref', 'first_name', 'last_name'],
        'filters-day_care_use': ['not_used'],
        'filters-status': ['pending', 'active'],
        'sort_by': 'full_name'
    }
)
service_users = api_client.request(
    'GET',
    'service-users',
    params: {
        'attributes' => ['ref', 'first_name', 'last_name'],
        'filters-day_care_use' => ['not_used'],
        'filters-status' => ['pending', 'active'],
        'sort_by' => 'full_name'
    }
)
Response
{
    "item_count": 61,
    "items": [
        {
            "_id": "66bfb4c09ab4e3d6eb735790",
            "first_name": "Anna",
            "last_name": "Murphy",
            "ref": "404"
        },
        {
            "_id": "66bfb4c09ab4e3d6eb73577a",
            "first_name": "Barry",
            "last_name": "Taylor",
            "ref": "398"
        },
        {
            "_id": "66bfb4c09ab4e3d6eb735748",
            "first_name": "Beth",
            "last_name": "Bishop",
            "ref": "385"
        },
        {
            "_id": "66bfb4c19ab4e3d6eb735834",
            "first_name": "Brian",
            "last_name": "Shaw",
            "ref": "455"
        },
        {
            "_id": "66bfb4c09ab4e3d6eb735776",
            "first_name": "Bruce",
            "last_name": "Bruce",
            "ref": "397"
        },
        {
            "_id": "66bfb4c09ab4e3d6eb7357e8",
            "first_name": "Carol",
            "last_name": "Watson",
            "ref": "430"
        },
        {
            "_id": "66bfb4c09ab4e3d6eb7357b2",
            "first_name": "Carol",
            "last_name": "Wilson",
            "ref": "413"
        },
        {
            "_id": "66bfb4c09ab4e3d6eb735768",
            "first_name": "Carolyn",
            "last_name": "Moss",
            "ref": "393"
        },
        {
            "_id": "66bfb4c09ab4e3d6eb735744",
            "first_name": "Charlene",
            "last_name": "Evans",
            "ref": "384"
        },
        {
            "_id": "66bfb4c09ab4e3d6eb735772",
            "first_name": "Damien",
            "last_name": "Ali",
            "ref": "396"
        }
    ],
    "page": 1,
    "page_count": 7,
    "per_page": 10
}

Retrieve a service user

Retreive a service user object.

Response

Returns a service user object.

GET
/v1/service-users/<service_user_id>
var serviceUser = apiClient.Request(
    HttpMethod.Get,
    $"service-users/{serviceUserId}"
);
<?php

$service_user = $api_client->request(
    'GET',
    'service-users/' . $service_user_id
);
service_user = api_client('GET', f'service-users/{service_user_id}')
service_user = api_client.request('GET', "service-users/#{service_user_id}")
Response
{
    "_id": "66bfb4c09ab4e3d6eb735790",
    "account_code": "AM0404",
    "anonymized": null,
    "assistance_with_dressing": true,
    "assistance_with_eating": true,
    "assistance_with_medication": false,
    "assistance_with_personal_care": true,
    "bill_self_for_expenses": true,
    "billing_comms_preference": null,
    "billing_enabled": true,
    "billing_party_for_expenses": null,
    "created": "2024-08-16 20:21:20",
    "day_care_deactivated": null,
    "day_care_leaving_notes": null,
    "day_care_reason_for_leaving": null,
    "day_care_status": "inactive",
    "day_care_use": "not_used",
    "deactivated": null,
    "dementia": false,
    "dementia_challenging_behaviour": null,
    "dementia_prone_to_wander": null,
    "dob": null,
    "email_invoices_to": null,
    "end_of_life_care": false,
    "first_name": "Anna",
    "fnc_application_date": null,
    "fnc_application_status": null,
    "funding_at_risk": null,
    "funding_type": "chc",
    "future_billing_disabled": null,
    "genders": [
        "female"
    ],
    "genders_other": null,
    "given_age": 100,
    "has_direct_debit_mandate": null,
    "invoices_service_user_id_fields": null,
    "large_print_requested_for_billing": null,
    "last_name": "Murphy",
    "leaving_notes": "",
    "location": "66bfb4bb9ab4e3d6eb734900",
    "lon_lat": null,
    "min_ledger_balance": null,
    "mobile": null,
    "mobility_bed_bound": null,
    "mobility_can_walk_unaided": true,
    "mobility_requires_aid_or_hoist": null,
    "mobility_uses_stick": null,
    "mobility_uses_wheelchair": null,
    "modified": "2024-08-16 20:21:20",
    "nhs_number": null,
    "notes": "Anna is mobile but her legs feel heavy and she tends to shuffle/furniture walk. Anna prefers not to use a frame but does have one and she will need help standing as it is an effort.\n\nAnna needs support with personal care and dressing.",
    "patient_id": null,
    "payment_method": "cash",
    "postal_address": null,
    "preferred_name": null,
    "reason_for_leaving": null,
    "ref": "404",
    "registered_blind": null,
    "send_balance_alert": null,
    "service": "nursing_home",
    "source_care_enquiry": null,
    "status": "active",
    "street_address": {
        "address_1": "",
        "address_2": "",
        "country": "",
        "county": "",
        "postcode": "",
        "town": ""
    },
    "title": "",
    "transferred_from": null,
    "visually_impaired": false
}