Skip to main content
This API is built for one shape of integration. Your member needs a scan, you have an imaging order to send with the referral, commercial terms with Scan are agreed, and you want us to handle the scheduling. If that describes you, the rest of this page covers how the model works and where the line falls between what you run and what Scan runs. Ownership and checkout are summarized on Introduction. Before you call anything you need a sandbox and an access token. Request keys from Get API keys, then see Authentication for how to send Authorization. Use synthetic data only on the initial sandbox.

​
What you can offer

The modalities and geographies available to you are set per account rather than published as a catalog endpoint, so what your contract covers is the list to build against. Eligibility works the same way: you decide whether a member qualifies from your own contracted catalog, before you create the referral and before they pay. You choose how much of the scheduling you drive. Send a preferred center and times with Submit preferred times and we work from those, or leave them out and Scan selects the center and books. Accounts enabled for live auto-book can submit a booking directly with a closest or soonest strategy. When no suitable center can be found, Scan handles the exception rather than handing it back to you. You will see the outcome on GET /api/v2/referrals/{referral_id} or the status changed webhook.

​
How the money works

You charge the member and you set the price, whether that is a fixed fee or a quote you generate. What the price covers on Scan’s side, such as the technical component, the interpretation, and any extras, varies by account and is settled in your contract rather than exposed in the API. So is the point at which you incur a Scan charge. Once the scan has happened you can pull the invoice with Invoice retrieval. Cancellations, no-shows, and changes of procedure are handled operationally by Scan. You reconcile them on your side and look after the member in your own product.

​
What you send us

Every referral carries an imaging order as order_form, sent as a base64 data URL. In practice the treating clinician has usually written it already, but what the API checks is that a document arrives with the referral. If you have not broken the order down yourself, POST /api/v2/referral_orders takes the document and the patient on their own and reads the procedures out of it. Use Submit a medical referral when you already have the visits and orders structured. At submit time we need the patient, the visits and the orders on them (modality, body part, and contrast), plus the workers-comp fields when that is the line of business. Check the payload is complete before you POST. Scan and the imaging center both check again at scheduling, but catching gaps early saves a round trip. The workers’ compensation field set is documented in Workers’ compensation and payers. Results are reviewed by you and the treating clinician. Scan files the radiology report PDF.

​
Who talks to the member

Scan reaches out to the member to schedule the appointment and to remind them about it when you use managed fulfillment. You stay in touch inside your own product for checkout, results, and support. When scheduling does not succeed, a center cancels, a report runs late, or the member complains, Scan handles the issue and you remain the first line of support for the member. Status changes land on the webhook and on GET referral, and the report itself comes from GET /api/v2/order_documents/report.

​
Not in this API

  • Eligibility, procedure quotes, and pre-purchase quotes
  • Partner cancellation quotes or an available_actions flag
  • Arranging an ordering clinician
These are handled through your contract and Scan operations rather than by an endpoint.

​
One MRI, end to end

A member has an order for an MRI. You have already charged them under your terms.
  1. Credentials. Bearer token on https://api.staging.scan.com — Authentication.
  2. Patient and order. Submit a medical referral (or the workers-comp payload if this is occupational).
  3. Optional intake. Safety answers: Submit medical questions. Preferred center and times: Submit preferred times. If you have the order, answers, and times in one sitting, use Submit for scheduling instead of the split guides.
  4. Schedule. Scan can schedule from those preferences. If auto-book is enabled for your account, submit a booking and receive its completion callback.
  5. Wait for booked. Subscribe to status changed. Key off booked (visits[].location and visits[].start_time). Treat other visit strings as opaque.
  6. Results. Pull the report PDF. Show it in your product. First-line support stays with you.
That is a complete workflow you can launch on: your experience and your checkout, Scan’s fulfillment and the report.