Create a user and a scan referral

Use this workflow to create a user, and create and update a referral.

1. Create a user and a scan referral.

Use the Create a user endpoint with the client_id and client_secret we shared with you.
It will return an access_token, a refresh_token and an expires_in number.
access_token can be used in all other endpoints that are not using basic authentication.
Every referral or patient created with this access_token will be linked to this user and can only be accessed via this access_token (or subsequent refreshed access_token).
The expires_in value indicates when the access_token expires, in seconds.
You can use the Request a refreshed Access Token endpoint to request a new access_token.
If you do not want to use this token refresh mechanism, feel free to ask us to disable it, and we'll make the expires_in extremely long so access_token would virtually never expire.

2. Create a referral

Use the Create a referral endpoint.
For now, we can create a referral with the minimum required information.
For example with this payload:

  "patient_information": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "date_of_birth_iso": "1999/01/30",
    "address_line_1": "123 Drury Lane",
    "address_postcode": "SK7 2EB",
    "gender": "male"

That endpoint returns an object referral and its id.

3. Search body parts

We want this referral to be for an MRI of both ankles. Let's update the referral with this information. First, we need to find the IDs for the left and right ankle body parts.

We can use the List body parts endpoint, with "MRI" as the modality parameter.

It returns the list of body parts supported by the MRI scan.

3. Update a referral

Let's update the referral with the Update a referral endpoint.

We can use this payload, (assuming 63 and 64 are IDs of left and right ankles):

  "body_part_ids": [63, 64],
  "modality": "MRI",
  "referral_information": "Persistent pain in both ankles"

4. Fetch referral(s)

We can use the Get a referral endpoint to fetch one specific referral, or the List referrals to browse all referrals of one user.

5. Upload additional documents

Optionally, we can upload additional documents to a referral. They could be images or reports of previous scans for example.

We can use the Upload a referral's additional document endpoint to upload them one by one.

6. Submitting or Confirming a referral

At that point, depending on how your account is set up, you could submit the referral. This means we would send an email to the patient inviting them to select an imaging provider, and a time slot, answer a few safety questions and pay for the scan.

Alternatively, you can enter all this information via this API and confirm the referral.

You can follow the Submit a referral or Confirm a referral