> ## 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. # Workers' compensation and payers > Required fields, call order, statuses, and when to pull payments for workers' compensation referrals 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](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. Register the patient first with [Submit a medical referral](/guides/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](/guides/submit-medical-questions) and [Submit preferred times](/guides/submit-preferred-times). The combined intake is [Submit for scheduling](/guides/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](/api-reference/referrals/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](/api-reference/cpt-codes/returns-cpt-code-mappings) and diagnosis IDs with [ICD-10 codes](/api-reference/icd-10-codes/returns-a-list-of-icd-10-codes). ## Send the workers' compensation referral **POST `/api/v2/referrals`** ```bash cURL theme={"dark"} 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": "adjuster@example.com", "visits": [ { "orders": [ { "cpt_code_id": "11111111-1111-1111-1111-111111111113" } ] } ] } }' ``` ```ruby Ruby theme={"dark"} 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: "adjuster@example.com", visits: [ { orders: [ { cpt_code_id: "11111111-1111-1111-1111-111111111113" } ] } ] } }.to_json response = http.request(request) puts response.body ``` ```python Python theme={"dark"} 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": "adjuster@example.com", "visits": [ { "orders": [ { "cpt_code_id": "11111111-1111-1111-1111-111111111113", } ], } ], } }, ) print(response.json()) ``` ```javascript JavaScript theme={"dark"} 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: "adjuster@example.com", visits: [ { orders: [ { cpt_code_id: "11111111-1111-1111-1111-111111111113", }, ], }, ], }, }), }); const referral = await response.json(); ``` ```php PHP theme={"dark"} $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" => "adjuster@example.com", "visits" => [ [ "orders" => [ [ "cpt_code_id" => "11111111-1111-1111-1111-111111111113", ], ], ], ], ], ]), CURLOPT_RETURNTRANSFER => true, ]); $response = curl_exec($ch); ``` ```go Go theme={"dark"} 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": "adjuster@example.com", "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}`](/api-reference/referrals/returns-a-referral-by-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](/api-reference/referrals/updates-a-referral). ## Status changes Every status, what it means, and how changes reach you are on [Track referral status](/guides/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](/guides/track-referral-status#referral-level-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`** ```bash cURL theme={"dark"} curl "https://api.staging.scan.com/api/v2/referrals/$REFERRAL_ID/payments" \ -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")}/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"] ``` ```python Python theme={"dark"} 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"] ``` ```javascript JavaScript theme={"dark"} 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(); ``` ```json theme={"dark"} { "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](/api-reference/referrals/lists-referral-payments).