> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scan.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Submit for scheduling
> Send us a patient, their physician order, their safety answers, and where and when they want to be seen
For who owns checkout, scheduling, and the member experience, start with
[Is this API right for you?](/guides/build-an-imaging-experience).
Before using this guide you need a sandbox and an access token. Request keys from
[Get API keys](https://admin.staging.scan.com/partner/api_access). How to send
`Authorization` is in [Authentication](/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.
If you only have the patient and physician order — no safety answers or preferred
times — use [Submit a medical referral](/guides/submit-a-medical-referral) instead.
If the referral already exists and you only need to send safety answers, use
[Submit medical questions](/guides/submit-medical-questions).
If the referral already exists and you only need to send preferred times, use
[Submit preferred times](/guides/submit-preferred-times).
**What you will build.** One referral that arrives at Scan ready to schedule: the
patient on file, the physician order attached, the safety questions answered, and
a preferred imaging center with the times that work for the patient.
**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.
## 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.
* **Medical safety questions** — the intake questionnaire. A yes on a blocking question, metal implants for example, rules some scanners out.
* **Preferred center and availability** — where and when the patient wants to be seen. We book from this.
***
## 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`**
```bash cURL theme={"dark"}
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"
}
}
}'
```
```ruby Ruby theme={"dark"}
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
```
```python Python theme={"dark"}
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())
```
```javascript JavaScript theme={"dark"}
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();
```
```php PHP theme={"dark"}
$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);
```
```go Go theme={"dark"}
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](/api-reference/patients/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:;name=;base64,`.
What is being scanned lives in `visits`, and each visit carries its orders. Look
up the exact procedure first with
[CPT codes](/api-reference/cpt-codes/returns-cpt-code-mappings), 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](/api-reference/icd-10-codes/returns-a-list-of-icd-10-codes).
You can still send the legacy
[modality](/api-reference/modalities/returns-a-list-of-modalities) and
[body-part](/api-reference/body-parts/returns-a-list-of-body-parts) fields
instead.
**POST `/api/v2/referrals`**
```bash cURL theme={"dark"}
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"
}
]
}
]
}
}'
```
```ruby Ruby theme={"dark"}
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
```
```python Python theme={"dark"}
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())
```
```javascript JavaScript theme={"dark"}
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();
```
```php PHP theme={"dark"}
$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);
```
```go Go theme={"dark"}
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`. Every remaining step
is addressed to that `id`.
Full payload: [Creates a referral](/api-reference/referrals/creates-a-referral).
***
## 3. Record the patient's safety answers
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 here.
Do this before you list centers. 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. List centers first and you may show the patient
somewhere they cannot go.
Fetch the questions, which come back with any answers already on file:
**GET `/api/v2/referrals/{referral_id}/medical_questionnaire`**
```bash cURL theme={"dark"}
curl "https://api.staging.scan.com/api/v2/referrals/$REFERRAL_ID/medical_questionnaire" \
-H "Authorization: Bearer $SCAN_API_TOKEN"
```
```ruby Ruby theme={"dark"}
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
```
```python Python theme={"dark"}
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())
```
```javascript JavaScript theme={"dark"}
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();
```
```php PHP theme={"dark"}
$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);
```
```go Go theme={"dark"}
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
}
```
Then send the answers back, using each question's `id`:
**PUT `/api/v2/referrals/{referral_id}/medical_questionnaire`**
```bash cURL theme={"dark"}
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" }
]
}'
```
```ruby Ruby theme={"dark"}
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
```
```python Python theme={"dark"}
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())
```
```javascript JavaScript theme={"dark"}
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();
```
```php PHP theme={"dark"}
$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);
```
```go Go theme={"dark"}
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 payloads: [Returns medical safety questions](/api-reference/referrals/returns-medical-safety-questions)
and [Submits medical safety answers](/api-reference/referrals/submits-medical-safety-answers).
***
## 4. 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`, and it already
accounts for the safety answers from the previous step.
These are candidate centers, not appointment times. Availability is not part of
this response.
**GET `/api/v2/locations?referral_id={id}`**
```bash cURL theme={"dark"}
curl "https://api.staging.scan.com/api/v2/locations?referral_id=$REFERRAL_ID" \
-H "Authorization: Bearer $SCAN_API_TOKEN"
```
```ruby Ruby theme={"dark"}
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
```
```python Python theme={"dark"}
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())
```
```javascript JavaScript theme={"dark"}
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();
```
```php PHP theme={"dark"}
$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);
```
```go Go theme={"dark"}
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](/api-reference/locations/returns-nearby-imaging-centers).
***
## 5. 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`**
```bash cURL theme={"dark"}
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" }
]
}
}'
```
```ruby Ruby theme={"dark"}
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
```
```python Python theme={"dark"}
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())
```
```javascript JavaScript theme={"dark"}
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();
```
```php PHP theme={"dark"}
$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);
```
```go Go theme={"dark"}
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](/api-reference/referrals/submits-preferred-center-and-availability).
***
## 6. Follow the referral to the report
You have two ways to stay current. Subscribe to the
[status changed webhook](/webhooks/status-changed) and we push each change to you,
or poll the referral when you need a snapshot.
**GET `/api/v2/referrals/{referral_id}`**
```bash cURL theme={"dark"}
curl "https://api.staging.scan.com/api/v2/referrals/$REFERRAL_ID" \
-H "Authorization: Bearer $SCAN_API_TOKEN"
```
```ruby Ruby theme={"dark"}
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
```
```python Python theme={"dark"}
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())
```
```javascript JavaScript theme={"dark"}
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();
```
```php PHP theme={"dark"}
$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);
```
```go Go theme={"dark"}
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`, `preferred_location`, and `scheduling_mode`, so
you can confirm every step above landed.
When the scan is read, pull the radiology report PDF with
[GET /api/v2/order\_documents/report](/api-reference/order-documents/returns-the-radiology-report-pdf-for-an-order).
Full payload: [Returns a referral by ID](/api-reference/referrals/returns-a-referral-by-id).