Submit a medical referral

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. One referral with the patient on file and the physician order attached. You do not send safety answers or preferred times in this flow. What Scan does after. We reach out for safety screening and scheduling, confirm the appointment with the patient, and file the radiology report back to you. If you already have safety answers and the times that work, use Submit for scheduling instead. Workers compensation payers should use Workers’ compensation and payers for payment_type, order_type, payer, and claim fields.

Terms you will see

Referral — the request for imaging. Holds one or more visits.
Visit — one trip to an imaging center, carrying the orders for that trip (modality, body part).
Order form — the physician’s signed order PDF, sent as order_form. There is no separate medical-referral object.

Safety questions on this referral belong to Submit medical questions. Preferred center and times belong to Submit preferred times.

1. Tell us who the patient is

Register the person being scanned so the rest of the flow can refer to them. Patients are scoped to your group, so you only ever see your own. If you would rather send everything at once, you can nest these same fields as referral.patient in the next step instead. POST /api/v2/patients

curl https://api.staging.scan.com/api/v2/patients \
  -H "Authorization: Bearer $SCAN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "patient": {
      "first_name": "John",
      "last_name": "Doe",
      "phone": "5551234567",
      "patient_profile_attributes": {
        "date_of_birth": "1988-05-21",
        "gender": "male",
        "state": "GA",
        "zip_code": "30301"
      }
    }
  }'

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

uri = URI("https://api.staging.scan.com/api/v2/patients")
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 = {
  patient: {
    first_name: "John",
    last_name: "Doe",
    phone: "5551234567",
    patient_profile_attributes: {
      date_of_birth: "1988-05-21",
      gender: "male",
      state: "GA",
      zip_code: "30301"
    }
  }
}.to_json

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

import os
import requests

response = requests.post(
    "https://api.staging.scan.com/api/v2/patients",
    headers={"Authorization": f"Bearer {os.environ['SCAN_API_TOKEN']}"},
    json={
        "patient": {
            "first_name": "John",
            "last_name": "Doe",
            "phone": "5551234567",
            "patient_profile_attributes": {
                "date_of_birth": "1988-05-21",
                "gender": "male",
                "state": "GA",
                "zip_code": "30301",
            },
        }
    },
)
print(response.json())

const response = await fetch("https://api.staging.scan.com/api/v2/patients", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCAN_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    patient: {
      first_name: "John",
      last_name: "Doe",
      phone: "5551234567",
      patient_profile_attributes: {
        date_of_birth: "1988-05-21",
        gender: "male",
        state: "GA",
        zip_code: "30301",
      },
    },
  }),
});

const patient = await response.json();

$ch = curl_init("https://api.staging.scan.com/api/v2/patients");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("SCAN_API_TOKEN"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "patient" => [
      "first_name" => "John",
      "last_name" => "Doe",
      "phone" => "5551234567",
      "patient_profile_attributes" => [
        "date_of_birth" => "1988-05-21",
        "gender" => "male",
        "state" => "GA",
        "zip_code" => "30301",
      ],
    ],
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($ch);

package main

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

func main() {
  body, _ := json.Marshal(map[string]any{
    "patient": map[string]any{
      "first_name": "John",
      "last_name":  "Doe",
      "phone":      "5551234567",
      "patient_profile_attributes": map[string]any{
        "date_of_birth": "1988-05-21",
        "gender":        "male",
        "state":         "GA",
        "zip_code":      "30301",
      },
    },
  })
  req, _ := http.NewRequest(
    http.MethodPost,
    "https://api.staging.scan.com/api/v2/patients",
    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 patient id. Hold onto it as patient_id for the next step. Full payload: Creates a patient.

2. Send the referral with the physician order

This is the step that creates the imaging request. It carries three things: the patient, the signed physician order, and what is being scanned. The order is the PDF the referring physician signed, sent as order_form in a base64 data URL shaped like data:<content_type>;name=<filename>;base64,<payload>. What is being scanned lives in visits, and each visit carries its orders. Look up the exact procedure first with CPT codes, then send its id as cpt_code_id. We infer modality, body part, contrast, laterality, modifier, and number of views from that mapping. Diagnosis IDs come from ICD-10 codes. You can still send the legacy modality and body-part fields instead. POST /api/v2/referrals

curl https://api.staging.scan.com/api/v2/referrals \
  -H "Authorization: Bearer $SCAN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "referral": {
      "order_form": "data:application/pdf;name=order.pdf;base64,JVBERi0xLjQ=",
      "payment_type": "pi",
      "order_type": "lien",
      "injury_type": "motor_vehicle_accident",
      "incident_date": "2026-04-01",
      "physician_notes": "Persistent neck pain",
      "referred_by": "Dr. Jane Smith",
      "state_brand_abbreviation": "GA",
      "patient_id": "11111111-1111-1111-1111-111111111111",
      "visits": [
        {
          "orders": [
            {
              "cpt_code_id": "11111111-1111-1111-1111-111111111113"
            }
          ]
        }
      ]
    }
  }'

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

uri = URI("https://api.staging.scan.com/api/v2/referrals")
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 = {
  referral: {
    order_form: "data:application/pdf;name=order.pdf;base64,JVBERi0xLjQ=",
    payment_type: "pi",
    order_type: "lien",
    injury_type: "motor_vehicle_accident",
    incident_date: "2026-04-01",
    physician_notes: "Persistent neck pain",
    referred_by: "Dr. Jane Smith",
    state_brand_abbreviation: "GA",
    patient_id: "11111111-1111-1111-1111-111111111111",
    visits: [
      {
        orders: [
          {
            cpt_code_id: "11111111-1111-1111-1111-111111111113"
          }
        ]
      }
    ]
  }
}.to_json

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

import os
import requests

response = requests.post(
    "https://api.staging.scan.com/api/v2/referrals",
    headers={"Authorization": f"Bearer {os.environ['SCAN_API_TOKEN']}"},
    json={
        "referral": {
            "order_form": "data:application/pdf;name=order.pdf;base64,JVBERi0xLjQ=",
            "payment_type": "pi",
            "order_type": "lien",
            "injury_type": "motor_vehicle_accident",
            "incident_date": "2026-04-01",
            "physician_notes": "Persistent neck pain",
            "referred_by": "Dr. Jane Smith",
            "state_brand_abbreviation": "GA",
            "patient_id": "11111111-1111-1111-1111-111111111111",
            "visits": [
                {
                    "orders": [
                        {
                            "cpt_code_id": "11111111-1111-1111-1111-111111111113",
                        }
                    ],
                }
            ],
        }
    },
)
print(response.json())

const response = await fetch("https://api.staging.scan.com/api/v2/referrals", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SCAN_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    referral: {
      order_form: "data:application/pdf;name=order.pdf;base64,JVBERi0xLjQ=",
      payment_type: "pi",
      order_type: "lien",
      injury_type: "motor_vehicle_accident",
      incident_date: "2026-04-01",
      physician_notes: "Persistent neck pain",
      referred_by: "Dr. Jane Smith",
      state_brand_abbreviation: "GA",
      patient_id: "11111111-1111-1111-1111-111111111111",
      visits: [
        {
          orders: [
            {
              cpt_code_id: "11111111-1111-1111-1111-111111111113",
            },
          ],
        },
      ],
    },
  }),
});

const referral = await response.json();

$ch = curl_init("https://api.staging.scan.com/api/v2/referrals");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("SCAN_API_TOKEN"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "referral" => [
      "order_form" => "data:application/pdf;name=order.pdf;base64,JVBERi0xLjQ=",
      "payment_type" => "pi",
      "order_type" => "lien",
      "injury_type" => "motor_vehicle_accident",
      "incident_date" => "2026-04-01",
      "physician_notes" => "Persistent neck pain",
      "referred_by" => "Dr. Jane Smith",
      "state_brand_abbreviation" => "GA",
      "patient_id" => "11111111-1111-1111-1111-111111111111",
      "visits" => [
        [
          "orders" => [
            [
              "cpt_code_id" => "11111111-1111-1111-1111-111111111113",
            ],
          ],
        ],
      ],
    ],
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($ch);

package main

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

func main() {
  body, _ := json.Marshal(map[string]any{
    "referral": map[string]any{
      "order_form":                 "data:application/pdf;name=order.pdf;base64,JVBERi0xLjQ=",
      "payment_type":               "pi",
      "order_type":                 "lien",
      "injury_type":                "motor_vehicle_accident",
      "incident_date":              "2026-04-01",
      "physician_notes":            "Persistent neck pain",
      "referred_by":                "Dr. Jane Smith",
      "state_brand_abbreviation":   "GA",
      "patient_id":                 "11111111-1111-1111-1111-111111111111",
      "visits": []map[string]any{
        {
          "orders": []map[string]any{
            {
              "cpt_code_id": "11111111-1111-1111-1111-111111111113",
            },
          },
        },
      },
    },
  })
  req, _ := http.NewRequest(
    http.MethodPost,
    "https://api.staging.scan.com/api/v2/referrals",
    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 full referral, including its id. Hold onto it to track the referral below. You can stop here. Scan will collect safety answers and book. If you already have safety answers, continue with Submit medical questions. If you already have preferred times, continue with Submit preferred times. If you already have safety answers and preferred times, use Submit for scheduling. Full payload: Creates a referral.

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. 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. Tell us who the patient is

2. Send the referral with the physician order

3. Follow the referral to the report

​Terms you will see

​1. Tell us who the patient is

​2. Send the referral with the physician order

​3. Follow the referral to the report

Terms you will see

1. Tell us who the patient is

2. Send the referral with the physician order

3. Follow the referral to the report