Create Appointment

This guide will detail how to find an available time at a Test Location, make an appointment and attach to a Test Registration for your patients.

It is necessary to attach the appointment to a Test Registration to allow the testing location to associate it with the correct patient, and for you to receive the results correctly.

Find Product To Test

First thing do to is find the product(s) you want to get tested. If you don't already have a list of available products you can use the API call below to get a list of all available products to you.

For the rest of this example we will use the product_id from the first result 73d1f6c9-dd60-4f78-bc10-7898d9c66d80

Request

GET

/api/product/

Response (Truncated)

{
    "nr_of_results": 32,
    "current_page": 1,
    "nr_of_pages": 1,
    "results_per_page": 100,
    "next_page": null,
    "items": [
        {
            "id": "73d1f6c9-dd60-4f78-bc10-7898d9c66d80",
            "name": "Allergy Complete - 295 allergens",
            "sku": "AL2",
            "preview_image_url": null,
            "price": {
                "amount_minor": 4900,
                "currency": "GBP",
                "formatted_value": "£49.00"
            },
            "slug": "allergy-complete-295-allergens",
            "description": "Allergy Complete - 295 allergens",
            "short_description": "Allergy Complete - 295 allergens"
        },
        {
            "id": "31e970c1-b59c-47a3-bbb2-227bafcb6379",
            "name": "Anaemia Profile",
            "sku": "ANE",
            "preview_image_url": null,
                "price": {
                "amount_minor": 8900,
                "currency": "GBP",
                "formatted_value": "£89.00"
            },
            "slug": "anaemia-profile",
            "description": "Anaemia Profile",
            "short_description": "Anaemia Profile"
        }
    ]
}

Find Test Location

We now need to find the best Test Location to send your patient to. You can see more details about this API here: Test Location API.

This call returns all Test Locations that you can store in your database and find the most suitable.

There is an optional query string parameter called products you can use to send an array of product IDs to this call. This makes sure that only locations that are able to test for the product in question are returned. If this parameter is not present, all locations are returned, but be aware that some might not be able to fulfil the request.

You can also use a Get Nearest call detailed in the Test Locations API reference: Get Nearest Test Locations

Note the ID as you will need this in the next call. In our case we are going to use fbd9c622-6d77-4b84-a2cd-bae0c0b76153 from the first result.

Request

GET

/api/test_location/?product_ids[]=73d1f6c9-dd60-4f78-bc10-7898d9c66d80

Response (Truncated)

{
    "nr_of_results": 174,
    "current_page": 1,
    "nr_of_pages": 2,
    "results_per_page": 100,
    "next_page": 2,
    "items": [
        {
            "id": "fbd9c622-6d77-4b84-a2cd-bae0c0b76153",
            "full_address": "62 Walsh Bridge, Reynoldstown, CV34 4DF",
            "city": "Reynoldstown",
            "postal_code": "CV34 4DF",
            "name": "Adams Ltd - 36",
            "nearest_bus_station": null,
            "nearest_train_station": null,
            "latitude": 51.521799,
            "longitude": -0.078065
        },
        {
            "id": "8174a6c1-ed20-494e-9d99-c9b63da07747",
            "full_address": "53 Lauren Springs, Lake Kimberlyville, L9 9BL",
            "city": "Lake Kimberlyville",
            "postal_code": "L9 9BL",
            "name": "Adams Ltd - 41",
            "nearest_bus_station": null,
            "nearest_train_station": null,
            "latitude": 51.52103,
            "longitude": -0.201161
        },
        {
            "id": "69529955-a26e-4572-90c8-3e2838da5fdb",
            "full_address": "Studio 43, Ward Junction, North Pete, HU7 4FE",
            "city": "North Pete",
            "postal_code": "HU7 4FE",
            "name": "Adams Ltd - 91",
            "nearest_bus_station": null,
            "nearest_train_station": null,
            "latitude": 57.801963,
            "longitude": 0.79932
        }
    ]
}

Get available days for location

Now you have the location, you need to get the days where timeslots are available for the patient to choose from. This will enable you to build a calendar for the patient to choose a suitable day.

The request includes the query parameter test_location_id with the unique identifier of the location.

Attributes

Name
year
Type
int
Description
Year in format YYYY i.e. 2024
Name
month
Type
int
Description
Month in format MM i.e. 03

Request

GET

/api/test_location/calendar/2024/03?test_location_id=fbd9c622-6d77-4b84-a2cd-bae0c0b76153

Response

{
    "id": "2024-03",
        "availability": {
        "2024-03-01": false,
        "2024-03-02": false,
        "2024-03-03": true,
        "2024-03-04": true,
        "2024-03-05": true,
        "2024-03-06": true,
        "2024-03-07": true,
        "2024-03-08": false,
        "2024-03-09": false,
        "2024-03-10": true,
        "2024-03-11": true,
        "2024-03-12": true,
        "2024-03-13": true,
        "2024-03-14": true,
        "2024-03-15": true,
        "2024-03-16": false,
        "2024-03-17": false,
        "2024-03-18": true,
        "2024-03-19": true,
        "2024-03-20": true,
        "2024-03-21": true,
        "2024-03-22": true,
        "2024-03-23": true,
        "2024-03-24": false,
        "2024-03-25": false,
        "2024-03-26": true,
        "2024-03-27": true,
        "2024-03-28": false,
        "2024-03-29": true,
        "2024-03-30": true,
        "2024-03-31": false
    }
}

Get Timeslots

Now you have a date selected by the patient, pass this to this API to get available times for that day. Take note of the selected ID as you will use this in the next call. We will use 261f070b-0c71-4430-ba3c-74d94936b04e from the first result.

The request includes the query parameter test_location_id with the unique identifier of the location.

Attributes

Name
year
Type
int
Description
Year in format YYYY i.e. 2024
Name
month
Type
int
Description
Month in format MM i.e. 03
Name
day
Type
int
Description
Day in format DD i.e. 21

Request

GET

/api/test_location/slots/2024/03/11?test_location_id=fbd9c622-6d77-4b84-a2cd-bae0c0b76153

Response (Truncated)

[
    {
        "id": "261f070b-0c71-4430-ba3c-74d94936b04e",
        "preview": "09:00",
        "available": false,
        "time": "2024-03-11 09:00",
        "is_past": false
    },
    {
        "id": "67685d89-d223-4cc9-be6f-669feb24ab71",
        "preview": "09:05",
        "available": true,
        "time": "2024-03-11 09:05",
        "is_past": false
    },
    {
        "id": "17544018-5685-468f-85d9-d84d3ebadde4",
        "preview": "09:10",
        "available": true,
        "time": "2024-03-11 09:10",
        "is_past": false
    },
    {
        "id": "bcbc52cb-5e83-4a01-bbc4-088ca68be58b",
        "preview": "09:15",
        "available": true,
        "time": "2024-03-11 09:15",
        "is_past": false
    },
    {
        "id": "a20b3980-8f3c-4e2c-a0d1-2428f8836bca",
        "preview": "09:20",
        "available": true,
        "time": "2024-03-11 09:20",
        "is_past": false
    }
]

Create Provisional Appointment

With the selected slot_id 261f070b-0c71-4430-ba3c-74d94936b04e we can now create an provisional appointment. This will create a hold on the selected time for 10 minutes to give you time to confirm details with the patient, take payment etc.

You will then confirm the appointment in the next call. If you don't confirm within 10 minutes, the appointment will be released at the expires_at, in this case 2024-01-23T20:36:13+00:00 and someone else could book it in the meantime.

If you are sure you want the time, you can pass through true for the confirmed field which will create a confirmed appointment, however be aware that if you need to cancel this, a charge might be applied to it, depending on how far away from the appointment time it currently is.

You can optionally pass through a patient ID now if you have all the details, or if not wait until you do or rely on our patient registration portal to register them.

Take a note of the returned appointment ID d6fcc74b-3664-4d8d-954f-694a8714bf1e. We will use this to confirm the appointment next.

Attributes

Name
patient_id
Type
string
Description
Patient ID
Name
slot_id
Type
string
Required
REQUIRED
Description
The slot ID from the previous call
Name
confirmed
Type
boolean
Required
REQUIRED
Description
false to create a provisional appointment. If you want to confirm it straight away, send true however please note that cancelling a confirmed appointment might lead to a cancellation charge being applied.

Request

POST

/api/appointment/

{
    "slot_id": "261f070b-0c71-4430-ba3c-74d94936b04e",
    "patient_id": null,
    "confirmed": false
}

Response

{
    "id": "d6fcc74b-3664-4d8d-954f-694a8714bf1e",
    "type": "brand_location",
    "test_location_id": "2532b9c5-0fa8-4f51-86e9-5ed663665333",
    "starts_at": "2024-03-11T09:00:00+00:00",
    "ends_at": "2024-03-11T09:15:00+00:00",
    "patient_id": "b4dcb08b-e7bd-4e88-b2ed-d67a6403d795",
    "confirmed": false,
    "expires_at": "2024-01-23T20:36:13+00:00",
    "full_address": "95 Walker Summit, Daniellemouth, HU8 8SH",
    "point": {
        "latitude": 53.082855,
        "longitude": -0.401372
    }
}

Confirm Provisional Appointment

Using the previous appointment ID d6fcc74b-3664-4d8d-954f-694a8714bf1e we can now PATCH to confirm the appointment.

Attributes

Name
confirmed
Type
boolean
Required
REQUIRED
Description
true to confirm appointment

Request

PATCH

/api/appointment/d6fcc74b-3664-4d8d-954f-694a8714bf1e

{
    "confirmed": true
}

Response

[
    {
        "id": "d6fcc74b-3664-4d8d-954f-694a8714bf1e",
        "type": "brand_location",
        "test_location_id": "2532b9c5-0fa8-4f51-86e9-5ed663665333",
        "starts_at": "2024-03-11T09:00:00+00:00",
        "ends_at": "2024-03-11T09:15:00+00:00",
        "patient_id": "b4dcb08b-e7bd-4e88-b2ed-d67a6403d795",
        "confirmed": true,
        "expires_at": "2024-01-23T20:36:13+00:00",
        "full_address": "95 Walker Summit, Daniellemouth, HU8 8SH",
        "point": {
            "latitude": 53.082855,
            "longitude": -0.401372
        }
    }
]

Create Patient

We now need to create a patient to assign to this appointment and test. If you have already made the patient on your system and have the ID you can skip this step.

Please note that this should be the person attending the appointment, not the purchaser or creator.

We will need the returned ID, in this case 12b46474-9f92-40b6-8ba9-0d1730a7917f in the next call.

Attributes

Name
first_name
Type
string
Required
REQUIRED
Description
Patient First Name
Name
last_name
Type
string
Required
REQUIRED
Description
Patient Last Name
Name
phone_number
Type
string
Required
REQUIRED
Description
Patient Mobile Number
Name
email
Type
email
Required
REQUIRED
Description
Patient Email
Name
date_of_birth
Type
string
Required
REQUIRED
Description
Date Of Birth in format YYYY-MM-DD
Name
gender
Type
string
Required
REQUIRED
Description
Gender enum Can be found here

Request

POST

/patient/

{
    "first_name": "John",
    "last_name": "Smith",
    "phone_number": "07429123456",
    "email": "john@example.com",
    "date_of_birth": "1980-02-01",
    "gender": "male"
}

Response

{
    "id": "12b46474-9f92-40b6-8ba9-0d1730a7917f",
    "first_name": "John",
    "last_name": "Smith",
    "gender": "male",
    "date_of_birth": "1980-02-01",
    "ethnicity": null,
    "email": "john@example.com",
    "foreign_id": null,
    "phone_number": "+07429123456",
    "address_id": null
}

Create Test Registration

Now we have an Appointment ID, Product ID(s) and a Patient ID we can create a Test Registration.

The returned ID, in this case "317adb14-bc83-40af-9db0-b6a86de56694 can be used later to get results, see the status of the test etc.

Without this step you will not be able to get results back to the patient, and nothing will generally work properly, so it's an essential part of the process.

Attributes

Name
product_ids
Type
array
Required
REQUIRED
Description
Array of Product IDs relating to the test
Name
patient_id
Type
string
Required
REQUIRED
Description
Patient ID from earlier call
Name
appointment_id
Type
string
Required
REQUIRED
Description
Appointment ID from earlier call

Request

POST

/test_registration

{
    "product_ids": [
        "73d1f6c9-dd60-4f78-bc10-7898d9c66d80"
    ],
    "patient_id": "12b46474-9f92-40b6-8ba9-0d1730a7917f",
    "appointment_id": "d6fcc74b-3664-4d8d-954f-694a8714bf1e"
}

Response

{
    "id": "317adb14-bc83-40af-9db0-b6a86de56694",
    "patient_id": "12b46474-9f92-40b6-8ba9-0d1730a7917f",
    "results_ready": false,
    "product_ids": [
        "73d1f6c9-dd60-4f78-bc10-7898d9c66d80"
    ],
    "product_skus": [
        "AL2"
    ],
    "email": "john@example.com",
    "date_of_birth": "1980-02-01",
    "first_name": "John",
    "last_name": "Smith",
    "ethnicity": null,
    "gender": "male",
    "created_at": "2024-01-24",
    "completed_at": null,
    "patient_registered_at": "2024-01-24",
    "uk_address": null,
    "doctors_note": null,
    "doctors_name": null,
    "download_url": null,
    "appointment_id": "d6fcc74b-3664-4d8d-954f-694a8714bf1e",
    "status": "pending",
    "trf_code": "zawfsek",
    "short_code": "PBNT8MX",
    "parent_id": null
}