Patient Management

Patient Management Guide

Learn about the key concepts of the Impilo API.

This guide is designed to help you understand how patients can be created, updated, and managed, and how to utilize webhooks and external identifiers for effective patient tracking.

Understanding Patients

Before diving into patient management, it’s important to understand the primary entity associated with patient operations:

• Patient: A patient profile is stored within Impilo and is managed by the customer. These profiles are essential for personalizing and managing patient-related activities and services.

Creating a Patient

To create a patient, you’ll interact with a specific endpoint designed for this purpose. This endpoint allows you to initiate and configure patient profiles based on your requirements.

Required Attributes

For a successful patient creation, you must ensure the following required attributes are correctly provided:

• Patient Information: Basic information about the patient such as name, dateOfBirth, and gender must be included.

Create Patient Example

The following request contains the bare minimum for creating a patient.

1
curl -X POST https://app.impiloplatform.com/api/v3/patient \
2
     -H "Impilo-API-Key: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "id": 456,
6
  "externalIdentifier": "external-identifier-123",
7
  "firstName": "John",
8
  "lastName": "Doe",
9
  "dateOfBirth": "1987-09-13",
10
  "email": "email@example.com",
11
  "phoneNumber": "111-222-3333",
12
  "address": {
13
    "lineOne": "1234 Market Street",
14
    "lineTwo": "Suite 110",
15
    "city": "Philadelphia",
16
    "state": "PA",
17
    "zipCode": "19137",
18
    "country": "USA"
19
  },
20
  "sex": "unknown"
21
}'

Updating a Patient

To update a patient, you’ll use a specific endpoint that allows modifying existing patient profiles. This can be useful for updating patient information as required.

Update Patient Example

The following request contains the minimum required for updating a patient.

Using Webhooks for Patient Updates

Impilo supports webhooks to notify your system when a patient is updated. This allows you to keep your system in sync with any changes in patient data. For more information see the webhook management guide.

Setting Up a Webhook

To set up a webhook, register a URL endpoint in your system that can receive POST requests from Impilo.

$
curl -X POST http://app.impiloplatform.com/api/v3/webhook \
>
-H "Content-Type: application/json" \
>
-d '{"type":"patient.updated","url":"https://example.com/webhook"}'

Webhook Example

When a patient is updated, a POST request will be sent to your registered webhook URL with the following payload:

1
POST /your-webhook-url
2
Content-Type: application/json
3
4
{
5
  "event": "patient.updated",
6
  "data": {
7
    "id": "12345",
8
    "name": "John Doe",
9
    "dateOfBirth": "1990-01-01",
10
    "gender": "male",
11
    "updatedAt": "2024-05-21T16:00:00Z"
12
  }
13
}

Using External Identifiers

To effectively track individual patients using customer specific identifiers, the external identifiers field can be used. This can be particularly useful for ensuring uniqueness and consistency in a way that matches external systems.

Example of Generating an External Identifier

For example purposes, a customer system may use email addresses and phone numbers as a way to track patients. The external identifier field could hold a hash of these two values:

1
import java.security.MessageDigest;
2
import java.security.NoSuchAlgorithmException;
3
4
public class HashGenerator {
5
6
    public static void main(String[] args) {
7
        String email = "example@example.com";
8
        String phone = "(123) 456-7890";
9
        String hash = generateMD5Hash(email, phone);
10
        System.out.println("MD5 Hash: " + hash);
11
    }
12
13
    public static String generateMD5Hash(String email, String phone) {
14
        try {
15
            // Remove non-numeric characters from phone number
16
            phone = phone.replaceAll("\\D", "");
17
            // Convert email and phone to lowercase and concatenate
18
            String input = email.toLowerCase() + phone;
19
            // Get MD5 MessageDigest instance
20
            MessageDigest md = MessageDigest.getInstance("MD5");
21
            // Hash the input
22
            byte[] hashBytes = md.digest(input.getBytes());
23
            // Convert byte array to hex string
24
            StringBuilder hexString = new StringBuilder();
25
            for (byte b : hashBytes) {
26
                hexString.append(String.format("%02x", b));
27
            }
28
            return hexString.toString();
29
        } catch (NoSuchAlgorithmException e) {
30
            throw new RuntimeException(e);
31
        }
32
    }
33
}

Using the Hash as an Identifier

You can use the generated hash as an external identifier in your patient profiles to uniquely identify and track patients within Impilo.