Submit a booking

This guide starts from a referral you already created. If you do not have a referral_id, follow Submit a medical referral first. Auto-book is an opt-in capability. A request returns 403 until Scan enables referrals_auto_book for your account. What you send. A ranking strategy, plus an optional radius, search address, and completion URL. What Scan does. We rank eligible centers, find live availability, and start booking asynchronously. You do not select a timeslot.

Choose a strategy

closest — choose the nearest eligible center that has availability.
soonest — choose the earliest opening within the radius.
closest_soonest — choose the earliest nearby opening, using distance to break ties.

radius is measured in miles, defaults to 200, and accepts 1 through 250. address is a free-form search origin such as 200 Peachtree St, Atlanta, GA 30303. Omit it to use the patient address. An override changes this search only; it does not update the patient.

Request the booking

POST /api/v2/referrals/{referral_id}/book

curl -X POST \
  "https://api.staging.scan.com/api/v2/referrals/$REFERRAL_ID/book" \
  -H "Authorization: Bearer $SCAN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "book": {
      "strategy": "closest",
      "radius": 25,
      "address": "200 Peachtree St, Atlanta, GA 30303",
      "webhook_url": "https://partner.example/hooks/scan-booking"
    }
  }'

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

uri = URI("https://api.staging.scan.com/api/v2/referrals/#{ENV.fetch("REFERRAL_ID")}/book")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("SCAN_API_TOKEN")}"
request["Content-Type"] = "application/json"
request.body = {
  book: {
    strategy: "closest",
    radius: 25,
    address: "200 Peachtree St, Atlanta, GA 30303",
    webhook_url: "https://partner.example/hooks/scan-booking",
  },
}.to_json

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
puts http.request(request).body

import os
import requests

response = requests.post(
    f"https://api.staging.scan.com/api/v2/referrals/{os.environ['REFERRAL_ID']}/book",
    headers={"Authorization": f"Bearer {os.environ['SCAN_API_TOKEN']}"},
    json={
        "book": {
            "strategy": "closest",
            "radius": 25,
            "address": "200 Peachtree St, Atlanta, GA 30303",
            "webhook_url": "https://partner.example/hooks/scan-booking",
        }
    },
)
print(response.json())

const response = await fetch(
  `https://api.staging.scan.com/api/v2/referrals/${process.env.REFERRAL_ID}/book`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SCAN_API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      book: {
        strategy: "closest",
        radius: 25,
        address: "200 Peachtree St, Atlanta, GA 30303",
        webhook_url: "https://partner.example/hooks/scan-booking",
      },
    }),
  },
);
const result = await response.json();

$referralId = getenv("REFERRAL_ID");
$body = json_encode([
  "book" => [
    "strategy" => "closest",
    "radius" => 25,
    "address" => "200 Peachtree St, Atlanta, GA 30303",
    "webhook_url" => "https://partner.example/hooks/scan-booking",
  ],
]);

$ch = curl_init("https://api.staging.scan.com/api/v2/referrals/{$referralId}/book");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("SCAN_API_TOKEN"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => $body,
  CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);

package main

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

func main() {
  payload := map[string]any{"book": map[string]any{
    "strategy": "closest",
    "radius": 25,
    "address": "200 Peachtree St, Atlanta, GA 30303",
    "webhook_url": "https://partner.example/hooks/scan-booking",
  }}
  body, _ := json.Marshal(payload)
  url := fmt.Sprintf(
    "https://api.staging.scan.com/api/v2/referrals/%s/book",
    os.Getenv("REFERRAL_ID"),
  )
  request, _ := http.NewRequest(http.MethodPost, url, bytes.NewBuffer(body))
  request.Header.Set("Authorization", "Bearer "+os.Getenv("SCAN_API_TOKEN"))
  request.Header.Set("Content-Type", "application/json")
  _, _ = http.DefaultClient.Do(request)
}

The API returns 202 Accepted with an auto_book_request.id, a processing status, and the current referral snapshot. This means work started; it does not mean the visit is booked. A referral accepts one booking attempt at a time. While an attempt is in flight, or while Scan operations is booking the same visits, a second request returns 422.

Receive completion

Booking can take several minutes. Scan sends X-Scan-Event: referral.auto_book_completed after the attempt reaches a final result:

{
  "event_name": "referral.auto_book_completed",
  "occurred_at": "2026-09-18T23:05:00Z",
  "auto_book_request": {
    "id": "11111111-1111-1111-1111-111111111111",
    "status": "completed",
    "outcome": "booked",
    "strategy": "closest",
    "radius": 25,
    "address": "200 Peachtree St, Atlanta, GA 30303"
  },
  "referral": {
    "id": "22222222-2222-2222-2222-222222222222",
    "visits": [
      {
        "status": "booked",
        "start_time": "2026-09-22T14:30:00Z",
        "location": {
          "name": "Peachtree Imaging"
        }
      }
    ]
  }
}

Delivery order:

The request’s webhook_url, when provided.
Your account’s configured api_credentials.webhook_url.
No push when neither exists; poll GET /api/v2/referrals/{referral_id} and inspect auto_book_request.status and auto_book_request.outcome.

The completion outcome is one of booked, contacted_for_booking, no_availability, or booking_failed. Return any HTTP 2xx response. The normal status changed webhook remains active for accounts with a configured webhook and continues to report later visit changes. Full payload: Requests automatic booking.

Get started

Launch

Patient journey

Referral status

Lines of business

Choose a strategy

Request the booking

Receive completion

​Choose a strategy

​Request the booking

​Receive completion

Choose a strategy

Request the booking

Receive completion