> ## 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. # Creates a referral > Creates an imaging referral for a patient, including visits and procedures. ## OpenAPI ````yaml /openapi.yaml post /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: post: tags: - Referrals summary: Creates a referral description: >- Creates an imaging referral for a patient, including visits and procedures. operationId: createReferral parameters: [] requestBody: content: application/json: schema: type: object properties: referral: oneOf: - title: Imaging referral type: object properties: order_form: type: string description: > Physician order as a base64 data URL. Include `;name=` to preserve the attachment filename. pattern: ^data:[^;]+;(?:name=[^;]+;)?base64, example: >- data:application/pdf;name=order.pdf;base64,JVBERi0xLjQK payment_type: type: string description: Legacy billing case type. Defaults to `pi`. enum: - pi order_type: type: string description: Order type enum: - lien - pip injury_type: type: string description: Type of injury enum: - motor_vehicle_accident - slip_and_fall - workplace_accident - other incident_date: type: string description: Date of incident physician_notes: type: string description: Physician notes referred_by: type: string description: Referring physician state_brand_abbreviation: type: string description: State brand abbreviation visits: type: array items: type: object properties: modality_id: type: string format: uuid description: >- Modality ID; optional when every order uses cpt_code_id orders: type: array items: type: object properties: cpt_code_id: type: string format: uuid description: >- CPT mapping ID. When supplied, modality, body part, contrast, laterality, modifier, and number of views are inferred. body_part_id: type: string format: uuid description: Body part ID contrast: type: string description: Contrast type enum: - with_contrast - without_contrast - without_and_with_contrast laterality: type: string description: Laterality enum: - left - right - not_present oneOf: - required: - cpt_code_id - required: - body_part_id - contrast - laterality required: - orders icd10_codes: type: array items: type: string format: uuid description: ICD-10 code IDs associated with the referral patient: type: object properties: first_name: type: string description: Patient first name middle_initial: type: string description: Patient middle initial last_name: type: string description: Patient last name email: type: string format: email description: Patient email address phone_number: type: string description: Patient phone number date_of_birth: type: string description: Patient date of birth address_line_1: type: string description: Primary address line address_line_2: type: string description: Secondary address line (optional) city: type: string description: City state: type: string description: State abbreviation zip_code: type: string description: ZIP code language_preferences: type: string description: Language preferences gender: type: string enum: - male - female - other description: Patient gender height_feet: type: integer description: Patient height in feet height_inches: type: integer description: Additional patient height in inches weight: type: integer description: Patient weight in pounds required: - first_name - last_name - phone_number - date_of_birth patient_id: type: string format: uuid description: Existing patient ID (alternative to patient object) required: - order_form - injury_type - incident_date - visits - title: Workers' compensation referral type: object properties: order_form: type: string description: > Physician order as a base64 data URL. Include `;name=` to preserve the attachment filename. pattern: ^data:[^;]+;(?:name=[^;]+;)?base64, example: >- data:application/pdf;name=order.pdf;base64,JVBERi0xLjQK payment_type: type: string description: Legacy billing case type. Defaults to `pi`. enum: - pi order_type: type: string description: Order type enum: - workers_comp injury_type: type: string description: Type of injury enum: - motor_vehicle_accident - slip_and_fall - workplace_accident - other incident_date: type: string description: Date of incident physician_notes: type: string description: Physician notes referred_by: type: string description: Referring physician state_brand_abbreviation: type: string description: State brand abbreviation visits: type: array items: type: object properties: modality_id: type: string format: uuid description: >- Modality ID; optional when every order uses cpt_code_id orders: type: array items: type: object properties: cpt_code_id: type: string format: uuid description: >- CPT mapping ID. When supplied, modality, body part, contrast, laterality, modifier, and number of views are inferred. body_part_id: type: string format: uuid description: Body part ID contrast: type: string description: Contrast type enum: - with_contrast - without_contrast - without_and_with_contrast laterality: type: string description: Laterality enum: - left - right - not_present oneOf: - required: - cpt_code_id - required: - body_part_id - contrast - laterality required: - orders icd10_codes: type: array items: type: string format: uuid description: ICD-10 code IDs associated with the referral patient: type: object properties: first_name: type: string description: Patient first name middle_initial: type: string description: Patient middle initial last_name: type: string description: Patient last name email: type: string format: email description: Patient email address phone_number: type: string description: Patient phone number date_of_birth: type: string description: Patient date of birth address_line_1: type: string description: Primary address line address_line_2: type: string description: Secondary address line (optional) city: type: string description: City state: type: string description: State abbreviation zip_code: type: string description: ZIP code language_preferences: type: string description: Language preferences gender: type: string enum: - male - female - other description: Patient gender height_feet: type: integer description: Patient height in feet height_inches: type: integer description: Additional patient height in inches weight: type: integer description: Patient weight in pounds required: - first_name - last_name - phone_number - date_of_birth patient_id: type: string format: uuid description: Existing patient ID (alternative to patient object) payer: type: string description: Workers' compensation payer claim_number: type: string description: Workers' compensation claim number wcb_number: type: string description: Workers' compensation board number adjuster_name: type: string description: Adjuster name adjuster_phone: type: string description: Adjuster phone number adjuster_email: type: string format: email description: Adjuster email address practice_id: type: string format: uuid description: Referring practice ID law_firm_id: type: string format: uuid description: Law firm ID required: - order_form - injury_type - incident_date - visits - order_type required: - referral required: true responses: '200': description: referral created content: application/json: examples: referral: value: 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: personal_injury payment_type: lien incident_state: GA referring_provider: Dr. Jane Smith provider: id: 11111111-1111-1111-1111-111111111111 name: Dr. Jane Smith npi: '1234567890' law_firm: id: 11111111-1111-1111-1111-111111111111 name: Acme LLP practice: id: 11111111-1111-1111-1111-111111111111 name: Peachtree Family Practice 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: Alex Patient first_name: Alex last_name: Patient date_of_birth: 05/21/1988 date_of_birth_iso: '1988-05-21' email: alex.patient@example.com phone_number: '5551234567' gender: male address_line_1: 123 Main St city: Anytown state: GA zip_code: '30303' schema: $ref: '#/components/schemas/ReferralResource' '401': $ref: '#/components/responses/Unauthorized' '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 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 `. 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. ````