Users

A user with access to the CareHQ application.

The user object

Attributes

  • _id
    string

    A unique Id for the user.

  • created
    string

    The date/time the user was created.

  • email
    string

    The user's email address.

  • first_name
    string

    The user's first name.

  • invite_accepted
    string

    The date/time the user accepted their invite to the application.

  • invited
    string

    The date/time the user was invited to the application.

  • last_name
    string

    The user's last name.

  • location_groups
    list of strings

    A list of location groups Ids that a regional manager has access to.

  • location_role
    string

    The user's role at their associated location (manager, deputy_manager, administrator, receptionist, senior_carer, carer, customer_relations_adviser, nurse, other). Only applicable to location users.

  • location_role_other
    string

    The user's role at their associated location defined when the role does not fit the standard list of roles. Only applicable to location users.

  • locations
    list of strings

    A list of locations Ids that a regional manager or location user has access to (location users will only ever have access to one location).

  • mfa_enabled
    boolean

    Flag indicating if the user has enabled Multi-Factor Authentication (a.k.a 2FA) for their account.

  • mobile
    string

    The user's mobile number.

  • modified
    string

    The date/time the user was last modified.

  • notify_on_admission_or_discharge
    boolean

    Flag indicating that this user is notified about service user admissions and discharges.

  • notify_on_care_fund_depleted
    boolean

    Flag indicating that this user is notified when a tracked fund for a service user is about to run out.

  • notify_on_data_export
    boolean

    Flag indicating that this user is notified about data exports.

  • notify_on_ledger_balance_low
    boolean

    Flag indicating that this user is notified when ledger balances are low.

  • notify_on_reply_received
    boolean

    Flag indicating that this user is notified when a reply is received form a care seeker, service user or contact this user has previously sent a message to.

  • notify_on_service_user_funding_at_risk
    boolean

    Flag indicating that this user is notified when a service user's funding is flagged as at risk.

  • owner_operator
    boolean

    Flag indicating if the user is an account owner and location operator. Typically only applicable to single location accounts. Only applies to the account owner role.

  • owner_operator_location
    string

    The Id of the location a user with the owner operator flag set is associated with. Only applicable to account owners with the owner operator flag set.

  • picture
    string

    The user's profile picture URL.

  • reason_for_suspension
    string

    The reason for the user's suspension (if suspended).

  • regional_operator
    boolean

    Flag indicating that a regional manager can act as an operator for locations they are assigned (either via locations or location groups). Only applicable to regional managers.

  • role
    string

    The role of the user within CareHQ (['account_owner', 'regional_manager', 'location_user', 'care_advisor']).

  • show_finance_inbox
    boolean

    Flag indicating if dedicated finance inbox is visible to the user.

  • suspended
    string

    The date/time the user was suspended (if suspended).

The user object
{
    "_id": "66bfb4bb9ab4e3d6eb734906",
    "created": "2024-08-16 20:21:15",
    "email": "ant.demo@crmhq.co.uk",
    "first_name": "Anthony",
    "invite_accepted": null,
    "invited": null,
    "last_name": "Blackshaw",
    "location_groups": [],
    "location_role": null,
    "location_role_label": null,
    "location_role_other": null,
    "locations": [],
    "mfa_enabled": null,
    "mobile": "07832 963 114",
    "modified": "2024-08-16 20:21:15",
    "notify_on_admission_or_discharge": null,
    "notify_on_care_fund_depleted": null,
    "notify_on_data_export": null,
    "notify_on_ledger_balance_low": null,
    "notify_on_reply_received": null,
    "notify_on_service_user_funding_at_risk": null,
    "owner_operator": true,
    "owner_operator_location": "66bfb4bb9ab4e3d6eb734900",
    "picture": null,
    "reason_for_suspension": null,
    "regional_operator": null,
    "role": "account_owner",
    "show_finance_inbox": null,
    "suspended": null
}

List all users

Return a list of CareHQ users for your organisation.

Parameters

  • attributes
    optional
    default ['_id']

    A list of attributes to include for fetched objects.

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

    A filter that accepts a list of location Ids and filters users by the locations they are associated with (as regional managers or location users).

  • 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; email_lower, full_name_lower.

  • filters-role
    optional

    A filter that accepts a list of roles for users and filters users by their role.

    • account_owner
    • regional_manager
    • location_user
    • care_advisor
  • filters-suspended
    optional
    default no

    A filter that allows users that are currently suspended to be included or excluded.

    • unset
    • yes
    • no
  • 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_lower

Response

Returns a page of users.

GET
/v1/users
var users = apiClient.Request(
    HttpMethod.Get,
    "users",
    new MultiValueDict()
        .Add("attributes", "email", "first_name")
        .Add("filters-role", "location_user")
);
<?php

$users = $api_client->request(
    'GET',
    'users',
    [
        'attributes'=>['email', 'first_name'],
        'filters-role'=>['location_user']
    ]
);
users = api_client(
    'GET',
    'users',
    params={
        'attributes': ['email', 'first_name'],
        'filters-roles': ['location_user']
    }
)
users = api_client.request(
    'GET',
    'users',
    params: {
        'attributes' => ['email', 'first_name'],
        'filters-role' => ['location_user']
    }
)
Response
{
    "item_count": 6,
    "items": [
        {
            "_id": "66bfb4bb9ab4e3d6eb734904",
            "email": "account.owner@marshallcare.co.uk",
            "first_name": "Account"
        },
        {
            "_id": "66bfb4bb9ab4e3d6eb734906",
            "email": "ant.demo@crmhq.co.uk",
            "first_name": "Anthony"
        },
        {
            "_id": "66bfb4bb9ab4e3d6eb734908",
            "email": "care.advisor@marshallcare.co.uk",
            "first_name": "Care"
        },
        {
            "_id": "66bfb4bb9ab4e3d6eb73490a",
            "email": "location.user@marshallcare.co.uk",
            "first_name": "Location"
        },
        {
            "_id": "66bfb4bb9ab4e3d6eb73490c",
            "email": "mark.demo@crmhq.co.uk",
            "first_name": "Mark"
        },
        {
            "_id": "66bfb4bb9ab4e3d6eb73490e",
            "email": "regional.manager@marshallcare.co.uk",
            "first_name": "Regional"
        }
    ],
    "page": 1,
    "page_count": 1,
    "per_page": 10
}

Retrieve a user

Retrieve a user object.

Response

Returns a user object.

GET
/v1/users/<user_id>
var user = apiClient.Request(HttpMethod.Get, $"users/{userId}");
<?php

$user = $api_client->request('GET', 'users/' . $user_id);
user = api_client('GET', f'users/{user_id}')
user = api_client.request('GET', "users/#{user_id}")
Response
{
    "_id": "66bfb4bb9ab4e3d6eb734906",
    "created": "2024-08-16 20:21:15",
    "email": "ant.demo@crmhq.co.uk",
    "first_name": "Anthony",
    "invite_accepted": null,
    "invited": null,
    "last_name": "Blackshaw",
    "location_groups": [],
    "location_role": null,
    "location_role_label": null,
    "location_role_other": null,
    "locations": [],
    "mfa_enabled": null,
    "mobile": "07832 963 114",
    "modified": "2024-08-16 20:21:15",
    "notify_on_admission_or_discharge": null,
    "notify_on_care_fund_depleted": null,
    "notify_on_data_export": null,
    "notify_on_ledger_balance_low": null,
    "notify_on_reply_received": null,
    "notify_on_service_user_funding_at_risk": null,
    "owner_operator": true,
    "owner_operator_location": "66bfb4bb9ab4e3d6eb734900",
    "picture": null,
    "reason_for_suspension": null,
    "regional_operator": null,
    "role": "account_owner",
    "show_finance_inbox": null,
    "suspended": null
}