> ## 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 preferred times

> Send the center and times that work for an existing referral

This guide starts from a referral you already created. If you do not have a
`referral_id` yet, follow [Submit a medical referral](/guides/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?](/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.

**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](/guides/submit-for-scheduling) instead. Safety answers
on an already-created referral belong to
[Submit medical questions](/guides/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](/guides/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](/guides/submit-medical-questions). The full intake path
belongs to [Submit for scheduling](/guides/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](/guides/submit-medical-questions). If you
skipped the questionnaire, you can still pick a center from this list.

**GET `/api/v2/locations?referral_id={id}`**

<CodeGroup>
  ```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
  }
  ```
</CodeGroup>

**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).

***

## 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`**

<CodeGroup>
  ```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
  }
  ```
</CodeGroup>

**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).

***

## 3. 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}`**

<CodeGroup>
  ```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
  }
  ```
</CodeGroup>

**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](/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).