> ## 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.

# Core objects

> Referral, visit, order, and patient — the four shapes the Partner API returns

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](/guides/track-referral-status).

Important nested fields:

* `patient` — see [Patient](#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`](/api-reference/referrals/lists-referral-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](/guides/lines-of-business/workers-comp-and-payers#pull-payments).

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](/guides/track-referral-status) and
[FHIR mapping](/guides/fhir).

## Order / procedure

On native reads this is `visits[].procedures[]`. Writes use `visits[].orders[]`.

| Field                        | Notes                                                  |
| ---------------------------- | ------------------------------------------------------ |
| `cpt_code` / `cpt_code_id`   | CPT; `cpt_system` is `http://www.ama-assn.org/go/cpt`  |
| `body_part`                  | Display, not SNOMED                                    |
| `laterality`                 | `left` / `right` / `not_present`                       |
| `accession_id`               | Order `reference_id`                                   |
| `study_uid` / `series_uid`   | DICOM UIDs when Scan has them                          |
| `image_link` / `report_link` | Convenience URLs; prefer order-documents for downloads |

Documents: [Order documents and DICOM](/guides/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.