Submit medical questions

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. Safety answers on that existing referral. You do not send a new patient, a new order, or preferred times in this flow. What Scan does after. We use the answers when ranking centers and booking, and reach out for anything still missing, then file the radiology report back to you. Do this before you list centers or send preferred times. The answers change which centers can take the patient: claustrophobia points to open scanners, and a yes on a blocking question rules some equipment out entirely. If you already have safety answers and the times that work, use Submit for scheduling instead. Preferred times on this referral belong to Submit preferred times.

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).
Medical safety questions — the intake questionnaire. A yes on a blocking question, metal implants for example, rules some scanners out.

1. Fetch the questions

These are the screening questions an imaging center asks before an MRI — claustrophobia, metal implants, and similar. Ask them however suits your product, then send the answers in the next step. Fetch the questions, which come back with any answers already on file: GET /api/v2/referrals/{referral_id}/medical_questionnaire

curl "https://api.staging.scan.com/api/v2/referrals/$REFERRAL_ID/medical_questionnaire" \
  -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")}/medical_questionnaire")
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}/medical_questionnaire",
    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}/medical_questionnaire`,
  { headers: { Authorization: `Bearer ${process.env.SCAN_API_TOKEN}` } },
);

const questions = await response.json();

$referral_id = getenv("REFERRAL_ID");
$ch = curl_init("https://api.staging.scan.com/api/v2/referrals/{$referral_id}/medical_questionnaire");
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/medical_questionnaire",
    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
}

Full payload: Returns medical safety questions.

2. Send the answers

Send the answers back, using each question’s id. PUT /api/v2/referrals/{referral_id}/medical_questionnaire

curl -X PUT "https://api.staging.scan.com/api/v2/referrals/$REFERRAL_ID/medical_questionnaire" \
  -H "Authorization: Bearer $SCAN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "medical_questionnaire": [
      { "id": "11111111-1111-1111-1111-111111111111", "answer": "no" }
    ]
  }'

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

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

request = Net::HTTP::Put.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("SCAN_API_TOKEN")}"
request["Content-Type"] = "application/json"
request.body = {
  medical_questionnaire: [
    { id: "11111111-1111-1111-1111-111111111111", answer: "no" }
  ]
}.to_json

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

import os
import requests

referral_id = os.environ["REFERRAL_ID"]
response = requests.put(
    f"https://api.staging.scan.com/api/v2/referrals/{referral_id}/medical_questionnaire",
    headers={"Authorization": f"Bearer {os.environ['SCAN_API_TOKEN']}"},
    json={
        "medical_questionnaire": [
            {"id": "11111111-1111-1111-1111-111111111111", "answer": "no"}
        ]
    },
)
print(response.json())

const referralId = process.env.REFERRAL_ID;
const response = await fetch(
  `https://api.staging.scan.com/api/v2/referrals/${referralId}/medical_questionnaire`,
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${process.env.SCAN_API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      medical_questionnaire: [
        { id: "11111111-1111-1111-1111-111111111111", answer: "no" },
      ],
    }),
  },
);

const questions = await response.json();

$referral_id = getenv("REFERRAL_ID");
$ch = curl_init("https://api.staging.scan.com/api/v2/referrals/{$referral_id}/medical_questionnaire");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("SCAN_API_TOKEN"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "medical_questionnaire" => [
      ["id" => "11111111-1111-1111-1111-111111111111", "answer" => "no"],
    ],
  ]),
  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{
    "medical_questionnaire": []map[string]any{
      {"id": "11111111-1111-1111-1111-111111111111", "answer": "no"},
    },
  })
  url := fmt.Sprintf(
    "https://api.staging.scan.com/api/v2/referrals/%s/medical_questionnaire",
    os.Getenv("REFERRAL_ID"),
  )
  req, _ := http.NewRequest(http.MethodPut, 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 question set with your answers applied, so you can show the patient what is on file. Full payload: Submits medical safety answers.

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 answered_medical_questionnaire, so you can confirm the answers 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. Fetch the questions

2. Send the answers

3. Follow the referral to the report

​Terms you will see

​1. Fetch the questions

​2. Send the answers

​3. Follow the referral to the report

Terms you will see

1. Fetch the questions

2. Send the answers

3. Follow the referral to the report