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

# Returns a list of referrals

> Returns a list of referrals that are associated with the user group.




## OpenAPI

````yaml /openapi.yaml get /api/v2/referrals
openapi: 3.1.0
info:
  title: Scan.com API
  version: v2
  description: >
    This API provides comprehensive access to Scan.com’s core functionalities, 

    including management of referrals, patient information, authentication, body
    parts, 

    and imaging modalities. It enables seamless integration for scheduling, data
    retrieval, 

    and workflow automation within the Scan.com platform, facilitating efficient
    and secure 

    handling of medical imaging processes.
servers:
  - url: https://api.staging.scan.com
    description: Sandbox
  - url: https://api.scan.com
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Courier SSO
    description: >-
      Mint a one-time Courier portal SSO URL with the same Bearer token used for
      the rest of the API.
  - name: Webhooks
    description: >-
      Outbound HTTP POST notifications sent to your api_credentials.webhook_url
      when visit or notification status changes. Configure api_credentials on
      your LawFirm, Practice, CoordinationGroup, Insurance, Employer, or
      NurseCaseManagementGroup.
  - name: Order Documents
    description: >-
      Retrieve radiology report PDFs, DICOM imaging, and invoices for orders
      visible to the authenticated group.
  - name: Locations
    description: >-
      Rank nearby imaging centers for a referral after medical safety answers
      are on file. Partners submit a preferred center; Scan books the visit.
  - name: Testing
    description: Staging-only fixture bootstrap, status advancement, and test webhooks.
  - name: FHIR
    description: >-
      Opt-in FHIR R4 read shapes for DiagnosticReport and ImagingStudy. Not a
      FHIR server.
paths:
  /api/v2/referrals:
    get:
      tags:
        - Referrals
      summary: Returns a list of referrals
      description: |
        Returns a list of referrals that are associated with the user group.
      operationId: listReferrals
      parameters:
        - name: page
          in: query
          required: false
          description: Page number
          schema:
            type: integer
        - name: per_page
          in: query
          required: false
          description: Number of referrals per page
          schema:
            type: integer
        - name: created_date
          in: query
          required: false
          description: Date of referral creation
          schema:
            type: string
        - name: date_of_service
          in: query
          required: false
          description: >-
            Filter by visit start time. Pass one date (YYYY-MM-DD) for that
            Eastern day, or two dates for an inclusive range. A referral matches
            if any visit start falls in the window. Unscheduled visits are
            excluded.
          schema:
            oneOf:
              - type: string
                format: date
              - type: array
                items:
                  type: string
                  format: date
                minItems: 1
                maxItems: 2
        - name: billable
          in: query
          required: false
          description: >-
            When true, also include referrals whose billing-company name matches
            the authenticated group
          schema:
            type: boolean
      responses:
        '200':
          description: referrals list
          content:
            application/json:
              examples:
                referrals list:
                  value:
                    appointments:
                      - id: 11111111-1111-1111-1111-111111111111
                        reference: '1234567890'
                        status: pending
                        visits:
                          - id: 11111111-1111-1111-1111-111111111111
                            modality: MRI
                            procedures:
                              - body_part: Brain
                                procedure: MRI Brain without contrast
                                contrast: without_contrast
                                laterality: not_present
                                cpt_code: '70551'
                                cpt_system: http://www.ama-assn.org/go/cpt
                                accession_id: ACC-1001
                                study_uid: null
                                series_uid: null
                                image_link: null
                                report_link: null
                            status: pending
                            start_time: '2021-01-01T00:00:00Z'
                            radiologist_group_name: East Coast Radiology
                            location:
                              id: 11111111-1111-1111-1111-111111111111
                              name: Anytown Medical Center
                              npi: '1234567890'
                              address_line_1: 123 Main St
                              address_line_2: null
                              city: Anytown
                              state: GA
                              zip_code: '30303'
                        line_of_business: workers_comp
                        payment_type: insurance
                        incident_state: GA
                        payor:
                          id: 44444444-4444-4444-4444-444444444444
                          name: Harbor Insurance
                        insurance_number: INS-123
                        wc_number: WCB-456
                        referring_provider: John Doe
                        provider:
                          id: 11111111-1111-1111-1111-111111111111
                          name: John Doe
                          npi: '1234567890'
                        law_firm:
                          id: 11111111-1111-1111-1111-111111111111
                          name: Acme LLP
                        practice:
                          id: 11111111-1111-1111-1111-111111111111
                          name: Main Street Imaging
                        icd10_codes:
                          - id: 11111111-1111-1111-1111-111111111111
                            code: M54.5
                            system: http://hl7.org/fhir/sid/icd-10-cm
                            short_description: Low back pain
                        patient:
                          id: 11111111-1111-1111-1111-111111111111
                          identifier:
                            system: https://scan.com/fhir/sid/patient-id
                            value: 11111111-1111-1111-1111-111111111111
                          name: John Doe
                          first_name: John
                          last_name: Doe
                          date_of_birth: 05/21/1988
                          date_of_birth_iso: '1988-05-21'
                          email: john.doe@example.com
                          phone_number: '5551234567'
                          gender: male
                          address_line_1: 123 Main St
                          city: Anytown
                          state: GA
                          zip_code: '30303'
                    meta:
                      current_page: 1
                      next_page: 2
                      prev_page: null
                      total_pages: 1
                      total_count: 1
              schema:
                type: object
                properties:
                  appointments:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReferralResource'
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        description: Current page number
                      next_page:
                        type: integer
                        nullable: true
                        description: Next page number (null if last page)
                      prev_page:
                        type: integer
                        nullable: true
                        description: Previous page number (null if first page)
                      total_pages:
                        type: integer
                        description: Total number of pages
                      total_count:
                        type: integer
                        description: Total number of appointments
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - BearerAuth: []
components:
  schemas:
    ReferralResource:
      type: object
      description: Referral snapshot (same shape as GET /api/v2/referrals/{id})
      properties:
        id:
          type: string
          format: uuid
          description: Appointment (referral) ID
        reference:
          type: string
          description: Human-readable referral reference
          example: '1234567890'
        status:
          type: string
          description: |
            The referral's case and billing state, distinct from
            `visits[].status`. `pending` covers an open referral from create
            through reporting; `invoice_ready`, `invoice_sent`, `closed`, and
            `canceled` are the other partner-meaningful values. Remaining
            values are internal accounts-receivable states with no integration
            meaning. Scheduling logic belongs on `visits[].status` — see
            [Track referral status](/guides/track-referral-status).
          example: pending
        line_of_business:
          type: string
          nullable: true
          description: |
            Encounter line of business. `patient_direct` can appear on reads but
            cannot currently be selected through `POST /api/v2/referrals`.
          enum:
            - personal_injury
            - workers_comp
            - health_plan
            - patient_direct
        payment_type:
          type: string
          nullable: true
          description: >
            Funding or order type returned by the referral serializer. This is

            distinct from the create request's legacy `payment_type` field

            (normally `pi`). Workers' compensation referrals are returned as

            `insurance`. `funding` is retained for older referrals; new
            referrals

            use `funded`.
          enum:
            - lien
            - insurance
            - med_pay
            - pip
            - cash_pay
            - funded
            - servicing
            - outside_servicing
            - funding
          example: lien
        incident_state:
          type: string
          nullable: true
          description: Two-letter state abbreviation associated with the incident
          example: GA
        visits:
          type: array
          description: All visits on the referral
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                description: Visit ID
              modality:
                type: string
                description: Modality name
                example: MRI
              procedures:
                type: array
                description: Orders on this visit
                items:
                  type: object
                  properties:
                    body_part:
                      type: string
                      description: Body part name
                      example: Brain
                    procedure:
                      type: string
                      description: Translated procedure label
                      example: MRI Brain w/o contrast
                    contrast:
                      type: string
                      description: Contrast type
                      example: without_contrast
                    laterality:
                      type: string
                      description: >-
                        Laterality. Same enum as write — `left`, `right`, or
                        `not_present`. Never `N/A`.
                      enum:
                        - left
                        - right
                        - not_present
                      example: not_present
                    cpt_code:
                      type: string
                      nullable: true
                      description: CPT code for the procedure when known
                      example: '70551'
                    cpt_code_id:
                      type: string
                      format: uuid
                      nullable: true
                      description: Stable CPT mapping ID for the procedure when known
                    cpt_system:
                      type: string
                      nullable: true
                      description: Coding system for `cpt_code`
                      example: http://www.ama-assn.org/go/cpt
                    accession_id:
                      type: string
                      nullable: true
                      description: >-
                        Order `reference_id`. Radiology systems often reconcile
                        on this.
                    study_uid:
                      type: string
                      nullable: true
                      description: DICOM Study Instance UID when Scan has it
                    series_uid:
                      type: string
                      nullable: true
                      description: DICOM Series Instance UID when Scan has it
                    image_link:
                      type: string
                      nullable: true
                      description: URL to imaging study when available
                    report_link:
                      type: string
                      nullable: true
                      description: URL to radiology report PDF when available
              status:
                type: string
                description: |
                  Where the visit is in scheduling, the exam, and reporting.
                  Key off `booked`, `report_uploaded`, and `sent_to_rp`; treat
                  the other values as progress information. New values may be
                  added, so ignore any string you do not recognize. Each value
                  is defined in the
                  [Track referral status](/guides/track-referral-status) guide.
                enum:
                  - pending
                  - pending_auth
                  - co_signed
                  - intake_sent
                  - ready_to_book
                  - contacted_for_booking
                  - booked
                  - complete
                  - exam_not_completed
                  - sent_to_rad
                  - report_uploaded
                  - qc_report_ready
                  - invoice_ready
                  - sent_to_rp
                  - canceled
                example: booked
              start_time:
                type: string
                format: date-time
                nullable: true
                description: Scheduled exam start time (ISO 8601)
              radiologist_group_name:
                type: string
                nullable: true
                description: Assigned radiologist group name
              location:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    nullable: true
                    description: Imaging location ID
                  address_line_1:
                    type: string
                    nullable: true
                    description: Imaging center street address
                  address_line_2:
                    type: string
                    nullable: true
                    description: Imaging center suite, unit, or secondary address
                  city:
                    type: string
                    nullable: true
                    description: Imaging center city
                  state:
                    type: string
                    nullable: true
                    description: Imaging center two-letter state abbreviation
                  zip_code:
                    type: string
                    nullable: true
                    description: Imaging center postal code
                  name:
                    type: string
                    nullable: true
                    description: Imaging center name
                  npi:
                    type: string
                    nullable: true
                    description: Imaging center NPI when the center has one
        referring_provider:
          type: string
          nullable: true
          description: Submitting provider full name
        provider:
          type: object
          description: Referring provider
          properties:
            id:
              type: string
              format: uuid
              nullable: true
            name:
              type: string
              nullable: true
            npi:
              type: string
              nullable: true
        law_firm:
          type: object
          properties:
            id:
              type: string
              format: uuid
              nullable: true
            name:
              type: string
              nullable: true
        practice:
          type: object
          properties:
            id:
              type: string
              format: uuid
              nullable: true
            name:
              type: string
              nullable: true
        payor:
          type: object
          description: >-
            Present only for workers' compensation and health plan referrals.
            Omitted entirely for PI and other lines. Nested keys are omitted
            when blank.
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
        insurance_number:
          type: string
          nullable: true
          description: >-
            Insurance member number. Present only for workers' compensation and
            health plan referrals.
        wc_number:
          type: string
          nullable: true
          description: >-
            Workers' compensation board number. Present only for workers'
            compensation referrals.
        icd10_codes:
          type: array
          description: Combined appointment and order ICD-10 codes
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              code:
                type: string
                example: M54.5
              system:
                type: string
                example: http://hl7.org/fhir/sid/icd-10-cm
              short_description:
                type: string
                example: Low back pain
        patient:
          type: object
          properties:
            id:
              type: string
              format: uuid
            identifier:
              type: object
              properties:
                system:
                  type: string
                  example: https://scan.com/fhir/sid/patient-id
                value:
                  type: string
                  format: uuid
            name:
              type: string
              description: Deprecated display name. Prefer `first_name` / `last_name`.
              example: John Doe
            first_name:
              type: string
            last_name:
              type: string
            middle_initial:
              type: string
              nullable: true
            date_of_birth:
              type: string
              description: MM/DD/YYYY. Deprecated. Prefer `date_of_birth_iso`.
              example: 05/21/1988
            date_of_birth_iso:
              type: string
              format: date
              nullable: true
              example: '1988-05-21'
            email:
              type: string
              format: email
              nullable: true
            phone_number:
              type: string
              nullable: true
            gender:
              type: string
              nullable: true
              description: Administrative sex, not gender identity
              enum:
                - male
                - female
                - other
            address_line_1:
              type: string
              nullable: true
            address_line_2:
              type: string
              nullable: true
            city:
              type: string
              nullable: true
            state:
              type: string
              nullable: true
            zip_code:
              type: string
              nullable: true
        call_notes:
          type: array
          description: Call log notes on the referral
          items:
            type: object
            properties:
              created_at:
                type: string
                format: date-time
              notes:
                type: string
        documents:
          type: array
          description: Public AOB and invoice attachments when available
          items:
            type: object
            additionalProperties: true
        answered_medical_questionnaire:
          type: boolean
          description: Whether medical safety answers are stored on the referral
        preferred_location:
          type: object
          description: Patient preferred imaging center, when set
          properties:
            id:
              type: string
              format: uuid
              nullable: true
            name:
              type: string
              nullable: true
        scheduling_mode:
          type: string
          nullable: true
          description: >-
            Availability preference submitted for this referral. Scan books from
            this preference.
          enum:
            - anytime_anywhere
            - time_preferences
            - existing_appointment
            - needs_other_location
        auto_book_request:
          allOf:
            - $ref: '#/components/schemas/AutoBookRequest'
          nullable: true
          description: Latest auto-book request, when one has been submitted
    AutoBookRequest:
      type: object
      required:
        - id
        - status
        - strategy
        - radius
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          description: |
            `processing` until the attempt reaches a terminal result, then
            `completed`. Read `outcome` for the result.
          enum:
            - processing
            - completed
        strategy:
          type: string
          enum:
            - closest
            - soonest
            - closest_soonest
        radius:
          type: integer
          minimum: 1
          maximum: 250
        address:
          type: string
          nullable: true
          description: Search origin override. Null means the patient address was used.
        outcome:
          type: string
          nullable: true
          enum:
            - booked
            - contacted_for_booking
            - no_availability
            - booking_failed
        error:
          type: string
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        type:
          type: string
          example: validation_error
        code:
          type: string
          example: unprocessable_entity
        request_id:
          type: string
        documentation_url:
          type: string
        errors:
          type: array
          items:
            type: string
      required:
        - error
        - message
        - type
        - code
  responses:
    Unauthorized:
      description: Missing, expired, or wrong-environment token
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unauthorized:
              value:
                error: Unauthorized
                message: Unauthorized
                type: authentication_error
                code: unauthorized
                request_id: abc-123
                documentation_url: https://docs.scan.com/guides/errors#unauthorized
            expired:
              value:
                error: API token expired
                message: API token expired
                type: authentication_error
                code: api_token_expired
                request_id: abc-123
                documentation_url: https://docs.scan.com/guides/errors#api_token_expired
    TooManyRequests:
      description: Sandbox request allowance exhausted
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Sandbox request limit reached
            message: Sandbox request limit reached
            type: rate_limit_error
            code: sandbox_request_limit_reached
            request_id: abc-123
            documentation_url: https://docs.scan.com/guides/errors#sandbox_request_limit_reached
    InternalServerError:
      description: Unexpected internal error
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Internal server error
            message: Internal server error
            type: api_error
            code: internal_error
            request_id: abc-123
            documentation_url: https://docs.scan.com/guides/errors#internal_error
  headers:
    RequestId:
      description: Correlate this response with Scan support.
      schema:
        type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >
        `Authorization: Bearer <api_token>`. Sandbox tokens come from Get API
        keys

        and allow 2,000 successful requests or 7 days. Failed 4xx/5xx responses
        do

        not consume the allowance. Production tokens are issued from the group's

        API access tab.

````