Track referral status

A referral changes status many times between the moment you create it and the moment a report is ready. Status changes are not a post-scan event: most of them happen while we are still authorizing, contacting the patient, and scheduling. This page lists every status you can receive, explains what each one means, and says which ones are worth wiring logic to.

Two different status fields

The API returns status in two places and they describe different things.

Field	Describes	Use it for
`visits[].status`	Where an individual visit is in scheduling, the exam, and reporting	Integration logic. This is what the webhook reports.
`status` (top level)	The referral’s case and billing state	Reference only. Do not key scheduling logic off it.

A referral with two visits tracks each one separately, so a referral can have one booked visit and one still waiting on authorization.

The visit lifecycle

Not every referral takes every hop. The gates before ready_to_book depend on the line of business, and a visit can leave the happy path at any point.

Before booking

Status	What it means
`pending`	Referral received. We are checking the physician order and patient details before scheduling starts.
`pending_auth`	Waiting on authorization or coverage approval from the payer. Common on workers’ compensation and health plan referrals.
`co_signed`	Waiting on a countersigned letter of protection from the referring law firm.
`intake_sent`	Safety and intake questions have gone to the patient and we are waiting on answers.
`ready_to_book`	Everything we need is on file and the visit is queued for scheduling. Your portal shows this as patient outreach.
`contacted_for_booking`	We are in contact with the patient to agree on a time and a center.

Scheduled

Status	What it means
`booked`	The appointment is confirmed. `visits[].location` and `visits[].start_time` are both set.

At and after the exam

Status	What it means
`complete`	The patient attended and the exam was performed.
`exam_not_completed`	The patient did not attend or the exam could not be performed.
`sent_to_rad`	Images are with the radiologist for reading.
`report_uploaded`	A radiology report is available. On a referral with several procedures, others may still be outstanding.
`qc_report_ready`	The report has passed quality control.
`invoice_ready`	Reporting is finished for the visit. Your portal shows all reports as ready.

Other outcomes

Status	What it means
`sent_to_rp`	Returned to the referring provider because we could not move it forward, for example we could not reach the patient or the order needs correcting. This one needs action from the provider.
`canceled`	The visit was canceled and no exam will take place.

Which statuses to act on

Three moments usually matter to an integration:

booked — tell the patient where and when. Read visits[].location and visits[].start_time from the same payload.
report_uploaded — a report exists. Pull the PDF with GET /api/v2/order_documents/report.
sent_to_rp — someone on your side needs to unblock the referral.

Visit invoice_ready means reporting is finished for that visit. It is not the signal to pull payments. Payments are a referral-level concern: once the top-level status is no longer pending or canceled, partners with payment read enabled can keep listing them with GET /api/v2/referrals/{referral_id}/payments. New payments can arrive months later. The workers’ compensation example is on Workers’ compensation and payers. Treat the rest as progress information you can surface but should not gate on. Statuses never move backwards through the reporting phases, so you can store the latest one you have seen. New statuses may be added over time, so ignore any string you do not recognize rather than failing.

Referral-level status

The top-level status tracks the case commercially rather than clinically. These are the values with a meaning outside Scan:

Status	What it means
`pending`	Open referral. This is the normal value from create through reporting.
`invoice_ready`	The case is ready to invoice.
`invoice_sent`	The invoice has been issued.
`closed`	The case is closed and no further activity is expected.
`canceled`	The referral was canceled.

Other values may appear on this field. They are internal accounts-receivable states and carry no integration meaning, so do not branch on them. invoice_ready appears at both levels but means different things. On visits[].status, reporting is complete for that visit. On the top-level status, the referral’s case is ready for billing. Payment pulls belong on the referral-level field. Skip pending and canceled. invoice_ready, invoice_sent, closed, and the other accounts-receivable values are when listing payments makes sense, and new rows can still appear months after the first invoice-ready event.

Receiving changes

You have two options, and they work well together: subscribe to the webhook for push updates, and poll when you need a snapshot on demand.

Webhook

We POST to the webhook_url on your api_credentials record every time a visit status changes. The full payload is on Status changed, and Webhooks covers the event catalog, retries, and delivery ordering across all three events.

Header	Value
`Content-Type`	`application/json`
`User-Agent`	`Scan.com-Webhook/1.0`
`X-Scan-Event`	`visit.status_changed`
`X-Scan-Timestamp`	Unix timestamp used in the signature
`X-Scan-Signature`	`v1=` followed by the HMAC-SHA256 digest

Verify the signature

Read the request body as raw bytes before parsing JSON. Compute HMAC-SHA256 over "{timestamp}.{raw_body}" with the signing secret shown on the API access tab, then compare it to the digest after v1= using a constant-time comparison. Reject timestamps older than five minutes to limit replay attacks.

timestamp = request.headers.fetch("X-Scan-Timestamp")
provided = request.headers.fetch("X-Scan-Signature").delete_prefix("v1=")
payload = "#{timestamp}.#{request.raw_post}"
expected = OpenSSL::HMAC.hexdigest("SHA256", ENV.fetch("SCAN_WEBHOOK_SECRET"), payload)

halt 401 unless OpenSSL.secure_compare(provided, expected)
halt 401 if (Time.now.to_i - Integer(timestamp)).abs > 300

The body carries a stable event_id, the new status, a changes.status array of [previous, current], the visit_id, an occurred_at timestamp, and a full referral snapshot so you rarely need a follow-up call.

{
  "event_id": "55555555-5555-5555-5555-555555555555",
  "event_name": "visit.status_changed",
  "status": "booked",
  "changes": { "status": ["contacted_for_booking", "booked"] },
  "visit_id": "11111111-1111-1111-1111-111111111111",
  "occurred_at": "2026-05-28T18:00:00Z",
  "referral": { "id": "22222222-2222-2222-2222-222222222222" }
}

Return HTTP 2xx as soon as you have stored the event, and do the rest of your work afterward. We retry failed deliveries, so the same event can arrive more than once — use event_id to discard duplicates.

Polling

Ask for the current state whenever you need it.

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")}")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("SCAN_API_TOKEN")}"

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

visit_statuses = JSON.parse(response.body)["visits"].map { |visit| visit["status"] }

import os
import requests

response = requests.get(
    f"https://api.staging.scan.com/api/v2/referrals/{os.environ['REFERRAL_ID']}",
    headers={"Authorization": f"Bearer {os.environ['SCAN_API_TOKEN']}"},
)
visit_statuses = [visit["status"] for visit in response.json()["visits"]]

const response = await fetch(
  `https://api.staging.scan.com/api/v2/referrals/${process.env.REFERRAL_ID}`,
  { headers: { Authorization: `Bearer ${process.env.SCAN_API_TOKEN}` } },
);

const { visits } = await response.json();
const visitStatuses = visits.map((visit) => visit.status);

Full payload: Returns a referral by ID. Do not poll for the internal steps between milestones. Wait for the next webhook or take a snapshot when your own workflow needs one.

Notification delivery

Separately from visit status, you can track the emails and texts Scan sends the patient about a referral, such as intake questions, booking confirmations, and appointment reminders. This is delivery metadata only. Recipients, subjects, message bodies, and provider failure text are never returned on either route. Both routes are off by default and are enabled independently of each other and of visit-status delivery, so you can take one without the other. Ask Scan to turn on what you need:

Capability	What it gives you
Notification read	`GET /api/v2/referrals/{referral_id}/notifications`
Notification webhooks	`notification.status_changed` deliveries to your webhook URL

Delivery statuses

pending means we have queued the message and dispatched means we have handed it to the email or SMS provider. Everything after that comes from the provider’s own callbacks, so the two channels do not share a vocabulary.

Status	Channel	What it means
`pending`	email, sms	Queued by Scan, not yet handed over.
`dispatched`	email, sms	Accepted by the delivery provider.
`sent`	email, sms	The provider reported it as sent.
`delivered`	email, sms	The provider confirmed it reached the recipient.
`opened`	email	The recipient opened the email.
`temporary_failure`	email	Soft bounce. The address may accept mail later.
`permanent_failure`	email	Hard bounce. Stop expecting delivery to this address.
`failed`	sms	The message could not be delivered.

How far a message gets depends on what the provider reports back, so not every notification reaches every status. As with visit status, ignore any value you do not recognize rather than failing.

Webhook

Notification events go to the same webhook_url and are signed the same way, so the verification code above works unchanged. The event header is what differs:

Header	Value
`X-Scan-Event`	`notification.status_changed`

You receive one event when the notification is created and one for every status change after it. On that first event changes.status is [null, "pending"].

{
  "event_id": "66666666-6666-6666-6666-666666666666",
  "event_name": "notification.status_changed",
  "referral_id": "22222222-2222-2222-2222-222222222222",
  "status": "delivered",
  "changes": { "status": ["sent", "delivered"] },
  "notification": {
    "id": "44444444-4444-4444-4444-444444444444",
    "channel": "sms",
    "notification_type": "hard_confirmation_to_patient",
    "status": "delivered",
    "created_at": "2026-09-21T18:00:00Z",
    "updated_at": "2026-09-21T18:00:08Z",
    "visit_id": "11111111-1111-1111-1111-111111111111"
  },
  "occurred_at": "2026-09-21T18:00:08Z"
}

Delivery is at least once, so deduplicate on event_id. Full payload: Notification status changed.

Pull the history

Ask for every notification attached to a referral and its visits, newest first.

curl "https://api.staging.scan.com/api/v2/referrals/$REFERRAL_ID/notifications" \
  -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")}/notifications")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("SCAN_API_TOKEN")}"

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

notifications = JSON.parse(response.body)["referral_notifications"]

import os
import requests

response = requests.get(
    f"https://api.staging.scan.com/api/v2/referrals/{os.environ['REFERRAL_ID']}/notifications",
    headers={"Authorization": f"Bearer {os.environ['SCAN_API_TOKEN']}"},
)
notifications = response.json()["referral_notifications"]

const response = await fetch(
  `https://api.staging.scan.com/api/v2/referrals/${process.env.REFERRAL_ID}/notifications`,
  { headers: { Authorization: `Bearer ${process.env.SCAN_API_TOKEN}` } },
);

const { referral_notifications: notifications } = await response.json();

{
  "referral_notifications": [
    {
      "id": "44444444-4444-4444-4444-444444444444",
      "channel": "sms",
      "notification_type": "hard_confirmation_to_patient",
      "status": "delivered",
      "created_at": "2026-09-21T18:00:00Z",
      "updated_at": "2026-09-21T18:00:08Z",
      "visit_id": "11111111-1111-1111-1111-111111111111"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

visit_id is set when the message is about a specific visit and null when it is about the referral as a whole. Results are paginated with page and per_page, which defaults to 20.

Get started

Launch

Patient journey

Referral status

Lines of business

Two different status fields

The visit lifecycle

Before booking

Scheduled

At and after the exam

Other outcomes

Which statuses to act on

Referral-level status

Receiving changes

Webhook

Verify the signature

Polling

Notification delivery

Delivery statuses

Webhook

Pull the history

​Two different status fields

​The visit lifecycle

​Before booking

​Scheduled

​At and after the exam

​Other outcomes

​Which statuses to act on

​Referral-level status

​Receiving changes

​Webhook

​Verify the signature

​Polling

​Notification delivery

​Delivery statuses

​Webhook

​Pull the history

Two different status fields

The visit lifecycle

Before booking

Scheduled

At and after the exam

Other outcomes

Which statuses to act on

Referral-level status

Receiving changes

Webhook

Verify the signature

Polling

Notification delivery

Delivery statuses

Webhook

Pull the history