Workers' compensation and payers

This guide is for workers’ compensation payers and TPAs. You submit an occupational-injury referral with claim identifiers, track it through the report, and pull payments once the referral is no longer pending or canceled. Before using this guide you need a sandbox and an access token. Request keys from Get API keys. How to send Authorization is in 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. Register the patient first with Submit a medical referral (or nest referral.patient on the create call below). Safety answers and preferred times are optional add-ons: Submit medical questions and Submit preferred times. The combined intake is Submit for scheduling.

Required and recommended fields

POST /api/v2/referrals selects workers’ compensation when order_type is workers_comp. The legacy payment_type field can be omitted and defaults to pi; it does not select the line of business. The create body is the workers’ compensation referral shape in Creates a referral.

Field	Required	Notes
`order_form`	Yes	Physician order as a base64 data URL
`order_type`	Yes	`workers_comp`
`injury_type`	Yes	Typically `workplace_accident`
`incident_date`	Yes	Date of injury
`physician_notes`	Recommended	Clinical context
`referred_by`	Recommended	Referring physician
`visits`	Yes	Orders identified by `cpt_code_id`; procedure details are inferred
`payer`	Recommended	Workers’ compensation payer name
`claim_number`	Recommended	Claim identifier
`patient_id` or `patient`	Yes	Existing patient, or nested patient object
`wcb_number`	Recommended	Board / claim-board number
`adjuster_name`, `adjuster_phone`, `adjuster_email`	Recommended	Claim adjuster
`state_brand_abbreviation`	Recommended	Two-letter state
`icd10_codes`	Recommended	ICD-10 IDs from the lookup endpoint

Look up exact procedure IDs with CPT codes and diagnosis IDs with ICD-10 codes.

Send the workers’ compensation referral

POST /api/v2/referrals

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=",
      "order_type": "workers_comp",
      "injury_type": "workplace_accident",
      "incident_date": "2026-04-01",
      "physician_notes": "Evaluate lower back injury after lifting accident.",
      "referred_by": "Dr. Jane Smith",
      "state_brand_abbreviation": "GA",
      "patient_id": "11111111-1111-1111-1111-111111111111",
      "payer": "Acme WC Insurance",
      "claim_number": "WC-12345",
      "wcb_number": "WCB-456",
      "adjuster_name": "Alex Adjuster",
      "adjuster_phone": "5559876543",
      "adjuster_email": "[email protected]",
      "visits": [
        {
          "orders": [
            {
              "cpt_code_id": "11111111-1111-1111-1111-111111111113"
            }
          ]
        }
      ]
    }
  }'

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=",
    order_type: "workers_comp",
    injury_type: "workplace_accident",
    incident_date: "2026-04-01",
    physician_notes: "Evaluate lower back injury after lifting accident.",
    referred_by: "Dr. Jane Smith",
    state_brand_abbreviation: "GA",
    patient_id: "11111111-1111-1111-1111-111111111111",
    payer: "Acme WC Insurance",
    claim_number: "WC-12345",
    wcb_number: "WCB-456",
    adjuster_name: "Alex Adjuster",
    adjuster_phone: "5559876543",
    adjuster_email: "[email protected]",
    visits: [
      {
        orders: [
          {
            cpt_code_id: "11111111-1111-1111-1111-111111111113"
          }
        ]
      }
    ]
  }
}.to_json

response = http.request(request)
puts response.body

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=",
            "order_type": "workers_comp",
            "injury_type": "workplace_accident",
            "incident_date": "2026-04-01",
            "physician_notes": "Evaluate lower back injury after lifting accident.",
            "referred_by": "Dr. Jane Smith",
            "state_brand_abbreviation": "GA",
            "patient_id": "11111111-1111-1111-1111-111111111111",
            "payer": "Acme WC Insurance",
            "claim_number": "WC-12345",
            "wcb_number": "WCB-456",
            "adjuster_name": "Alex Adjuster",
            "adjuster_phone": "5559876543",
            "adjuster_email": "[email protected]",
            "visits": [
                {
                    "orders": [
                        {
                            "cpt_code_id": "11111111-1111-1111-1111-111111111113",
                        }
                    ],
                }
            ],
        }
    },
)
print(response.json())

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=",
      order_type: "workers_comp",
      injury_type: "workplace_accident",
      incident_date: "2026-04-01",
      physician_notes: "Evaluate lower back injury after lifting accident.",
      referred_by: "Dr. Jane Smith",
      state_brand_abbreviation: "GA",
      patient_id: "11111111-1111-1111-1111-111111111111",
      payer: "Acme WC Insurance",
      claim_number: "WC-12345",
      wcb_number: "WCB-456",
      adjuster_name: "Alex Adjuster",
      adjuster_phone: "5559876543",
      adjuster_email: "[email protected]",
      visits: [
        {
          orders: [
            {
              cpt_code_id: "11111111-1111-1111-1111-111111111113",
            },
          ],
        },
      ],
    },
  }),
});

const referral = await response.json();

$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=",
      "order_type" => "workers_comp",
      "injury_type" => "workplace_accident",
      "incident_date" => "2026-04-01",
      "physician_notes" => "Evaluate lower back injury after lifting accident.",
      "referred_by" => "Dr. Jane Smith",
      "state_brand_abbreviation" => "GA",
      "patient_id" => "11111111-1111-1111-1111-111111111111",
      "payer" => "Acme WC Insurance",
      "claim_number" => "WC-12345",
      "wcb_number" => "WCB-456",
      "adjuster_name" => "Alex Adjuster",
      "adjuster_phone" => "5559876543",
      "adjuster_email" => "[email protected]",
      "visits" => [
        [
          "orders" => [
            [
              "cpt_code_id" => "11111111-1111-1111-1111-111111111113",
            ],
          ],
        ],
      ],
    ],
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($ch);

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=",
      "order_type":               "workers_comp",
      "injury_type":              "workplace_accident",
      "incident_date":            "2026-04-01",
      "physician_notes":          "Evaluate lower back injury after lifting accident.",
      "referred_by":              "Dr. Jane Smith",
      "state_brand_abbreviation": "GA",
      "patient_id":               "11111111-1111-1111-1111-111111111111",
      "payer":                    "Acme WC Insurance",
      "claim_number":             "WC-12345",
      "wcb_number":               "WCB-456",
      "adjuster_name":            "Alex Adjuster",
      "adjuster_phone":           "5559876543",
      "adjuster_email":           "[email protected]",
      "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 referral, including id. On GET /api/v2/referrals/{referral_id} expect line_of_business: workers_comp, plus payor, insurance_number, and wc_number when those identifiers are on file. The field names intentionally differ by direction: send payer and wcb_number; read payor and wc_number. To correct claim, payer, or adjuster details after create, use Updates a referral.

Status changes

Every status, what it means, and how changes reach you are on Track referral status. One thing is specific to workers’ compensation: a visit sits in pending_auth while we wait on claim authorization, which can hold up booking for as long as the payer takes. Do not poll for the internal steps in between — wait for the next webhook or take a snapshot when you need one.

Pull payments

Payments are logged against the referral, not the visit. They can arrive months after invoice ready, so treat the list as something you keep pulling rather than a one-shot after the report. Do not call this while the referral’s top-level status is pending or canceled. Once it leaves those two — typically invoice_ready, then invoice_sent, closed, or another accounts-receivable value — keep listing payments. An empty referral_payments array is expected until Scan logs one; do not treat the first empty response as final. Visit invoice_ready only means reporting is finished for that visit. It is not a signal that a payment exists. See Track referral status. This capability is off until Scan enables payment read for your account. Without it the endpoint returns 403. GET /api/v2/referrals/{referral_id}/payments

curl "https://api.staging.scan.com/api/v2/referrals/$REFERRAL_ID/payments" \
  -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")}/payments")
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)

payments = JSON.parse(response.body)["referral_payments"]

import os
import requests

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

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

const { referral_payments: payments } = await response.json();

{
  "referral_payments": [
    {
      "id": "77777777-7777-7777-7777-777777777777",
      "amount": 10.0,
      "date": "2026-09-01",
      "check_number": "1002",
      "procedures": [
        {
          "order_id": "88888888-8888-8888-8888-888888888888",
          "accession_id": "ACC-1002",
          "cpt_code": "73721",
          "description": "MRI Left Ankle w/contrast"
        }
      ]
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1
  }
}

Results are newest first and paginated with page and per_page (default 20). Procedure description is the portal study string. date and check_number can be null on older payments. Full schema: Lists referral payments.

Get started

Launch

Patient journey

Referral status

Lines of business

Required and recommended fields

Send the workers’ compensation referral

Status changes

Pull payments

​Required and recommended fields

​Send the workers’ compensation referral

​Status changes

​Pull payments

Required and recommended fields

Send the workers’ compensation referral

Status changes

Pull payments