> ## 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. # Submits an order form referral > Creates a referral from an uploaded order form, sent as a base64 data URL. Use this endpoint when you have the order document but have not broken it down into visits and orders yourself. Scan reads the document after submit and extracts the procedures from it, so the visits on the referral are populated asynchronously rather than in this response. Poll `GET /api/v2/referrals/{id}` or subscribe to the status webhook to see them. If you already have the modality, body part, and contrast structured, use `POST /api/v2/referrals` instead. ## OpenAPI ````yaml /openapi.yaml post /api/v2/referral_orders 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/referral_orders: post: tags: - Referral Orders summary: Submits an order form referral description: > Creates a referral from an uploaded order form, sent as a base64 data URL. Use this endpoint when you have the order document but have not broken it down into visits and orders yourself. Scan reads the document after submit and extracts the procedures from it, so the visits on the referral are populated asynchronously rather than in this response. Poll `GET /api/v2/referrals/{id}` or subscribe to the status webhook to see them. If you already have the modality, body part, and contrast structured, use `POST /api/v2/referrals` instead. operationId: createReferralOrder parameters: [] requestBody: content: application/json: schema: type: object properties: referral_order: type: object properties: order_form: type: string description: Order form file as a base64 data URL payment_type: type: string description: Legacy billing case type. Defaults to `pi`. enum: - pi order_type: type: string description: Order type enum: - lien - pip - workers_comp physician_notes: type: string description: Physician notes referred_by: type: string description: Referring physician state_brand_abbreviation: type: string description: State brand abbreviation preferred_location: type: string description: Preferred location name practice_id: type: string format: uuid description: Practice ID law_firm_id: type: string format: uuid description: Law firm ID coordination_group_id: type: string format: uuid description: Coordination group ID 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 format: date description: Patient date of birth address_line_1: type: string description: Primary address line address_line_2: type: string description: Secondary address line 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 required: - referral_order required: true responses: '201': description: referral order submitted content: application/json: examples: referral order submitted: value: id: 11111111-1111-1111-1111-111111111111 reference: '1234567890' status: pending visits: [] 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: [] 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: type: object properties: id: type: string format: uuid description: Unique referral identifier reference: type: string description: Referral reference status: type: string enum: - pending - completed description: Referral status visits: type: array items: type: object referring_provider: type: string description: Referring provider name patient: type: object required: - id - reference - status - visits - referring_provider - patient '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' security: - BearerAuth: [] components: 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 Forbidden: description: Endpoint is not enabled for this account headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: This endpoint is not enabled for your account message: This endpoint is not enabled for your account type: permission_error code: endpoint_not_enabled request_id: abc-123 documentation_url: https://docs.scan.com/guides/errors#endpoint_not_enabled 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 schemas: 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 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. ````