Skip to main content
Four objects carry almost everything the Partner API returns. A referral is the case. It holds one or more visits, each visit holds one or more orders, and a patient sits on the referral. OpenAPI is the source of truth for every field below; these notes cover the parts that are easy to get wrong.

​
Referral

A referral is a Scan Appointment. The same snapshot appears on GET /api/v2/referrals/{id}, create responses, and visit.status_changed. Operational status lives on visits[].status, not the top-level status field. See Track referral status. Important nested fields:
  • patient — see Patient below
  • icd10_codes[] — code plus system
  • visits[].procedures[] — cpt_code plus cpt_system, accession_id, study_uid, series_uid when known
  • visits[].location.npi — present only when the center has one
  • documents[].aob — an assignment of benefits attachment, when available
GET /api/v2/referrals/{referral_id}/payments returns amount, date, check number, and allocated procedures. Procedure description is the portal study string (for example MRI Left Ankle w/contrast). This capability is off until Scan enables payment read for your account. Workers’ compensation partners pull while referral status is not pending or canceled; payments can arrive months after invoice ready. See Workers’ compensation and payers. Create and read names differ for a few legacy fields. On create, the legacy payment_type defaults to pi; use order_type for lien, pip, or workers_comp. On reads, payment_type is the funding/order type; workers’ compensation referrals currently return insurance. For workers’ compensation identifiers, send wcb_number and read wc_number. OpenAPI source of truth: ReferralResource in openapi.yaml.

​
Visit

A visit is one scheduled exam. Partners should key automation off visits[].status (15 values). The FHIR Appointment mapping collapses those values; the Scan field stays authoritative. See Track referral status and FHIR mapping.

​
Order / procedure

On native reads this is visits[].procedures[]. Writes use visits[].orders[]. Documents: Order documents and DICOM.

​
Patient

GET /api/v2/patients/{id} already returns split name, address, phone, and gender. The nested referral patient historically returned only { id, name, date_of_birth, email }. It now also includes structured name, date_of_birth_iso, identifier, gender, phone_number, and address. The standalone POST /api/v2/patients request uses phone; patient responses and a patient nested in a referral create request use phone_number. name and MM/DD/YYYY date_of_birth stay for compatibility. Prefer first_name / last_name and date_of_birth_iso. gender is administrative sex, not gender identity.