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

# Updates a referral

> Updates assignable ownership, ICD-10, and workers' compensation fields for a referral
belonging to the authenticated group.




## OpenAPI

````yaml /openapi.yaml patch /api/v2/referrals/{id}
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/{id}:
    patch:
      tags:
        - Referrals
      summary: Updates a referral
      description: >
        Updates assignable ownership, ICD-10, and workers' compensation fields
        for a referral

        belonging to the authenticated group.
      operationId: updateReferral
      parameters:
        - name: id
          in: path
          required: true
          description: Referral ID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - referral
              properties:
                referral:
                  type: object
                  properties:
                    practice_id:
                      type: string
                      format: uuid
                    law_firm_id:
                      type: string
                      format: uuid
                    coordination_group_id:
                      type: string
                      format: uuid
                    user_id:
                      type: string
                      format: uuid
                    icd10_codes:
                      type: array
                      items:
                        type: string
                        format: uuid
                    payer:
                      type: string
                    claim_number:
                      type: string
                    wcb_number:
                      type: string
                    adjuster_name:
                      type: string
                    adjuster_phone:
                      type: string
                    adjuster_email:
                      type: string
                      format: email
      responses:
        '200':
          description: referral updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferralResource'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '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
    NotFound:
      description: Resource not found or not accessible to this account
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Referral not found
            message: Referral not found
            type: not_found_error
            code: not_found
            request_id: abc-123
            documentation_url: https://docs.scan.com/guides/errors#not_found
    UnprocessableEntity:
      description: Request body failed validation
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Phone is invalid
            message: Phone is invalid
            type: validation_error
            code: unprocessable_entity
            request_id: abc-123
            documentation_url: https://docs.scan.com/guides/errors#unprocessable_entity
            errors:
              - Phone is invalid
    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.

````