Locations

A location such as a care home or an office from which home care is provided.

The location object

Attributes

  • _id
    string

    A unique Id for the location.

  • accepts_dementia
    boolean

    Flag indicating that the location accepts service users with dementia.

  • app_number
    string

    The VMN (virtual mobile number) for the location.

  • brand
    string

    The Id of the brands the location falls under. If not set the location will use the account brand.

  • company_name
    string

    The name of the company running the location. If not set the account company name is used. This field appears on emails invoices and statements.

  • created
    string

    The date/time the location was created.

  • email
    string

    An email address for the location. This will appear on emails and documents (such as invoices).

  • groups
    list of strings

    A list of location groups that the location belongs to.

  • invoice_payment_instructions
    string

    The default payment instructions included at the bottom of invoices for this location when either no payment method is defined for the billing party or no instructions are defined for the payment method.

  • invoice_payment_instructions_bac
    string

    The payment instructions included at the bottom of invoices for BAC payments for this location.

  • invoice_payment_instructions_card
    string

    The payment instructions included at the bottom of invoices for card payments for this location.

  • invoice_payment_instructions_cash
    string

    The payment instructions included at the bottom of invoices for cash payments for this location.

  • invoice_payment_instructions_cheque
    string

    The payment instructions included at the bottom of invoices for cheque payments for this location.

  • invoice_payment_instructions_direct_debit
    string

    The payment instructions included at the bottom of invoices for direct debit payments for this location.

  • invoice_payment_instructions_standing_order
    string

    The payment instructions included at the bottom of invoices for standing order payments for this location.

  • invoicing_address
    hash

    The address that will appear on invoices for the location, if not set the locations street address will be used.

    • invoicing_address.address_1
      string

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

    • invoicing_address.address_2
      string

      Address line 2 (e.g. street).

    • invoicing_address.town
      string

      Town, city or village.

    • invoicing_address.county
      string

      County.

    • invoicing_address.postcode
      string

      Postal code.

    • invoicing_address.country
      string

      Country.

  • invoicing_email
    string

    The email address that will appear on invoices for the location, if not set the locations street address will be used.

  • lon_lat
    list of floats

    The geographical coordinates of the location in longitude and latitude.

  • modified
    string

    The date/time the location was created.

  • name
    string

    The name of the location.

  • offers_daycare
    boolean

    Flag indicating that the location offers day care for service users.

  • offers_respite
    boolean

    Flag indicating that the location offers respite stays for service users.

  • phone
    string

    A phone number for the location. This will appear on emails and documents (such as invoices).

  • reason_for_suspension
    string

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

  • ref
    string

    A settable unique reference for the location.

  • service_user_expenses_assigned_to
    string

    The user actions regarding service user expense billing for this location are assigned to.

  • service_user_expenses_invoices_due_rule
    string

    The rule for determining when an invoice for service user expenses will fall due;day_current_month, day_following_month, days_after_invoice_date, days_after_invoice_month.

  • service_user_expenses_invoices_due_unit
    integer

    The day or number of days from the date of invoice after which an invoice for service user expenses is due.

  • service_user_expenses_invoicing_day
    integer

    The day of the month when invoices for service user expenses are typically raised.

  • service_user_expenses_invoicing_enabled
    boolean

    Flag indicating that invoicing of service user expenses is enabled for this location.

  • service_user_expenses_tax_rate
    string

    The tax rate set for any invoice line item raised for service user expenses.

  • services
    list of strings

    A list of services the location supports: residential_home, nursing_home, learning_disability_care, bariatric_care, specialist_care, home_care, live_in_care.

  • street_address
    hash

    The street (geographical) address for the location, see 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.

  • suspended
    string

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

  • vat_number
    string

    The VAT number for the company running the location. If not set the account VAT number is used. This field appears on emails invoices and statements.

  • website_url
    string

    The URL of the location's website. This will appear on emails and documents (such as invoices).

The location object
{
    "_id": "66bfb4bb9ab4e3d6eb734900",
    "accepts_dementia": true,
    "app_number": "+447380307491",
    "brand": null,
    "company_name": null,
    "created": "2024-08-16 20:21:15",
    "email": "douglascourt@marshallcare.co.uk",
    "groups": [
        "66bfb4bb9ab4e3d6eb7348fa"
    ],
    "invoice_payment_instructions": "Bank transfers should be made to Account Holder: Marshall Care, Douglas court / Sort code: 00-00-00 / Account No. 00000000",
    "invoice_payment_instructions_bac": null,
    "invoice_payment_instructions_card": null,
    "invoice_payment_instructions_cash": null,
    "invoice_payment_instructions_cheque": null,
    "invoice_payment_instructions_direct_debit": null,
    "invoice_payment_instructions_standing_order": null,
    "invoicing_address": {
        "address_1": "",
        "address_2": "",
        "country": "",
        "county": "",
        "postcode": "",
        "town": ""
    },
    "invoicing_email": null,
    "lon_lat": [
        -0.9075,
        51.7
    ],
    "modified": "2024-08-16 20:21:15",
    "name": "Douglas Court",
    "offers_daycare": null,
    "offers_respite": true,
    "phone": "01865 680331",
    "reason_for_suspension": null,
    "ref": null,
    "service_user_expenses_assigned_to": "66bfb4bb9ab4e3d6eb734906",
    "service_user_expenses_invoices_due_rule": "days_after_invoice_date",
    "service_user_expenses_invoices_due_unit": 7,
    "service_user_expenses_invoicing_day": 1,
    "service_user_expenses_invoicing_enabled": true,
    "service_user_expenses_tax_rate": "66bfb4bb9ab4e3d6eb73481c",
    "services": [
        "residential_home",
        "nursing_home"
    ],
    "street_address": {
        "address_1": "Douglas Court",
        "address_2": "Station Road",
        "country": "",
        "county": "Oxfordshire",
        "postcode": "OX39 4HA",
        "town": "Chinnor"
    },
    "suspended": null,
    "vat_number": null,
    "website_url": "https://marshallcare.co.uk/douglas-court"
}

List all locations

Return a list of CareHQ locations (care homes and home care offices) for your organisation.

Parameters

  • attributes
    optional
    default ['_id']

    A list of attributes to include for fetched objects.

  • filters-accepts_dementia
    optional
    default unset

    A filter that allows locations to be filtered by whether they accept dementia service users or not.

    • unset
    • yes
    • no
  • filters-brand
    optional

    A filter that accepts a list of brand Ids and filters locations by the brand they are assigned.

  • filters-groups
    optional

    A filter that accepts a list of location group (Group) Ids and filters locations by the group they belong to.

  • 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-offers_respite
    optional
    default unset

    A filter that allows locations to be filtered by whether they offer respite or not.

    • unset
    • yes
    • no
  • filters-q
    optional

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

  • filters-services
    optional

    A filter that accepts a list of services a location can offer and filters locations by the services they offer.

    • residential_home
    • nursing_home
    • learning_disability_care
    • bariatric_care
    • specialist_care
    • home_care
    • live_in_care
  • filters-suspended
    optional
    default no

    A filter that allows locations 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
    • name

Response

Returns a page of locations.

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

$locations = $api_client->request(
    'GET',
    'locations',
    [
        'attributes'=>['name'],
        'filters-services'=>['residential_home']
    ]
);
locations = api_client(
    'GET',
    'locations',
    params={
        'attributes': ['name'],
        'filters-services': ['residential_home']
    }
)
locations = api_client.request(
    'GET',
    'locations',
    params: {
        'attributes' => ['name'],
        'filters-services' => ['residential_home']
    }
)
Response
{
    "item_count": 2,
    "items": [
        {
            "_id": "66bfb4bb9ab4e3d6eb734900",
            "name": "Douglas Court"
        },
        {
            "_id": "66bfb4bb9ab4e3d6eb734902",
            "name": "Upton House"
        }
    ],
    "page": 1,
    "page_count": 1,
    "per_page": 10
}

Retrieve a location

Retreive a location (care home or home care office) object.

Response

Returns a location object.

GET
/v1/locations/<location_id>
var location = apiClient.Request(HttpMethod.Get, $"locations/{locationId}");
<?php

$location = $api_client->request(
    'GET',
    'locations/' . $location_id
);
location = api_client('GET', f'locations/{location_id}')
location = api_client.request('GET', "locations/#{location_id}")
Response
{
    "_id": "66bfb4bb9ab4e3d6eb734900",
    "accepts_dementia": true,
    "app_number": "+447380307491",
    "brand": null,
    "company_name": null,
    "created": "2024-08-16 20:21:15",
    "email": "douglascourt@marshallcare.co.uk",
    "groups": [
        "66bfb4bb9ab4e3d6eb7348fa"
    ],
    "invoice_payment_instructions": "Bank transfers should be made to Account Holder: Marshall Care, Douglas court / Sort code: 00-00-00 / Account No. 00000000",
    "invoice_payment_instructions_bac": null,
    "invoice_payment_instructions_card": null,
    "invoice_payment_instructions_cash": null,
    "invoice_payment_instructions_cheque": null,
    "invoice_payment_instructions_direct_debit": null,
    "invoice_payment_instructions_standing_order": null,
    "invoicing_address": {
        "address_1": "",
        "address_2": "",
        "country": "",
        "county": "",
        "postcode": "",
        "town": ""
    },
    "invoicing_email": null,
    "lon_lat": [
        -0.9075,
        51.7
    ],
    "modified": "2024-08-16 20:21:15",
    "name": "Douglas Court",
    "offers_daycare": null,
    "offers_respite": true,
    "phone": "01865 680331",
    "reason_for_suspension": null,
    "ref": null,
    "service_user_expenses_assigned_to": "66bfb4bb9ab4e3d6eb734906",
    "service_user_expenses_invoices_due_rule": "days_after_invoice_date",
    "service_user_expenses_invoices_due_unit": 7,
    "service_user_expenses_invoicing_day": 1,
    "service_user_expenses_invoicing_enabled": true,
    "service_user_expenses_tax_rate": "66bfb4bb9ab4e3d6eb73481c",
    "services": [
        "residential_home",
        "nursing_home"
    ],
    "street_address": {
        "address_1": "Douglas Court",
        "address_2": "Station Road",
        "country": "",
        "county": "Oxfordshire",
        "postcode": "OX39 4HA",
        "town": "Chinnor"
    },
    "suspended": null,
    "vat_number": null,
    "website_url": "https://marshallcare.co.uk/douglas-court"
}