Submit preferred times

This guide starts from a referral you already created. If you do not have a referral_id yet, follow Submit a medical referral first. Do not create the patient or the referral again here. For who owns checkout, scheduling, and the member experience, start with Is this API right for you?. Before using this guide you need a sandbox and an access token. Request keys from Get API keys. How to send Authorization is in Authentication. Use synthetic data only on the initial sandbox. Listing imaging centers, searching or creating practices or law firms, and submitting an order-form-only referral may be off until Scan enables them for your account. What you will build. Preferred center and availability on that existing referral. You do not send a new patient, a new order, or safety answers in this flow. What Scan does after. We book the appointment from the preference you send, confirm it with the patient, and file the radiology report back to you. You never pick a timeslot yourself in this flow. If you still need to collect safety answers as well as preferred times, use Submit for scheduling instead. Safety answers on an already-created referral belong to Submit medical questions. If your account has live auto-book enabled and you want Scan to choose from live availability instead of recording patient preferences, use Submit a booking.

Terms you will see

Referral — the request for imaging. Holds one or more visits. You already have its id from the previous guide.
Visit — one trip to an imaging center, carrying the orders for that trip (modality, body part).
Preferred center and availability — where and when the patient wants to be seen. We book from this.

Safety questions on this referral belong to Submit medical questions. The full intake path belongs to Submit for scheduling.

1. Show the patient nearby imaging centers

Get the centers that can perform this scan, closest first. The search starts from the patient’s address unless you pass a different address. These are candidate centers, not appointment times. Availability is not part of this response. Ranking is more accurate after safety answers are on the referral. Send those first with Submit medical questions. If you skipped the questionnaire, you can still pick a center from this list. GET /api/v2/locations?referral_id={id}

curl "https://api.staging.scan.com/api/v2/locations?referral_id=$REFERRAL_ID" \
  -H "Authorization: Bearer $SCAN_API_TOKEN"

require "net/http"
require "uri"

uri = URI("https://api.staging.scan.com/api/v2/locations")
uri.query = URI.encode_www_form(referral_id: ENV.fetch("REFERRAL_ID"))
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("SCAN_API_TOKEN")}"

response = http.request(request)
puts response.body

import os
import requests

response = requests.get(
    "https://api.staging.scan.com/api/v2/locations",
    headers={"Authorization": f"Bearer {os.environ['SCAN_API_TOKEN']}"},
    params={"referral_id": os.environ["REFERRAL_ID"]},
)
print(response.json())

const referralId = process.env.REFERRAL_ID;
const response = await fetch(
  `https://api.staging.scan.com/api/v2/locations?referral_id=${referralId}`,
  { headers: { Authorization: `Bearer ${process.env.SCAN_API_TOKEN}` } },
);

const { locations } = await response.json();

$referral_id = getenv("REFERRAL_ID");
$ch = curl_init("https://api.staging.scan.com/api/v2/locations?referral_id={$referral_id}");
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("SCAN_API_TOKEN")],
  CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($ch);

package main

import (
  "io"
  "net/http"
  "net/url"
  "os"
)

func main() {
  endpoint, _ := url.Parse("https://api.staging.scan.com/api/v2/locations")
  query := endpoint.Query()
  query.Set("referral_id", os.Getenv("REFERRAL_ID"))
  endpoint.RawQuery = query.Encode()

  req, _ := http.NewRequest(http.MethodGet, endpoint.String(), nil)
  req.Header.Set("Authorization", "Bearer "+os.Getenv("SCAN_API_TOKEN"))

  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  body, _ := io.ReadAll(resp.Body)
  _ = body
}

What you get back. A ranked list with each center’s name, address, and distance in miles. Keep the id of whichever one the patient picks. Full payload: Returns nearby imaging centers.

2. Send the center and times the patient wants

Tell us how to book. There are two ways to answer, depending on how particular the patient is. If they are flexible on both place and time, send anytime_anywhere and nothing else — we find the soonest good option. If they are not, send time_preferences with the location_id they picked in the previous step, plus either the days and times that work (preferred_times) or asap: true to take the soonest opening at that center. POST /api/v2/referrals/{referral_id}/scheduling_preferences

curl "https://api.staging.scan.com/api/v2/referrals/$REFERRAL_ID/scheduling_preferences" \
  -H "Authorization: Bearer $SCAN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduling_preference": {
      "mode": "time_preferences",
      "location_id": "11111111-1111-1111-1111-111111111111",
      "preferred_times": [
        { "day_of_week": "monday", "time_of_day": "morning" }
      ]
    }
  }'

require "net/http"
require "json"
require "uri"

uri = URI("https://api.staging.scan.com/api/v2/referrals/#{ENV.fetch("REFERRAL_ID")}/scheduling_preferences")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("SCAN_API_TOKEN")}"
request["Content-Type"] = "application/json"
request.body = {
  scheduling_preference: {
    mode: "time_preferences",
    location_id: "11111111-1111-1111-1111-111111111111",
    preferred_times: [
      { day_of_week: "monday", time_of_day: "morning" }
    ]
  }
}.to_json

response = http.request(request)
puts response.body

import os
import requests

referral_id = os.environ["REFERRAL_ID"]
response = requests.post(
    f"https://api.staging.scan.com/api/v2/referrals/{referral_id}/scheduling_preferences",
    headers={"Authorization": f"Bearer {os.environ['SCAN_API_TOKEN']}"},
    json={
        "scheduling_preference": {
            "mode": "time_preferences",
            "location_id": "11111111-1111-1111-1111-111111111111",
            "preferred_times": [
                {"day_of_week": "monday", "time_of_day": "morning"}
            ],
        }
    },
)
print(response.json())

const referralId = process.env.REFERRAL_ID;
const response = await fetch(
  `https://api.staging.scan.com/api/v2/referrals/${referralId}/scheduling_preferences`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SCAN_API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      scheduling_preference: {
        mode: "time_preferences",
        location_id: "11111111-1111-1111-1111-111111111111",
        preferred_times: [{ day_of_week: "monday", time_of_day: "morning" }],
      },
    }),
  },
);

const referral = await response.json();

$referral_id = getenv("REFERRAL_ID");
$ch = curl_init("https://api.staging.scan.com/api/v2/referrals/{$referral_id}/scheduling_preferences");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("SCAN_API_TOKEN"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "scheduling_preference" => [
      "mode" => "time_preferences",
      "location_id" => "11111111-1111-1111-1111-111111111111",
      "preferred_times" => [
        ["day_of_week" => "monday", "time_of_day" => "morning"],
      ],
    ],
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($ch);

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  body, _ := json.Marshal(map[string]any{
    "scheduling_preference": map[string]any{
      "mode":        "time_preferences",
      "location_id": "11111111-1111-1111-1111-111111111111",
      "preferred_times": []map[string]any{
        {"day_of_week": "monday", "time_of_day": "morning"},
      },
    },
  })
  url := fmt.Sprintf(
    "https://api.staging.scan.com/api/v2/referrals/%s/scheduling_preferences",
    os.Getenv("REFERRAL_ID"),
  )
  req, _ := http.NewRequest(http.MethodPost, url, bytes.NewBuffer(body))
  req.Header.Set("Authorization", "Bearer "+os.Getenv("SCAN_API_TOKEN"))
  req.Header.Set("Content-Type", "application/json")

  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  result, _ := io.ReadAll(resp.Body)
  _ = result
}

What you get back. The updated referral, with preferred_location and scheduling_mode reflecting what you just sent. The referral is now with our scheduling team. Full payload: Submits preferred center and availability.

3. Follow the referral to the report

You have two ways to stay current. Subscribe to the status changed webhook and we push each change to you, or poll the referral when you need a snapshot. GET /api/v2/referrals/{referral_id}

curl "https://api.staging.scan.com/api/v2/referrals/$REFERRAL_ID" \
  -H "Authorization: Bearer $SCAN_API_TOKEN"

require "net/http"
require "uri"

uri = URI("https://api.staging.scan.com/api/v2/referrals/#{ENV.fetch("REFERRAL_ID")}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("SCAN_API_TOKEN")}"

response = http.request(request)
puts response.body

import os
import requests

referral_id = os.environ["REFERRAL_ID"]
response = requests.get(
    f"https://api.staging.scan.com/api/v2/referrals/{referral_id}",
    headers={"Authorization": f"Bearer {os.environ['SCAN_API_TOKEN']}"},
)
print(response.json())

const referralId = process.env.REFERRAL_ID;
const response = await fetch(
  `https://api.staging.scan.com/api/v2/referrals/${referralId}`,
  { headers: { Authorization: `Bearer ${process.env.SCAN_API_TOKEN}` } },
);

const referral = await response.json();

$referral_id = getenv("REFERRAL_ID");
$ch = curl_init("https://api.staging.scan.com/api/v2/referrals/{$referral_id}");
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("SCAN_API_TOKEN")],
  CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($ch);

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  url := fmt.Sprintf(
    "https://api.staging.scan.com/api/v2/referrals/%s",
    os.Getenv("REFERRAL_ID"),
  )
  req, _ := http.NewRequest(http.MethodGet, url, nil)
  req.Header.Set("Authorization", "Bearer "+os.Getenv("SCAN_API_TOKEN"))

  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  body, _ := io.ReadAll(resp.Body)
  _ = body
}

What you get back. Once we book, visits[].location and visits[].start_time tell you where and when the patient is going. The snapshot also carries preferred_location and scheduling_mode, so you can confirm the preference landed. When the scan is read, pull the radiology report PDF with GET /api/v2/order_documents/report. Full payload: Returns a referral by ID.

Get started

Launch

Patient journey

Referral status

Lines of business

Terms you will see

1. Show the patient nearby imaging centers

2. Send the center and times the patient wants

3. Follow the referral to the report

​Terms you will see

​1. Show the patient nearby imaging centers

​2. Send the center and times the patient wants

​3. Follow the referral to the report

Terms you will see

1. Show the patient nearby imaging centers

2. Send the center and times the patient wants

3. Follow the referral to the report