Integrating your website's enquiry form with CareHQ

The most common API integration clients ask us about is syncing care enquiries from their website to CareHQ automatically. This simple integration removes the need to manually copy over care enquiries from one system to another, saving time and reducing the potential for human error.

This article provides a set of recommendations for software developers integrating a website enquiry form with CareHQ's care enquiries. However, the recommendations here are generally applicable to any CareHQ integration task.

1. API Documentation

Technical documentation for the API can be found in the developers section of this website. You may find it helpful to keep this section open in another window/tab whilst reading through the remaining recommendations.

2. Develop against the staging API

We recommend developing integrations against the staging API (https://api.carehq.dev/v1/) to prevent any disruption and to avoid working with live data during development. Data within the staging API is entirely fictitious and email and SMS messages from the instance are suppressed but otherwise the functionality is identical.

To get access to the staging API please contact a member of the CareHQ support team referencing the client you are undertaking the integration for, and they will provide you with the necessary credentials.

3. Grant minimal access against API keys

Against an API key there are a set of permissions granted which determine what data the API key can create, read, update and delete (CRUD). CareHQ allows multiple named API keys to be created so that developers can ensure each website or application they integrate uses a key with only the permissions it requires.

Granting permissions against an API key that are not required, or sharing a key across multiple applications, increases the potential risk should the API key be compromised.
For example, to sync care enquiries received on your website with care enquiries on CareHQ, your API key only needs to be able to create care enquiries, not read them. Giving the API key permission to read care enquiries would expose data for all care enquiries if the key was compromised, whereas restricting the key's permissions to just the ability to create care enquiries means that it cannot be used to steal sensitive data.

To sync care enquiries from your website to CareHQ your API key typically requires the following permissions:

4. Mapping fields

CareHQ captures a lot of data about care enquiries - more than you can expect a care seeker to fill in when they leave an enquiry on your website.

Mapping the fields in your website enquiry form to the fields against care enquiries in CareHQ is a planning stage that should involve the software developer as well as a client stakeholder; this is especially true if the software developer has limited experience of the care sector.

You can find the fields stored on CareHQ for care enquiries in the API documentation. Pay close attention to the fields that are required, these will need to be provided and so must either also be present in your website form or you must agree on sensible default values.

Of the small number of fields required there are two fields which will typically not be present in your website enquiry form but will be provided as part of the request you send to the API; these are:

Once you start creating care enquiries via the staging API you'll be able to review them within the staging version of the application (you'll be given access to a staging app when your staging API credentials are provided).

5. Mark care enquiries as from an untrusted source

Website enquiry forms are accessible by anyone with an internet connection and SPAM can be a problem. We recommend putting in place measures to reduce unwanted enquiries and there are a number of excellent tools to help (such as Google's ReCAPTCHA), however, a full discussion of the available measures is beyond the scope of this article.

Even with measures in place to reduce SPAM, there will be scenarios where a family member of an existing resident will perhaps fill in the wrong form and create a care enquiry when what they actually wanted to do was ask about visiting next Monday.

By default care enquiries in CareHQ cannot be deleted by users without account owner privileges. However, when a care enquiry is marked as being from an untrusted source any user can delete it upon review if they deem it to be an invalid enquiry (such as SPAM). This helps maintain the integrity of data in CareHQ which is crucial for producing accurate reporting.

To mark a care enquiry as from an untrusted source, simply set the untrusted_source field to true when creating the care enquiry.

6. Handling multiple care homes

If you need to assign care enquiries to more than one care home (location) from the same website or application you will need a way to map a form or page to a specific location Id on CareHQ.

You can get a list of locations on CareHQ via the API or by asking the client to export the list of locations (as a CSV or Excel file).

Once you have the list of locations and their Ids you need to decide how you will store them. There are two options we recommend:

• The simplest option is to store the locations in a mapping structure (such as a dictionary,  associative array, hash map, etc.) within your code. The key in the mapping relates to your local reference for the location, such as an Id or slug, and the value holds the Id for the location on CareHQ. Locations are added infrequently and there is typically plenty of notice ahead of a new location coming online, so this is often a practical approach to take.
• A more flexible option is to store the CareHQ location Id within your website or application database as a field against care home records. To allow users to update the association you can provide a select field that is driven by location data pulled from the CareHQ API.  This allows new locations to be integrated without changing your application code and may be worth the additional effort.

7. Sync care enquiries in the background

Whilst it is possible to send care enquiries to CareHQ as part of the enquiry process for your website, in practice this approach is not overly robust as on its own it doesn't allow for repeat attempts to sync a care enquiry if a previous attempt fails. This means temporary issues (such as a network outage, timeouts, maintenance windows, etc.) can lead to care enquiries never being synced.

A more robust approach is to use a background task (such as a script run by a cron job) to check at regular intervals for care enquiries on your website database that have not yet been synced and attempt to sync them, marking them as synced after you receive a successful response from the CareHQ API. This way, if the API request to create a care enquiry on CareHQ fails, your background task will simply try again the next time it runs. A good frequency at which to sync care enquiries is every 15 minutes.

You can also combine the two approaches, syncing initially as part of the enquiry process and implementing the background sync as a fallback. This combined approach means that in most cases care enquiries will appear on CareHQ as soon as they are received on your website.

8. Transitioning to the production API

When your integration is complete on staging and you're ready to move it to the production environment you'll need a new set of credentials for the production CareHQ API. If you're an external software developer these will typically be created on request by a member of the CareHQ support team or the client. You'll need to provide:

• A list of IP addresses that you will be calling the API from (and if these change in the future you'll need to notify either our support team or your client).
• A list of permissions you need assigned to the API key (e.g. Care enquiries > Create, Groups > Read, etc.).

If you have access to the production CareHQ application you'll be able to create and manage API keys yourself.

Credentials for the production API should never be sent over unencrypted channels such as email. We instead recommend using a service such as One Time Secret to generate a link you can send the recipient and that can only be used once.